MultiPart images on GigE: get all components in one frame

You enable Range, Reflectance and Scatter on your 3D line profile camera, trigger a frame, and the grab call returns a single 200-line height image. The camera is not broken and the trigger is not the problem. On a GigE Vision camera those components travel as separate parts inside one frame, and a receiver set up for single-part delivery shows you only the first one. This walkthrough is for integration engineers bringing 3D profile cameras and multi-component GigE streams into host software. It works through the causes in the order they appear in practice, sizes a 1 Gbit/s link for a three-part composite with the arithmetic shown, and clears the acquisition timeouts that follow a crashed session. You finish knowing which switch to set, which API generation to use and whether your link carries the payload.

The symptom, stated precisely

In the feature browser, one AOI (Region0) is enabled with one Scan 3d Extraction 0 configuration at 200 Height extractions, and the Component list carries Range, Reflectance and Scatter. Every trigger returns one 200-line picture. Adding regions or a second extraction changes nothing. Disabling two of the three components removes an image one component at a time, which says the data exists and delivery is the problem. Work the causes below in order; the first two explain nearly every case of this signature.

What a multi-part frame is

Multi-part is the GigE Vision 2.0 mechanism for delivering several images per frame as one composite. The stream opens with a multi-part leader, every part is followed by its own trailer, and each part is tagged with a source ID plus its width, height and pixel format. The receiver library reassembles everything into a single composite buffer that exposes the parts in order. A 3D profile camera uses it to ship the height map, the reflectance image and the scatter image from one capture, with one trigger. Other side components ride the same way; for one worked example of consuming a side component, see 3D camera confidence image values: decode bitflags and mask bad pixels.

Current laser profile sensors are built around exactly this delivery model; the card below is one example of the class.

Cause 1: multi-part delivery is off on the stream channel

The switch lives in the stream channel control category of the feature browser; one SDK's browser labels it Gev SCC Multi-Part Enable. It reads FALSE on an untouched setup, and FALSE means the camera never assembles a composite for you.

Test: read the switch, then set it to TRUE and start the stream. The proof: trigger one frame and read the part count from the received buffer — the Range, Reflectance and Scatter setup reports three parts per composite. While you are there, confirm the Component list and the extraction height match your layout.

Cause 2: the grab API predates multi-part

With the flag on, the host side becomes the gate. Some SDKs still expose a second-generation grab interface, written in one vendor's stack as IGrab2 with a per-frame wait call named G2Wait. That generation delivers a single image per frame no matter what the camera sends; multi-part support is one of the reasons acquisition SDKs introduced third-generation stacks. An older loop keeps only the first part, which is exactly the symptom.

Test: run your SDK's multi-part composite example. If it reports several parts per trigger while your code reports one, the API layer is the cause. Fix: move the grab loop to the newer interface. One wait returns the whole composite; iterate the parts and map each source ID to its component name once, at startup.

This is not the software-side pattern of capturing several images per shot; that mechanism is covered in Multi image capture per trigger: get an image set from one shot.

Worked example: three components at 4096 × 200 lines on a 1 Gbit/s link

Inputs: width 4096 px, a 4K line profile — the line length the line scan cameras category lists as 4K; height 200 lines, the Height setting of the opening case; three parts; 8 bits per pixel, one byte per part, assuming 8-bit components — a 16-bit Range part doubles that part's bytes; usable payload 110 MB/s on Gigabit Ethernet with jumbo frames, or about 100 MB/s at the default 1,500-byte MTU. The 110 MB/s figure is wire rate minus Ethernet, IP/UDP and GigE Vision packet overhead.

One part: 4096 × 200 × 1 B = 819,200 B. Composite: 819,200 × 3 = 2,457,600 B, about 2.46 MB. Transfer time: 2,457,600 ÷ 110,000,000 B/s = 22.3 ms. Ceiling: 110,000,000 ÷ 2,457,600 = 44.7, so about 44 composites per second.

Range-only comparison: 819,200 ÷ 110,000,000 B/s = 7.4 ms, about 134 frames per second.

Decision: up to about 44 triggers per second, the 1 Gbit/s link carries all three parts. At 60 triggers per second you need 60 × 2.46 MB = 147.5 MB/s, 34% over budget. Drop the Scatter component — two parts move 1,638,400 B, about 67 composites per second — or cut the extraction height to 130 lines, 4096 × 130 × 3 = 1,597,440 B, about 68 per second, or move to 2.5G or 10 GigE hardware. Whichever you pick, set the grab timeout above the worst-case transfer time: below 22.3 ms of wire time, a tight timeout starves the queue for reasons that look like a bug.

