Image Guided Filter

Smooth an image and you usually trade away its edges - a Gaussian blur is the enemy of crisp. Bilateral filters were built to fix that (blur the flat areas, spare the edges), but they have a famous flaw: around strong edges they leave halos, bright or dark fringes that announce the filter ran. The guided filter is the correction - it smooths flat regions and keeps edges crisp without the halo artifact. Image Guided Filter is the WAS Node Suite implementation, and the second trick is the one that makes it special: wire a different image into guide and that image's edges are the ones preserved.

It's from WASasquatch's MIT pack (v3, 457 nodes), under WAS Suite/Image/Filter. There's a sibling, Mask Guided Filter, that applies the same math to masks - this one handles images.

How it works

The guided filter's mechanism is deceptively simple: it assumes the output image is locally a linear function of the guide image. Around each pixel, it fits that relationship over a local window (the radius), and where the window is flat it averages - smoothing - while where the guide has an edge, the local fit respects it and the edge survives. The clever bit is the implementation: it's built from box filters, which is why radius costs the same at any size. A radius of 200 is no slower than 2 - unlike a Gaussian, there's no bigger kernel to run. That's the property that makes a "detail smoothing with a huge radius" pass practical.

The inputs

• image - what gets smoothed. Smaller than the guide, it's lifted to the guide's size first (more on that below).
• radius - how far the smoothing reaches, in pixels. Because it's box-filter based, wide is free, so don't be shy.
• epsilon - what counts as flat and therefore gets smoothed. 0.001 keeps almost every edge and barely smooths; 0.1 smooths through all but the strongest edges. It's squared brightness, so 0.01 corresponds to a step of about 0.1. This is your "how much smoothing" knob in disguise.
• guide (optional) - the image whose edges are kept. Unconnected, the image guides itself. Color guides follow an edge that only changes hue, which a luminance-only filter would miss.

The two jobs

Job one: detail smoothing without halos. Skin smoothing that doesn't smear the jawline, denoising that doesn't soften text, flattening a background while a subject's outline stays razor sharp. If bilateral left you with fringes, this is the node you were looking for.

Job two: joint upsampling. Feed a small image in and a large, detailed guide alongside, and the filter both lifts the small image to the guide's size and transfers the guide's edges onto it. That's the classic use in the computer-vision literature: you have a cheap low-res signal (a depth map, a lighting estimate, a mask) and a high-res photograph, and you want the cheap signal expressed at the photo's resolution with the photo's edges. The same trick is why guided filters show up all over upscaling and matting pipelines.

Install and notes

WAS Node Suite via ComfyUI Manager (search "WAS Node Suite v3") or git clone https://github.com/WASasquatch/was-node-suite-comfyui into ComfyUI/custom_nodes, then restart - ComfyUI 0.14.0+, Python 3.10+. v3 installs no Python packages, and the filter runs on torch, so there's no pip ceremony. (The pack's spacepxl-style Image-Filters cousins exist too, but if you're already running WAS Node Suite for other nodes, this one is right here.)

The gotcha is reading epsilon honestly: it's a squared-brightness threshold, so the number on the widget is not the pixel difference you'll feel. A "step of 0.1" needs epsilon 0.01, which is why the default sits there. If a photo comes back with edges intact but texture untouched, lower epsilon; if it comes back smeared like a heavy blur, you've pushed epsilon too high or the image has no strong edges to protect. And remember the joint-upsample direction: image is the one that gets moved to the guide's size, so put your full-res picture in guide, not the other way around.