Fix a null image result in a vision pipeline

A processing flow returns a clean score and then hands your image getter a null pointer. The instinct is to suspect the camera; in most integration cases the camera is fine, and the image was never exported for that execution or its buffer was reused before you read it. This guide walks the five causes in order of likelihood, gives a one-minute test for each, and shows the stride and timing arithmetic that separates a software fault from an acquisition fault. You finish with a 20-run bench proof, a log format, and a checklist that keeps the fault from coming back.

Classify the null before you change anything

Four different faults all present as a null image, and each needs a different fix. Log the result container's state before you dereference anything, then match what you see to a row.

A non-null wrapper can still carry zero pixels, so the pointer alone is not evidence of an image. When the pixels are valid and only the window is black, the fault is in the display — the blank image window troubleshooting guide covers that path, and no display setting can repair a missing result object.

Cause 1: the execution had not finished

A readable score says the measurement branch completed. It says nothing about the image branch: the two outputs can sit on different paths with different timing. Work one execution at a time:

1. Submit one known input frame and record the execution identifier you get back.
2. Wait for the completion event — the synchronous call's return or the result callback — never a fixed sleep.
3. Read the overall execution status and the status of the module that produces the image.
4. Retrieve the scalar and the image from that same execution's result scope.

Set the wait to about ten times the single-frame processing time you measured on the bench: a flow that returns in 60 ms gets a 600 ms timeout, which absorbs load spikes without hanging the station. A fixed sleep gives you none of that margin. A 100 ms delay passes while one execution takes 60 ms on an idle PC and fails the day a loaded CPU pushes the same execution past 100 ms.

Check the branch conditions as well. A measurement branch can finish while an optional annotation branch is skipped, and a proper log says so plainly:

exec=42 status=done score=0.98 module=annotate skipped=1 img=null

That line is a configuration fault, not an acquisition fault.

Cause 2: the image was never exported

An image you can see in the flow editor is not an output until the configuration exports it. Editor previews, internal module images and public results are three different interfaces. Audit the export contract against six questions:

• Is the output exported at the scope your application reads — flow scope, not module scope?
• Is its type an image, not a filename, a byte array or a display object?
• Does the mapping point at the source, intermediate or annotated image you intend?
• Does the producing module run on the branch you are testing?
• Is the configuration the application loaded the one you saved?
• Does the getter receive the exact identifier, case included?

Then run the controlled test: export the raw source image under a simple name such as img_test and retrieve it. When that works, move the mapping one module downstream and repeat until retrieval fails again. The failure marks the exact module that breaks the export.

Re-read the names after every recipe load: application code keeps the old identifier while the new recipe maps that name to something else.

Cause 3: the returned object is not a raster

An encoded file, an editor display object and a pixel buffer are three different things, and a loose mapping hands you the wrong one. Query the runtime type before any cast, then take the size fields from the frame itself: under GigE Vision the frame leader carries the pixel format, width, height and X padding, so the stride arrives in the stream rather than in your head.

The pixel format fixes the bytes per pixel. The GenICam PFNC convention defines Mono8 at 8 bits per pixel and RGB8 at 24 bits per pixel, which makes the layout arithmetic:

where width and padding_x come from the frame metadata and bytes_per_pixel from the format definition.

where height is the frame's row count.

Work the numbers for a 1280 x 1024 Mono8 frame: stride = 1280 x 1 + 0 = 1280 bytes, and the buffer holds 1280 x 1024 = 1,310,720 bytes, or 1.25 MiB. Align each row to 64 bytes and padding_x rises to 64: stride 1344 bytes, total 1,376,256 bytes. The same frame in RGB8 carries 24 bits per pixel, so the stride is 1280 x 3 = 3840 bytes and the buffer holds 3,932,160 bytes, or 3.75 MiB.

Two adjacent faults live here. An encoded payload is not a raster until it is decoded — the image bytes and pixel data guide separates the two. And a converted image can keep its destination layout rather than the source one, so check the converted object's pixel format before processing. For anything beyond a single plane, size the destination with the multi-channel image buffer sizing guide.

