ComfyUI Face Detection Node

ComfyUI Face Detection Node

A ComfyUI custom node for face detection and cropping using OpenCV Haar cascades — optimized for H100 cloud pipelines and LTX-Video avatar workflows. Full ComfyUI v3 schema support with backward compatibility for v1/v2.

Features

• Auto-Padding: Adaptive padding based on detected face size (no hardcoded values)
• Temporal Smoothing: Exponential moving average of bbox coordinates across video frames — eliminates jitter in batch/video processing
• Aspect Ratio Presets: 1:1, 9:16, 16:9, 4:3, auto — with forced crop recalculation
• Full Batch Processing: Iterates all batch items, outputs aligned batch tensors
• GPU-First: torch.no_grad() everywhere, minimal CPU transfers, stateless class-level caching
• Face Output Format: strip (horizontal layout) or individual (separate batch items) for multi-face output
• Dual Classifiers: Choose between default and alternative Haar cascades
• Proper Error Signaling: Returns flagged tensor + metadata when no face detected
• ComfyUI v3 Ready: Full schema support with async execution
• Legacy Workflow Compat: Handles old v1.x workflows with positional widgets_values misalignment gracefully

Installation

Via ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for "Face Detection Node"
3. Click Install

Manual Installation

1. Navigate to your ComfyUI custom nodes directory:

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

Usage

1. Add the "Face Detection and Crop v2" node to your workflow
2. Connect an image batch input
3. Adjust parameters as needed

Parameters

| Parameter | Type | Range | Default | Description | |-----------|------|-------|---------|-------------| | detection_threshold | Float | 0.1–1.0 | 0.8 | Face detection confidence threshold (0.1=lenient, 1.0=strict) | | min_face_size | Int | 32–512 | 64 | Minimum face dimension in pixels | | auto_padding_ratio | Int | 0–100 | 35 | Padding as percentage of detected face size | | aspect_ratio | Combo | — | auto | Crop aspect ratio: auto, 1:1, 9:16, 16:9, 4:3 | | output_mode | Combo | — | largest_face | largest_face or all_faces | | temporal_smoothing | Int | 0–100 | 0 | 0=disabled (image mode) · 1–100=EMA smoothing strength for video | | output_height | Int | 256–2048 | 512 | Output height for cropped faces (width derived from aspect ratio) | | instance_id | String | — | "0" | Unique ID for temporal smoothing (share across frames). Use "0" for image mode | | classifier_type | Combo | — | default | Haar cascade: default or alternative | | face_output_format | Combo | — | strip | strip (horizontal) or individual (separate batch items) | | padding | Int | 0–256 | 0 | Legacy padding in pixels — if >0, overrides auto_padding_ratio |

Outputs

| Output | Type | Description | |--------|------|-------------| | cropped_faces | IMAGE | Batch of cropped face tensors [B, H, W, C] | | face_metadata | FLOAT | Per-face metadata [x, y, w, h, score, detected] normalized to image dims. Shape: [B, 6] — NOT an image, use for downstream bbox logic only |

Temporal Smoothing for Video

When processing video frames through ComfyUI, face detection bboxes can jitter frame-to-frame. Enable temporal smoothing to stabilize:

• Set temporal_smoothing to 1–100 (higher = more smoothing)
• Use a consistent instance_id across all frames in the same video sequence
• Set to "0" for single-image mode (no smoothing)

Changelog

v2.1.3

• FIX: VALIDATE_INPUTS now includes required combo fields (aspect_ratio, output_mode, classifier_type) in its signature, forcing ComfyUI to delegate their validation to our method instead of doing strict framework-level "Value not in list" checks. Legacy workflows with misaligned positional widgets_values (e.g. 'auto' landing on output_mode, 0 landing on classifier_type) are now caught and replaced with defaults.
• FIX: Added defensive combo sanitization in both v1 and v3 execute methods — invalid combo values are replaced with defaults at runtime as a safety net.

v2.1.2

• FIX: instance_id input type changed from INT to STRING. Legacy workflows pass instance_id="default" (string) from old v1 nodes — ComfyUI's validate_inputs runs before execute(), so _coerce_int never fires. Since instance_id is only a dict key, STRING is the correct type.

v2.1.1

• FIX: temporal_smoothing input validation error — moved to optional section in INPUT_TYPES to prevent ComfyUI framework-level int() coercion crash when legacy workflows pass string "default" (from classifier_type) into this slot via positional widgets_values mapping
• FIX: Added _coerce_int() helper for safe string→int conversion with fallback to defaults, applied defensively in both v1 and v3 execute methods
• FIX: Enhanced VALIDATE_INPUTS to handle type mismatches gracefully (was only handling face_output_format before)

v2.1.0

• BACKWARD-COMPAT: Re-added optional face_output_format param (strip/individual) — old workflows now work; invalid values auto-fallback with warning
• BACKWARD-COMPAT: Re-added optional padding param — auto-converts to auto_padding_ratio
• FIX: all_faces mode now actually detects ALL faces (not just largest)
• FIX: OUTPUT_NODE=True on v3 schema
• FIX: VALIDATE_INPUTS on v1 wrapper to catch invalid combo values early

v2.0.0

• Auto-Padding, Temporal Smoothing, Aspect Ratio Presets, Full Batch Processing, GPU-First, Proper Error Signaling

Compatibility

• ComfyUI v3: Full schema support with async execution (DEFINE_SCHEMA)
• ComfyUI v1/v2: Backward compatibility via FaceDetectionNodeV1 wrapper class
• Auto-detection: Automatically selects appropriate implementation based on available ComfyUI API

Requirements

• Python ≥ 3.10
• OpenCV ≥ 4.5.0
• PyTorch ≥ 2.0.0
• NumPy ≥ 1.21.0

License

Apache License Version 2.0, January 2004 — see LICENSE file for details.