3D visionTroubleshooting

Flickering depth image, no infrared stream: check the pixel formats

Depth image flickers or tears while the infrared stream never appears? Check Y8I, Y12I and Z16 support in your kernel headers, then rebuild uvcvideo.

LumaSpec Vision12 min read Share on LinkedIn

On this page 9 sections
  1. 01Why does the depth image flicker while the infrared stream stays blank?
  2. 02Which checks prove the driver is the cause before you rebuild?
  3. 03Why did the patch script fail with a hunk error in videodev2.h?
  4. 04How do you tell which uvcvideo module is loaded and what it was built for?
  5. 05How do you rebuild uvcvideo against the matching kernel source?
  6. 06What test proves the fix worked?
  7. 07When is flickering depth not a driver problem at all?
  8. 08How do you keep the fix in place across kernel updates?
  9. 09Questions

The depth image tears and shimmers, the infrared preview stays black, and yet dmesg shows the camera enumerating without complaint. That combination looks like a dead sensor and almost never is one. It is the signature of a uvcvideo driver that cannot decode the camera's interleaved pixel formats — depth as Z16, infrared as Y8I or Y12I — typically after a patch script stopped on a hunk failure or a module built for a different kernel release is still loaded. The sections below give the ordered diagnosis: checks that separate a driver fault from a USB fault, the grep that shows which fourcc codes your headers already define, a rebuild that matches the running kernel, and the soak test that proves the fix before the camera goes back on the line.

Why does the depth image flicker while the infrared stream stays blank?

Because the loaded uvcvideo driver enumerates the camera but cannot decode its interleaved formats: depth arrives as Z16, infrared as Y8I or Y12I, and a driver lacking those entries parses the payload with the wrong stride and bit depth, so depth shears while infrared is never negotiated.

Both heads share one USB link and one driver format table. When the table knows the formats, the depth node delivers Z16 — 16-bit depth values per pixel — and the infrared nodes deliver Y8I, two 8-bit left/right images interleaved, or Y12I, two 12-bit sources bit-packed into one stream. When it does not, the driver either offers the node only generic formats the camera will not honour, or accepts the stream and reads it with the wrong layout. Wrong-layout depth looks like flicker and horizontal shear; a stream the driver never offers looks like a missing device to the application, which is why capture tests abort instead of showing a black window.

The pairing is the tell. Depth flickering and infrared absent at the same time points at the driver first. Clean depth with only infrared missing points at the application never requesting the second head, or the emitter disabled. And if the flicker shows up only in a viewer such as rviz while raw capture looks fine, follow Depth image flickering in rviz: fix the driver first, which starts one step later in the same chain.

Which checks prove the driver is the cause before you rebuild?

Run three checks in order: dmesg should show the driver register without errors, every /dev/video node should list the formats it advertises, and a capture test should fail with a named error rather than a hang.

First, dmesg | grep -i uvc right after plugging the camera in. A clean enumeration prints lines such as usbcore: registered new interface driver uvcvideo and a driver version string. If those lines appear, the USB side is fine and the fault lives in the format handling above them.

Second, list what each node offers. A depth camera exposes several /dev/video nodes — depth, one or two infrared, RGB — and each advertises its own format list. Ask every node with v4l2-ctl. On a driver that handles the camera, the depth node lists Z16 and the infrared nodes list Y8I and Y12I; on a stock driver the same nodes offer only generic formats such as YUYV or MJPG, or the depth node offers nothing usable. That short list is the decisive observation: Unknown pixel format: diagnose missing depth streams shows how to read it, and Depth camera pixel format rejected: kernel support on Linux covers a format the driver refuses outright.

Third, run the capture test that ships with the camera SDK and read its error. An abort reading VIDIOC_DQBUF error 19, No such device reports ENODEV — the driver tore the stream down while the application waited for a frame. That message at start-up plus a short format list closes the case. If instead no stream ever appears, start at Depth stream missing on Linux: find where frames stop.

Why did the patch script fail with a hunk error in videodev2.h?

The script's first hunk tries to add the V4L2_PIX_FMT_Y8I, V4L2_PIX_FMT_Y12I and V4L2_PIX_FMT_Z16 definitions to include/uapi/linux/videodev2.h, and on 4.4.0-34 and 4.4.0-36 headers those three #define lines already exist, so the hunk fails, the script stops, and the driver code behind the formats is never built.

Confirm it in one command:

grep -E "V4L2_PIX_FMT_(Y8I|Y12I|Z16)" /usr/src/linux-headers-$(uname -r)/include/uapi/linux/videodev2.h