Cause 4: the buffer was reused before you read it

Acquisition rings recycle buffers, and the clock starts the moment you retrieve. At 30 fps the next frame wants its memory back in 33 ms; at 60 fps, 17 ms. The bench camera in this guide runs at 9 fps, which buys 111 ms (1000 / 9) — comfortable for a single-trigger test, and a trap the moment you restore production rates.

The signature is an image that reads correctly right after retrieval and turns to garbage or throws one frame later. Copy before anything else runs: stride x height bytes, which is 1,310,720 bytes for the 1280 x 1024 Mono8 case above and about 0.13 ms of work on a 10 GB/s memory bus. Copy the metadata — pixel format, stride, timestamp — with the pixels; a shallow assignment copies only the address.

The same lifetime rules apply at the acquisition boundary: the camera frame memory lifetime guide works through them for managed code. In a processing flow, repeat the analysis for every intermediate image and exported result.

Cause 5: the image belongs to another execution

A score from execution 42 paired with an image from execution 43 is an invalid inspection record, even though both objects are individually valid. Stamp an identifier at both ends. GigE Vision numbers every frame with a block ID that increments by one, so capture it when the frame arrives and attach it to every result you read back. Where the processing engine issues its own execution identifier, log the two side by side.

The block ID doubles as an acquisition check. A trace that jumps from 1042 to 1044 lost a frame before any processing ran, which points at the link, cable or trigger rather than at your output mapping; the frame corruption after a power cycle guide covers that family. For pairing results with frames under load, the asynchronous result and frame matching guide gives the timestamp discipline.

Prove the fix with 20 fixed-input runs

Return to one known input and one execution at a time. That removes camera timing and overlapping runs from the test and makes the log readable. Twenty runs is the smallest useful sample, and the sampling arithmetic says why:

where q is the per-run failure rate and n is the number of runs. With q = 0.1, twenty runs surface the fault at least once with p = 1 - 0.9^20, about 0.88; five runs manage about 0.41.

Log every run, passes included:

run 17: exec=61 img=valid Mono8 1280x1024 stride=1280 bytes=1310720

Then run the negative test. A configuration that intentionally produces no image must report an absent state distinct from a failed retrieval; downstream code that cannot tell the two apart raises acquisition alarms for configuration decisions.

Hardware for the reproduction bench

The bench camera needs one thing above all: a stream that carries the fields these tests read — pixel format, width, height, padding and block ID. For the fixed-frame work here, the LS-CMR-0053 is that camera: a 12 MP GigE model with a C-mount and a 9 fps rolling shutter.

For the acquisition side of the bench:

A 12 MP frame at Mono8 — 4000 x 3000 pixels — is 12,000,000 bytes of pixel data. A 1 Gbit/s GigE link moves about 125 MB/s at its theoretical limit, so one frame needs 12,000,000 / 125,000,000, about 0.096 s, or 96 ms on the wire. At 9 fps there are 111 ms between frames, so single-trigger frames arrive whole; keep the trigger spacing above the transfer time as frame rates climb. For the wider choice, compare area scan cameras in the camera finder.

When the station has no PC, run the flow on a vision controller: a box with camera ports and onboard processing, so the pipeline and its image outputs stay on one machine beside the line. For that station:

Prevention checklist and the next step

Fold these into the integration acceptance test:

• Completion: retrieve outputs only after the completion event and a status read, with the wait set to ten times the measured single-frame time.
• Mapping: re-read the output definition after every recipe load; identifiers live in configuration, not in application code.
• Type: query the runtime type and the pixel format before any pixel access.
• Layout: compute with the stride the frame reports, never the width you expect.
• Ownership: copy stride x height bytes immediately after retrieval; release only what you allocated.
• Correlation: stamp the block ID or execution ID on every image and every scalar.
• Absence: treat an intentional skip as a state, not an error.

When the trace ends at the processing interface, take the minimal configuration and the run log to that vendor's support channel. When acquisition sizing is still open, size the station in the camera configurator or contact the applications team with your interface, frame size, frame rate and retention requirements.