| 参数名称 | 说明 |
|---|---|
| image | 原始图像，用于提取并构建最终人脸区域掩膜（mask）。 |
| swapped_image | 已完成换脸操作的图像，在 mask 区域会被贴回原图。建议为 reactor 输出的换脸图像，需与 image 尺寸一致或可适配。 |
| mask_optional | 外部传入的掩膜，可跳过内部 bbox + SAM 计算流程。进阶参数，用于复用已有掩膜以加速。 |
ReActor 🌌 Masking Helper
节点功能：专门用于创建和优化人脸替换过程中使用的遮罩，帮助用户获得更精确、更自然的人脸替换效果。
输入参数
输出参数
| 参数名称 | 说明 |
|---|---|
| IMAGE | 最终将 swapped_image 的人脸部分粘贴回 image 的图像。主输出。融合了掩膜、贴图、模糊后的人脸区域。 |
| MASK | 原始掩膜，类型 [B, H, W]，仅包含二值结果。可用于调试或下游处理。 |
| MASK_PREVIEW | 用于展示的可视化掩膜图像（3 通道）。适合直接接 PreviewImage 节点查看效果。 |
| SWAPPED_FACE | 从 swapped_image 中切出并调整尺寸的人脸贴图区域，RGBA 格式。可用于进一步处理，或作为 debug 输出确认位置与对齐。 |
控件参数
| 参数名称 | 说明 |
|---|---|
| bbox_model_name | YOLO 系列的边界框检测模型或分割模型，前缀为 bbox/ 或 segm/。 |
| bbox_threshold | YOLO 检测框置信度阈值，过滤掉低置信度目标。范围 [0.0, 1.0]。阈值过低会引入伪目标，过高可能漏检人脸。建议 0.4~0.6 之间调整。 |
| bbox_dilation | 检测框膨胀像素，调整 mask 覆盖范围。范围 [-512, 512]。可用于拓宽或收缩人脸区域，负值为收缩。 |
| bbox_crop_factor | YOLO 检测框裁剪后的区域放大比例。范围 [1.0, 100]。值越大，送入 SAM 的区域越大，更容易包含面部。 |
| bbox_drop_size | 忽略尺寸小于该值的检测框，单位为像素。范围 [1, 8192]。清除背景误检点（如眼镜、耳环），建议默认。 |
| sam_model_name | SAM 模型名称，来自 sams 文件夹，过滤掉含 hq 的模型。SAM 用于精细掩膜提取，通常使用 vit_h 系列精度最高。 |
| sam_dilation | 对 SAM 输出 mask 做形态学膨胀，控制范围扩大。范围 [-512, 512]。与 bbox_dilation 类似但作用于 SAM 精细结果。 |
| sam_threshold | SAM 掩膜输出置信度阈值。范围 [0.0, 1.0]。控制最终掩膜的精度，过低会含糊，过高可能缺失细节。 |
| bbox_expansion | 控制 bbox 扩展边缘像素数，补充头发或边缘特征。范围 [0, 1000]。可用于让掩膜包含发际线、耳朵等部位。 |
| mask_hint_threshold | mask 提示置信度阈值，控制 hint 的筛选。范围 [0.0, 1.0]。 |
| mask_hint_use_negative | 是否使用负向提示，选项为 "False" / "Small" / "Outter"。"Small" 表示抛弃小面积掩膜，适合多目标消除背景；"Outter" 去掉边缘，保持核心面部区域。 |
| morphology_operation | 掩膜形态学处理方式，选项：dilate/erode/open/close。"open" = 先腐蚀再膨胀，"close" = 先膨胀再腐蚀。 |
| morphology_distance | 形态学操作的内核半径。范围 [0, 128]。值越大，膨胀或腐蚀效果越明显。 |
| blur_radius | 高斯模糊半径，影响掩膜边缘融合度。范围 [0, 48]。越大越柔和，掩膜边缘越自然。 |
| sigma_factor | 高斯模糊标准差因子。范围 [0.01, 3.0]。一般保持默认即可。调整过大会使边缘丢失。 |
mask_optional主要作用是让用户能够跳过内置的人脸检测和分割过程，直接使用自定义或预先生成的遮罩。（前提是有更好的人脸分割模型）
以下这个效果还不如使用ReActor 🌌 Masking Helper节点内置的人脸分割。
bbox_threshold：边界框检测阈值。该值越高，检测结果越严格，人脸部位定位越精确；但如果设置过高，可能导致无法检测出任何人脸。例如，当阈值设为 1.0 时，所有人脸可能会被过滤掉，最终不会生成任何 mask。