ComfyUI-JH-PixelPro

<div align="center">

PixelPro for ComfyUI

Pro-grade retouch, colour and mask tools for ComfyUI — 64 GPU nodes built on PyTorch + Kornia.

English · Tiếng Việt · Documentation

</div>

What it is

PixelPro brings the techniques of a professional retouching desk into ComfyUI as plain nodes: frequency separation, luminosity masks, LAB colour matching, LUTs, a Photoshop-style layer stack, hair-accurate alpha mattes, face alignment and paste-back, plus QA metrics to check your result.

• Real retouch techniques, not renamed filters: every node does what a retoucher expects from its name.
• GPU first, CPU safe. Heavy filters run on CUDA with bounded memory, and everything also runs on CPU.
• Built for AI pipelines. Align a face, run inpaint or ControlNet, paste it back seamlessly. Masks work with any segmenter.
• Tested and documented. 800+ automated tests, sample workflows, and a bilingual guide for every node.

<table> <tr> <td><img src="docs/assets/nodes/frequency-separation.jpg" alt="Frequency Separation"></td> <td><img src="docs/assets/nodes/alpha-matte.jpg" alt="Alpha Matte"></td> </tr> <tr> <td align="center"><b>Frequency Separation</b> — colour and detail on separate layers</td> <td align="center"><b>Alpha Matte</b> — trimap to a hair-accurate alpha</td> </tr> <tr> <td><img src="docs/assets/nodes/color-matcher-region.jpg" alt="Color Matcher Region"></td> <td><img src="docs/assets/nodes/pyramid-blend.jpg" alt="Pyramid Blend"></td> </tr> <tr> <td align="center"><b>Color Matcher Region</b> — match skin to skin, sky to sky</td> <td align="center"><b>Pyramid Blend</b> — composites without a visible seam</td> </tr> </table>

Install

ComfyUI Manager: search for ComfyUI-JH-PixelPro, install, restart ComfyUI.

Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/jetthuangai/ComfyUI-JH-PixelPro.git
cd ComfyUI-JH-PixelPro
pip install -r requirements.txt   # use the Python that runs ComfyUI

Restart ComfyUI. The nodes appear under Add Node → ComfyUI-JH-PixelPro.

Requirements: Python 3.10+, PyTorch (from ComfyUI), Kornia ≥ 0.7, MediaPipe ≥ 0.10, OpenCV ≥ 4.8, SciPy ≥ 1.10. Optional: onnxruntime-gpu (or onnxruntime) for Depth Anything and Depth Lens Blur. An NVIDIA GPU with 8 GB+ VRAM is recommended; CPU works too.

Quick start

1. Copy workflows/sample_portrait.jpg (and sample_binary_mask.png) into ComfyUI/input/.
2. Drag any workflow from workflows/ onto the canvas, for example the CLAHE, Face Detect Lite or Mask Cleanup examples.
3. Queue the prompt and change one setting at a time.

Full walk-through: Quickstart.

The 64 nodes

Each name links to its guide (settings, tips, before/after image).

Color & Tone · 21

| Node | What it does | |---|---| | ColorLab | Camera Raw style panel in tabs: exposure, contrast, highlights/shadows, texture, clarity, dehaze, white balance, HSL, colour-grading wheels, B&W mix; edge-aware local engine; outputs its settings as a preset. | | Shadows/Highlights Pro | Lift shadows and recover highlights without halos, Camera Raw or Photoshop style. | | HDR Merge (bracket) | Fuse bracketed exposures into one image with detail in shadows and sky (aligned, deghosted). | | Defringe | Remove purple/green fringes along high-contrast edges and lateral chromatic aberration. | | Auto: Tone & White Balance | One-click exposure, Whites/Blacks, Highlights/Shadows and colour cast; outputs the settings for ColorLab. | | Apply ColorLab Preset | Put a ColorLab look on any photo or batch, with strength and mask. | | Lightroom Preset (XMP) | Use Lightroom / Camera Raw presets (.xmp, .lrtemplate) with a thumbnail browser, favourites and a report. | | Lightroom Preset Contact Sheet | Compare a whole preset collection on one photo. | | Tone Curve | Smooth master or per-channel RGB curves with presets. | | Color Matcher | Transfer the colour of a reference photo in LAB. | | Color Matcher Region | Match colour between two masked regions, any image sizes. | | CLAHE Local Contrast | Adaptive local contrast on lightness only; colours stay put. | | Hue/Saturation per Range | Shift hue or saturation of one colour band. | | Luminosity Masking | Shadow, midtone and highlight masks. | | Saturation Mask | Select by colour strength. | | LUT Preset | Bundled .cube looks from a dropdown. | | LUT Import | Apply any .cube LUT, with mask and strength. | | LUT Export | Bake a graded HALD into a .cube file. | | HALD Identity | Neutral HALD image to grade into a LUT. | | Tone Match LUT | Generate a .cube from one graded reference frame. | | Palette Extract | Dominant colours as swatches + HEX, and a flat-colour version. |

