Simswap Masking Helper

Raw Simswap output is a whole new image - swapped face and everything around it. Fine when the background is whatever, annoying when you only wanted the face to change and the swap has subtly re-rendered the neck, ears, or hairline. Simswap Masking Helper is the fix: it's a self-contained composite pass that builds a mask around the swapped face, cuts it out, and pastes it back onto the untouched original. You get a swap that changes the face and leaves the rest alone.

It's also the most capable node in this pack, and the most demanding. Fair trade.

What it actually does

Two images go in: the original image and the swapped_image that comes out of the main Simswap - Fast Face Swap node. Then a two-stage mask gets built:

1. A YOLO face detector (bbox_model_name) finds the face and hands you a rough bounding box.
2. A SAM model (sam_model_name) refines that box down to a precise face-shaped mask.

From there it's a tidy little post-processing chain: optional morphology (dilate / erode / open / close) to grow or shrink the mask, a Gaussian blur_radius to feather the edge, then it computes the mask's bounding box and cuts the swapped face out of swapped_image and pastes it into image. If you've used Impact Pack, this should feel familiar - it is Impact Pack's detect-mask-paste machinery (UltraBBoxDetector, make_sam_mask_segmented, the whole r_masking bag of tricks), shipped inside this pack. The loop is the same one FaceDetailer made famous; this version just skips the re-sampling.

The inputs that matter

Most of the inputs are Impact Pack defaults wearing a Simswap coat, and you can leave them alone at first. The ones you'll actually touch:

• bbox_threshold (0.5) - how confident the YOLO detector has to be before it counts something as a face.
• bbox_dilation (10) - grow the bounding box so it covers the whole face, not just the tightest crop. Negative shrinks.
• mask_hint_use_negative - False by default; Small or Outter includes the negative-region SAM hint. This is the "SAM gets confused, nudge it" knob.
• blur_radius (9) - the feather on the final paste. Too low and you'll see a hard edge; too high and the face starts to look soft.

mask_optional deserves a mention: pass in your own MASK and it skips the whole bbox+SAM dance and jumps straight to morph/blur/paste. That's the escape hatch when the automatic detection is fighting you.

The outputs

Three of them, and they're all useful:

• IMAGE - the composited result: original background, swapped face on top.
• MASK - the mask itself. Wire this into an inpaint node or a second sampling pass if you want to rework the face region rather than just composite it.
• MASK_PREVIEW - the mask rendered as an image so you can actually see what it decided.

Installing it

Standard for this pack, which is one GitHub repo shared by all its nodes:

cd ComfyUI/custom_nodes
git clone https://github.com/TaiTair/comfyui-simswap
# or: ComfyUI Manager → search "simswap" → install
# then restart ComfyUI

On first start the pack's install.py pip-installs its dependencies (pinned insightface==0.7.3, onnxruntime, onnx, opencv-python, numpy, segment_anything) and drops simswap_512_beta.onnx into ComfyUI/models/simswap/. But nothing in this pack downloads the models this node needs. The bbox_model_name and sam_model_name dropdowns read from ComfyUI/models/ultralytics and ComfyUI/models/sams - folders the pack creates but never fills. If both dropdowns are empty, that's your first stop: put a YOLO model (a yolo8x-face.pt or Impact Pack's bbox/segm files work) and a SAM checkpoint (sam_vit_b or sam_vit_h) in those folders.

Gotchas

• The pack is unmaintained - the README says so in so many words, and it's honest about being a personal, hacky port. Expect rough edges.
• If you already run Impact Pack you'll have the ultralytics and SAM models sitting there ready; if not, this node is the reason you're about to download a ~2GB SAM vit_h.
• InsightFace itself is the other classic pain point; the pack pins 0.7.3 because newer versions broke everything that depends on it. Let install.py do its thing and don't "help" by upgrading.

One more honest note: this node is the reason to use this pack over plain ReActor if you're here at all - the swap itself is fine, but the mask helper is where it actually shines.