You retrieved a disparity measure, wrapped it for OpenCV, and the viewer window came back black or all white. The capture is usually fine: a disparity measure is a single channel of 32-bit floats whose values are pixel offsets, negative on many stereo SDKs, and cv::imshow reads float pixels as 0-1 intensities, clamping everything else. This guide is for engineers displaying stereo output from a 3D camera SDK in OpenCV. You will copy the measure into CPU memory, wrap it as a CV_32FC1 Mat, compute one scale factor from the disparity range, and show a usable map — plus the checks that tell a scaling bug apart from a matching failure.
What the disparity measure holds
The API describes sl::MEASURE_DISPARITY as one channel of 32-bit floats, one value per pixel: disparity in pixels. That value is the horizontal offset between where the left and right rectified images place the same physical point. Near objects give large offsets, distant ones small offsets, and the whole map shares one scale as long as the calibration holds.
In this SDK the values are negative. A scene spans from a negative floor, say -50 px on a close object, up to around 0 px at the far edge of the search range; other libraries flip the convention, so read the sign from your first frame with cv::minMaxLoc instead of assuming it. Pixels where the matcher finds no correspondence hold a sentinel, often 0, which is why even a correct map shows black speckle.
Disparity is not distance, and every scaled image in this guide is display only. Real measurement goes back through your SDK's depth function with per-camera calibration — the stereo depth scale guide shows where to read the focal length and baseline per camera.
Why cv::imshow turns a float map black
The window is not broken; imshow applies a fixed rule per Mat depth. CV_8U shows values 0-255 as they are, CV_16U values are divided by 256, and a CV_32F image is shown as value × 255, with anything below 0 clamped to black and anything above 1 clamped to white. The highgui reference states the rule in one line.
A raw disparity map spanning -50 to 0 px sits entirely at or below zero, so every pixel clamps to 0 and the window paints black. A positive-disparity map spanning 5 to 60 px is the mirror failure: everything is at or above 1, and the window paints white. Same symptom, opposite sign.
A map carrying both signs needs the offset form instead: (d - dmin) / (dmax - dmin), dimensionless, maps the full signed range into 0-1. For the negative-only maps this SDK produces, the single constant below is enough.
Retrieve, wrap, scale: the five steps
The calls below use the sl:: names from the SDK's depth_sensing sample; the OpenCV side is identical for any SDK that hands you a float Mat.
- Retrieve into CPU memory. The sample's OpenGL viewer reads GPU buffers; a cv::Mat cannot. Pass the CPU memory flag to the retrieve call.
- Wrap it as a cv::Mat. The SDK's OpenCV example ships a helper named slMat2cvMat that builds a Mat header over the buffer without copying. Confirm the type is 5, which is CV_32FC1.
- Read the range once. cv::minMaxLoc gives dmin and dmax. Fix the scale from these or from the matcher's search range, not per frame — a moving scale makes the display flicker.
- Scale with the sign flipped. Multiply by -1 / |dmin| when dmax is zero or negative, then show the product with imshow.
- Prove it. cv::minMaxLoc on the scaled Mat must return 0.0 and 1.0.
sl::Mat disparity_measure; // one channel, 32-bit float
zed.retrieveMeasure(disparity_measure, sl::MEASURE_DISPARITY, sl::MEM_CPU);
cv::Mat disparity = slMat2cvMat(disparity_measure); // header, no copy
// disparity.type() == 5, i.e. CV_32FC1, for this measure
double dmin = 0.0, dmax = 0.0;
cv::minMaxLoc(disparity, &dmin, &dmax); // e.g. -50.0 and 0.0 px
double range = std::max(std::abs(dmin), std::abs(dmax)); // 50.0 px
double scale = (dmax <= 0.0) ? -1.0 / range : 1.0 / range; // -0.02 per px
cv::Mat view = disparity * scale; // CV_32FC1, 0.0 to 1.0
cv::imshow("disparity", view);
cv::minMaxLoc(view, &dmin, &dmax);
// the check passes when dmin = 0.0 and dmax = 1.0 for the -50 to 0 pixel case
The wrapper shares memory with the SDK buffer. If the capture loop requeues that buffer before you are done, copy it first — the torn-frame guide shows the failure. For building the header by hand, or deciding when a deep copy pays for itself, use the SDK buffer wrapping guide.
Worked example: -50 to 0 pixel disparities at scale 0.02
One case end to end: a bench stereo pair, a matcher searching 50 px, and a nearest object whose disparity comes back at -50 px.
Inputs, with their source:
- Measure: one channel, CV_32FC1, values in pixels (the API's description of sl::MEASURE_DISPARITY).
- Scene range: -50 px nearest to 0 px at the far edge, so a 50 px search range (illustrative bench case).
- Display rule: a CV_32F Mat is shown as value × 255, clamped to 0-255 (the imshow rule above).
- Sign: negative in this SDK.
The rule in words: pick one constant so the most negative pixel maps to 1.0 and zero maps to 0.0. Because the range is negative, the constant must be negative — a positive constant keeps the products negative and the window black.
The arithmetic:
- scale = -1 / 50 px = -0.02 per px
- nearest object: -50 px × (-0.02 / px) = 1.0 → 1.0 × 255 = 255 → white
- mid-scene object: -25 px × (-0.02 / px) = 0.5 → round(0.5 × 255) = 128 → mid grey
- far edge: 0 px × (-0.02 / px) = 0.0 → 0 → black
- wrong sign, for contrast: -50 px × (+0.02 / px) = -1.0 → clamped to 0 → the whole window black
Result: the display Mat spans 0.0 to 1.0, and the step-5 check returns min 0.0, max 1.0.
Decision: set scale = -1 / search range once, when you configure the matcher — -0.02 at 50 px, -0.015625 at 64 px, -0.0078125 at 128 px. Touch it only when the search range changes. If the check ever reports values outside 0-1 by more than 1/255 (about 0.004), the constant no longer matches the configured range; fix the constant, not the scene.
8-bit and coloured copies for saving and overlays
imshow is enough for live checks; recordings and overlays want CV_8UC1, and tuning wants colour. Both come from the scaled Mat in two lines.
cv::Mat view8;
disparity.convertTo(view8, CV_8UC1, -255.0 / range); // -255 / 50 = -5.1 per px
// -50 px becomes 255 (white), 0 px stays 0 (black), overflow saturates
convertTo saturates out-of-range pixels, so anything beyond the search range pins at 0 or 255 instead of wrapping. Eight bits hold 256 grey levels across the range — about 0.2 px of disparity per level at 50 px — which is plenty for an overlay and coarse for calibration work; keep measurements on the float Mat. For colour, run applyColorMap with COLORMAP_JET on view8: the JET colormap guide covers keeping the numeric values next to the colours. A 16-bit depth image has its own recipe — the aligned depth display guide walks the 16-bit-to-8-bit path.
When the map stays black after a correct scale
If step 5 passes and the window still looks empty, the scale is right and the matches are missing. Re-read the raw range: when the largest magnitude is well under 1 px, nearly every pixel failed to match, and that is a capture problem — baseline, texture, exposure or rectification — not a display one. The disparity mostly black guide lists the causes in test order.
Speckled black patches inside otherwise solid objects are the sentinel pixels from failed matches. Mask them with the SDK's confidence output before judging the map — the confidence masking guide decodes the flags.
Choosing hardware that hands you disparity directly
If you are choosing hardware rather than debugging a viewer, a factory-calibrated stereo 3D camera removes the rig-building half of the problem: matching, rectification and calibration ship with the SDK, and the five steps above become the whole integration. Browse the stereo and structured-light 3D cameras, narrow the field with the camera finder, and lay out camera, mount and trigger in the configurator's camera step.
Laser profilers and stereo 3D cameras
170 models · from $699.00Both cards come from the stereo / structured-light group: one pairs stereo cameras with a laser galvanometer, the other projects a structured light pattern onto the part. Block the beam path while you align a galvanometer head, and keep to the laser labels on the housing. More on the capture side — mounting, exposure, point clouds — sits on the 3D topic page.
- Type
- Stereo / structured light
- Type
- Stereo / structured light
If the pairing for your scene is not obvious from the cards, describe the part, the stand-off and the cycle rate to the applications team through the contact page.
Questions
Why does my float disparity map show up black or white in OpenCV?
cv::imshow reads a CV_32FC1 Mat as intensities in the 0-1 range and clamps everything outside it. Raw disparity values are pixel offsets such as -50 to 0, so an unscaled map clamps to 0 and paints black; a positive-disparity map saturates to white for the same reason. First print the range with cv::minMaxLoc: if it already sits inside 0-1, you have scaled twice and should go back to the raw measure. Otherwise apply one constant with the sign flipped.
How do I save or overlay a disparity map as an 8-bit image?
Use cv::Mat::convertTo with CV_8UC1 and alpha = -255.0 / search range: at 50 px that is -5.1, so -50 px becomes 255 and 0 px becomes 0, with overflow saturated rather than wrapped. Eight bits give 256 grey levels across the range, about 0.2 px of disparity per level at 50 px, which is plenty for an overlay but coarse for judging calibration. Keep the CV_32FC1 Mat for measurements.
How do I turn displayed disparity into real distance?
Never measure from the scaled display copy; go back to the raw floats. Depth follows Z = (f × B) / d, with the focal length f in pixels and the baseline B in metres, both read from your camera's calibration, and d the signed disparity of that pixel. SDKs disagree on sign, so compute with the raw value exactly the way your SDK's depth function defines it, then confirm one known distance end to end.
Why are the disparity values negative, and what do OpenCV's own matchers return?
The sign records which rectified image the pixel offset is measured against; this SDK returns negative disparity so its own depth conversion stays positive. OpenCV's StereoBM and StereoSGBM return positive disparity as CV_16SC1 fixed point in 1/16-pixel units, so divide by 16.0 before scaling. Check the Mat type first: type 5 is CV_32FC1 float measures, type 3 is CV_16SC1 fixed point, then apply the matching scale rule.
Which camera hands me a disparity map without building the stereo rig myself?
A factory-calibrated stereo 3D camera computes disparity and depth onboard and hands both to the SDK, so you skip rig alignment and rectification and go straight to the retrieval call above. If the task is a profile of one edge or groove rather than an area map, a laser profiler from the same category measures height per line and skips stereo entirely.

