ComfyUI Node
CV Stereo Disparity (BM)
Per-pixel disparity from a RECTIFIED stereo pair with the classic BLOCK MATCHER (cv2.StereoBM) - the fast, local cousin of 'CV Stereo Disparity (SGBM)'. It compares raw SAD windows scanline by scanline with no global smoothness term, so it runs several times faster but leaves far more holes in low-texture areas; that is what texture_threshold controls. Use it for a quick preview, a speed/quality comparison, or when the scene is richly textured. The pair MUST be rectified (epipolar lines horizontal). Preview the disparity with 'Preview CV Array' (normalize / heatmap); larger disparity = closer.
CV Stereo Disparity (BM)
- left
- right
- disparity
- valid
- valid_fraction
◄num_disparities64►
◄block_size15►
◄min_disparity0►
◄texture_threshold10►
◄uniqueness_ratio10►
◄prefilterx-Sobel►
◄prefilter_cap31►
◄speckle_window_size100►
◄speckle_range2►
◄disp12_max_diff-1►
Categoryimage/CV/features
Inputs (12)
| Name | Type | Default | Description |
|---|---|---|---|
| left | NPARRAY,IMAGE | Left rectified frame (grayscaled internally). Accepts a ComfyUI IMAGE/MASK directly (frame 0 of a batch) or an NPARRAY. Arithmetic ops (add, multiply, etc.) process the full IMAGE batch when both inputs have the same batch size. | |
| right | NPARRAY,IMAGE | Right rectified frame; resized to left if sizes differ. Accepts a ComfyUI IMAGE/MASK directly (frame 0 of a batch) or an NPARRAY. Arithmetic ops (add, multiply, etc.) process the full IMAGE batch when both inputs have the same batch size. | |
| num_disparities | INT | 6416–512 | Disparity search range (0..num_disparities), rounded up to a multiple of 16. Larger covers nearer objects / wider baselines but is slower. |
| block_size | INT | 155–51 | SAD window size in pixels; forced ODD and clamped to 5..51 (StereoBM rejects anything else). Larger = smoother but blurs depth edges; 15-21 is typical. |
| min_disparity | INT | 0-256–256 | Smallest disparity to search from (usually 0). |
| texture_threshold | INT | 100–163863 | Reject a block whose texture (summed x-gradient) is below this - the main reason BM leaves holes on flat walls. 0 accepts every block (noisy). It is a SUM over the whole SAD window, so it only bites in the thousands: the ceiling above which every pixel is rejected is block_size^2 * prefilter_cap (about 7000 at the defaults, 163863 at block_size 51 / prefilter_cap 63). |
| uniqueness_ratio | INT | 100–100 | Margin (%) by which the best match must beat the runner-up to be accepted. |
| prefilteropt | COMBO | x-Sobel | Pre-filter applied before matching to remove lighting differences between the two cameras. x-Sobel (an x gradient, clipped to prefilter_cap) is what OpenCV itself defaults to and the usual choice. normalized response is the older local brightness normalisation kept from the legacy C API - it is more tolerant of a smooth exposure difference between the cameras but weaker on repetitive texture. |
| prefilter_capopt | INT | 311–63 | Pre-filtered values are clipped to +/- this. |
| speckle_window_sizeopt | INT | 1000–1000 | Largest smooth disparity blob treated as speckle noise and invalidated (0 = off). |
| speckle_rangeopt | INT | 20–64 | Max disparity variation within a speckle component. |
| disp12_max_diffopt | INT | -1-1–256 | Max allowed left-right consistency error in pixels (-1 = do not run the left-right check). |
Outputs (3)
| Name | Type | Description |
|---|---|---|
| disparity | NPARRAY | HxW float32 disparity in pixels; rejected pixels are below min_disparity (see 'valid'). |
| valid | NPARRAY | uint8 0/255 mask of pixels with a valid disparity - BM rejects many more than SGBM, so always check it. |
| valid_fraction | FLOAT | Fraction of pixels with a valid disparity (0..1) - the headline number when comparing BM against SGBM. |