Black RGB stream from a depth camera: isolate hardware or software

A depth camera that streams usable depth and an all-black RGB frame is a fault you can prove at the bench in about half an hour. You need two tools: your SDK's capture utility and the camera app built into your operating system. Depth and RGB are separate silicon with separate data pipes, so one working proves nothing about the other. This guide gives the isolation order that settles hardware versus software: physical checks, one stream at a time, a histogram test that separates a dark scene from empty data, a generic camera app that bypasses the depth SDK, and the driver fix for the most common software cause. It ends with the evidence to record when the sensor is dead and the unit goes back.

Why is the RGB stream black while depth still works?

Because the two streams come from separate silicon: the depth path pairs an infrared projector with an infrared sensor and computes range from that pair, while RGB is its own color sensor with its own data pipe. A healthy depth frame tells you nothing about the color side.

A depth camera therefore enumerates as several video devices — depth, infrared and RGB — and any one of them can fail alone. A protocol or firmware problem usually breaks every stream or none, so one dead stream beside healthy ones points at that stream's sensor or its driver. That is what makes the isolation order below decisive. Rule out the one look-alike first: a gray, grainy frame on the color stream is usually the infrared stream selected by mistake, and Depth camera RGB shows black and white: you are on the IR stream covers it. A frame that is truly all black is a different failure, and the rest of this guide decides it.

What should you check on the camera before opening any software?

Check the color lens itself first: remove the protective cap or film, look for tape, glue or moisture across it, confirm the cable is fully seated at both ends, and note whether the camera is a new unit that never streamed or one that worked before.

The cap decides more than it sounds like. On a new unit that has never produced an image, a cap or film left over the color lens is the most common cause and costs nothing to rule out. On a unit that worked and then stopped, ask what changed; an operating system update in the install log points straight at the driver fix later in this guide. Swap the cable and try a different USB port or host before blaming the camera, because a marginal link drops single streams at random. A camera that is not detected at all is a separate fault — One 3D camera not detected while others work: isolate it covers that path.

How do you isolate the RGB stream from depth and infrared?

Capture one stream at a time: enable depth only in your SDK's capture tool and grab a frame, then infrared only, then RGB only. Record each frame's minimum, maximum, mean and histogram, because a combined preview hides which pipe is delivering nothing.

1. Depth only. Point at a scene you know, capture 10 frames, and check the histogram spans the scene range with no spike at 0.
2. Infrared only. Capture 10 frames; with the projector running you should see speckle texture and a spread histogram.
3. RGB only. Capture 10 frames and write down the minimum, maximum, mean and histogram of each. Save the raw frames — they are the evidence a return will need.

Valid depth and infrared frames beside an RGB stream whose statistics sit at 0 isolate the fault to the RGB pipe: sensor, driver or SDK path. The same one-stream-at-a-time discipline that finds frame-rate collisions on multi-camera rigs localizes this one; Three depth cameras drop to low FPS: test one stream at a time shows the method on a bigger bench.

Is the RGB frame dark, or is it empty data?

Read the histogram instead of judging the preview: a 1920 × 1080 RGB frame holds 2,073,600 pixels, and a working color sensor carries a black-level offset around 16-64 DN even with the lens capped. Every pixel sitting at exactly 0 is empty data, not a dark scene.

The arithmetic carries two conclusions. First, a full-rate zero stream needs only 186.6 MB/s, which fits a USB 3 link with roughly 350-400 MB/s usable, so the pipe is delivering zeros at full speed rather than choking; bandwidth is not the cause. Second, the probability: even granting one pixel a generous 1% chance of reading 0, all 2,073,600 reading 0 works out to 10^-4,147,200 — zero for engineering purposes. A real dark frame scatters a few DN around the black level. So a histogram that is a single spike at exactly 0 under sane exposure settings means no image data ever arrived.

A histogram at 20-40 DN with visible noise is the other case: a real but nearly unlit image, which is an exposure fault, not a dead sensor. Read the applied exposure time from the frame metadata and correct it — Read exposure time from frame metadata under auto exposure shows how.

How do you test the RGB sensor outside the depth SDK?

Open the RGB device with a generic capture app — the built-in Camera app on Windows, or any V4L2 viewer your Linux distribution ships. That app streams the sensor through the operating system's own stack, and what it shows is what decides hardware versus software.

Close the depth SDK first: most depth stacks hold the device exclusively, and a viewer left open in the background makes the test lie. That is the same one-client rule behind Camera works in vendor tool but not in ROS: one client at a time. Then step through the video devices the camera exposes — depth, infrared and RGB appear as separate device nodes — aiming each at a lit, textured wall.

The verdict holds because the generic app shares nothing with the depth SDK: no vendor pipeline, no SDK settings and no processing in between. What it shows is the sensor.

Which software faults let the sensor pass the generic test?

The most common is a driver swap: a Windows update can auto-install a generic USB video driver over the depth camera vendor's driver. Depth keeps running through its own interface while the color stream returns nothing, which is the exact failure our Windows update guide walks through.

Fix it in this order. Reinstall the manufacturer's driver package from its own support site, following the vendor's install steps, and if the operating system keeps swapping the driver back, pause automatic driver updates for the duration of set-up. Next, request an RGB profile the SDK actually lists: a pixel format or resolution the camera does not support yields a stream that never fills, sometimes with no error at all. Keep one application on the device at a time. Depth camera RGB and virtual drivers missing after Windows update walks the driver replacement end to end.

What do you record before you return the camera?

When the generic app also returns black, the color sensor is proven dead at the hardware level. Record the serial number, firmware version, SDK version, operating system and the saved single-stream frames, then return the unit for replacement — within the 90-day return window for orders from us.

The record that gets a replacement accepted without argument:

• Serial number, as printed by the SDK's device enumeration. A unit whose serial reads all FF or all 0 has a deeper board fault — Depth camera shows an all-FF serial number: hardware, not settings.
• Firmware version and SDK version, from the same enumeration output.
• Operating system and build, plus the driver version currently bound to the RGB device.
• The saved depth, infrared and RGB frames from the single-stream captures.

When the verdict is replacement, start from the 3D sensors category or write to us through the contact page with the record above. For bench and inspection cells, these are the units we carry:

For volume measurement and logistics stations, the shop also carries dedicated logistics 3D cameras built around speckle structured light; the 3D sensors category filters them by type.

How do you stop a black RGB stream on the next install?

Install the manufacturer's driver before the camera's first connection and run a three-stream test on every camera at receipt. Five minutes per unit catches a left-on cap, a swapped driver and a dead color sensor before the camera is mounted in a cell.

• Before first connect. Install the vendor SDK and driver package from the manufacturer, and pause automatic driver updates during set-up. The generic-driver swap strikes at the first connection.
• At receipt. Remove every cap and film, capture depth, infrared and RGB one stream at a time, and check the RGB histogram is not a single spike at 0. To make it one step, capture the 2D and 3D images together; Capturing 2D and 3D images together from one scene shows the pattern.
• After any operating system update. Rerun the RGB capture and confirm the vendor driver is still bound. Updates can quietly redo the swap months after commissioning.

That is the whole decision path: cap, then per-stream captures, then the histogram, then the generic app, then the driver. If it ends at a replacement, the 3D camera finder filters by type and series, the configurator builds the rest of the station around the camera, and the 3D topic page collects the other depth-camera fixes.