DOGMA PrepMasksB 1.0.21

This is where the DOGMA pipeline gets its masks. You feed it an image and a plan - a list of targets, each with one text query - plus a SAM model and its CLIP, and it returns a category bundle with per-instance masks, a preview strip, and a timing report. No detector weights, no YOLO. The queries are words.

That is the promptable-segmentation idea the KB describes: name the region instead of training a detector for it, then feed the resulting masks into the same detect-crop-repaint loop everyone else uses for faces. SAM 3's open-vocabulary text prompting is what made this practical in ComfyUI, and this node is a wrapper that runs one text search per target and applies geometry guards on the results.

How it works

The node text-encodes each target's query through your CLIP, handling the sam3_multi_cond metadata that the newer SAM conditioning produces, and caches the encodings so a query is only encoded once even if several targets share it. It then loads the SAM model and prepares the analysis image once - one image encoding for the whole run, which is the main reason this is not slow. Each target gets session.detect() at your score threshold, capped at max_instances per query.

What comes back is filtered by two geometry guards before it becomes a mask: a mask covering essentially the entire view is rejected (max_mask_coverage), and a mask that sprawls far outside its own detection box is rejected (min_box_agreement). Near-identical duplicate detections are merged with the original silhouette kept. Every rejection lands in the report with a reason.

The pack is unusually honest about what these guards are: geometry flags, not semantic validation. A mask that passes every check can still be the wrong object. If the plan's rows and the returned masks are both empty, the node raises rather than handing you an empty category list, and it prints the queries it used - because the usual cause is a query the model does not understand, not a broken install.

Inputs and outputs

image and plan (DOGMA_PREP_PLAN, from the phase-3 planner node) are the load-bearing inputs. model and clip are the SAM checkpoint pair, marked lazy so they are only demanded when the plan actually has rows. Then the tuning: analysis_side (1536 - the resolution SAM works at; masks come back at this scale, not at native photo size), score_threshold (0.35), max_instances (32), max_mask_coverage (0.97), min_box_agreement (0.85), and rerun (bump it to force re-execution).

Outputs: categories (DOGMA_CATEGORIES, into a chooser), category_previews (IMAGE, into the same chooser's preview input), and mask_timing_and_diagnostics (STRING).

Install

The node ships with the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/axior/ComfyUI-DOGMA-Nodes

Manager users: search DOGMA Nodes. The pack's own dependency list is just scipy>=1.10 - but this node is not self-contained. It needs a SAM 3.x checkpoint loadable as a ComfyUI MODEL plus its matching CLIP, and a plan produced by the pack's planner node in the same generation (1.0.21). The source warns you in Italian if either is missing.

Where people get burned

Regenerating the plan, always. The first check in run is whether the plan has schema 2 and exactly one query per row. Older grouped plans raise with "regenerate the inventory." If you upgraded the pack mid-project, that error is your prompt to rebuild the plan node's output, not a bug.

Instance caps masquerading as "the model missed it." When a query hits max_instances, the report says so explicitly, along with a warning that additional objects may be missing. Raise the cap or add a second, more specific query - a street full of similar signs will hit the limit before it hits the model's ability.

Analysis resolution confusion. Masks and previews are produced at analysis_side, not at your source resolution. Everything downstream interpolates them back for compositing, so this is normally invisible, but if you are eyeballing mask quality in the preview strip, remember you are looking at a 1536px pass dressed up in a 4000px photograph.