Depth stream missing on Linux: diagnose absent frames

A working color preview does not prove that depth frames reach your application. Depth may travel through another interface, require another stream configuration, or arrive correctly but appear black in the viewer. This troubleshooting workflow is for Linux vision systems where color works but depth seems absent. You will separate acquisition failure from display failure, preserve useful evidence, and choose a documented recovery path without guessing at kernel patches or replacing hardware prematurely.

1. Find the first missing piece of evidence

Treat the pipeline as separate checkpoints: device enumeration, stream discovery, configuration, frame delivery, data interpretation, and display. Stop at the first checkpoint that fails. Changing display settings cannot repair a stream that never delivers a buffer.

A device node is not necessarily a complete camera, and a color endpoint is not evidence of a working depth endpoint. Use Linux camera device selection when applications appear to open different interfaces.

Also distinguish metric depth from infrared images, disparity, confidence maps, and colorized previews. These outputs are not interchangeable. Confirm the stream's documented meaning before treating its pixel values as distances.

2. Capture a baseline before changing the system

Record the operating system release, active kernel, processor architecture, camera firmware, SDK version, and application build. Include the connection topology and whether another camera application is running.

The following are read-only diagnostic examples. Some utilities may require installation from your operating system distribution's official repositories, and access to kernel logs may require authorized administrator privileges.

cat /etc/os-release
uname -r
uname -m
lsusb -t
journalctl -k -b --no-pager
v4l2-ctl --list-devices

For a camera interface exposed through the Linux video subsystem, inspect its advertised modes. This example uses a device path that you must replace with the interface identified during enumeration:

v4l2-ctl --device=/dev/video0 --list-formats-ext

Not every depth camera exposes its measurement stream through that subsystem. Some use a manufacturer SDK or another documented transport. An empty video-device listing therefore does not, by itself, prove that depth acquisition is unsupported.

Save the relevant log interval around connection and stream startup. Look for rejected formats, failed interface claims, endpoint errors, and repeated disconnects. A format warning matters most when it identifies the interface used for depth.

For that specific branch, use unknown pixel-format diagnosis and Linux depth pixel-format support checks. The next sections determine whether acquisition actually failed or the viewer merely concealed valid data.

3. Run a minimal depth-only acquisition test

Remove processing stages before drawing conclusions about the driver. Disable inference, recording compression, point-cloud generation, and visualization where the supported application permits it. Close other applications that might hold the device.

Use the manufacturer's diagnostic application first, with a depth mode explicitly supported by that camera and software release. Then repeat the same configuration in your application.

1. Select depth explicitly rather than relying on the first enumerated stream.
2. Log the requested mode and the mode actually accepted by the acquisition API.
3. Count depth callbacks or dequeued depth buffers before filtering or display.
4. Record frame identifiers, timestamps, buffer sizes, and reported completion status.
5. Save several original depth buffers together with their metadata.
6. Repeat with visualization disabled, then enabled, without changing acquisition settings.

As an illustrative test, request 10 frames per second for 5 seconds. The nominal count is 10 × 5 = 50 frames. Startup delay, device scheduling, and application behavior can reduce the observed count, so investigate the timestamps rather than treating that nominal count as a guaranteed acceptance limit.

A zero count before any processing supports an acquisition problem. A rising count with a black window points toward interpretation or display, but the buffers still need validation. Repeated timestamps, incomplete buffers, or constant invalid values are not proof of usable depth.

If frames arrive initially and then stop, follow stereo pipeline queue-stall diagnosis. A blocked consumer can resemble a failed camera even when acquisition started correctly.

4. Validate saved data before adjusting the viewer

Save the original buffer, not just a screenshot or a colorized export. Store width, height, pixel format, row stride, byte order, depth scale, timestamp, and documented invalid-value definitions alongside it.

For an uncompressed, single-plane example with no additional framing, the expected payload follows:

Suppose the accepted output is a hypothetical unsigned depth image with 640 columns, 480 rows, and 2 bytes per pixel. With no row padding:

• Minimum row size: 640 × 2 = 1,280 bytes.
• Frame payload: 1,280 × 480 = 614,400 bytes.
• At 30 frames per second: 614,400 × 30 = 18,432,000 bytes per second.

That last value is approximately 18.4 MB/s using decimal units. It excludes metadata, transport overhead, and other streams. Compressed, packed, or multi-plane formats require their own documented size calculation.

A matching byte count is necessary for this example, but it does not prove correct content. Check the numeric type, signedness, byte order, and stride against the acquisition API. Consult image type and pixel-format mismatch diagnosis if rows repeat, images appear doubled, or dimensions seem inconsistent.

Next, count valid samples using the format's documented rules. Do not assume that zero is the only invalid marker. Inspect the valid-value range and compare it with a stationary target inside the camera's documented operating region.

