BD Parts Refine

Ask a vision-language model to list a character's parts and it will enthusiastically describe the same thing three different ways - "shoe," "sneaker," "left shoe" - and then SAM3 happily produces a mask for each. Now your part pipeline has three overlapping masks for one foot, and every downstream step (crop, edit, export) treats them as separate parts. BD Parts Refine exists to collapse that: it clusters masks by pairwise IoU, picks one canonical label per cluster, and merges the geometry. Three entries become one "shoe."

The mechanism is exactly that: compute IoU between every pair of masks, and any pair above iou_threshold (default 0.7) joins the same cluster. Lower the threshold for more aggressive dedup. Per cluster it picks the canonical tag - the shortest label, on the theory that "shoe" is more general than "left sneaker" - and merges with merge_strategy:

• union (default) - pixel-wise max across the cluster. More inclusive, keeps every bit of all three masks.
• keep_largest - the member with the most pixels. Cleaner edges, but you lose the slivers the other masks added.

The inputs you'll actually set

• masks - the MASK batch, one per prompt.
• labels - one label per line, parallel to the masks.
• iou_threshold - 0.7 to start; lower only if genuine duplicates are surviving.
• min_pixels (default 64) - drops tiny masks before clustering, which filters the noise SAM3 throws out from low-confidence prompts.
• max_parts (default 0 = no cap) - cap the number of kept parts by area, largest first. If a prompt list produces 15 masks and you only want the 8 biggest, set it to 8.

Optionally wire image and flip output_debug_viz to get a color-coded overlay of the refined masks on the source - the fastest way to see which clusters formed and whether your threshold is doing what you think. Outputs: refined_masks, refined_labels, debug_overlay, and a summary string.

Where it sits

This is step two of the README's character parts pipeline: BD SAM3 Multi-Prompt → BD Parts Refine (iou_threshold=0.7) → BD Parts Builder → .... SAM3 Multi-Prompt hands over per-prompt masks from an open-vocabulary part list; Refine dedups them; Builder turns the cleaned set into a PARTS_BUNDLE of per-part crops. Skip Refine and your export gets duplicate "shoe" sprites.

Install

Part of ComfyUI-BrainDead - Manager search "BrainDead", or clone + pip install -r requirements.txt, restart. Under 🧠BrainDead/Segmentation; V3-API pack, so keep ComfyUI current.

The one judgment call is threshold tuning, and it's worth being deliberate about it. Too aggressive (0.5 and below) and genuinely distinct parts start merging - "left hand" and "right hand" have low IoU so they're safe, but two overlapping accessories might not be. Too conservative and duplicates survive. 0.7 is the pack's tested starting point for SAM3 output; if you see "shoe" and "left shoe" both surviving, drop toward 0.6. And remember the canonical tag choice is shortest-label-wins: if you care which name survives the merge, order your labels so the general term is the shortest.