A disparity image can have a value at every pixel location without containing a usable depth measurement at every location. An XYZ exporter may correctly omit failed matches, nonfinite coordinates and points outside an accepted depth range. A viewer can then hide otherwise valid points through unsuitable axis limits or an incorrect file import.
For engineers validating a stereo reconstruction pipeline, the fastest approach is to reconcile counts before changing matching settings. Follow the checks below to separate expected filtering from disparity decoding, reprojection, export and display faults. Keep the original disparity array, calibration data and export settings together so each test uses the same capture.
1. Reconcile the pixel and point counts first
Start with the dimensions of the actual disparity array, not the original camera image. Rectification, cropping or resizing may have changed its dimensions. Then identify whether the exported cloud is organized or compact.
An organized cloud preserves an image-like layout, potentially using invalid entries where measurements failed. A compact cloud stores only accepted points. Consequently, the number of compact XYZ records usually equals the final valid-mask count, not image width multiplied by height.
Count each rejection stage separately. The following example uses hypothetical data, not a sensor specification:
| Processing stage | Remaining samples | Removed at this stage |
|---|---|---|
| Disparity array, 1200 × 800 pixels | 960,000 | None |
| Matcher-valid pixels within the accepted image region | 816,000 | 144,000 |
| Finite reprojected XYZ coordinates | 812,000 | 4,000 |
| Coordinates inside the application's accepted depth range | 780,000 | 32,000 |
| Compact export with no further filtering | 780,000 | None |
The arithmetic is:
This result needs no export repair if every rejection is intentional. However, a high valid fraction does not prove that the coordinates are correct.
Build an explicit mask from the matcher's documented validity conditions and any valid rectification region. Do not assume that every invalid result is zero, or that every negative disparity is invalid. Encodings and disparity search ranges differ.
For failures already visible in the disparity image, use stereo disparity troubleshooting after rectification. That guide addresses matching quality; the checks here follow measurements through reprojection and export.
2. Verify disparity scaling before reprojection
Use numerical disparity values, not a display image saved for viewing. A contrast-stretched grayscale preview usually discards the scale and offset needed for geometric reconstruction.
Some matchers encode fractional-pixel disparity in an integer array. For example, a documented scale factor of 16 would mean that a stored value of 384 represents a disparity of 24 pixels:
The scale factor is an example, not a universal setting. Check the producing algorithm's documentation and the array's data type. Also check whether an earlier processing stage has already converted the values; dividing twice creates another error.
For a simplified rectified stereo pair with aligned principal points:
Suppose the rectified focal length is 900 pixels, the baseline is 120 mm and the disparity is 24 pixels:
If the encoded value of 384 were used directly, the calculated depth would be about 281 mm. That large scale error can make a cloud appear compressed or place it outside the viewer's expected range.
3. Check calibration, coordinate units and geometry
The simplified depth equation assumes compatible rectified camera geometry. When rectified principal points differ horizontally, the relevant denominator includes their offset:
This expression assumes the convention d = x_left - x_right and a compatible positive baseline magnitude. Different coordinate conventions require corresponding signs. Use the reprojection matrix produced for your actual rectified pair rather than rebuilding it from guessed conventions.
A common matrix-based representation is:
Here, Q is the reprojection matrix, u and v are pixel coordinates, and d is decoded disparity. Reject undefined homogeneous division and nonfinite output. Any additional depth limits should come from the application's measurement envelope, not an arbitrary threshold chosen to improve the picture.
Confirm these calibration dependencies:
- The left and right image order matches the calibration and disparity convention.
- The reprojection matrix belongs to the rectified images being processed.
- Image resizing or cropping has been reflected in the projection geometry and pixel coordinates.
- The calibration target dimensions used the intended length unit.
- The output frame and axis directions are documented.
Depth generally inherits the length unit used for stereo translation. A result around 0.8 could represent meters, while a result around 800 could represent the same distance in millimeters. Magnitude alone cannot establish the unit.
Measure a stationary reference at a known distance and check a known physical dimension as well. A single plausible distance can conceal an incorrect crop or projection model. The principles in camera calibration for length measurement help distinguish numerical output from validated measurement.
4. Audit the export independently of the viewer
Before opening a graphics window, compare the final accepted-point count with the number of parsed XYZ records. Use parsed records rather than raw file lines because headers, comments and blank lines may be present.
A useful audit sequence is:
Read the original disparity array.
Decode disparity into pixel units.
Build the documented matcher-valid and image-region mask.
Reproject using the matching calibration geometry.
Count finite coordinates within the accepted application range.
Export those accepted coordinates.
Read the exported file back using its declared format.
Compare the parsed record count and coordinate values.
Account for every operation between the accepted mask and the file writer. Decimation, voxel filtering, duplicate removal and region selection can all legitimately reduce the record count further.
Check the file structure explicitly:
| Symptom | Likely export or import cause | Discriminating test |
|---|---|---|
| Parsed records are fewer than accepted points | Additional filtering or incomplete write | Compare counts immediately before and after the writer |
| Coordinates occupy unexpected columns | Incorrect field mapping | Inspect several complete records and their field names |
| Values become much larger after import | Decimal or delimiter interpretation | Read a known decimal value back numerically |
| Only part of the cloud appears | Incorrect declared count or truncated file | Compare format metadata with parsed records |
| Geometry changes after export | Rounding or unintended transformation | Compare selected coordinates before and after saving |
For plain XYZ text, document the delimiter, decimal convention, axis order and units alongside the file. For formats with headers, keep their declared fields and counts consistent with the records actually written.
Write to a temporary file and complete the write before asking another process to load it. Also preserve enough numerical precision for the required measurement tolerance. Displaying rounded labels is harmless; permanently rounding the saved coordinates may not be.
5. Make the cloud visible with controlled axis limits
Once the read-back test passes, inspect coordinate statistics before plotting. Report the minimum, maximum and median of each axis, plus a central percentile interval. A few extreme depths can expand automatic axis limits until the useful surface appears as a tiny dot.
For example, suppose most accepted points occupy these hypothetical bounds:
- X: -0.30 to 0.30 m.
- Y: -0.20 to 0.20 m.
- Z: 0.70 to 1.10 m.
If one outlier reaches 500 m, an automatic full-range view may hide the useful structure. Temporarily set limits around the expected work volume, then examine excluded points separately. Do not silently delete them from the measurement data.
Use the following viewing sequence:
- Import the file with the correct X, Y and Z column assignments.
- Confirm the coordinate unit and select a view fitted to the expected work volume.
- Use equal physical axis scaling when judging geometry.
- Increase point size if the display is sparse, without changing the underlying coordinates.
- Color points by depth to reveal layers, discontinuities and outliers.
- Inspect both an oblique view and a view along the depth axis.
For a large cloud, display every tenth accepted record during an initial performance check. Treat that as a display sample, not as the measurement export. Periodic sampling can hide repetitive features, so inspect the complete dataset before acceptance.
Repeated Y and Z values across neighboring records are not automatically wrong. A row of points on a nearly front-facing plane can have that pattern. Judge the complete surface and its measured dimensions rather than a short text excerpt.
6. Separate viewing faults from geometric faults
A cloud that looks wrong needs a test that identifies which stage is responsible. Changing several matching and display settings together destroys that evidence.
If a known plane looks reasonable in the coordinate statistics but disappears in the viewer, investigate import settings, clipping and camera position first. If every depth is wrong by a similar ratio, inspect disparity scale and calibration units. If distortion varies across the image, inspect rectification geometry, image transformations and calibration consistency.
Use a selected image pixel as a traceable sample. Record its disparity, validity status, reprojected coordinate and exported record. For compact clouds, preserve the source pixel indices in a companion mapping if downstream processing needs image correspondence.
The guide to mapping image pixels to 3D points explains why a compact record index cannot automatically serve as an image pixel index.
If static scenes reconstruct consistently but moving scenes split or smear, investigate capture timing rather than viewer axes. Multi-camera point cloud synchronization covers the timing relationship that a geometrically correct export cannot repair.
7. Choose hardware only after locating the fault
A valid export with poor viewing settings does not justify replacing cameras. Likewise, purchasing a depth sensor will not correct a downstream unit conversion or file parser.
If you are reconsidering the acquisition architecture, distinguish a calibrated stereo system assembled from area scan cameras from a device that performs depth sensing internally. The camera finder supports hardware selection, while the 3D sensors category groups alternative sensing approaches.
Laser profilers and stereo 3D cameras
170 models · from $699.00The MV-DLS300P-04 is listed as a laser galvanometer stereo camera. Consider it as a different acquisition architecture, not as evidence that existing disparity files are compatible with its output.
- Type
- Stereo / structured light
The MV-DPS200P-02 is listed as a projected structured-light 3D camera. Confirm coordinate conventions, output formats and application suitability before selecting it for a replacement system.
- Type
- Stereo / structured light
Product category alone does not establish working range, accuracy, frame timing or export compatibility. Request the required documentation and evaluate representative surfaces. For a passive stereo redesign, the wide-baseline stereo camera selection guide addresses acquisition geometry rather than file visualization.
8. Finish with a repeatable acceptance checklist
Keep a small reference dataset containing the rectified images, numerical disparity, calibration, masks and exported coordinates. Run the same checks after changing software, image size or export settings.
- Count: final accepted points equal exported records unless a documented reduction follows.
- Encoding: disparity scale and invalid markers come from the producing algorithm's documentation.
- Geometry: calibration, image order, crop and resolution describe the same capture pipeline.
- Units: a known distance and physical dimension agree with the reconstructed coordinates.
- File integrity: read-back preserves record count, field order and numerical values.
- Viewing: axis limits, units and physical aspect ratios match the intended work volume.
- Traceability: selected image pixels can be followed through to their exported coordinates.
Keep both the unfiltered coordinate data and the application-filtered cloud when practical. The former supports diagnosis; the latter represents the declared operating envelope. Record the reason for every reduction instead of treating all missing points as the same fault.
For a new acquisition setup, begin with the camera configurator. For an existing pipeline, send the count ledger, coordinate bounds and format requirements through applications support before choosing replacement hardware.
The configurator matches a camera, lens, light, light controller and cables to each other, step by step, and lists only parts that fit what you already picked.
Questions
Why does my XYZ file contain fewer points than the disparity image has pixels?
A compact cloud normally excludes pixels without accepted depth measurements. Matcher-invalid locations, rectification borders, nonfinite coordinates and application filters can all reduce the total. Compare the exported record count with the final accepted mask, accounting separately for any decimation or other reduction performed during export.
How can I tell whether my point cloud uses meters or millimeters?
Use the calibration's translation unit and confirm it against a known physical reference. Coordinate magnitude alone is unreliable because different working distances can produce similar-looking numbers. Check both a known distance and a known object dimension, then record the unit with the exported file.
Why does a valid point cloud appear as a dot or a flat patch?
A small number of extreme coordinates can stretch automatic axis limits until the useful surface becomes almost invisible. Inspect coordinate bounds, fit the view to the expected work volume and verify the imported columns. Use equal physical axis scaling when evaluating shape and proportions.
Should I change stereo matching settings to recover every missing point?
No. First confirm that the export count matches the documented validity mask and that disparity decoding, calibration and file writing are correct. Adjust matching only when the disparity itself contains unacceptable failures. Increasing accepted-point density can also admit unreliable measurements, so point count alone is not a quality target.