Crop By Mask V5 (Batch)

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), or max_inscribed_rect (biggest rectangle that fits inside the mask). mask_area is 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 via top/bottom/left/right_reserve) or ratio (fraction of the mask's own size, capped by reserve_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) or batch_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) and cropped_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.