kubakub regions from sam3

SAM 3 is the reason this node is interesting. Click-a-point segmentation was always useful, but it didn't scale to a facade with forty windows - you'd be clicking forty times, and that's before you get to the balustrade. SAM 3 (November 2025) added promptable concept segmentation: give it a noun phrase and it returns masks for every matching instance at once. That collapsed the old GroundingDINO-then-SAM pipeline into one model, and it's exactly the shape a building needs.

kubakub regions from sam3 wraps ComfyUI's core SAM3 Detect and turns it into a facade tool: every hit becomes its own named mask, ready to plug into kubakub regions from masks.

The prompt field is the whole node

prompts is one line per kind of object - name = text : N, or just text:

window : 60
stone balustrade : 10

The :N matters and it's the one gotcha worth internalising. Core finds a single object per prompt unless you cap the count. This node defaults the cap to 50 for you, but if you write a bare window and get one mask back, that's why. Every hit becomes its own mask named window_01, window_02… in reading order.

drop_groups (on by default) throws away hits that cover two or more other hits of the same prompt. SAM has a strong tendency to return one mask for an entire row of balustrades alongside the individual ones, and that big blob would swallow all your real regions. Leave it on.

threshold is text detection confidence (0.5 default) - the first thing to move if you get nothing, or get junk. refine_iterations is core's SAM decoder passes. min_area drops specks.

Points and boxes, with the detail pass

You don't have to use text. clip (the CLIP output of the same checkpoint) is needed for text prompts. For clicks and boxes, connect positive_coords and negative_coords from the KJNodes Points Editor, and bboxes (boxes in image pixels). point_names names them in click order.

point_mode decides what a set of positive points means. one region per point gives each positive point its own object, with negatives applying to all; all points one region is core's behaviour of making one object from the lot.

Then the clever bit: detail. SAM sees every image at 1008×1008, so on a 4K matrix a balustrade is a few dozen pixels and the mask comes back as mush. With detail on, points and boxes get a second pass on a square crop at full resolution, pasted back - so the edges follow the balusters and the window frames. Because the model is being asked about a smaller field, not a bigger image, this is not upscaling trickery; it's giving the model the pixels it needs. If the refined mask is under 0.3× or over 3× the first one it's discarded and the first one is kept, with a note.

scope clips everything to a mask (the building's coverage, say), and save_folder writes each mask as <name>.png into a folder - e.g. your project's Masks folder - with overwrite controlling whether existing files get replaced. That one turns an interactive segmentation session into a reusable asset.

Outputs

masks is a batch, one per object, and names is one name per line. Those two go straight into kubakub regions from masks - same order, same count, no glue. preview shows the found objects coloured and numbered over the image, and report lists every object with its size in pixels, how it was found (text, point, box), its score, and the notes about dropped hits or saved files.

The README's own test is a good calibration of what to expect: window : 60 and stone balustrade : 10 found 41 windows and 5 balustrades, dropped the whole-row hit, and took about 24 seconds in total. Not instant, but a hell of a lot faster than tracing.

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; registry name comfyui-kubanodes. ComfyUI 0.37.0 or newer matters here more than elsewhere in the pack: this node rides on core SAM3, so an older ComfyUI is the difference between a node that runs and a module that won't load.

You need the model: sam3.1_multiplex_fp16 loaded with Load Checkpoint, giving you MODEL and CLIP. One caveat from the wider ecosystem worth knowing - third-party SAM 3 node packs have a reputation for requiring Triton, which is genuinely painful on Windows. This node goes through core instead, which is why it's worth the version requirement. If you were put off SAM 3 by install stories, that's not the node you're looking at.

Model-free test: tests/test_sam_prompts.py. Workflow: example_workflows/regions_sam3_masks.json - matrix → Points Editor → SAM3 Masks → Regions From Masks, patched on top of a mask-folder atlas.

Notes

Text hits and clicked objects behave differently. Text prompts tend to come back as closed outlines; clicked objects with detail on cut out the gaps between balusters properly. If one route looks wrong, try the other before assuming the model is failing.

Segmentation hugs the object. Expect to add one or two pixels of grow_px in kubakub regions to mask, or a region will leave a rim of the original content around whatever you generated inside it.