3D visionTroubleshooting

Stereo disparity map mostly black: fix baseline and matching range

A mostly black stereo disparity map means the search window or the surface, not the calibration. Sizing rule, worked example and ordered fixes.

LumaSpec Vision8 min read Share on LinkedIn

On this page 8 sections
  1. 01What a black pixel in a disparity map means
  2. 02The sizing rule: d = f·B/Z
  3. 03Worked example: 160 mm baseline, 2 m target, 64-pixel window
  4. 04Five tests before you recalibrate
  5. 05Fixes in order of effort
  6. 06When to stop tuning and specify a calibrated 3D sensor
  7. 07Prevention: size the rig before you mount it
  8. 08Questions

A disparity map that comes back mostly black looks like a calibration failure, and the usual reflex is to reshoot the chessboard. In a calibrated pair it almost never is. Black pixels are pixels the matcher refused, and the refusal has two ordinary causes: the true disparity falls outside the search window your geometry implies, or the surface carries nothing to match. You will size the window from your own geometry, work a 160 mm baseline and a 2 m target end to end, run five tests that separate range from texture and rectification, and reach the point where tuning stops and a calibrated 3D sensor starts.

What a black pixel in a disparity map means

Block matchers such as OpenCV's StereoBM and StereoSGBM search a fixed disparity window per pixel, from minDisparity to minDisparity + numDisparities. Matches rejected by the uniqueness or texture checks are written out as invalid, and every viewer draws invalid pixels black. Two inputs produce a mostly black map: a true disparity above the top of the window, which is geometry, and a patch with no distinguishable pattern, which is the surface. Exposure rarely causes it, because the matcher works on relative pixel differences and a dark but sharp image still matches. A map that is noisy or frozen at one value is a different branch; the stereo disparity map troubleshooting after rectification and stereo depth stuck at a fixed value guides cover those.

The sizing rule: d = f·B/Z

d = f·B / Z disparity in pixels; f in pixels, B and Z in one unit numDisparities ≥ f·B / Z_closest the window must reach the closest distance σZ ≈ Z²·σd / (f·B) depth noise caused by disparity noise

f in pixels comes from calibration, not from the lens barrel: focal length in mm divided by pixel pitch. The window rule exists because disparity grows without bound as the object approaches, so a window sized for a 2,000 mm working distance goes black again at 1.4 m. Once a value does match, convert it with depth from a matched stereo point pair: disparity to 3D coordinates. The third line is your accuracy budget: every pixel of disparity noise costs Z²/(f·B) of depth error, so millimetres come from a large f·B, not from more matcher iterations.

Worked example: 160 mm baseline, 2 m target, 64-pixel window

Illustrative pair, not a catalog model: two 1920 × 1080 mono cameras with 1/2.9-inch sensors and 2.8 mm lenses, mounted 160 mm apart, target at 2.0 m, matcher left at numDisparities = 64.

  • Sensor width is about 4.8 mm, so pixel pitch = 4.8 mm ÷ 1920 = 2.5 µm.
  • f_px = 2.8 mm ÷ 0.0025 mm = 1120 px.
  • d = (1120 px × 0.160 m) ÷ 2.0 m = 89.6 ≈ 90 px.
  • The window covers 0–63 px, so the entire target sits outside it: black.
  • numDisparities = 96 covers the target point, since 90 ≤ 95. numDisparities = 128 reaches down to Z = 179.2 ÷ 128 = 1.4 m.
  • Noise budget: f·B = 179.2 px·m, so 1 px of disparity error is 4.0 ÷ 179.2 = 22 mm of depth at the target; with 0.5 px of matching noise, about 11 mm. Fine for robot guidance, not for gauging.

Now swap the 2.8 mm lenses for 8 mm. f_px = 3200 and d = 256 px at the target distance, past any practical window; that is the signature of a rig that went fully black after a lens change.

Decision: keep the 2.8 mm lenses and set numDisparities = 128, or narrow the baseline to B = 48 × 2.0 ÷ 1120 ≈ 86 mm if the window must stay at 64. Millimetre trueness at the nominal range is not reachable with this geometry; that decision comes two sections down.

Five tests before you recalibrate

  1. Hand-measure one disparity. Pick a sharp, high-contrast corner visible in both rectified images, read its x coordinate left and right, and subtract: d = x_left − x_right. Agreement with f·B/Z within a pixel or two clears the calibration.
  2. Check the rows. The same feature must sit on the same pixel row in both rectified images. If it drifts, fix rectification first — see stereo rectification horizontal lines: fix camera order and baseline.
  3. Push a board frame back through the distortion model. Straight board edges that come out bent point to bad intrinsics, not to the matcher.
  4. Offer the part texture. Hold a chessboard at the target distance. If the board matches and the part stays black, geometry is innocent and the surface is the cause.
  5. Separate invalid from zero. Print the valid-pixel count or mask, so rejected pixels stop looking identical to a true disparity of zero.

Fixes in order of effort

