ReActor 🌌 Masking Helper

A plain face swap replaces a rectangle. That's usually fine, until it isn't - a hard edge where the swapped patch meets the original, hair or glasses that got clipped, a jaw that doesn't quite line up. ReActor Masking Helper (class ReActorMaskHelper) is the cleanup crew. It detects the face, builds a precise mask around it, and composites the swapped face back onto the original image only inside that mask, with a feathered edge. Everything outside the face - hair, background, ears, neck - stays untouched, and the seam blends instead of showing. Added in 0.5.0, it's the node you reach for when a swap is technically right but looks pasted-on.

If this sounds like ADetailer or Impact Pack's FaceDetailer, that's because it's the same lineage: a YOLO detector finds the face, and SAM (Segment Anything) refines the box into a tight, face-shaped mask. ReActor just wires that detect-and-mask machinery specifically to the swap-compositing job.

How it works

You give it two images: image (the original target) and swapped_image (ReActor's output). A YOLO bbox model locates the face and SAM segments it into a mask that follows the actual face outline rather than a rectangle. The node then blends swapped_image into image within that mask, feathering the boundary so there's no visible cut. The masked-swap approach is exactly the "detect a region, then only touch that region" pattern the community relies on to fix faces without disturbing the rest of the frame.

The inputs and outputs that matter

There are a lot of knobs here - it exposes nearly the full detection/SAM stack - but a beginner touches maybe three:

• bbox_model_name - the detector. Pick bbox/face_yolov8m.pt for faces (the other options detect hands or whole persons). This is the one that has to be right, and it has to be downloaded (see install).
• bbox_dilation / sam_dilation - grow (or shrink, with negatives) the mask. If the swap is getting clipped at the edges, nudge dilation up so the mask covers a bit more; if it's bleeding onto hair, pull it in.
• blur_radius - how soft the mask edge is (default 9). This is your seam-hider. More blur means a gentler, less detectable transition; too much and the swap ghosts into the original.

The rest - bbox_threshold (detection confidence), sam_threshold, bbox_crop_factor, morphology_operation, sigma_factor and friends - are fine on defaults until you have a specific problem to solve. There's also an optional mask_optional input if you'd rather supply your own mask than have it detected.

Four outputs: IMAGE (the final composited result - the one you save), MASK (the generated face mask, reusable downstream), MASK_PREVIEW (a visual of the mask for debugging what got selected), and SWAPPED_FACE (the isolated swapped face). Wire IMAGE onward; glance at MASK_PREVIEW when a result looks wrong.

How to install it

Comes with the ReActor pack. ComfyUI Manager: search ReActor, install, restart. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/Gourieff/comfyui-reactor-node

then run install.bat / install.py and restart. This node needs two extra model downloads the README calls out explicitly: put face_yolov8m.pt into ComfyUI/models/ultralytics/bbox, and sam_vit_b_01ec64.pth into ComfyUI/models/sams (both are on the ReActor HF dataset). Miss these and the model dropdowns come up empty and the node can't run.

Common issues & troubleshooting

"No detection" / the node errors out. Two usual causes. Either face_yolov8m.pt/sam_vit_b aren't in the folders above, or the face is too small or too turned for the detector. The README specifically shipped a 0.5.0 fix for a "No detection" bug in this node, so also make sure you're updated. Lower bbox_threshold slightly to catch a harder face.

Visible seam or halo around the face. Raise blur_radius to soften the edge, and adjust bbox_dilation so the mask isn't cutting through the jaw or hairline. Check MASK_PREVIEW to see exactly what's being selected.

The mask grabs too much (hair, background) or too little. That's dilation. Negative bbox_dilation/sam_dilation shrink it; positive grows it. Tune against the MASK_PREVIEW output rather than guessing.

It errors after a ReActor update. This pack changes input sockets between versions - the author's own first move is to delete the node and re-add it fresh. And if the whole menu is missing, that's InsightFace failing to build at the pack level (the recurring Visual Studio / C++ toolchain problem); use the prebuilt Insightface wheel the README links. As always, InsightFace's non-commercial weights mean this is personal/research work, not for sale.