ComfyUI Extension: ComfyUI-FaceFilter
ComfyUI nodes for face based filtering plus image batch merging.
Custom Nodes (0)
README
ComfyUI Face Filter
Two nodes for ComfyUI (face based filtering and batch merge).
What you get
- FaceFilter node (filter images by face similarity relative to reference images)
- MergeImageBatches (merge two image batches index by index with simple rules)
Install
-
Install the node manually by going to
ComfyUI/custom_nodes/
and runninggit clone [email protected]:Kidev/ComfyUI-FaceFilter.git
-
Install Python deps:
pip install -r ComfyUI-FaceFilter/requirements.txt
-
Models (InsightFace packs)
- Default search paths (both are supported automatically)
~/.insightface/models
(home cache)<this repo>/models/insightface
(local repo models)
- Example pack folder name
antelopev2
- Default search paths (both are supported automatically)
-
Restart ComfyUI
Optional helper
python install.py
This only ensures the two model folders exist and prints where to drop packs.
Nodes
FaceFilter
Inputs
ref_images
(IMAGE) reference images that define the target identity setcandidate_images
(IMAGE) images to test and filterthreshold
(FLOAT) cosine similarity threshold (default0.30
)on_empty_matching
(CHOICE) behavior when matching is empty (return_empty
orblack_51
2 orpass_through
)on_empty_rejected
(CHOICE) behavior when rejected is empty (same choices)debug
(BOOLEAN) return a debug string with counts and scoresmodel_name
(CHOICE) an auto discovered InsightFace pack name (exampleantelopev2
)providers
(CHOICE)auto(cuda+cpu)
orcpu_only
detector_size
(INT) face detector working sizeresize_mode
(CHOICE)fit_min_side
orfit_longest_side
Outputs
MATCHING
(IMAGE) batch of accepted candidates (faces matching one of the reference faces)REJECTED
(IMAGE) batch of rejected candidatesDEBUG
(STRING) multi line diagnostics when enabled
Behavior
- Embeddings are L2 normalized
- Cosine similarity against the reference set
- Accept if any ref is above
threshold
- Stable fallbacks keep downstream graphs valid when a batch is empty
MergeImageBatches
Inputs
batch1
(IMAGE)batch2
(IMAGE)prefer
(CHOICE) pickbatch1
orbatch2
when both look valid
Output
MERGED
(IMAGE)
Rule
- For each index pick the non black image if the other is black or empty
- If both valid pick according to
prefer
Examples
A simple filter
Workflow avaiable here: (FaceFilter-simple.json)
A simple usage of the FaceFilter node: the images in the candidates that have pictures with the same face in the reference batch of images are passed to the matching group, the others to the rejected group.
Face matching faceswap using FaceFilter and ReActor
Workflow avaiable here: (FaceFilter-Faceswap.json)
A simple faceswap tool that will swap the faces of particular persons with another. It does not uses indices or face position, only the face of the target using the FaceFilter node.
Performance tips
- Use
providers=auto(cuda+cpu)
on machines with CUDA detector_size=256
is a good balance- Keep one model pack (example
antelopev2
) available in either supported path