If three #define lines print, the header side is already complete and the failure says nothing about your kernel's capability — only that the script's expectations no longer match the tree. Re-running the script reproduces the same .rej file byte for byte, because nothing on disk changed.

The reassuring dmesg lines after a failed run — the video capture interface banner and the uvcvideo registration — only confirm the stock module loaded. The patch never reached the format table inside the driver, which is why the symptoms persist on a camera that registered fine.

Stop re-running; change tactics. Apply the driver-source hunks by hand: skip a rejected hunk that only re-adds existing #define lines — the .rej file tells you which — and apply the hunks that touch the driver's format table, using the patch file itself as the map of what changes. UVC patch kernel mismatch: match the source tree covers trees that do not line up with the running release, Kernel patch can't find file to patch: check the source tree covers a script pointed at the wrong tree, and UVC video patch stops silently: fix duplicate kernel headers covers runs that exit cleanly while doing nothing.

How do you tell which uvcvideo module is loaded and what it was built for?

modinfo uvcvideo prints the filename of the loaded module and its version: a path under /lib/modules/$(uname -r)/kernel/drivers/media/usb/uvc/ is the stock in-tree driver, a path under updates/ or a DKMS-managed name is a patched build.

Note the version and compare it with the driver string dmesg printed at load — they should agree. Then match the release. The release directory in that path must equal uname -r; if modinfo names an older or newer release, you are loading a module built for a different kernel — classic after an upgrade that left an old updates/ directory in place. Check the build inputs too: ls /usr/src/ should show linux-headers-$(uname -r), because nothing you compile can target the running kernel without them.

dkms status adds the last piece: it lists each registered module with the kernel releases it was built against. An entry for the old release and none for the current one means the patched module you remember no longer exists for this kernel. When the build tree and the kernel disagree, the failure shows up either at load time or during the build itself — the cp cannot stat videobuf2-common.ko: match the kernel build tree case.

How do you rebuild uvcvideo against the matching kernel source?

A rebuild only works when the source tree, the patch and the running kernel match: build against /usr/src/linux-headers-$(uname -r), apply only the hunks the headers still need, install the resulting uvcvideo.ko for exactly that release, then reload the module and read the new version line in dmesg.

  1. Match the headers. Confirm uname -r and that /usr/src/linux-headers-$(uname -r) exists. Install the matching headers package if it does not — every later step inherits a mismatch made here.
  2. Source the tree for that release. Use the distribution's source package for the running kernel or the SDK tree prepared for it. A tree for a different release builds a module with unresolved symbols.
  3. Apply the patch by hand where needed. Skip any hunk that only re-adds #define lines already present — the .rej file is your record of what was skipped — and apply the format-table hunks to the driver source files.
  4. Build and install. Compile the module, place uvcvideo.ko under /lib/modules/$(uname -r)/updates/, and run depmod -a so the module database picks it up.
  5. Reload and read. Run sudo modprobe -r uvcvideo && sudo modprobe uvcvideo, then dmesg | tail: the driver line should now carry the new version. If the version string did not change, the loader is still finding the old file.
  6. Register with DKMS. A registered build rebuilds itself at every kernel upgrade. If the DKMS run targets the wrong kernel, DKMS uvcvideo patch fails on the wrong kernel: clean and rebuild is the cleanup recipe.

What test proves the fix worked?

The pass criteria are concrete: the format list shows Z16 on the depth node and Y8I and Y12I on the infrared nodes, a capture runs 1,000 frames or 10 minutes without VIDIOC_DQBUF error 19, and the depth image holds still on a static scene.

Put a textured object on a plain background, start capture, and watch three things: the depth values on the object stay steady frame to frame, no VIDIOC_DQBUF error 19 appears in the log, and the two infrared images frame the scene identically — they are a stereo pair, and a mismatch between them shows up as doubled edges in depth. A soak that passes on the bench passes on the line.

A run that still flickers with correct formats and a matched module has moved to a different fault — bandwidth, power or motion — taken up in the next section. Frames that arrive but drift against the RGB clock while running are yet another fault, described in Depth color timestamp drift that grows while running.

When is flickering depth not a driver problem at all?

If the format list already shows Z16, Y8I and Y12I and the module matches the kernel, work down this list instead: USB bandwidth or power first, camera motion second, firmware mismatch last.

Bandwidth and power. Both heads share one link, and the interleaved formats are expensive. The arithmetic:

bytes per frame = width × height × bytes per pixel link load (Mbit/s) = bytes per frame × frame rate × streams × 8 / 1,000,000

