CV Stereo Disparity (BM)

Block matching is the original stereo algorithm and it makes no apologies: compare a small window on one scanline against windows on the other, take the best SAD score, move on. No global smoothness, no propagation between scanlines, no second pass. It runs several times faster than SGBM and gives you a disparity map with holes punched through every low-texture region - flat walls, sky, road, blurry backgrounds.

That's the deal, and it's a fine deal for three jobs: a fast preview while you tune, an honest speed/quality comparison, and scenes that are richly textured where BM does surprisingly well.

How it works

cv2.StereoBM is another class API the generated wrappers can't reach, so the node creates it, configures it from its widgets, computes, and drops it. The node clamps block_size to odd within 5..51 (and no larger than the image, which would raise), so you can't crash it from the UI.

Two BM-specific knobs are worth understanding.

texture_threshold is why BM leaves holes. It rejects a block whose summed x-gradient is below the threshold - a flat wall has no texture to match, so BM says "no idea" rather than guessing. Set it to 0 and every block gets accepted, which mostly means noise. And note the units: it's a sum over the whole SAD window, so it only bites in the thousands, not at the default 10. The widget ceiling of 163863 is block_size² × prefilter_cap at the node's own maxima - above that, BM would reject literally every pixel, so the range is set to the point where the parameter stops meaning anything.

prefilter handles the two cameras disagreeing about exposure. x-Sobel (the default, and OpenCV's own) applies an x-gradient clipped to prefilter_cap; the older normalized response is more forgiving of a smooth brightness difference between lenses but weaker on repetitive texture.

num_disparities, min_disparity, uniqueness_ratio, speckle_window_size, speckle_range and disp12_max_diff work as they do in SGBM.

The inputs and outputs that matter

left and right - rectified frames, epipolar lines horizontal. The node grayscales internally and resizes right to match left if needed, so don't be clever with pre-processing that changes one of them. Feed unrectified images and nothing complains; you just get garbage.

Outputs: disparity (HxW float32 in pixels), valid (uint8 0/255 mask), and - nicely - valid_fraction, the share of pixels that produced a value. That last one is the headline number when you're comparing BM against SGBM on your own footage; run both and read it before you trust either map. Preview with Preview CV Array in normalize or heatmap mode.

Any of this only means something after rectification: cv2_stereoRectify + initUndistortRectifyMap + cv2_remap, following CV Stereo Calibrate (Chessboard) or CV Stereo Rectify (Uncalibrated).

Install

ComfyUI Manager → search ComfyUI CV (publisher bmad4ever), or:

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv
pip install "opencv-contrib-python-headless~=5.0.0.93"

Restart afterwards. Python ≥ 3.12 and a recent ComfyUI built on the V3 node API. Keep the contrib wheel even though this node is core cv2 - a plain opencv-python install shares site-packages/cv2 and quietly strips the contrib submodules, taking other nodes in the pack with it. tools/repair_opencv_contrib.py --check / --apply is the recovery tool.

workflows/58_stereo_bm_vs_sgbm.json wires BM, SGBM and the WLS variant off the same rectified pair, which is exactly the comparison this node exists for. Sample inputs come in via 01_install_example_inputs.json (run it, then reload the page).

Where it bites

The classic own-goal is judging BM on a flat-lit scene and concluding stereo depth is garbage. BM's holes are honest - it's telling you those blocks are untextured - and they're why SGBM (or WLS-filtered SGBM) is the default in every serious pipeline. Use BM when you want it fast or when you're sanity-checking something more sophisticated.

And the standard pack caveat: bmad4ever's README states plainly that this is a personal, heavily LLM-assisted project, not production-ready, with no support promised and stereo settings tuned to one dataset. The BM wrapper is faithful to OpenCV; the numbers you tune around it are on you.