CV Quasi-Dense Stereo

If you've used CV Stereo Disparity (SGBM) or the (BM) node in this pack, you know the ritual: set num_disparities, guess block_size, run it, look at the holes, adjust, run again. Quasi-dense stereo is the third answer, and it drops the one parameter everybody gets wrong.

What it actually does

cv2.stereo.QuasiDenseStereo is a seed-and-grow matcher. Instead of searching a disparity range at every pixel independently, it picks a few hundred goodFeaturesToTrack corners in the left frame, tracks them into the right frame with Lucas-Kanade, and then grows each confirmed match into its neighbourhood for as long as the correlation holds and the local disparity gradient stays smooth.

Two consequences fall out of that, and both matter:

• There is no disparity range. A seed can land at any disparity, so a wide baseline or a close object costs you nothing parameter-wise. That's the whole appeal.
• It's quasi-dense, not dense. Propagation can't cross a textureless gap, so the sky, a blank wall or an out-of-focus background stays unmatched. The output has holes by construction, and that's not a bug to fix with settings.

It also runs on an unrectified pair - but the disparity numbers only mean something on a rectified one. Match on a raw pair and you get matched points, not measurements.

Inputs worth touching

left and right take an IMAGE or an NPARRAY directly (the pack's own array socket, which every other node in this graph speaks). Frame 0 of a batch is what gets used, and the right frame is resized to the left if the sizes differ - the underlying class asserts on mismatched frames, so the node spares you that.

Then the seed controls, which are where you'll spend your time:

• max_seeds (default 500) and seed_min_distance (10) - how many corners to start from and how spread out they are. More seeds reach more regions; propagation can't invent a match in an area it never seeded.
• texture_threshold (200) is the one that stops the growth from flooding a blank wall with an invented disparity. Raise it and the mask gets more honest and smaller.
• correlation_threshold (0.5) trades coverage for correctness. Raise it when you'd rather have fewer, better matches.
• correlation_window (5) and disparity_gradient (1) control how far a match spreads and how steep a slope it can follow.

Outputs

disparity is HxW float32 in the pack's usual signed convention (x_left - x_right), which is what you want - it feeds CV Disparity Interpolate, the WLS filter, and cv2.reprojectImageTo3D like any other disparity map. 0 means unmatched, so read valid (a 0/255 uint8 mask) rather than treating zero as a measurement.

There's a second map called displacement, and it's a genuine trap: that's cv2's own getDisparity(), which returns the unsigned Euclidean length of each match's motion, vertical component included. On a rectified pair the two agree; on an unrectified one they can differ by tens of pixels. Use disparity.

points_left / points_right give you the dense match set as Nx1x2 coordinates - straight into CV Triangulate Points for a sparse cloud, no disparity math in between. seeds_left / seeds_right are the sparse seeds the growth started from, handy for debugging why a region came out empty. dense_count, seed_count and found round it out; found=false on a blank or uncorrelated pair, with empty arrays instead of the assertion the class would otherwise raise.

Install

It ships in ComfyUI CV (bmad4ever/comfyui_cv), a fork of opencv-comfyui that wraps OpenCV as ComfyUI nodes. Via Manager, search the pack title; manually:

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv
# then restart ComfyUI

Its single hard requirement is a recent contrib OpenCV:

pip install "opencv-contrib-python-headless~=5.0.0.93"

The pack needs Python ≥ 3.12 and a ComfyUI built on the V3 node API. The node exists because QuasiDenseStereo is a class, and the pack's ~470 auto-generated raw cv2.* wrappers only cover plain functions - so this is the only way to reach it from a graph.

When it goes wrong

The classic failure is a confident-looking result on a bad pair. If you didn't rectify first, disparity will be nonsense while points_left/points_right still look plausible - check that first. Second: empty regions aren't tunable away. If a region has no texture, no max_seeds value will fill it; that's the design. And if found comes back false, branch on it rather than feeding zeros downstream, because an all-zero disparity map reproduces as a perfectly flat wall.

The pack is honest that it's a personal, heavily AI-assisted project, not production software, and that its example workflows exist to demonstrate rather than to ship. There's one for this node - workflows/60_quasi_dense_stereo.json - which runs it side by side with SGBM on a synthetic pair, and that side-by-side is the fastest way to see what you're buying.