Worked example — illustrative inputs, a 640 × 480 depth stream in Z16 (2 bytes per pixel) plus a 640 × 480 Y8I infrared pair (2 bytes per pixel) at 30 fps on a dedicated link:

  • 640 × 480 = 307,200 pixels per frame; × 2 B = 614,400 B per frame, per stream.
  • 614,400 B × 30 fps = 18,432,000 B/s ≈ 18.4 MB/s per stream; × 8 = 147.5 Mbit/s.
  • Both streams together: ≈ 36.9 MB/s, or 294.9 Mbit/s.
  • At 15 fps the same pair drops to ≈ 18.4 MB/s combined.

USB 2.0 moves roughly 35-40 MB/s of real throughput, so the 30 fps pair sits at that ceiling and a shared hub pushes it over, while the 15 fps pair fits with margin. That margin — not the driver — explains cameras that tear at 30 fps and run clean at 15. Decision: run any two-stream depth head on a root USB 3 port with no hub; if the link must stay USB 2.0, cap the frame rate near 15 fps. On embedded boards the same arithmetic decides, as Depth stream waiting on ARM Linux: bandwidth and driver checks shows.

Motion. Structured-light heads compute depth from several frames; a camera on a flexible bracket or a scene that moves mid-capture shimmers even with a perfect driver. Rigid mounting during capture is the whole fix — 3D camera mounting: stillness during capture decides image quality has the details.

Firmware. A head that drops out at the same point in every session, with a clean format list and a quiet USB link, points at the camera itself; Camera firmware version mismatch: fix detection failures safely is the ordered path.

How do you keep the fix in place across kernel updates?

Register the patched module with DKMS so every kernel upgrade rebuilds it automatically, and pin or delay kernel upgrades on a production cell until you have re-run the three-check routine.

Keep four values in the station's build notes: uname -r at commissioning, the modinfo filename and version, the SDK and patch versions applied, and the dmesg driver line the working build printed. After any system update the 60-second re-check is: modinfo agrees with uname -r, the format list still shows the three formats, one clean capture runs.

Two failure paths are worth knowing in advance. If an update breaks the module and the line must run today, Linux uvcvideo driver rollback after patch failures is the recovery path. On a cell where uptime matters more than new kernel features, pinning the release and rebuilding on your own schedule is the standard pattern — MIPI camera driver kernel version match: pin or rebuild lays out both options.

Everything above is software. When the question is instead which depth camera to put on the next station, shortlist models whose Linux support matches your kernel before the hardware choice: the camera finder filters by interface and resolution, and the depth line is browsable in the 3D sensors category.

Cameras3D sensors

Laser profilers and stereo 3D cameras

170 models · from $699.00

Questions

Does the GPG 'public key not found' message mean the patch failed?

No. That message only says the signature on the downloaded kernel source package could not be checked because the signing key is missing from your keyring; the build continues past it. The failure that decides the outcome is the hunk rejection in videodev2.h — resolve that or hand-apply the remaining hunks, and treat the signature warning as noise.

Can a depth camera run on the stock uvcvideo driver with no patch at all?

Test it before building anything — the check takes two minutes. Load the stock module, list the formats each /dev/video node advertises, and stream a few hundred frames. If Z16, Y8I and Y12I appear and both streams hold steady, no patched build is needed. If the depth node offers only generic formats, the rebuild path above is required.

What does VIDIOC_DQBUF error 19 actually report?

Error 19 is ENODEV, no such device: the driver dropped the camera while the application waited for a frame. When it fires immediately after start-up it means the stream was torn down — read it as a format or module problem. When it fires mid-run under load it usually means the USB link folded, so suspect bandwidth, hub or cable and check dmesg timestamps.

Which values should be recorded before opening a support case?

Four things: the output of uname -r, the filename and version lines from modinfo uvcvideo, the format list from every /dev/video node, and the last 50 lines of dmesg from a failing run. With those four, the question becomes answerable in one round: whether the loaded module is stock, patched for the wrong release, or healthy and fighting the USB link.

Do all depth cameras with infrared use Y8I and Y12I?

No. Those two formats carry paired infrared for stereo-style depth heads; time-of-flight and other structured-light designs stream different layouts. The fourcc names come from the V4L2 standard, so the method is identical for any UVC depth camera: whichever formats your camera's documentation names must appear in the node's format list before an application can negotiate them.

The format list is correct but rows still look shifted — what now?

Check the row stride before suspecting the sensor again. Some UVC devices pad each row to an alignment boundary, and a reader that assumes width times bytes per pixel pulls every row out of step, which looks exactly like shear. Read the stride the driver reports for each frame and consume that many bytes per row instead of the nominal width.