Camera preview freezes after first frame: channel checks

A preview that stops updating does not necessarily mean the camera stopped sending images. A conditional annotation can change a monochrome array into a color image, breaking the viewer’s established input format. This troubleshooting procedure is for engineers adding detection results, markers or status graphics to live images. You will separate acquisition from display failures, identify changing frame properties and establish a consistent display format without altering the inspection image.

Confirm that acquisition continues

First determine which part of the pipeline stopped. An increasing loop counter proves that code is executing, not that new images are arriving or reaching the display.

Record separate counters for completed acquisitions, processed images and successful display submissions. Where the acquisition interface provides them, also record frame identifiers and timestamps. Check that identifiers advance and that image content changes when the scene changes.

Temporarily send unannotated images directly to the viewer. Disable detection, tracking and drawing, but retain the same acquisition settings. If this preview remains active, reintroduce processing stages individually.

A viewer error about changed input dimensions is strong evidence of an input-contract problem. Investigate that before changing camera bandwidth, trigger timing or transport settings. If images actually stop arriving, follow the separate procedure for camera acquisition stalls under load.

Check the most likely format changes

Many fixed-format viewers establish their accepted input properties when they receive the first image. Those properties can include height, width, channel count and element type.

A monochrome image commonly uses a two-dimensional array. A drawing operation may return a three-channel image so that colored graphics can be represented. If drawing runs only when detection succeeds, the viewer can receive different array shapes on different iterations.

The following causes are ordered for a preview that fails when annotations first appear or disappear.

A window’s position and visible dimensions do not define the underlying image-array format. Making the window larger cannot repair an unexpected channel count.

The related guide to camera preview overlays for debugging motion tracking addresses what to draw. Here, the priority is keeping the viewer input unchanged regardless of whether anything is drawn.

Log the exact image submitted to the viewer

Logging only the camera output misses changes introduced during processing. Capture diagnostic properties at acquisition, after display conversion, after annotation and immediately before viewer submission.

Include these fields:

• Frame identifier and acquisition timestamp, where available.
• Processing branch, such as detection absent, detection present or tracking lost.
• Image height, width and logical channel count.
• Element type and the number of array dimensions.
• Submission result or complete viewer error text.

For a two-dimensional grayscale array, report a logical channel count of one. Also retain the actual array shape so that a singleton channel dimension does not conceal a representation change.

Use language-neutral instrumentation such as:

raw = acquire_image()
log_properties("acquired", raw, frame_id)

display = prepare_display(raw)
log_properties("prepared", display, frame_id)

if annotation_available:
    display = draw_annotations(display, annotation)

log_properties("viewer_input", display, frame_id)
assert_matches_display_contract(display)
submit_to_viewer(display)

In a hypothetical failure, the first viewer input might have shape (1024, 1280) and type uint8. The next could have shape (1024, 1280, 3) with the same type. Width and height are unchanged, but the complete input shape is different.

Also check failure transitions in the opposite direction. A preview may initialize successfully with annotated color output, then fail when a later no-detection branch returns unmodified grayscale.

Normalize a separate display buffer

Keep the acquisition image separate from the presentation image. Detection, measurement and storage should use the intended source data, not an image modified for visualization.

For colored annotations over monochrome imagery, a practical display contract is a fixed-height, fixed-width, three-channel image with an explicitly selected element type. A grayscale-only display is also valid if every drawing operation preserves it.

Apply the following sequence on every iteration:

1. Acquire the source image. Preserve its original values and metadata for inspection processing.
2. Create an independent display buffer. Avoid modifying a shared acquisition buffer that another stage still uses.
3. Normalize channels unconditionally. For a grayscale source and a color display contract, copy the intensity values into each color channel, even when nothing was detected.
4. Apply a defined intensity mapping. If source and display types differ, use an explicit scale and clipping policy rather than an unexplained cast.
5. Draw optional annotations. Check the drawing function’s documented output type and channel layout.
6. Validate the final buffer. Assert dimensions, channels and element type immediately before submission.

Replicating grayscale values across color channels creates a neutral display image; it does not recover color information. Likewise, raw color-mosaic data requires its documented conversion rather than simple channel replication.

Do not rescale every frame independently unless that behavior is intentional. Per-frame contrast stretching can make a changing process appear visually stable, or make stable measurements look unstable.