Translate your trigger rate into a line-rate budget with the calculator below.

The same discipline applies as when you set the line rate of a line scan camera: the rate you ask for and the wire have to agree, or the queue grows and latency with it. When the ceiling you measure lands far below the calculation, the data-stream settings are the usual suspects, as in 3D camera frame rate low on software trigger: mode and data streams.

Budget the host side too

Every camera stream shares the NIC, so a multi-camera cell divides the same arithmetic across ports; size the host before the cameras arrive.

Host-side cards for the common cell sizes:

Both sit in the frame grabbers category next to the accessories finder. When several GigE cameras share one NIC or one switch and frames still drop, the pattern is contention, and troubleshooting multi-camera GigE frame drops walks that failure directly. Short bursts above the steady rate are a different case: the camera's own buffer bridges them, as in Camera burst capture faster than link bandwidth: use the buffer.

Cause 3: buffers sized for one image, not three

A composite buffer is sized for its full layout, not for the first part. A pool allocated from a single 200-line image fails once three parts arrive, and the failure shows up as allocation errors, truncated parts or silent drops.

Test: ask the API for the composite buffer size instead of computing it from one image, and assert the part count on every received buffer. Fix: allocate the pool from the composite size and queue at least three composites — one filling, one waiting, one processing. The sizing habit is the same as in Check multi channel image buffer size before processing, and the wider mismatch family is described in GenICam buffer height mismatch: TDI camera in area mode.

At the worked numbers, ten queued composites of 2.46 MB occupy about 25 MB of host RAM, so queue generously.

Cause 4: timeouts after a crashed session

This failure follows a crash, not a first start. Quit the multi-part application while it streams, restart it, and every acquisition times out; the same setup recovers only after another tool grabs frames or the camera loses power. The behavior tracks the camera's internal handling of a lost host connection: the acquisition state stays latched after the abnormal exit, and a plain restart does not clear it.

Test: a clean power cycle fixes it, and the crash always reproduces it — that is latched state, not bandwidth. Fix: call the data stream's documented abort/reset before every start. In one SDK the data stream object exposes TryDeviceAbort(), placed immediately before dataStream->Start(); after an abnormal exit it resets the acquisition status and the next start succeeds. Put the call inside the restart path itself, so the launch after a crash opens a clean stream.

A restart that stops after one frame is the same latch in single-part systems: Hardware trigger stops after one frame: check acquisition mode. When the timeout does arrive, read what it says before retrying, as in Frame didn't arrive within timeout: one wait call per frame. And after any SDK or firmware change, rule out a mismatched driver first — Frame grabber driver mismatch after a vision software upgrade produces the same timeout signature from a different cause.

Checks before you enable multi-part in production

Run down this list once per camera and once per host build:

• Camera: the multi-part switch reads TRUE before every start; the Component list carries only the parts the algorithm uses; the extraction height matches the layout, 200 lines in the opening case.
• API: the grab loop runs on the multi-part-capable generation; every buffer reports its part count; each source ID maps to a component name before the first pixel is processed.
• Buffers: the pool is sized from the composite, at least three queued, and an allocation failure raises an error instead of truncating.
• Link: composite bytes times trigger rate sits below 110 MB/s with jumbo frames, or about 100 MB/s at the default MTU; the grab timeout exceeds the worst-case transfer time, 22.3 ms in the worked example.
• Restart: the data-stream abort/reset runs before every start, including the first start after a crash.

When the usual answer is wrong

• You only need height. Leave multi-part off. A single-part Range stream is the most compatible path and, at the worked numbers, runs about 134 frames per second where the composite manages 44.
• Reflectance exists only for setup tuning. Enable the components during bring-up, then drop back to Range-only and keep the bandwidth.
• Reflectance and Scatter feed the production algorithm. Keep them and spend the wire: the laser line quality that depends on those components is treated in Laser line extraction noise: get a clean height line.
• You are just over budget. Cut the extraction height before cutting a component the algorithm reads; the pixel data stays intact, only the payload shrinks.

The decision

One flag set to TRUE on the stream channel, one grab loop on the multi-part-capable API, one bandwidth number — 2.46 MB per composite, about 44 per second on Gigabit Ethernet at 4096 × 200 — and one abort call before every restart. Those four items turn the single 200-line picture into the three parts the camera has been sending all along.

If you are selecting hardware for this workflow, start in the 3D sensors category or the camera finder, size the host cell with the parts above, and the camera configurator walks the remaining steps. The systems topic page collects the acquisition-side guides that pair with this one.