What you see Most likely cause First fix
Black nearly everywhere Window smaller than f·B/Z numDisparities ≥ f·B/Z_closest
Part black, test board matches No surface texture Projected pattern or structured light
Black beyond one distance The window edge Widen window or shorten baseline
Features not on one row Rectification Fix camera order, recalibrate
  1. Widen the window. Set numDisparities ≥ f·B/Z_closest, rounded up to the next multiple of 16 — StereoBM and StereoSGBM both require it. Run time scales roughly with the window; 128–256 px is routine at 1080p, 512 and above gets slow.
  2. Shrink the baseline. B = d_target × Z ÷ f_px. For a 48 px disparity at the nominal distance with f_px = 1120, B ≈ 86 mm. Depth noise doubles when the baseline halves: 1 px then costs 4.0 ÷ 96.3 ≈ 42 mm at the same range. The full trade is in choose stereo camera baseline distance for 3D vision.
  3. Cap the focal length. Solve the window rule the other way: f_px ≤ numDisparities × Z_closest ÷ B. At a 160 mm baseline with a 128 window reaching down to 1.5 m, that is 128 × 1.5 ÷ 0.16 = 1200 px, about a 3 mm lens on 2.5 µm pixels.
  4. Set minDisparity on verged mounts. If the optical axes converge on the target, disparities move toward zero and negative values; give minDisparity a negative value and count it inside the window.
  5. Add texture. A projected pattern restores matching on moulded plastic, machined metal and other low-texture surfaces. The black depth image on a textureless surface guide covers that failure in detail.

When to stop tuning and specify a calibrated 3D sensor

A textureless part plus a needed disparity of several hundred pixels is two problems on one baseline, and parameter tuning closes neither. Industrial stereo cameras remove both at once: an integrated projector supplies the texture, and factory calibration ships intrinsics, extrinsics and a disparity window already matched to a stated volume. A projected structured-light stereo camera carries its own pattern projector; a laser galvanometer stereo camera steers the pattern over larger volumes. Building your own pair stays right when the scene is textured, centimetre-class accuracy is enough, and you want the flexibility — pick the cameras from area scan cameras, or compare factory alternatives in 3D sensors.

Two families cover the worked-example case:

3D sensorsHikrobot MV-DPS200P-02 Projected structured-light 3D cameraMV-DPS200P-02
Type
Stereo / structured light
$8,829.00 · quotedView and quote
3D sensorsHikrobot MV-DLS300P-04 Laser galvanometer stereo cameraMV-DLS300P-04
Type
Stereo / structured light
$16,579.00 · quotedView and quote

Prevention: size the rig before you mount it

  • Write down Z_closest, Z_nominal and the accuracy target first; every other choice derives from them.
  • Aim the nominal disparity near half the window: d_nom = f·B/Z_nom, so the window is 2 × d_nom and approach headroom is built in.
  • Keep the optical axes parallel and the vertical offset within a few pixels.
  • Calibrate with boards at several distances and angles through the working volume, not one pose, and confirm with a board at Z_closest.
  • Budget accuracy with σZ ≈ Z²·σd/(f·B). Plan on 0.2–0.5 px of disparity noise on textured targets with subpixel refinement, and split your tolerance half to matching noise, half to calibration.
  • Keep a texture plan for every shiny or unpatterned part: projector, contrasting finish, or a structured-light sensor.

Size the hardware last: the camera finder filters mono global-shutter models by sensor, resolution and interface, the camera configurator matches a lens to your working distance, and the 3D vision topic page collects the rest of the stereo fixes. If the rig is already bolted down, run the hand-measured disparity test first — it answers the calibration question in one minute.

Questions

Should the cameras be toed in so the target sits centred in both images?

Keep the optical axes parallel and accept a target that is not centred in both frames; rectification and the disparity window do not care where the target sits in the frame. Toe-in moves the target's disparity toward zero or negative, which pushes it outside a window starting at 0 unless you set minDisparity accordingly. If the mount must converge, calibrate the pair as mounted and re-run the hand-measured disparity test.

Should the calibration board be at the same distance as the target?

No. Cover positions, distances and angles through the whole working volume, from closer than the target to a little beyond it, at least ten poses. Intrinsics come from the lens and sensor and do not depend on target distance; what hurts accuracy is a board photographed at one pose or one depth. A board held at the closest working distance is the final check that the window and rectification hold.

How much baseline do I need for 1 mm depth accuracy at 2 m?

With subpixel matching at 0.5 px of disparity noise, σZ = Z²σd/(f·B) demands f·B = 2000 px·m. A 16 mm lens on 2.5 µm pixels gives f = 6400 px, so B = 310 mm, and the disparity at that distance is 1000 px — a search window no practical block matcher reaches. This is the accuracy class where a laser profiler or a factory 3D sensor takes over from a two-camera rig.

Why did my disparity map change after updating the vision library?

Matcher defaults move between releases: block size, pre-filtering, uniqueness ratio and even the disparity window can change, and any parameter you left implicit follows the new default. Set numDisparities, minDisparity and the block size explicitly in your code, then re-run the hand-measured disparity check above on one known feature before re-tuning anything. If the map degrades only at range, suspect the window first.