Work through the buffer-size example

Channel promotion changes memory requirements even when the viewer accepts the result. Estimate the payload of an uncompressed image buffer using:

Consider a hypothetical application producing images measuring 1280 × 1024 pixels, using unsigned 8-bit elements, at 30 frames/s. Each element occupies one byte.

The grayscale buffer contains:

1280 × 1024 × 1 × 1 = 1,310,720 bytes = 1.25 MiB

The three-channel display buffer contains:

1280 × 1024 × 3 × 1 = 3,932,160 bytes = 3.75 MiB

At the example frame rate, the respective buffer payload rates are:

• Grayscale: 1.25 × 30 = 37.5 MiB/s.
• Three-channel display: 3.75 × 30 = 112.5 MiB/s.

These are buffer payload estimates, not measured memory bandwidth or camera-link traffic. Copies, drawing operations, transfers and queued images add work. Converting an image after acquisition does not itself increase the camera’s transmitted payload.

This distinction helps separate two failures. A format rejection can stop updates immediately at a branch transition. Excessive conversion or copying more often produces growing latency, reduced update frequency or queue accumulation. Diagnose those separately using callbacks and buffer queues in multi-camera acquisition.

Reinitialize only for deliberate format changes

Changing the camera region of interest, display resolution or channel layout may legitimately require viewer reconfiguration. Treat that as a controlled transition rather than an incidental consequence of detection results.

Stop submissions to the old viewer configuration. Drain or discard queued display images according to the application’s latency requirements. Then use the viewer’s documented release, reset or recreation procedure, establish the new input contract and resume submissions.

Keep old-format frames from reaching the newly configured viewer. Tagging display configurations with a generation identifier can help reject stale queued buffers.

Do not release and recreate the viewer on every frame. That can conceal inconsistent inputs while adding initialization overhead, flicker and resource-management problems. A fixed-format pipeline should normally initialize once and run until an intentional configuration change.

If the application genuinely needs variable-sized images, consider a viewer documented to support them or place each image inside a fixed-size display canvas.

Test the remaining display-path causes

If the final input properties remain constant, continue with targeted checks rather than replacing the camera.

• UI scheduling: Confirm that the application services its display event loop. A long processing task can prevent repainting even when submissions continue.
• Buffer ownership: Check whether the viewer copies input data or retains a reference. Do not overwrite or return a buffer to its pool before the documented consumption point.
• Queue growth: Compare acquisition timestamps with display time. Bound the preview queue and define whether stale preview frames may be dropped.
• Hidden exceptions: Record errors inside callbacks and worker threads. A failed display worker may leave acquisition running normally.
• Pixel interpretation: Confirm the documented channel order, supported element types and memory-layout requirements.

For a live operator preview, displaying the newest available image may be preferable to replaying an old backlog. Keep that policy separate from inspection processing, where dropping an image could lose a required decision.

Match hardware only after software checks

A consistent display contract applies across area scan cameras and vision controllers. Changing interfaces or adding processing capacity does not correct a conditional channel-count change.

For a new acquisition system, compare interface requirements through the camera finder. The LS-CMR-0053 is a GigE option to evaluate against the acquisition requirements.

The LS-CMR-0166 is a USB3 option to evaluate against the acquisition requirements.

Neither listing establishes compatibility with a particular viewer or drawing library. Before ordering, verify the supported operating environment, acquisition interface, returned pixel formats and intended preview conversion. Select processing hardware using measured workload and the complete inspection task, not preview appearance alone.

Verify the fix across every branch

A successful first image is not sufficient. Exercise transitions that previously changed the presentation path:

• Start with no detection, then introduce a detectable target.
• Start with a detection, then remove the target.
• Trigger tracking loss and recovery repeatedly.
• Enable and disable every annotation layer.
• Confirm that dimensions, channels and element type remain constant before each submission.
• Confirm that source-image data remains unchanged by drawing.
• Test intentional format changes through the documented reconfiguration sequence.
• Run long enough to detect accumulating display latency or retained buffers.

Keep the format assertion available in diagnostic builds. It turns a vague frozen-preview report into a specific mismatch at the failing stage.

If the application also needs new acquisition hardware, start with the camera configurator. For help reviewing the display contract and acquisition requirements together, send the frame-property log and processing sequence through application support.