🎭 ZenFace Detailer (Clownshark Edition)

An all-in-one ComfyUI face detailing node that combines face detection + inpainting + advanced sampling in a single node — no complex node chains required.

Detects faces using Impact Pack's BBOX detector, crops each face, re-samples with your chosen sampler/scheduler, and composites back with feathered blending. One node does it all.

---

✨ Features

• Automatic face detection via Impact Pack's BBOX_DETECTOR
• Per-face VAE encode → KSample → VAE decode pipeline
• Advanced sampler controls — choose any sampler, scheduler, noise type, and sampling mode (standard/unsample/resample)
• Shaped mask blending — ellipse, squircle, or rectangle masks for natural face-shaped transitions
• Smooth feathering — distance-transform-based feathering for artifact-free compositing, even at high denoise
• Blend modes — normal, soft light, and overlay blending for seamless integration
• Color matching — automatic per-channel color statistics transfer prevents color shifts at high denoise
• Mask expand/shrink — fine-tune the mask boundary before feathering
• Batch processing — handles multiple images in a batch
• Outputs both image and mask — use the mask for further processing downstream
• VAE-aligned crops — automatically pads face crops to multiples of 8

---

🚀 Installation

Prerequisites

This node requires ComfyUI Impact Pack to be installed (provides the BBOX_DETECTOR).

Option 1: Git Clone (Recommended)

cd ComfyUI/custom_nodes
git clone https://github.com/MONKEYFOREVER2/ComfyUI-ZenFaceDetailer.git
cd ComfyUI-ZenFaceDetailer
pip install -r requirements.txt

Restart ComfyUI.

Option 2: Manual Download

1. Click the green Code button → Download ZIP
2. Extract into ComfyUI/custom_nodes/
3. Rename folder to ComfyUI-ZenFaceDetailer if needed
4. Install dependencies:

   cd ComfyUI/custom_nodes/ComfyUI-ZenFaceDetailer
   pip install -r requirements.txt
   

5. Restart ComfyUI

Option 3: ComfyUI Manager

1. Open ComfyUI Manager → Install Custom Nodes
2. Search for ZenFace Detailer
3. Click Install → Restart ComfyUI

---

🎯 Finding the Node

Right-click → Add Node → Zen/Detailers → 🎭 ZenFace Detailer (Clownshark Edition)

---

⚡ Quick Start

1. Connect your MODEL, CLIP, VAE, positive/negative conditioning, and image
2. Connect a BBOX_DETECTOR (e.g. from Impact Pack's UltralyticsDetectorProvider)
3. That's it — defaults are tuned for good face detailing out of the box

Recommended Workflow

[Generate Image] → [🎭 ZenFace Detailer] → [SaveImage]
                          ↑
              [UltralyticsDetectorProvider] (bbox_detector)

---

🔧 Parameters

Inputs (Required Connections)

| Input | Type | Description | |-------|------|-------------| | image | IMAGE | The image to process | | model | MODEL | Your checkpoint model | | clip | CLIP | CLIP model for conditioning | | vae | VAE | VAE for encode/decode | | positive | CONDITIONING | Positive prompt conditioning | | negative | CONDITIONING | Negative prompt conditioning | | bbox_detector | BBOX_DETECTOR | Face detector from Impact Pack |

Face Detection Settings

| Parameter | Default | Description | |-----------|---------|-------------| | bbox_threshold | 0.5 | Detection confidence threshold (0–1) | | bbox_dilation | 10 | Expand/shrink detected bbox (pixels) | | bbox_crop_factor | 3.0 | How much area around the face to crop | | drop_size | 10 | Minimum face size to process (pixels) |

Mask & Feathering Settings

| Parameter | Default | Description | |-----------|---------|-------------| | mask_shape | ellipse | Shape of the compositing mask: ellipse (natural face shape), squircle (rounded rectangle), or rectangle | | feather_amount | 40 | Pixel radius of the soft feathered falloff (0–200). Higher = softer edges | | mask_expand | 0 | Expand (positive) or shrink (negative) the mask before feathering (-100 to 100) |

Blending Settings

| Parameter | Default | Description | |-----------|---------|-------------| | blend_mode | normal | How the detailed face blends: normal (standard alpha), soft_light (subtle, preserves shadows), overlay (contrasty, punchy) | | color_match | True | Match color statistics of the detailed region to the original — prevents color shifts at high denoise |

Sampler Settings

| Parameter | Default | Description | |-----------|---------|-------------| | noise_type_init | default | Noise type: default, gaussian, uniform, perlin, simplex | | eta | 0.0 | Ancestral sampling noise factor | | sampler_mode | standard | Sampling mode: standard, unsample, resample | | sampler_name | — | KSampler sampler (euler, dpmpp_2m, etc.) | | scheduler | — | KSampler scheduler (normal, karras, etc.) | | steps | 20 | Number of sampling steps | | cfg | 8.0 | Classifier-free guidance scale | | denoise | 0.45 | Denoise strength (lower = preserve more detail) | | seed | 0 | Random seed for reproducibility |

Outputs

| Output | Type | Description | |--------|------|-------------| | image | IMAGE | Processed image with detailed faces | | mask | MASK | Combined mask of all detected face regions |

---

💡 Blending Tips

| Scenario | Recommended Settings | |----------|---------------------| | Low denoise (< 0.5) | normal blend, feather_amount 20–40, color_match off | | High denoise (0.5–0.8) | soft_light blend, feather_amount 60–100, color_match on | | Very high denoise (> 0.8) | soft_light or overlay, feather_amount 100+, mask_shape ellipse, color_match on | | Multiple faces, different sizes | Use squircle shape if ellipse clips edges on small faces |

---

📋 Requirements

• ComfyUI (latest version recommended)
• ComfyUI Impact Pack — provides face detection
• opencv-python — listed in requirements.txt
• Python 3.10+

---

⚠️ Upgrading from v1.0

v1.1 replaces blur_mask with the new mask_shape, feather_amount, mask_expand, blend_mode, and color_match parameters. If you have existing workflows using the old node, you'll need to delete and re-add the ZenFaceDetailer node, or manually update your workflow JSON.

---

🤝 Contributing

Pull requests welcome! Feel free to open issues or PRs.

📄 License

MIT License — free to use, modify, and distribute.