Masks · 13

| Node | What it does | |---|---| | Sub-Pixel Mask Refiner | Turn a hard mask into a soft alpha edge, protecting the inside and outside. | | Edge-Aware Mask Refiner | Snap a mask edge to the real edges of the photo (guided filter, brightness or colour edges). | | Trimap Builder | Foreground / unknown / background map for matting. | | Alpha Matte | Closed-form matting: hair-accurate alpha from a trimap. | | Sky Mask | Soft mask of the sky without an AI model, edges refined on the photo. | | Decontaminate Colors | Remove green-screen or sky fringes from a cut-out's soft edges. | | Mask Morphology | Grow, shrink, open, close and other shape operations on a mask. | | Mask Combine | Add, subtract, intersect, union or multiply two masks. | | Mask Edge Smoother | Bilateral cleanup of jagged mask edges (CPU or GPU). | | Mask Cleanup | Remove specks, fill holes, distance feather. | | SAM One-Click Mask | Segment Anything from one point, a face box or a rough mask. | | Mask Preview | See any mask as overlay, heatmap or cutout. | | Detail Mask | Mask of fine detail (hair, eyes, texture) to protect or sharpen. |

Face · 9

| Node | What it does | |---|---| | Face Detect | MediaPipe face boxes and 5-point landmarks. | | Face Detect Lite | Fast YuNet detector on the GPU, with a face mask and real confidence. | | Face Landmarks | 468-point face mesh for reshaping. | | Face Warp | Reshape by moving landmarks (per-triangle). | | Face Warp TPS | Same idea with one smooth thin-plate-spline field, no seams. | | Unwrap Face | Paste an edited aligned face back onto the original. | | Face Beauty Blend | Blend a retouched face plate in with mask and strength. | | Auto Blemish | Find faces and heal pimples and small marks on the skin, keeping pores. | | Skin Tone Tri-Region | Shadow / midtone / highlight masks of the skin. |

Compositing · 5

| Node | What it does | |---|---| | Layer Stack Start | Start a layer stack from a background. | | Layer Add | Add a layer with blend mode, opacity, fill, mask and clipping. | | Layer Group | Nest a sub-stack as one grouped layer. | | Layer Flatten | Render the stack to an image. | | Pyramid Blend | Multi-band blending for seamless composites. |

Filters · 7 · Depth · 2 · Geometry · 4 · Looks · 1 · QA · 2

| Node | What it does | |---|---| | Frequency Separation | Split colour/tone (low) from texture (high). | | Frequency Recombine | Rebuild the image from low + high, with a texture amount. | | Skin Smoother | Edge-preserving skin smoothing with mask and strength. | | Smart Sharpen | Unsharp mask on luminance, with threshold and mask. | | Dust & Spot Removal | Heal small specks and dust, leave larger details alone; smooth or texture-keeping fill. | | Heal / Content-Aware Fill | Paint what should go; it is rebuilt from the rest of the photo. | | Motion / Zoom Blur | Directional motion blur or zoom burst, with a mask. | | Depth Anything V2 | Depth map from a single photo (Small model: Apache-2.0). | | Depth Lens Blur | Bokeh from depth, focus picked by a face or subject mask. | | Facial Aligner | Align a face to a standard square crop; outputs the matrix Unwrap Face needs to paste it back. | | Lens Distortion | Correct or add barrel/pincushion distortion. | | Auto Align | Align a second shot to a reference (SIFT or LoFTR). | | Auto: Upright | Level horizons and make converging verticals parallel, from the photo's lines. | | Look Select | Finished colour looks with intensity. | | Cull Score | Rank a batch by sharpness, exposure, closed eyes and duplicates; keep the best. | | QA Image Diff | SSIM, PSNR and a diff heatmap between two images. |

Documentation

• Guide (EN / VI): https://jetthuangai.github.io/ComfyUI-JH-PixelPro/
• Sample workflows: workflows/README.md
• Changes: CHANGELOG.md

License

Apache-2.0. See LICENSE. Sample portrait by cottonbro studio on Pexels (Pexels License).

Maintained by JH (@jetthuangai).