You recorded a stereo session in your 3D SDK's viewer, saved it as a file camera, and pointed your vision software's acquisition interface at it. The device opens, the assistant reports a connection, and the first grab_data call fails with a short message that names the step, not the cause — one German installation showed a string the user translated as "adding images". The case below had an 18.8 MB recording that was healthy from the start. The failure sat in three settings: a device type of Item instead of Stereo, a file camera name the interface read as a hardware EEPROM ID, and an acquisition DLL built against a different 3D SDK build than the one installed. Fix them in that order and the replay returns images.
What a file camera is, and how it fails
A file camera is a recording played back as a device. The 3D SDK's viewer writes a stereo capture — image pairs, calibration data and the point clouds computed from them — into one file, and the acquisition layer opens that file as if it were the camera. Your grab loop and processing pipeline run unchanged, which is the whole point: you debug on captured data without the hardware.
The failure is quiet. The connect step reports success while binding to something that is not a camera, and only the grab fails. The dialog message is often a localized string that hides the cause; the real text sits in the vision software's output console, a separate window from the main interface. In this case that console carried the warnings the connect button never mentioned. Read it first, every time, before changing a setting.
Check 1: the device type must name a camera, not Item
The acquisition interface exposes a device tree: cameras, and the raw items they hang from. The CameraType input decides what open_framegrabber binds to. Set it to Item and you hold a tree node; grab_data on a node returns an invalid-handle error, because a node is not a camera.
For a stereo 3D camera the value is Stereo. The failing dialog carried Item in the field beside the camera-type label — Kameratyp on a German install — so no grab could succeed.
Test: read CameraType before connecting. Anything named Item, or any raw tree path, fails the test.
Fix: set Stereo (or the type the interface lists for your device class) and put the camera's name or serial in the device-identity field.
After the change to Stereo, the same case saw the device refuse to open at all. That is progress, not regression: the interface now honestly reports it cannot find a camera, which checks 2 and 3 repair.
Check 2: a numeric name becomes an EEPROM ID
The interface has special handling for the device-identity input: a string that can be transformed to a number is handled as an eeprom_id — a serial held in physical hardware. Name a file camera 01 and the interface searches for hardware carrying that EEPROM ID. No file camera can ever match, and the grab fails on data that replays perfectly in the viewer.
This also explains the symptom that confuses everyone first: you type the name you gave the recording, and the dialog hands back a serial number. Your input was resolved as an ID lookup, so the name never reached the by-name search that would have found the file.
Fix: recreate the file camera in the SDK viewer under a name that starts with a letter — replay01, not 01. The recording itself is untouched; the name is metadata. The 18.8 MB file in this case needed no second capture.
Check 3: the interface DLL must match the SDK build
The acquisition interface is a DLL built against one specific 3D SDK build. The failing workstation had SDK 4.1.1033 installed while the interface banner read Rev. 6.6, built against 4.1.976: same 4.1 line, 1033 − 976 = 57 patch builds apart. The interface is built to stay compatible across a few patch versions; 57 is not a few, and a grab that fails on a known-good recording is the symptom.
The DLL comes from the SDK installer, but the installer cannot know where your vision software lives, so it does not place the file there. Follow the installation guide in the SDK manual and copy it yourself:
- Reinstall the 3D SDK, so the library and the interface DLL on disk come from one build.
- Copy the interface DLL from the SDK install into the vision software's acquisition-interface folder, replacing the older Rev.
- Restart the vision software, reopen the device, and read the banner: it must carry your installed build — 4.1.1033 in this case.
- Run one grab_data and confirm the output console stays empty.
Worked example: one replay from failed grab to first image
Inputs, all from the failing workstation:
- Recording: one file camera, 18.8 MB (.enscam), written by the SDK viewer, named with a leading number.
- Installed 3D SDK: 4.1.1033.
- Acquisition interface in the vision software: Rev. 6.6, built against 4.1.976.
- CameraType at open time: Item.
Rule in words: a successful grab needs a handle to a camera node, an identity the interface resolves by name, and an interface built against the installed library build. Fail any one of the three and the grab fails, whatever the recording contains.
Arithmetic:
- Interface against SDK: the major and minor lines match (4.1 = 4.1); the patch gap is 1033 − 976 = 57 builds.
- Recording size against replay speed: reading the entire file per frame at a conservative 100 MB/s disk floor gives 18.8 ÷ 100 ≈ 0.19 s. File size and disk speed are never the reason a file camera fails to grab.
Result: rename the file camera to a letter-first name, set CameraType to Stereo, reinstall the SDK and copy the interface DLL over. The first grab_data after that returned the recorded pair and its point cloud.
Decision: with all three gates passed and the grab still failing, stop tuning the vision software. Replay the recording in the viewer that wrote it and step frames there. A file that steps in its own viewer but not through the interface is an interface problem; a file that steps nowhere is a recording problem, and you re-record.
Prove the fix before you build on it
Three checks, in this order:
- The device-identity field shows the name you typed, not a serial number.
- One grab_data returns the recorded image pair, and the point cloud computes from it with the pipeline unchanged.
- A ten-frame loop runs with an empty output console — no warnings, no error text.
If all three hold, the replay path is sound and any remaining defect is in your processing, not the acquisition.
From replay to the real camera
The three settings transfer to hardware unchanged. CameraType stays Stereo. The identity becomes the camera's serial — numeric is correct there, because an eeprom_id lookup on real hardware is exactly what you want. The interface build must still match the SDK. What changes is the link: a stereo 3D camera streaming depth over GigE wants a dedicated interface card rather than a motherboard port shared with the plant network, and the cable and distance rules in 5GBASE-T camera interface: bandwidth, cables and distance apply to whatever card you pick. A dual-port PoE card is the usual fit for one stereo camera plus a spare connection.
- Interface
- GigE
- Ports
- 2 ports
The MV-GE2002P is a dual-port PoE card on GigE, so one card carries the camera and its power.
For the camera itself, start among the 3D sensors — stereo and structured-light models such as the MV-DLS300P-04, a laser galvanometer stereo camera, or projected structured-light units like the MV-DPS200P-02. Compare interface cards from the frame grabbers range side by side when one card must carry several cameras:
| Specification | MV-GE2002P | MV-GE1104 | LS-FGB-0004 |
|---|---|---|---|
| Interconnect | PCI-E gen2 × 4 | PCI-E gen2 ×4 | – |
| Delivery bandwidth | 860 MB/s (max. transmission bandwidth); 800 MB/s (sustained transmission bandwidth) | 860 MB/s (peak bandwidth), 800 MB/s (sustained bandwidth) | – |
| Standard | IEEE 802.3 | GigE Vision | – |
| Interface | 2 × RJ45 | 4 × RJ45 | – |
| Camera type supported | GigE industrial camera | GigE industrial camera | – |
| Camera quantity supported | 2 at most | 4 at most | – |
| Camera connection speed | 10/100/1000 Mbps | 1 Gbps | – |
| Stream | 2 | 4 | – |
| Power consumption | 7.5 W (excl. PoE) | 10 W | – |
| Dimension | 181 mm × 126.3 mm × 21.6 mm | 181 mm × 126.3 mm × 21.6 mm | – |
| Temperature | Working temperature: 0 °C to 60 °C (32 °F to 140 °F); Storage temperature: –20 °C to 70 °C (–4 °F to 158 °F) | Working temperature: 0 °C to 60 °C (32 °F to 140 °F); Storage temperature: –20 °C to 70 °C (–4 °F to 158 °F) | – |
| Humidity | 10% RH to 95% RH (no condensation) | 10% RH to 95% RH (no condensation) | – |
| Price | $249.00 | $699.00 | $359.00 |
Values as printed in each product's data sheet; open a part for its drawing and full specifications.
One difference replay never warns you about: a laser-based stereo camera emits light the recording did not. Treat the laser class on the camera's label as binding, and never look into the beam or its specular reflection.
When the real camera then misbehaves, the same version discipline applies — read 3D camera SDK v2 firmware version mismatch: no device found and depth camera not detected: check the SDK version before the cable before you touch a cable. If the acquisition layer cannot even enumerate the device, GenTL CTI file added but no error: validate before you enumerate and camera not found: make sure the API matches the camera interface cover that layer. More set-up and SDK articles sit on the 3D topic page, and the camera finder narrows the hardware list.
Next step: once the replay is stable and the hardware is chosen, run the system configurator, or write to us through the contact page with your SDK build and interface banner — those two lines settle most of these cases on the first reply.
Checklist: file camera grab in five lines
- CameraType names a camera class — Stereo — never Item.
- The file camera's name starts with a letter.
- After connect, the identity field shows your name, not a serial.
- The interface banner's build equals the installed SDK build.
- The output console is the first window you read; the dialog is the last.
Questions
Why does my file camera show a serial number instead of the name I gave it?
Because the acquisition interface treats any device identity that can be read as a number as an eeprom_id, a serial held in physical hardware. Your numeric file-camera name never reaches the by-name search, so the dialog resolves it as an ID and reports the serial it matched or failed to match. Rename the file camera with a leading letter and the name you type is the name the device keeps.
Where does the correct acquisition interface DLL come from?
From the 3D SDK installer you already have. The installer copies the interface DLL to the system, but it cannot know where your vision software is installed, so it does not place the file there. Copy the DLL from the SDK install into the vision software's interface folder yourself; the installation guide in the SDK manual gives the folder. Avoid third-party driver-download sites entirely.
How far apart can the interface DLL and SDK versions be?
The interface is built to stay compatible across a few patch versions, so a gap of a handful of builds is normal. The failing case ran SDK 4.1.1033 against an interface built on 4.1.976, which is 1033 minus 976, or 57 patch builds apart, and the grab failed on a healthy recording. When a grab fails, match the builds exactly; it costs one reinstall.
Do I need the physical camera connected to replay a file camera?
No. The file camera is a virtual device: the recording stands in for the hardware, which is what lets you debug algorithms on captured data. What you do need is the SDK that wrote the recording, an acquisition interface built against that same SDK build, and a device type that selects a camera class such as Stereo rather than Item.
Can a large recording file cause the grab error?
No. The 18.8 MB file in this case reads in a fraction of a second: 18.8 MB at even a conservative 100 MB/s disk floor is about 0.19 s, and replay reads locally with no camera bandwidth in the path. Size is a red herring. Look at device type, the file camera's name, and the interface build instead.