🧱 Region Mask List (+background)

Most of the aioli pack's multi-region pipeline is about the dramatic stuff - per-region crops, regional conditioning, stitching N results back. This node is the unglamorous part that makes the whole thing hold together: it turns your raw SAM3 masks into a clean, ordered list of regions, and optionally appends a background layer so the outside of your objects doesn't fall through the floor.

It's the node you reach for at the start of a SAM3 multi-region workflow, right after the segmentation masks come out. Those masks usually arrive as a batch tensor, possibly unordered, and several downstream nodes want a tidy per-region list. RegionMaskList flattens the batch or list into a clean full-size list in the order received, and that's the fix.

How it works

The core trick is what it appends. With add_background = True (default), it computes the inverse of the union of all masks - everything in the image that no object mask covers - and appends it as the last element of the list. That matters because the pack's assembler (BBoxMultipleAssembler) uses list_first_on_top ordering by default, where the last list item is the bottom layer. So the background lands underneath the objects automatically, and it gets its own crop, caption and inpaint pass just like everything else. It's a simple piece of design, and it's the difference between a pipeline that feels layered and one where you're constantly patching holes around your subjects.

Two supporting knobs: threshold binarises the masks, but only for computing that inverse-union background - it has no effect on the object masks themselves, and no effect at all when add_background is off. min_bg_area (0.0–1.0) skips the background entirely if it covers less than that fraction of the image - handy when your objects fill the frame and a "background" would be a sliver that just wastes a sampler pass.

Inputs and outputs

• masks - the SAM3 masks, as a batch or a list (it handles both).
• add_background - default True; append the inverse-union background last.
• threshold - binarisation used only for the background computation, default 0.5.
• min_bg_area - skip a too-small background, default 0.0.

Outputs: masks (the clean list, N+1 with background), background_mask (the computed background on its own, if you want it separately), and count so you know how many layers you're about to run.

The same list then feeds everything downstream: MaskBoundingBox+ for per-region crops and coordinates, the per-region captioning pass, the KSampler (N passes), and RegionalMaskConditioning for the single-pass alternative. That's why the order you put masks in matters - it flows straight through to the final layering.

Installing it

Part of Aioli Nodes. ComfyUI Manager → search "Aioli Nodes", or:

cd ComfyUI/custom_nodes
git clone https://github.com/aiolicollective/aioli-nodes

Restart ComfyUI; it's under Aioli Nodes. No extra dependencies - it's torch only, already in ComfyUI.

Gotchas

Two things to keep in mind. First, order received = priority order: the pack's own examples assume the SAM3 masks come in with the biggest/most important object first, and the background last. If you feed them scrambled, your layering will look scrambled too. Second, if you turn add_background off, the space outside your object masks has no layer - fine when objects fill the frame, but if they don't, un-masked background pixels can end up untouched or missing a pass depending on how you've wired the rest. When in doubt, leave it on. And as with the rest of this young pack, if something misbehaves, the GitHub issues page is the place that actually gets answers.