🪐TTP Tile Preprocessor HYDiT GF

This is the tile preprocessor to reach for when a plain Gaussian blur flattens your image into soup. It lives in the TTP pack, the "for comfyui image proprocessor" repo from TTPlanetPig - the same person behind the TTPLanet ControlNet tile models and the TTP Toolset for LTX 2 frame control. The README is one line ("Adapt for Hunyuan now"), so nobody is going to hand you a manual. Good news: the code is only about forty lines of OpenCV, and it does something genuinely useful.

What it's for

Tile ControlNet is the foundation of tiled upscaling workflows. The idea: the preprocessor feeds a detail-stripped version of your image to the tile model, and the model spends its denoising budget adding detail back while staying faithful to the source. That's what makes the "tile controlnet + tiled diffusion = very realistic upscaler" recipe work, and it's also how people do style transfer at low control weight.

Most tile preprocessors blur first and hope. The GF version smooths with an edge-preserving guided filter instead, so texture and compression noise get scrubbed without smearing the hard edges the ControlNet actually wants. If you've ever seen a tile upscale come out plastic because the preprocessor nuked every boundary, this is the fix for that specific failure.

How it works

Reading the source, the pipeline is: Gaussian blur → guided filter (cv2.ximgproc.guidedFilter) → downscale by scale_factor with area interpolation → upscale back with linear interpolation → return. The downscale/upscale round trip is the classic tile trick - resample to a lower resolution so the model has to invent detail on the way back up. The guided filter is the twist: it's a local edge-aware smoothing that keeps gradients sharp.

The inputs that matter

Only five, and honestly three of them are worth touching:

• image - your input. Any size; it's processed in RGB and handed back the same dimensions.
• scale_factor (1–8, default 1) - how far down it resamples before coming back up. Note the default is 1.0, which makes the round trip a no-op. If you want the strip-and-rebuild effect, bump it to 2–4; the default basically just blurs.
• blur_strength (1–10, default 2) - the Gaussian kernel size and, implicitly, how aggressively fine detail is killed.
• radius and eps - the guided filter's two knobs. Radius is the smoothing window (default 7), and eps (default 0.01) is the edge-preservation threshold. Lower eps = more edges kept. Set-and-forget for most people.

The single output is image_output, an IMAGE tensor that wires straight into your tile ControlNet's image input (typically through an Apply ControlNet node with a tile model loaded).

Installing it

Easiest path is ComfyUI Manager - search "Comfyui_TTP_CN_Preprocessor" (or "TTPlanet") and hit install. Manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/TTPlanetPig/Comfyui_TTP_CN_Preprocessor
# restart ComfyUI

No model downloads, no API keys, nothing to fetch. The only Python dependency the pack declares is opencv-python-headless, and torch/numpy/PIL come from ComfyUI itself. The "HYDiT" in the display name is branding for Hunyuan DiT, but the math here is base-agnostic - it works with any tile ControlNet on SDXL, Hunyuan DiT, or whatever else.

The one gotcha

The guided filter lives in cv2.ximgproc, which is not part of the standard opencv-python distribution - it ships in opencv-contrib. On a fresh ComfyUI install you will likely hit:

AttributeError: module 'cv2' has no attribute 'ximgproc'

The pack's requirements.txt only pulls in opencv-python-headless, which won't help. Fix it once, per environment:

pip install opencv-contrib-python-headless

That's the single most common way this node fails, and it's not your fault when it does.

Bottom line

It's a small, dependency-light preprocessor that does the tile trick with better edge discipline than a plain blur. The GF variant is the one I'd actually reach for in this pack - just remember to set scale_factor above 1, and expect to install the contrib OpenCV if you're on a bare setup.