BD Mask Correlate

BD Mask Correlate is the node that reconciles two very different kinds of masks. On one side you have precise candidates - SAM3 segments, pixel-accurate but unpredictable, one per prompt in a batch. On the other side you have coarse guides - MediaPipe face hulls, reliable location but rough shape. This node matches the precise candidates to the coarse targets by IoU, then combines each pair in a mode you choose. If you've ever watched a SAM3 "eyes" segment drift onto the cheek, this is the leash.

The workflow it serves is the pack's face-segmentation pipeline: BD MediaPipe Face Mask gives you tight per-feature hulls (eyes, brows, lips), SAM3 gives you pixel-accurate segments, and BD Mask Correlate is the middle layer that says "that SAM3 segment belongs inside this hull." For each wired target (up to 8), it finds the candidate with the highest overlap and merges them. Result: masks that have SAM3's pixel fidelity and MediaPipe's structural sanity.

The inputs that matter

• candidates - the SAM3 batch (per_prompt_masks). One frame = one candidate segment.
• target_1 … target_8 - your coarse guide masks, e.g. the left_eye, right_brow, lips outputs from BD MediaPipe Face Mask. Leave unwired to skip a slot.
• mode - the default combine mode for all slots. intersect (default) clips the candidate to the target region - the safest choice for eyes/brows/lips so SAM3 stays inside the MediaPipe hull. replace uses the raw SAM3 segment (right for skin, where SAM3's boundary is the good part). union and weighted_blend exist for the other cases. You can override per-slot in slot_modes (one label: mode per line).
• min_iou - acceptance threshold (default 0.05, very permissive). Raise to 0.2+ if candidates keep matching the wrong target. When nothing qualifies, fallback decides between returning the original target (original) or an empty mask (blank).
• exclusive - when ON, each candidate can be claimed by only one target, assigned in priority order. When OFF, one SAM3 segment can match several targets - fine for non-overlapping features, wrong if segments overlap.
• subtract_slots - post-match subtraction, the skin-pipeline trick. Lines like skin: eyes, brows, lips subtract the refined eye/brow/lip masks from the skin mask, cutting precise feature holes out of a broad skin region.
• target_expand - dilate targets before matching. If MediaPipe's hull is tight and SAM3's segment sits just outside it, 4–10 px of expansion fixes the match without loosening the final mask.

There's also max_target_fill (default 0.95) which exists for a specific failure mode: when a SAM3 prompt isn't found, the multi-prompt node can return a full-white mask, and a full-white target scores high IoU against everything. This rejects targets covering more than 95% of the frame.

Outputs

You get refined_1…refined_8 (one per slot, blank if unwired), a combined_mask (union of all matched slots, optionally clipped by a silhouette_mask), and masked_image - the reference image composited with the matched union as alpha. invert_masked_image flips it to show everything except the matched regions (e.g. the face with eyes and lips cut out), and combined_mask_invert does the same as a MASK. The debug_overlay is color-coded per slot - wire it to a preview and you'll see instantly which candidates landed where, which is usually faster than reading match_info.

Installing

Same as the whole pack - ComfyUI Manager search "BrainDead", or clone + pip install -r requirements.txt + restart. All V3 API.

The mental shortcut: intersect mode + subtract_slots is the recipe this pack actually uses for faces - SAM3 defines the skin boundary, MediaPipe keeps the features in bounds, subtraction carves the features out of the skin. Start there and only reach for the exotic modes when you have a specific failure.