If the format defines a scale of 0.001 metres per count, a stored value of 1,500 represents 1,500 × 0.001 = 1.5 metres. This is an example conversion, not a universal depth scale.

5. Test the display with an explicit mapping

A viewer may interpret a measurement buffer as ordinary brightness data. Valid depth can then look nearly black, saturated, or oddly patterned. Correct visualization requires an intentional mapping, not a change to the saved measurements.

For a hypothetical valid depth range from 1,000 to 3,000 counts, a simple grayscale mapping is:

A valid sample of 2,000 counts becomes 255 × 1,000 / 2,000 = 127.5, or approximately 128 after rounding. Mask invalid samples before applying the mapping. Keep the original depth buffer unchanged for measurement and later analysis.

Use a fixed display range during diagnosis. Automatic scaling can make the same physical scene look different between frames, obscuring the comparison.

Move a suitable target between two documented working positions. Confirm that valid depth values change consistently with the movement. A changing color preview alone proves nothing about the depth data.

If valid buffers render correctly offline but fail in the live application, investigate its display conversion, buffer ownership, and thread synchronization before changing the operating system.

6. Work through causes in a controlled order

Check configuration and application behavior before invasive driver changes. The table below is a practical test order, not a universal ranking of failure rates.

For depth-only negotiation failures, continue with depth camera connection diagnosis. If the device disappears or repeatedly reconnects, use startup disconnect diagnosis.

Only pursue bandwidth or power changes when the evidence supports them. The depth camera bandwidth and power checks explain that branch. A normal-looking connection tree does not replace a successful acquisition test.

Change one variable per test and keep the same scene. Otherwise, a different target or processing setting can hide the effect of the change you intended to evaluate.

7. Recover through documented software installation

Do not apply an old driver patch merely because another system once needed it. Driver requirements depend on the camera, kernel, distribution, firmware, and SDK combination.

Before changing a production station, stop acquisition and place the machine in its approved maintenance state. Preserve configuration files, calibration data, package versions, and a documented rollback route.

1. Find the camera manufacturer's supported operating system, kernel, firmware, and SDK combination.
2. Obtain the complete release package from the manufacturer or an authorized distributor.
3. Follow its documented installation method, including prerequisites and required working directory.
4. Capture the complete installation output and resolve errors before treating the installation as successful.
5. Disconnect devices, reload components, or reboot only as the documentation directs.
6. Recheck the active kernel and driver, then repeat the minimal acquisition test.

A missing-file error makes installation status uncertain; earlier steps may already have changed the system. Check whether the package is complete and whether the documented command was launched from the required directory. Relative paths depend on that directory.

Do not fetch an isolated patch from an unrelated mirror or combine files from different releases. Avoid manually replacing kernel modules or disabling security controls as a generic troubleshooting shortcut.

An installer success message also does not prove that the running driver changed. Verify the active environment after the prescribed restart. If the required combination is unavailable, ask the manufacturer for a supported migration or recovery route rather than maintaining an undocumented patch chain.

8. Check compatibility before replacing hardware

Replacing the camera is appropriate only after identifying a support gap, hardware fault, or application requirement that the existing device cannot meet. A display conversion error will usually follow the application to its replacement.

The 3D sensors category covers different measurement approaches. By contrast, area scan cameras may provide the color or monochrome images used elsewhere in a system; an ordinary image stream is not automatically metric depth.

The MV-DPS200P-02 is listed as a projected structured-light camera. Its listing identifies a measurement approach, not proof of compatibility with your Linux installation.

The MV-DT01WMU is listed as a ToF sensing camera. Confirm its supported software environment and output definitions before selecting it for an existing application.

Use the camera finder to narrow hardware candidates after defining the required measurement task. Before ordering, request confirmation of processor architecture, operating system support, SDK availability, output format, depth units, trigger behavior, and supported simultaneous streams.

9. Verify the repair and preserve the evidence

Repeat the original failing test before restoring the complete application. Then add visualization, processing, recording, and additional streams one at a time.

Use this acceptance checklist:

• Depth is selected explicitly, and accepted settings match the intended configuration.
• Frame counts increase without unexplained stalls or repeated timestamps.
• Buffer sizes and row layout match the documented format.
• Valid samples exist on a suitable target in the operating region.
• Original buffers reproduce the expected image through a documented display mapping.
• A stop-and-start cycle and a planned system restart reproduce the working configuration.
• Kernel logs show no recurring acquisition errors associated with the test.
• The complete application meets its agreed frame-loss and latency limits.

Keep a known-good configuration record and a small reference capture. Future changes to kernels, SDKs, firmware, or application dependencies should trigger the same acceptance checks.

If the cause remains unclear, send the environment record, accepted stream settings, startup logs, and a non-sensitive sample capture through technical support. For a replacement or new station, start with the camera configurator once the software requirements are written down.