ComfyUI Node
BD Mask Correlate
Match coarse guide masks (targets) to a batch of precise candidate masks by IoU. For each wired target the candidate with highest overlap is selected and combined with the target using the chosen mode. Includes colour-coded debug overlay and priority ordering for exclusive assignment.
BD Mask Correlate
- candidates
- reference_image
- silhouette_mask
- target_1
- target_2
- target_3
- target_4
- target_5
- target_6
- target_7
- target_8
- refined_1
- refined_2
- refined_3
- refined_4
- refined_5
- refined_6
- refined_7
- refined_8
- debug_overlay
- match_info
- masked_image
- combined_mask
◄masked_image_bgtransparent►
◄invert_masked_imagefalse►
◄combined_mask_invertfalse►
◄combined_mask_exclude►
◄labelsleft_brow
right_brow
left_eye
right_eye
lips►
◄priorities►
◄min_iou0.05►
◄modeintersect►
◄slot_modes►
◄fallbackoriginal►
◄target_expand0►
◄exclusivefalse►
◄max_target_fill0.95►
◄subtract_slots►
◄overlay_alpha0.55►
Category🧠BrainDead/Segmentation
Inputs (26)
| Name | Type | Default | Description |
|---|---|---|---|
| candidates | MASK | Batch of precise candidate masks (B, H, W) — e.g. SAM3 segment output. Each frame in the batch is a separate candidate segment. | |
| reference_imageopt | IMAGE | Original character image. When wired: • Used as the base for the debug overlay • Produces masked_image (union of all matched slots applied as alpha) Leave unwired to composite the debug overlay on black. | |
| silhouette_maskopt | MASK | Head or body silhouette (white=subject, black=background). When wired, all output masks are clipped to this boundary after matching. Useful for ensuring matched segments don't bleed outside the head/body shape. | |
| masked_image_bgopt | COMBO | transparent | Background for the masked_image output when reference_image is wired. transparent → RGBA output, background is fully transparent white / black → RGB composite over solid colour checker → grey checkerboard (visually indicates transparency) |
| invert_masked_imageopt | BOOLEAN | false | When True, masked_image shows everything EXCEPT the matched regions — the inverse composite. If silhouette_mask is wired: image × (silhouette − union_of_matched) — shows the subject with matched areas cut out (e.g. remove eyes/lips from face). If silhouette_mask is not wired: image × (1 − union_of_matched). Useful for: baking a head mask that has feature holes, or showing the non-feature areas of the subject. |
| combined_mask_invertopt | BOOLEAN | false | When True: combined_mask = silhouette_mask − union (if wired) or 1 − union. Gives you the head-minus-features shape as a mask — same logic as invert_masked_image but as a MASK output for downstream use. |
| combined_mask_excludeopt | STRING | Comma-separated labels or 1-based slot indices to EXCLUDE from the combined_mask output (and from the union used in masked_image). Example: 'skin' or '1' — skin slot is excluded so combined_mask = union of eyes + eyebrows + lips only, not the skin region. Useful when one slot is a large 'base' mask (skin, clothing) and you want combined_mask to represent just the smaller feature masks. | |
| labelsopt | STRING | left_brow right_brow left_eye right_eye lips | One label per line, aligned with target_1..target_N slots. Used for the match_info status string and overlay legend. |
| prioritiesopt | STRING | Comma-separated priority values for each slot, aligned with target_1..N. Higher value = matched first in exclusive mode (gets first pick of candidates). Example: '2,2,1,1,3' — slot 5 (lips) gets first pick, slots 1-2 (brows) second, slots 3-4 (eyes) last. Empty (default) = all slots equal priority, processed in slot order. | |
| min_iouopt | FLOAT | 0.050–1 | Minimum IoU for a candidate to be accepted as a match. 0.05 is permissive (any reasonable overlap counts). Raise to 0.2+ if candidates are bleeding into the wrong target regions. |
| modeopt | COMBO | intersect | Default combine mode for all slots: intersect — candidate clipped to target region (safest; use for eyes/brows/lips so SAM3 segments stay within MediaPipe hull bounds). replace — raw SAM3 segment used directly (use for skin — lets SAM3 define the boundary, then subtract_slots removes features). union — expand target by candidate shape. weighted_blend — smooth blend biased toward confident candidate areas. Override per slot with slot_modes. |
| slot_modesopt | STRING | Per-slot mode overrides — one line each: label_or_index: mode Overrides the global mode setting for specific slots. All others use mode. Example: skin: replace left_eye: intersect Typical skin pipeline: skin: replace ← SAM3 defines the skin boundary (pixel-accurate) (all feature slots stay on intersect — clipped to MediaPipe hull) subtract_slots: skin: eyes, brows, lips ← then remove features Valid modes: intersect, replace, union, weighted_blend | |
| fallbackopt | COMBO | original | What to output for a target slot when no candidate meets min_iou: original — return the unmodified target mask. blank — return an empty mask (signals 'no confident match'). |
| target_expandopt | INT | 00–60 | Pixels to dilate each target mask BEFORE computing IoU. Useful when MediaPipe landmarks produce a tight hull that doesn't fully overlap the actual SAM3 segment. 4–10 px is usually enough. |
| exclusiveopt | BOOLEAN | false | When True each candidate can only be matched to ONE target (assigned in priority order, highest first). When False the same SAM3 segment can match multiple targets (safe for non-overlapping features like left/right brow). |
| max_target_fillopt | FLOAT | 0.950–1 | If a target mask covers MORE than this fraction of the image, treat it as invalid and apply the fallback instead of attempting to match. Why: BD_SAM3MultiPrompt with invert_negative=True returns a FULL WHITE mask when a prompted item is not found. A full-white target has high IoU with every candidate, causing false matches across the whole image. 0.95 (default) rejects masks covering >95% of pixels. Set to 1.0 to disable. Lower values (e.g. 0.7) also reject partial-failure masks — useful when SAM3 returns an overly broad segment for a missed prompt. |
| subtract_slotsopt | STRING | Post-matching subtraction rules. Each line: target: source1, source2, ... Tokens can be label names (from the labels field) or 1-based slot numbers. After all slots are matched, the listed source refined masks are subtracted from the target refined mask — useful for cutting precise eye/brow/lip regions out of the skin mask. Example: skin: eyes, brows, lips 1: 3, 4, 5 Subtraction clamps to 0 (no negative values). Applied in line order. | |
| overlay_alphaopt | FLOAT | 0.550–1 | Opacity of the colour overlay on the debug image. 0 = overlay invisible, 1 = solid colour. Unmatched/fallback slots show at 40% of this value in grey. |
| target_1opt | MASK | Target slot 1 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_2opt | MASK | Target slot 2 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_3opt | MASK | Target slot 3 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_4opt | MASK | Target slot 4 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_5opt | MASK | Target slot 5 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_6opt | MASK | Target slot 6 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_7opt | MASK | Target slot 7 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. | |
| target_8opt | MASK | Target slot 8 — coarse guide mask (e.g. from BD_MediaPipeFaceMask). Leave unwired to skip this slot. |
Outputs (12)
| Name | Type | Description |
|---|---|---|
| refined_1 | MASK | Refined mask for target slot 1. Blank (zeros) if slot was not wired. |
| refined_2 | MASK | Refined mask for target slot 2. Blank (zeros) if slot was not wired. |
| refined_3 | MASK | Refined mask for target slot 3. Blank (zeros) if slot was not wired. |
| refined_4 | MASK | Refined mask for target slot 4. Blank (zeros) if slot was not wired. |
| refined_5 | MASK | Refined mask for target slot 5. Blank (zeros) if slot was not wired. |
| refined_6 | MASK | Refined mask for target slot 6. Blank (zeros) if slot was not wired. |
| refined_7 | MASK | Refined mask for target slot 7. Blank (zeros) if slot was not wired. |
| refined_8 | MASK | Refined mask for target slot 8. Blank (zeros) if slot was not wired. |
| debug_overlay | IMAGE | Colour-coded debug image: each matched slot in a distinct colour, unmatched slots in dimmed grey. Wire to PreviewImage to inspect results. |
| match_info | STRING | Per-slot match summary: label, best candidate index, IoU, mode used. |
| masked_image | IMAGE | reference_image composited with the union of all matched slot masks as alpha. With invert_masked_image=True: shows everything EXCEPT the matched regions (clamped to silhouette_mask if wired). Requires reference_image to be wired. Background controlled by masked_image_bg. |
| combined_mask | MASK | Union of all wired+matched refined slot masks as a single MASK. Clipped to silhouette_mask if wired. Use downstream to treat all matched regions as one shape. |