129 lines
7.3 KiB
Markdown
129 lines
7.3 KiB
Markdown
# Point Grey / FLIR USB2 camera on Ubuntu 24.04 / Linux Mint 22
|
||
|
||
Setup for a legacy **Point Grey Research USB 2.0 camera** (USB vendor `1e10`) on a modern Debian/Ubuntu-family machine. Tested against the camera that reports:
|
||
|
||
```
|
||
idVendor=1e10 idProduct=2005
|
||
Product: USB 2.0 Digital Imaging Camera
|
||
Manufacturer: Point Grey Research
|
||
```
|
||
|
||
These cameras predate FLIR's Spinnaker SDK and are supported only by the older **FlyCapture2 SDK** (here, version 2.13.3.31). Spinnaker will not see them.
|
||
|
||
## What this camera actually is
|
||
|
||
The reference unit was handed over as a "SWIR camera," but it is a standard visible/near-IR machine-vision camera with a wavelength converter fitted in front of the sensor. Worth knowing before you trust it for anything quantitative.
|
||
|
||
`FlyCapture2Test` reports:
|
||
|
||
```
|
||
Camera model - Chameleon CMLN-13S2M
|
||
Sensor - Sony ICX445AL (1/3" 1296x964 CCD)
|
||
```
|
||
|
||
That is a plain silicon CCD, which physically cannot detect 1550 nm on its own (silicon's band edge sits near 1050 nm). It images 1550 nm because someone fitted an **anti-Stokes upconversion phosphor** over the sensor together with a visible-blocking filter. The phosphor absorbs roughly 1495–1595 nm and re-emits around 532 nm green, which the silicon CCD detects normally. The modification is entirely optical, so the camera still identifies itself as a stock Chameleon and there is nothing to configure for it in software.
|
||
|
||
In practice:
|
||
|
||
- **Band-limited to about 1495–1595 nm.** It will not see 1310 nm, 1064 nm or 2 µm. It responds to incandescent bulbs (blackbody emission reaches into that band) but not to visible LEDs.
|
||
- **Direct sources only.** It needs roughly 1–2 mW imaged onto the array (a laser spot, or a hot filament). It cannot image reflected or diffuse SWIR scenes.
|
||
- **Resolution is phosphor-limited.** The phosphor point-spread is around 70 µm, so 1550 nm images are much softer than the 1296×964 sensor implies, and dynamic range is only about 30 dB.
|
||
|
||
It is a cheap 1550 nm beam/source viewer, not a SWIR scene camera. Genuine quantitative or reflected-scene SWIR imaging needs an InGaAs sensor. The FlyCapture2 setup below is the same either way, since the camera electronics are unmodified.
|
||
|
||
## What gets installed
|
||
|
||
The FlyCapture2 SDK was built for Ubuntu 18.04. Its GUI applications (`FlyCap2`, `UpdatorGUI`) depend on GTK2-era libraries (`libgtkmm-2.4`, `libglademm-2.4`, `libgtkglextmm`) that no longer exist in Ubuntu 24.04, so we do not install them. The **core** libraries only need `libusb` and `libraw1394`, which are still present, so this setup installs:
|
||
|
||
- `libflycapture2` / `libflycapture-c2` and their `-dev` packages (C++ and C runtime + headers).
|
||
- `FlyCapture2Test` and `FlyCapture2Test_C` — prebuilt command-line tools that list attached cameras and grab test frames. They link only the core library, so they run fine without the GUI stack.
|
||
- `fc2view` — a small **live viewer** built from `fc2view.cpp` in this repo, using OpenCV. It replaces the vendor's GTK2 GUI: it streams the first camera into a window and saves snapshots (see below).
|
||
- The example source tree at `/usr/src/flycapture/src` for building your own capture programs.
|
||
|
||
It also does the two bits of host configuration these cameras need:
|
||
|
||
- **A udev rule + `flirimaging` group** so the camera is readable/writable without root.
|
||
- **A larger USBFS buffer** (`usbcore.usbfs_memory_mb=1000`, up from the 16 MB default). Camera frames exceed the default buffer, which otherwise shows up as grab failures or dropped images.
|
||
|
||
The vendor GUI itself is the only thing lost by not being on 18.04, and `fc2view` covers the common need for a live viewport. If you specifically need the vendor GUI (e.g. for firmware updates via `UpdatorGUI`), run it in an 18.04/20.04 container.
|
||
|
||
## Live viewer (`fc2view`)
|
||
|
||
`install.sh` compiles `fc2view.cpp` and installs it as `/usr/local/bin/fc2view`. With the camera plugged in:
|
||
|
||
```bash
|
||
fc2view
|
||
```
|
||
|
||
It connects to the first camera, prints its model and serial, and opens a live window. Keys: **`s`** saves a snapshot to the current directory as `fc2-<serial>-<timestamp>.png` (saved from the raw frame, so a 16-bit sensor keeps its full bit depth); **`q`** or **Esc** quits. It converts each frame to BGR for display, so it works on mono and colour sensors alike.
|
||
|
||
It's about 130 lines and depends only on OpenCV and the FlyCapture2 core library. Treat it as a starting point for your own acquisition code. Rebuild by hand with:
|
||
|
||
```bash
|
||
g++ fc2view.cpp -I/usr/include/flycapture $(pkg-config --cflags --libs opencv4) -lflycapture -o fc2view
|
||
```
|
||
|
||
## Install
|
||
|
||
The SDK `.deb` files are bundled under `sdk/` because FLIR's download is behind a login, so the repo is self-contained. From this directory:
|
||
|
||
```bash
|
||
sudo ./install.sh
|
||
```
|
||
|
||
Then **log out and back in** (for the `flirimaging` group to apply). The USBFS limit is set live during install and made permanent on the next reboot; a reboot covers both at once.
|
||
|
||
Verify, with the camera plugged in:
|
||
|
||
```bash
|
||
FlyCapture2Test # prints camera info + grabs frames
|
||
fc2view # opens the live window
|
||
```
|
||
|
||
`FlyCapture2Test` should show the camera's serial, model and firmware, then a batch of grabbed frames. That serial should match the one in `dmesg`/`lsusb` (`00FBA0C0` on the reference machine).
|
||
|
||
## Rolling out to another machine
|
||
|
||
The camera model and the OS release are the same across your machines, so:
|
||
|
||
1. Copy this whole directory (it includes `sdk/` with the `.deb` files).
|
||
2. Run `sudo ./install.sh`.
|
||
3. Log out and back in (or reboot).
|
||
|
||
The script is idempotent, so re-running it to repair a machine is safe. If a machine is a **different architecture** (e.g. arm64) or a **different OS release**, the bundled amd64 debs will not apply; get the matching FlyCapture2 build from FLIR and drop its debs into `sdk/`.
|
||
|
||
## Building your own capture program
|
||
|
||
Headers are in `/usr/include/flycapture`; the library links with `-lflycapture`. A minimal build:
|
||
|
||
```bash
|
||
g++ my_capture.cpp -I/usr/include/flycapture -lflycapture -o my_capture
|
||
```
|
||
|
||
Or start from a worked example:
|
||
|
||
```bash
|
||
cp -r /usr/src/flycapture/src/FlyCapture2Test ~/fc2test && cd ~/fc2test
|
||
g++ FlyCapture2Test.cpp -I/usr/include/flycapture -lflycapture -o FlyCapture2Test
|
||
```
|
||
|
||
## Uninstall
|
||
|
||
```bash
|
||
sudo ./uninstall.sh
|
||
```
|
||
|
||
This removes the libraries, CLI tools, example source and udev rule. It leaves the `flirimaging` group, the GRUB USBFS setting and the apt dependencies in place (they are harmless and may be shared); the script prints how to undo those by hand.
|
||
|
||
## Troubleshooting
|
||
|
||
- **`FlyCapture2Test` finds no camera** — confirm `lsusb` shows `1e10:2005`. If it does, you probably have not logged out/in since install, so you lack the `flirimaging` group (`id` should list it). As a one-off check you can run `sudo FlyCapture2Test`.
|
||
- **Camera detected but frames fail or time out** — the USBFS buffer did not take. Check `cat /sys/module/usbcore/parameters/usbfs_memory_mb` (should read `1000`); if it reads `16`, reboot so the GRUB setting applies.
|
||
- **`error while loading shared libraries: libflycapture.so.2`** — run `sudo ldconfig`.
|
||
- **USB 2.0 bandwidth** — this is a USB 2.0 camera (~480 Mbps shared). On a busy hub you may need to lower resolution or frame rate. Plugging it into its own port/controller helps.
|
||
|
||
## Reference
|
||
|
||
- Vendor SDK README: `sdk/README`.
|
||
- FLIR "Configuring USBFS" note explains the buffer limit (the SDK README links to `ptgrey.com/tan/10685`, now under flir.com support).
|