cv2.ximgproc.fastGlobalSmootherFilter

If you want to see the difference between this node and every other smoother in the pack, look at what it throws away: nothing local. fastGlobalSmootherFilter solves one weighted-least-squares problem over the entire frame, guided by a second image, so a gradient can stay smooth from one corner of the picture to the other. Every bilateral-style filter next to it makes a decision inside a small window and lives with the consequences. That's the whole reason to reach for this one.

It's also not exotic - it's the base of OpenCV's WLS disparity filter, the "smooth along the left image's edges" step in a lot of stereo pipeline code you've probably seen.

How it works

You supply a guide (8-bit, 1 or 3 channels) and a src (8-bit, 16-bit signed or float, up to 4 channels). The solver looks for an output close to src in flat regions and close to the guide where the guide has an edge - a global fit, iterated a few times, with the regularization strength decaying between iterations.

The side effect is the useful part. Because the output keeps every strong edge and flattens everything under the threshold, subtracting it from the original gives you a detail layer. That's the classic structure/detail split, and it's a much more controllable way to soften skin, kill sensor grain, or build a "sharpen by adding detail back" branch than any blur radius.

Inputs and outputs that matter

• guide - the image whose edges you're preserving. Feed the same image as src for self-guided smoothing. Same size as src, no exceptions.
• src - what actually gets filtered. It can be a disparity map or any float data, not just a photo.
• lambda_ - smoothing strength; larger flattens more. The pack's own example workflow smooths a photo at 800, and 8000 for a disparity map. That's your range.
• sigma_color - the guide's colour difference that counts as an edge, in 0–255 units. 12 for a photo, 1.5 for disparity - disparity varies as fast as the number, so the edge threshold has to be tighter.
• lambda_attenuation (0.25) and num_iter (3) - leave them. The tooltip is blunt: attenuation at 1.0 gives you streaking artifacts.

Output is a single result, and it echoes the format of guide: an IMAGE link in comes back as an IMAGE, a MASK as a MASK, an NPARRAY as an NPARRAY. So wire a photo in and you can preview it directly.

Install

Same pack for all of it:

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

Then restart ComfyUI. Or search ComfyUI CV in ComfyUI Manager. You need Python ≥3.12, a recent ComfyUI built on the V3 node API, and opencv-contrib-python-headless~=5.0.0.93 - the version the pack's behaviour is curated against. No models, no downloads.

Common issues

The contrib build. All the ximgproc nodes live in the contrib wheel. The four OpenCV wheels (opencv-python, -headless, -contrib-python, -contrib-python-headless) share one site-packages/cv2, so installing a plain wheel over a contrib one silently empties the contrib submodules and these nodes vanish from the menu. tools/repair_opencv_contrib.py --check diagnoses it, --apply fixes it.

Expect a one-second pause. This node is on the pack's unconditional-offload list: the cv2 call runs in an interruptible subprocess because a global WLS solve is slow enough that you'll want to hit cancel. The ~1 s spawn is noise next to that, but it's why the node feels like it "hangs" before the preview appears.

It has no concept of an invalid pixel. If you point it at a disparity map, the −1 markers that mean "no match here" get averaged into their neighbours like real measurements. Use it to smooth a map, not to fill holes - the pack's curated disparity nodes exist for the other job.

eps-style confusions don't apply here, but lambda is scale-blind. A lambda tuned on a 512×384 frame is a very different amount of smoothing on a 4K frame (same story as guidedFilter). Tune per resolution, not per workflow.