Depth camera GenTL producer setup: how the data path works

A depth camera that your GenICam software cannot enumerate natively is not a dead end. If its vendor ships a GenTL producer, the camera joins the same device list as your GigE and USB3 cameras, and your existing acquisition code opens it unchanged. What surprises integrators is what shows up next: two devices for one physical camera, 16-bit pixels full of zeros, and distances that need one multiply to become millimetres. This page walks the data path end to end — the two-device enumeration, the depth decode, the discovery variables, the license — so you can commit to the approach before ordering hardware.

What a GenTL producer does for a depth camera

GenTL is the transport-layer part of the GenICam standard. It defines a library interface — the producer, delivered as a CTI file — that a GenICam consumer loads in order to enumerate devices and move buffers. A camera with no GigE Vision or USB3 Vision stack of its own can be wrapped in one, and then it appears in your consumer beside every other GenICam device.

The practical win is a single acquisition path: your code already knows how to open a device, walk its parameter tree and pull buffers, and a depth camera behind a producer plugs into exactly that code. No second SDK gets embedded. The producer adds nothing on top — it exposes the depth module's own parameters, including the depth-unit setting that turns pixels into distances.

Stations like this start from the shop's 3D sensors; the depth families below are the ones a producer-style integration usually wraps.

Why one depth camera appears as two devices

Depth cameras that also carry an RGB sensor commonly show up as two GenICam devices under the GenICamTL interface list: a depth module and a color module. Each opens its own stream with its own format and its own intrinsic calibration, so the device dialog lists the same physical camera twice. That is the design, not a fault.

Open the depth entry when you need the range image; open the color entry only for a texture overlay. If color arrives but depth never does, you have almost certainly opened the color device — the stereo camera RGB-works-but-no-depth diagnosis walks that failure step by step. Overlaying the two streams correctly is its own alignment task; aligned depth streams: data layout and which intrinsics apply covers the buffer layout and the intrinsics question.

Reading the 16-bit depth image

The depth module delivers, by default, a 16-bit unsigned image with a two-line contract:

• 0 — no measurement. The pixel has no valid range: it sits outside the rated distance window, returned too little signal, or is occluded.
• 1 to 65535 — calibrated depth, scaled by the device's depth-unit parameter.

Decoding is one multiply:

Worked example, with illustrative inputs. Say the device reports a depth unit of 1 mm — the value you meet most often on indoor depth modules; the real number always comes from the parameter. A pixel reading 3,214 then decodes as 3,214 × 1 mm = 3,214 mm ≈ 3.21 m. Set the unit to 0.25 mm instead, and the same pixel reads 3,214 × 0.25 mm = 803.5 mm. The depth unit and precision settings on 3D cameras article follows the same parameter through its consequences.

The same arithmetic yields two sanity checks. The representable span is 65535 × 1 mm = 65,535 mm ≈ 65.5 m, far beyond any indoor depth camera's rated metres, so 16 bits never cap the range — the optics do. And the zeros describe the scene, not the encoding: take an illustrative 640 × 480 frame, 307,200 pixels, of which 12,400 read zero. The invalid share is 12,400 ÷ 307,200 ≈ 4.0%. A few percent on a static bench scene is healthy; double digits at the rated working distance points at exposure or ambient light first, hardware second.

Many pipelines cut the scene to a z-window before any of this, processing a slab of range instead of the full span — the depth camera ROI and z-layer scan configuration page walks that set-up.

Discovery: GENICAM_GENTL64_PATH

Consumers find producers through environment variables, not through a registry sweep: a 64-bit application reads GENICAM_GENTL64_PATH, a 32-bit application reads GENICAM_GENTL32_PATH. Each variable lists directories; the consumer loads every producer library it finds there and enumerates the devices behind them. The producer's installer normally creates or extends the variable, so a fresh install usually just works.

When the depth camera never appears, walk down this list. Confirm the variable exists and names the directory that holds the producer library. Confirm the bitness matches — a 64-bit consumer ignores the 32-bit variable and vice versa. Point the consumer at the directory by hand; most acquisition dialogs have a browse control for exactly this. On Linux, path escaping is the classic trap, as GenTL CTI file path errors in Python shows. A producer that enumerates in one tool but not another is a Windows DLL search path problem, not a camera fault. In containers the variables do not pass through by default; the container discovery diagnosis lists what to forward.

License and security software: the two silent blockers

A GenTL producer is licensed software from its vendor. Many stamp a watermark into every frame or refuse to open the device until the license is in place, so arrange the license through the vendor's normal channel before any image-quality work — tuning against a watermarked frame wastes the trial.

Second, consumer security software sometimes quarantines a producer library it does not recognise, and then neither the producer nor its devices appear anywhere. Restore the library from the vendor's installer and add the exclusion for your own application the way your IT policy permits. If devices vanish after a security-software update, check the quarantine before you re-install anything.

Choosing the camera and the controller

On the camera side, the depth technology follows the task: speckle structured light for logistics and volume work, projected structured light for closer surface work, and time of flight where the target moves. These are the depth-camera families in the shop's 3D range:

On the host side, size the vision controllers to the streams. A producer moves the same buffers as any GenICam device, so port count and memory decide, not anything exotic. For a multi-camera station, the MV-VC5525-256G70-NN carries 32 GB of memory, PoE camera ports and 8 built-in light channels. A single-camera depth station runs on the MV-VC3301H-128G66, which pairs 8 GB of memory with 4 built-in light channels and 5+ LAN ports.

All 2 share: Humidity 20% RH to 95% RH (no condensation); Certification CE, KC. Values as printed in each product's data sheet; open a part for its drawing and full specifications.

The camera finder filters the 3D range by technology, and the system configurator assembles both sides in one pass. When the depth data feeds a robot, resolving camera coordinates is the next subject — depth for robot coordinate resolution explains why depth is what makes the camera frame usable, and 3D camera robot integration checks lists the compatibility items to clear before you order.

When the producer is the wrong tool

Skip the producer when the camera already speaks a vision standard natively: a GigE Vision or USB3 Vision depth device opens directly, with less software between you and the socket. Extra hops in the path cost real time even on a direct connection — the depth camera latency caused by a wrong network path is the cautionary example. Profile work is a different data shape altogether: a laser profiler streams height profiles, not range images, and its toolchain assumes them; 3D scanning method selection for inspection sorts the technologies by task. And when the vendor SDK computes on-camera outputs your pipeline leans on — fused point clouds, presets, aligned exports — weigh honestly: GenTL buys a common acquisition path, not extra features.

Pre-flight checklist

Run this before you commit the station:

• License first. Arrange the producer license through its vendor before image-quality trials; a watermarked frame is not the camera's real output.
• Right variable, right bitness. GENICAM_GENTL64_PATH for 64-bit consumers, GENICAM_GENTL32_PATH for 32-bit, each naming the producer's directory.
• Open the depth device. Two entries per camera is normal; the depth module is the one streaming the 16-bit range image.
• Decode with the parameter. distance = raw × depth unit, read at startup — never a hard-coded scale.
• Measure the invalid share. zeros ÷ total pixels on a static bench scene: a few percent is healthy, double digits at rated distance means light and exposure before hardware.
• Watch the quarantine. If devices vanish after a security-software update, restore the producer from its installer before re-installing anything.

More depth-integration reading sits on the 3D topic page, and the contact page is the fast route when you want a controller spec'd around a specific consumer.