kubakub regions from masks

Every road in this pack leads here. SAM 3 masks, render passes, ID renders, painted PNGs, Illustrator layers, a batch of masks from your own graph - they all arrive as a MASK batch plus a list of names, and this node turns that into the region atlas the plan, the sampler and the director work on.

If you only learn one node in the 2d/regions group, learn this one. It's the contract.

The core behaviour

masks is a batch, one mask per region, values over 0.5 count as inside. names is one name per line in batch order, or one comma-separated line. name = group sets the group explicitly; otherwise the group is the name without its trailing number, so W_F1_02 lands in group W_F1. Leave names empty and you get mask_01, mask_02, and so on - fine for a quick look, useless for a plan.

Where new masks overlap, the smaller one wins. That one rule is doing a lot of work: it's what lets a window mask sit cleanly inside a wall mask without you ordering anything, and it's the same rule the pack uses everywhere else that masks meet.

min_region_area (64 px by default) catches the junk - antialiased specks, single-pixel slivers - and merge_small_regions decides whether they join the neighbour they share the longest border with or get dropped. Keep the merge on. A dropped region is a hole that nothing will ever diffuse into.

Patching an existing atlas

This is the part that makes the node more than a converter. Connect a KUBA_REGIONS to the optional base_regions and set patch:

• on_top - new masks cut themselves out of the regions below. A window gets cut out of the wall. A base region that loses every pixel is removed, with a note.
• underneath - new masks only fill pixels that no base region already has. For adding the bits the first pass missed.

The base keeps its names, groups, tags and scope, and new masks are clipped to that scope. Best detail: each new region is tagged with the base region it was cut from, plus that region's tags. So if you patch a balcony into a floor-1 wall region, the balcony inherits the tag that region had, and [tag:M_FLOOR_1] in your plan reaches it without you adding a rule. That's how you build a facade in passes - mask folder first, then SAM for the fiddly bits - and still write rules against the whole thing.

You also get, in the advanced inputs, scope_masks (masks that aren't regions but bound where regions may be), split_masks (one mask holding fifteen separate windows becomes fifteen regions windows_01..15 in group windows), and tag_only_masks (masks that only tag what they cover). All three are matched by name or wildcard.

Outputs

regions is the thing - a label map plus a table, for the plan, the mask node, the vector node, the director. region_masks gives you the batch back, one mask per region in region_id order. regions_json is the whole table as text: names, groups, tags, boxes, notes. preview is one colour per group with region borders and ids drawn over a greyed-out matrix, and it's the fastest way to spot a mis-named mask. scope echoes the scope that was used. And report tells you how many masks became how many regions and groups, how many pixels are still unassigned, and every note about renamed, resized, merged or dropped masks.

Read the report the first time. Half of "the sampler didn't do anything" turns out to be "the mask was dropped at 63 pixels".

Install

cd ComfyUI/custom_nodes
git clone https://github.com/kubakubkub/ComfyUI_KubaNodes
python -m pip install -r ComfyUI_KubaNodes/requirements.txt

Manager → kubakub nodes, or comfy node install comfyui-kubanodes. ComfyUI 0.37.0+ and OpenCV; no models, no Blender, no ffmpeg. This node works on a bare install.

Model-free test: tests/test_regions_from_masks.py, and example_workflows/regions_from_masks_patch.json demonstrates the patch flow on the sample facade.

Practical notes

Sizes have to agree. With no base_regions, matrix sets the size and masks of another size get resized with a note. With a base, the base's scope rules and mismatches are your problem. Don't discover this at the end of a chain.

The batch order is the contract. If you shuffle masks upstream - a split_masks on a different node, a different SAM prompt order - the names stop matching the shapes. The preview is where you see it.

Groups are the unit of authoring, regions are the unit of processing. You will write far more rules against groups than against individual windows, which is why the trailing-number convention exists. Name your masks w_f1_c03_glass, not glass3.