Guided Filter Image

A regular gaussian blur doesn't know or care what it's blurring - it smears equally across a sharp edge and a flat wall alike. A guided filter is smarter: it blurs within regions of similar color and stops at boundaries where color changes sharply, using a second "guide" image to decide where those boundaries are. The README's own framing is the most useful summary: "works best with a strong color separation between FG and BG." If your subject and background are reasonably distinct in color, this filter blurs the background into mush while leaving your subject's edge crisp - something a plain gaussian blur can't do without a mask.

Why this over a normal blur

This is the node the pack's own "Enhance Detail" and low-frequency-layer workflows lean on instead of a plain gaussian blur. When you build a low-frequency layer for manual frequency separation (see Frequency Separate), a gaussian blur bleeds color across edges - a bright highlight next to a dark shadow gets smeared into a muddy gradient that doesn't represent either region well. A guided filter keeps that boundary intact because it's respecting where the color actually changes, not just applying a fixed-radius kernel everywhere. Same logic makes it useful for refining a rough mask's edges, or for detail-enhancement passes where you want to boost the difference between an image and its smoothed version without also boosting edge halos.

Inputs and outputs

• images (IMAGE) - what actually gets blurred.
• guide (IMAGE) - the reference the filter uses to decide where edges are. This can be the same image as images (self-guided, the most common case) or a different one if you want the blur shaped by something else's structure.
• size (0–1023, default 4) - the filter's window radius. Bigger means it looks at a wider neighborhood when deciding local color similarity, which generally means a stronger blur.
• sigma (0.01–100, default 0.1) - the regularization strength. Push it up and the filter tolerates more color variation before it stops blurring across a boundary (softer, more like a regular blur); push it down and it holds edges more strictly.

Output is a single IMAGE - the filtered result.

Installing it

Via ComfyUI Manager: search "ComfyUI-Image-Filters," install, restart. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/spacepxl/ComfyUI-Image-Filters

pip install -r requirements.txt (or install.bat on Windows), then restart ComfyUI. No models to fetch - it's OpenCV-based tensor math, so the install is quick.

The pack's whole dependency footprint really is just OpenCV, and that's also the one thing that bites people: if a different custom node pack already pulled in a conflicting opencv/cv2 build, nodes here can fail to import. The fix is the author's import_error_install.bat, which uninstalls every opencv variant and reinstalls the single one (opencv-contrib-python) that covers all of this pack's needs.

Where people get burned

The most common disappointment is running this on an image with weak FG/BG separation - say, a subject and background in similar tones - and finding it barely blurs anything, or blurs unevenly in a way that looks noisy rather than smooth. That's the filter doing its job correctly: it's declining to blur across what it perceives as an edge, even if to your eye the color difference is subtle. If you actually want a uniform blur regardless of content, use Blur Image (Fast) instead - this node is for when you specifically want the blur to respect structure. The other trap is treating size and sigma as interchangeable strength knobs - they aren't; size is about how far the filter looks, sigma is about how much color difference it tolerates, and getting the blur you want usually means adjusting both together rather than just cranking one.