ComfyUI Node
Person Data Refiner
Regenerate PERSON_DATA masks at a new image resolution. Use after upscaling: takes original person_data + hi-res images, re-detects faces and regenerates all masks at the new resolution while preserving face-to-reference assignments. Accepts either sam_model (SAM2) or sam3_model (SAM3) for body masks. SAM3 takes priority when both are connected. Chainable: when image resolution matches person_data, skips face re-detection entirely and just runs YOLO aux detection. Chain multiple refiners with different aux_model/aux_label combos to build separate aux mask passes (hands, feet, etc.). Optional depth map input improves masks by filling gaps and removing overlapping objects using depth coherence.
Person Data Refiner
- person_data
- images
- sam_model
- sam3_model
- depth_map
- person_data
- aux_masks
- report
◄mask_fill_holestrue►
◄mask_blur0►
◄det_size640►
◄depth_edge_threshold0.05►
◄depth_carve_strength0.80►
◄depth_grow_pixels30►
◄aux_model▾►
◄aux_confidence0.35►
◄aux_label►
◄aux_fill_holesfalse►
◄aux_expand_pixels0►
◄aux_blend_pixels0►
◄aux_yolo_sam_refinetrue►
◄aux_yolo_sam_bbox_expansion0►
CategoryFVM Tools/Face
Inputs (19)
| Name | Type | Default | Description |
|---|---|---|---|
| person_data | PERSON_DATA | Original PERSON_DATA from Person Selector Multi / SAM3 | |
| images | IMAGE | New images (batch size must match original person_data) | |
| mask_fill_holes | BOOLEAN | true | — |
| mask_blur | INT | 00–100 | — |
| det_size | COMBO | 640 | Face detection resolution |
| sam_modelopt | SAM_MODEL | SAM2 model for body mask generation (fallback when sam3_model not connected) | |
| sam3_modelopt | SAM3_MODEL_CONFIG | SAM3 model from LoadSAM3Model. Takes priority over sam_model when both connected. | |
| depth_mapopt | IMAGE | Depth map batch for depth-guided mask refinement | |
| depth_edge_thresholdopt | FLOAT | 0.050.01–0.3 | Depth gradient threshold for edge detection |
| depth_carve_strengthopt | FLOAT | 0.800–1 | How strongly depth edges cut masks |
| depth_grow_pixelsopt | INT | 300–200 | Gap filling between depth edges |
| aux_modelopt | COMBO | YOLO segm model for body-part detection (hands, feet, etc.). Runs on the current images and injects results into person_data["aux_masks"]. Chainable: each refiner replaces aux_masks, so chain multiple refiners with different models/labels for separate aux passes. Set to 'none' to skip YOLO. If aux_label is non-empty AND a SAM3 model is connected, the refiner falls back to SAM3 text-grounded segmentation using aux_label as the prompt. | |
| aux_confidenceopt | FLOAT | 0.350.05–1 | Detection confidence threshold. YOLO path: per-detection score gate. SAM3-text-aux path: passed as the SAM3 grounding threshold (lower = more permissive). |
| aux_labelopt | STRING | YOLO path: filter detections by class label (substring match; comma-separated for multiple, e.g. 'hand,foot'). Empty = all classes. SAM3-text-aux path (when aux_model='none'): this is the SAM3 grounding prompt itself, e.g. 'legs', 'arms'. Comma-separated values are run as separate prompts and unioned. | |
| aux_fill_holesopt | BOOLEAN | false | Fill holes inside YOLO aux masks |
| aux_expand_pixelsopt | INT | 00–100 | Dilate YOLO aux masks by N pixels |
| aux_blend_pixelsopt | INT | 00–100 | Gaussian blur radius for YOLO aux mask edges |
| aux_yolo_sam_refineopt | BOOLEAN | true | On (default): refine bbox-only YOLO detections into pixel masks using SAM3 (priority) → SAM2 (fallback). Off: use raw bbox rectangles as aux masks (today's bbox-only behavior). |
| aux_yolo_sam_bbox_expansionopt | INT | 00–64 | Pixels to expand bbox before SAM refinement (helps thin objects). |
Outputs (3)
| Name | Type | Description |
|---|---|---|
| person_data | PERSON_DATA | — |
| aux_masks | MASK | — |
| report | STRING | — |