CV Disparity Filter (WLS)

Runs the ximgproc weighted-least-squares filter over a disparity map you already have, from ANY matcher: StereoBM, quasi-dense stereo, a depth network, or an earlier refinement pass. It fills holes and smooths the map while sticking to the edges of the guide image - on the example gallery pair a StereoBM map goes from 22% to 54% valid. Wire disparity_right (the right-to-left map, negative) to also get the confidence map and the left-right consistency check. Set num_disparities / min_disparity to the search range the map was computed with: they only pick the region to filter, but getting them wrong lets the invalid left band poison the whole result. Use 'CV Stereo Disparity (WLS filtered)' instead when you want SGBM and the filter in one node. NOTE the filter's prior is fronto-parallel, so a textureless SLANTED surface (a road) is bent towards a staircase - 'CV Disparity Interpolate (Edge-Aware)' fits a local plane instead and is the better choice there.

By bmad4ever·Created 3 months ago·Updated 2 days ago· 0

disparity
guide
disparity_right

disparity
confidence
valid

◄wls_lambda8000►

◄wls_sigma_color1.5►

◄num_disparities64►

◄min_disparity0►

◄block_size7►

◄lrc_threshold24►

◄depth_discontinuity_radius0►

◄roiauto (skip the invalid left band)►

Categoryimage/CV/contrib

Inputs (11)

Name	Type	Default	Description
disparity	NPARRAY		HxW float32 disparity in PIXELS (what every disparity node in this pack outputs), not the raw 1/16 int16 map cv2 returns. Invalid pixels are the ones below min_disparity.
guide	NPARRAY,IMAGE		The left rectified frame the disparity belongs to; its edges are what the filter follows. 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.
wls_lambda	FLOAT	80000–100000	Regularization strength: how strongly the filtered disparity is smoothed towards the edges of the guide image. 8000 is the OpenCV-recommended default; larger = smoother, more hole filling, more bleeding across depth edges.
wls_sigma_color	FLOAT	1.50–10	How sensitive the filter is to guide-image edges. 0.8-2.0 is the useful range: too low leaks disparity across object boundaries, too high makes it follow image noise.
disparity_rightopt	NPARRAY		Optional HxW float32 right-to-left disparity in pixels, NEGATIVE as ximgproc.createRightMatcher produces it. With it the filter runs its left-right consistency check and the confidence output is real; without it confidence comes back as zeros.
num_disparitiesopt	INT	6416–512	The search range the disparity map was computed with. Used ONLY to place the region to filter - the leftmost min_disparity + num_disparities columns can never have been matched, and letting them into the solve corrupts the whole map.
min_disparityopt	INT	0-256–256	The smallest disparity the map was searched from. Also the threshold for the 'valid' output.
block_sizeopt	INT	71–21	The block size the map was matched with (forced odd). It sets depth_discontinuity_radius to ceil(block_size / 2), exactly as the matcher-bound filter does - and that is not a cosmetic detail: one step off there changes the filtered disparity by 2000+ px at the worst pixel. Leave it matching the matcher.
lrc_thresholdopt	FLOAT	240–256	Left-right consistency tolerance in 1/16 pixel units: disagreements above it are marked unconfident and re-filled by the filter. Only does anything when disparity_right is wired.
depth_discontinuity_radiusopt	INT	00–32	Radius (px) around depth discontinuities used when computing confidence. 0 = ceil(block_size / 2), which is what the matcher-bound filter picks.
roiopt	COMBO	auto (skip the invalid left band)	'auto' filters everything except the invalid left band implied by num_disparities/min_disparity, which is what the matcher-bound filter does. 'full frame' reproduces cv2's own generic default - keep it only to demonstrate the difference, it corrupts a real map.

Outputs (3)

Name	Type	Description
disparity	NPARRAY	HxW float32 WLS-filtered disparity in pixels.
confidence	NPARRAY	HxW float32 confidence map, 0-255; low where the two matching directions disagreed. ALL ZEROS when disparity_right is not wired - the filter has nothing to check against.
valid	NPARRAY	uint8 0/255 mask of pixels whose filtered disparity is at or above min_disparity.