Mask Crop (Swwan)
Batch-aware mask cropping that keeps one stable box across a whole video
- image
- mask_image
- crop_box
- mask
- cropped_image
- cropped_mask
- crop_box
- box_preview
- region_info
- region_mask
- width
- height
- encoder_resolution
- native_crop_width
- native_crop_height
- working_resolution
Crop By Mask V5 is the workhorse of the "detect, crop, process, paste back" loop - the same family of idea that Impact Pack's FaceDetailer made famous, just at the mask level. You give it an image and a mask (or a whole video batch and a mask), it finds the region the mask marks, crops it out with some padding, and hands you the cropped image, cropped mask, the crop box, and a preview. The V5 part is that it does this for batches without turning your video into a pile of individual frames.
If you've ever done face/object inpainting on a video, you know the pain: crop one frame, process it, and every other frame uses a slightly different box, so the result jitters. V5's batch_first_reuse mode computes the crop box once from the first frame and applies it to the whole batch. One stable box, temporally consistent output, and it's cheap.
Inputs that matter
Most of the widgets are reserve/padding controls, and they're the ones you'll actually touch:
detect- how the region is found from the mask:mask_area(bounding box of the mask),min_bounding_rect(tighter rectangle around the mask), ormax_inscribed_rect(biggest rectangle that fits inside the mask).mask_areais the safe default; the others matter when your mask is a weird shape.reserve_mode- how much padding around the detected region:absolute(fixed pixels viatop/bottom/left/right_reserve) orratio(fraction of the mask's own size, capped byreserve_max). Ratio is the one for video, because it scales as the subject's size changes frame to frame. The README's guidance: 0.3 tight, 0.5 standard, 0.8 loose.round_to_multiple- snaps the crop dimensions up to a multiple of 8/16/32/…/None. Set this to match your model's preferred resolution; it's what keeps the cropped region sampler-friendly for inpainting.batch_mode-single_frame(recompute per frame, compatible with older V4 behavior) orbatch_first_reuse(the one you want for video).device- CPU or GPU. GPU is genuinely faster here; the box math is tensor-based.
Optional inputs: image (the frames to crop), mask_image (the mask as an IMAGE - see the gotcha below), and crop_box (skip detection entirely and reuse a box from somewhere else, like an earlier pass).
Outputs:
cropped_image(IMAGE) andcropped_mask(IMAGE) - the crops, all frames in one batch.crop_box(BOX) - the[x1, y1, x2, y2]box. This is what you wire into the pack's restore nodes to paste the processed result back.box_preview(IMAGE) - a visualization: red for the detected region, green for the final padded box. Look at this once before you commit to a long batch.
The mechanism, briefly
It takes the mask's first frame, blurs it, computes the box with your chosen detect and reserve settings, then crops every frame with that same box. In batch_first_reuse the mask is read from frame zero only - that's deliberate, and it's why the box doesn't drift. The box_preview output is your sanity check that the box actually covers what you think it covers.
Install
In ComfyUI_Swwan. ComfyUI Manager → search "ComfyUI_Swwan", or:
cd ComfyUI/custom_nodes
git clone https://github.com/aining2022/ComfyUI_Swwan
cd ComfyUI_Swwan
pip install -r requirements.txt
Restart, then find Crop By Mask V5 (Batch) under Swwan/image.
The gotchas
Biggest one: mask_image is an IMAGE, not a MASK. Most mask-aware nodes take the MASK type; this one takes an IMAGE and treats its first frame as a black/white mask. Feed it a MASK output directly and you'll get a type error. Convert your mask to an image first, or use Load Image on a mask file.
Second, batch_first_reuse uses only the first frame's mask. If the subject moves a lot across the video, the fixed box can lose it later in the clip. That's the tradeoff for stability - if you genuinely need per-frame boxes, that's single_frame, but expect some jitter and per-frame cost.
Third, you must provide either mask_image or crop_box. No mask, no box, no crop - the node raises. And if you supply a crop_box, detection is skipped entirely, so your detect/reserve settings are ignored for that run.
Inputs (35)
| Name | Type | Default | Description |
|---|---|---|---|
| detect | COMBO | 仅 bounds 且未接 crop_box:mask_area 按遮罩区域,min_bounding_rect 最小外接矩形,max_inscribed_rect 最大内接矩形;后两者使用平滑后的遮罩。 | |
| reserve_mode | COMBO | 仅 bounds:absolute 使用四向像素边距;ratio 上下按遮罩框高度、左右按宽度乘比例,并受 reserve_max 限制。编辑模式改用 edit_expansion_mode。 | |
| top_reserve | INT | 20-9999–9999 | 仅 bounds + absolute:向上保留的像素边距;负值收缩,边界受原图限制。编辑模式不使用此项。 |
| bottom_reserve | INT | 20-9999–9999 | 仅 bounds + absolute:向下保留的像素边距;负值收缩,边界受原图限制。编辑模式不使用此项。 |
| left_reserve | INT | 20-9999–9999 | 仅 bounds + absolute:向左保留的像素边距;负值收缩,边界受原图限制。编辑模式不使用此项。 |
| right_reserve | INT | 20-9999–9999 | 仅 bounds + absolute:向右保留的像素边距;负值收缩,边界受原图限制。编辑模式不使用此项。 |
| top_reserve_ratio | FLOAT | 0.50–10 | 向上扩展比例。bounds + ratio 按对应宽/高计算并受 reserve_max 限制;编辑模式 + reserve_ratio 按选区框短边 S×ratio 增加上下文,不受 reserve_max 限制。 |
| bottom_reserve_ratio | FLOAT | 0.50–10 | 向下扩展比例。bounds + ratio 按对应宽/高计算并受 reserve_max 限制;编辑模式 + reserve_ratio 按选区框短边 S×ratio 增加上下文,不受 reserve_max 限制。 |
| left_reserve_ratio | FLOAT | 0.50–10 | 向左扩展比例。bounds + ratio 按对应宽/高计算并受 reserve_max 限制;编辑模式 + reserve_ratio 按选区框短边 S×ratio 增加上下文,不受 reserve_max 限制。 |
| right_reserve_ratio | FLOAT | 0.50–10 | 向右扩展比例。bounds + ratio 按对应宽/高计算并受 reserve_max 限制;编辑模式 + reserve_ratio 按选区框短边 S×ratio 增加上下文,不受 reserve_max 限制。 |
| reserve_max | INT | 1000–1024 | 仅 bounds + ratio:每侧边距的最大像素数。对 edit_region/qwen21_aligned 的上下文扩展不生效。 |
| round_to_multiple | COMBO | 仅 bounds:裁剪框宽高向上对齐指定倍数,尽量限制在原图内。不是 aligned 的 Qwen 32 对齐,也不是遮罩块化。 | |
| batch_mode | COMBO | 仅 bounds:两个选项均按首帧遮罩/同一 crop_box 裁剪输入批次,不逐帧检测;batch_first_reuse 显式表示复用。edit_region/aligned 始终只处理首张。 | |
| device | COMBO | CPU | 仅 bounds 自动检测时选择平滑计算设备,后续检测仍含 CPU/PIL。不是 Qwen 推理设备;edit_region/aligned 不使用此参数。 |
| imageopt | IMAGE | 待裁剪的干净原图。edit_region/qwen21_aligned 必须连接,且仅处理首张;mask 必须与该图同尺寸、同坐标。 | |
| mask_imageopt | IMAGE | 遮罩的 IMAGE 输入。bounds 使用灰度遮罩;编辑模式未接 mask 时才使用它,edit_region 转灰度,aligned 读取红通道。请与原图保持同尺寸。 | |
| crop_boxopt | BOX | 仅 bounds:复用 [left, top, right, bottom] 原图坐标框,右/下为排他边界;连接后跳过自动检测和边距计算。不是 BBOX/SEAM。 | |
| crop_modeopt | COMBO | bounds | bounds:传统边界裁剪/批次复用;edit_region:局部编辑裁剪与恢复记录;qwen21_aligned:局部裁剪 + BlueBox 32 对齐/不动点校验 + Qwen 面积预算。模式决定其他控件是否生效。 |
| maskopt | MASK | 仅 edit_region/qwen21_aligned:白色为选区,黑色为非选区,优先于 mask_image。LoadImage 的 MASK 是 1-alpha,不是自动主体选区。aligned 按 >0 取外接框,保留软值;低于512预算缩小时按面积覆盖采样,细小选区可能变灰但不直接丢弃。空选区报错。 | |
| fill_mask_holesopt | BOOLEAN | false | 仅编辑模式:填充选区内部封闭孔洞,可能把原本保留的内部区域纳入选区;不是最终保护区。aligned 保留已有软值,仅补孔。默认关闭。 |
| output_sizeopt | COMBO | 原像素 | 仅 edit_region:原像素保持裁剪像素尺度;原像素1:1 扩成正方形;自定义宽高按指定尺寸处理。aligned 由面积预算决定画布,不使用此项。 |
| custom_widthopt | INT | 10240–8192 | 仅 edit_region + 自定义宽高:与另一维共同设置输出;仅一维为0时,非零值作为长边预算;两维不能同时为0。aligned 不使用此项。 |
| custom_heightopt | INT | 10240–8192 | 仅 edit_region + 自定义宽高:与另一维共同设置输出;仅一维为0时,非零值作为长边预算;两维不能同时为0。aligned 不使用此项。 |
| alignmentopt | INT | 80–256 | 仅 edit_region:原像素/原像素1:1尺寸向上对齐此倍数,自定义输出按该模式规则取整;0/1 不额外对齐。aligned 固定使用自己的 32 倍数候选,不读取此项。 |
| edit_expansion_modeopt | COMBO | reserve_ratio | 仅编辑模式:factor 使用四向 edit_*_factor;reserve_ratio 使用四向 *_reserve_ratio(内部转为 1+ratio)。均按选区外接框短边增加上下文,不是整个宽高乘倍数。 |
| edit_top_factoropt | FLOAT | 1.21–10 | 仅编辑模式 + factor:向上增加 S×(factor-1) 像素,S 为选区框短边;1=不扩展,1.3=增加约 0.3S,不是整张图放大1.3倍。aligned 向上取整,edit_region 截断取整。上下文不自动获得最终修改权限。 |
| edit_bottom_factoropt | FLOAT | 1.21–10 | 仅编辑模式 + factor:向下增加 S×(factor-1) 像素,S 为选区框短边;1=不扩展,1.3=增加约 0.3S,不是整张图放大1.3倍。aligned 向上取整,edit_region 截断取整。上下文不自动获得最终修改权限。 |
| edit_left_factoropt | FLOAT | 1.21–10 | 仅编辑模式 + factor:向左增加 S×(factor-1) 像素,S 为选区框短边;1=不扩展,1.3=增加约 0.3S,不是整张图放大1.3倍。aligned 向上取整,edit_region 截断取整。上下文不自动获得最终修改权限。 |
| edit_right_factoropt | FLOAT | 1.21–10 | 仅编辑模式 + factor:向右增加 S×(factor-1) 像素,S 为选区框短边;1=不扩展,1.3=增加约 0.3S,不是整张图放大1.3倍。aligned 向上取整,edit_region 截断取整。上下文不自动获得最终修改权限。 |
| qwen_resolutionopt | INT | 1024512–2048 | 仅 aligned + fixed:固定面积预算 R,目标画布约 R² 像素,不是固定 R×R,也不是长边上限。crop_area 不读取此项。 |
| qwen_toleranceopt | FLOAT | 1.00.2–3 | 仅 aligned:BlueBox 候选面积容差,越大可选画布越多;不是位移容忍像素。1.0 在 R=1024 时约为 3.125% 面积容差;最终仍验证不动点。 |
| qwen_restore_backendopt | COMBO | swwan | 仅 aligned:swwan 的 region_info 接 SwwanRestoreCropBoxV4;goohai 接原生 GH_CropRestore,保留该节点的校色/羽化能力。本节点只准备几何记录,不执行校色,两个 SEAM 合同不可混接。 |
| qwen_resolution_modeopt | COMBO | fixed | 仅 aligned:fixed 使用 qwen_resolution;crop_area 按原生选区框+上下文的 sqrt(W×H) 取最近 32 档(半档向上),再限制在 min/max 内。预算在缩放/比例扩框/补边之前计算,不按白色像素总数计算。 |
| qwen_max_resolutionopt | INT | 1024512–2048 | 仅 aligned + crop_area:面积预算上限,默认 1024,向下取 32 倍数(1560→1536)。不是最长边;狭长画布单边可以更大。降低上限可减少大裁剪的推理像素,也可能损失细节。 |
| qwen_min_resolutionopt | INT | 12832–2048 | 仅 aligned + crop_area:面积预算下限,默认 128,向上取 32 倍数(129→160)。不是最短边;小裁剪可能被放大到约 min²。低于 512 的模型质量/速度未验收。对齐后的下限不能超过上限。 |
Outputs (12)
| Name | Type | Description |
|---|---|---|
| cropped_image | IMAGE | 实际裁剪/对齐后的图像。aligned 下可接任务标记处理再送编码器;保留干净图作颜色参考。 |
| cropped_mask | IMAGE | 与裁剪图同尺寸的三通道遮罩预览(IMAGE);需要 MASK 连线时使用 region_mask。 |
| crop_box | BOX | 原图坐标 BOX:[left, top, right, bottom],右/下排他。aligned 的缩放/补边恢复还必须带同源 region_info,不能只靠 BOX。 |
| box_preview | IMAGE | 原图或遮罩上的裁剪框预览,供检查选区是否完整;不是模型输入。 |
| region_info | SEAM | 同源 SEAM,记录原图、裁剪、缩放和补边。aligned 按 qwen_restore_backend 连接匹配恢复器;edit_region 接 SwwanRestoreCropBoxV4;bounds 为 None。 |
| region_mask | MASK | 与裁剪图同步变换后的原生 MASK,用于标记或同源贴回;不等于最终硬保护范围或生成 alpha。 |
| width | INT | 实际输出画布宽度;aligned 下为32倍数,可能大于面积预算数值。 |
| height | INT | 实际输出画布高度;aligned 下为32倍数,可能大于面积预算数值。 |
| encoder_resolution | INT | 供官方 TextEncodeQwenImage21.resolution 使用,aligned 输出0以保持已对齐画布;采样使用同一编码器的 latent。其他模式也返回0,但不保证已32对齐。 |
| native_crop_width | INT | 原生裁剪宽度:aligned 中为选区框+上下文,尚未进行比例扩框、缩放或补边。用于理解预算来源。 |
| native_crop_height | INT | 原生裁剪高度:aligned 中为选区框+上下文,尚未进行比例扩框、缩放或补边。用于理解预算来源。 |
| working_resolution | INT | 实际选中的面积预算R(目标面积约R²,不等于width或height);aligned fixed/dynamic均返回实际值,其他模式返回0。 |