Batch Crop From Mask

You've got a batch of images and matching masks, and you want to crop them all down to the masked region. BatchCropFromMask does that across the whole batch and, crucially, hands you back the bounding boxes and the crop dimensions so you can paste your processed crops back into the originals later. It's the workhorse front-half of the "crop a region, work on it, stitch it back" pattern - the same idea behind every inpaint-and-composite flow, done as a plain utility.

Think of it as the sensible default in the crop-from-mask family. There's a heavier BatchCropFromMaskAdvanced with per-frame tracking, smoothing, and a pile of extra outputs - but for a lot of jobs you don't need all that, and this leaner version is easier to reason about.

How it works

It reads the masks, works out the bounding box of the masked region, and crops the images to it, giving you crops at a consistent size along with the box coordinates and width/height. Two knobs shape the result: crop_size_mult scales the box up so you can include some context around the subject, and bbox_smooth_alpha smooths the box so it doesn't jump around frame to frame. Because you also get the bboxes out, a downstream paste-back node knows exactly where each crop belongs when you composite it home.

If your masked subject barely moves, this is all you need. If it darts around the frame and you need tight per-frame tracking, that's the case for the Advanced node.

The inputs and outputs that matter

Inputs:

• original_images (IMAGE) and masks (MASK) - the frames and their masks.
• crop_size_mult (FLOAT, default 1.0) - enlarge the crop for margin. 1.2–1.5 gives breathing room around the subject.
• bbox_smooth_alpha (FLOAT, default 0.5) - how much to smooth the box across the batch. Higher = calmer, laggier; lower = tighter, jumpier.

Outputs:

• cropped_images (IMAGE) - the crops you run your sampler or detailer on.
• bboxes (BBOX) - coordinates for pasting back. Hold onto these; they're the round-trip key.
• original_images (IMAGE) passthrough, plus width and height (INT) - the crop dimensions, useful for nodes that want explicit sizes.

The flow: crop here → process cropped_images → feed the result and bboxes to a paste-back node that composites onto the originals.

How to install it

ComfyUI Manager: search KJNodes for ComfyUI, install, restart. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-KJNodes
pip install -r ComfyUI-KJNodes/requirements.txt

Restart and find it under KJNodes/masking. No models, minimal dependencies - standard for this pack.

Common issues & troubleshooting

One stray white pixel blows the crop out. The bounding box grows to contain every white pixel in the mask, so a speck in the corner stretches the box to near-full-frame. Clean the mask upstream (threshold, then grow/shrink) before cropping.

The crop wobbles between frames. Raise bbox_smooth_alpha. If it's already high and still jumpy, your masks are flickering - some frames have the subject, some don't - and no amount of box smoothing fixes an intermittent mask. Fix mask consistency first.

Paste-back is misaligned. Feed the exact bboxes this node produced to your stitching node; don't recompute them. Mismatched boxes are the usual cause of a detailed crop landing a few pixels off the original.

You needed per-frame tracking. If the subject moves a lot and one shared box can't keep up, switch to BatchCropFromMaskAdvanced, which tracks each frame's box (with smoothing) and gives you cropped masks and a combined view on top.