DOGMA SAMInstanceGuard v56.6

SAM 3 is very good at segmenting the thing you named. It is not promise-bound to stay inside the box it detected that thing with, and this node exists because of that gap. It's the geometry half of the v56.6 phase-3 correction: clip every instance to its own detector box, drop the speckle, and refuse to pretend you know which mask belongs to which object when the counts don't line up.

Why it's needed

The KB's segmentation notes describe the SAM lineage as promptable, zero-shot, concept-level: ask for "car" and you get masks for every car. The ComfyUI SAM 3 nodes return refined masks plus the detector boxes that seeded them, and the refinement can pull in coarse-mask pixels outside the box - pixels from whatever the coarse pass thought was nearby. That's how a single-instance repair pass ends up repainting a strip of road attached to a car.

Instances also arrive as a pile with no identity. If you detected eight vehicles and got eight masks and eight boxes, fine. If the counts differ, every downstream pairing is a guess.

What it does

The node takes masks, boxes, the source image and a category, and returns cleaned instance masks plus a report. The checks, in the order they bite:

• One image only. A batch of source frames gets SKIP: one source image is required for instance/box pairing. Pairing boxes across frames is meaningless, so it refuses.
• Dimensions must match. Masks whose spatial size differs from the image come back as an empty (0, h, w) tensor with a SKIP note.
• Counts must match. If the number of masks doesn't equal the number of boxes, or the boxes aren't dictionaries, it refuses: SKIP: SAM instance/box count mismatch; refusing to guess ownership. This is the important one. It fails soft - empty output, not an exception - which is a deliberate difference from the v56.7 search node, which raises.
• Per-instance validity. Each box needs x, y, width, height, score; non-finite numbers, non-positive sizes, or a score below min_score drop that instance.
• Mask values must be probabilities. Anything outside 0–1, or non-finite, drops the instance with invalid mask values. Logits will not sneak through.
• Speckle removal inside the box. The box region is thresholded at 0.5, 8-connected labelling runs, and components smaller than max(4, 1% of the largest) are discarded. Holes and substantial disconnected fragments are kept - no closing, no filling, no dilation, ever. The code says it in a comment and the report says it in words.
• Diffuse detection rejection. If the box covers more than 35% of the frame and the largest component is under 35% of the in-box pixels, the detection is scattered islands rather than an object, and it's dropped.

Then it reports: how many instances survived out of how many, how many out-of-box/speckle pixels were removed, and the union coverage of the kept masks as a percentage, with a semicolon-separated list of the skip reasons.

Inputs and outputs

• masks - MASK, from the SAM nodes.
• bboxes - BOUNDING_BOX, from the same SAM3_Detect call, on the same image. The docstring is emphatic about this and it's the most common mistake: boxes from one detection run and masks from another are not paired data.
• image - the analysis image, single frame.
• category - STRING wire. Empty, none, __none__, unused or n/a short-circuits to an empty mask with a SKIP note.
• min_score - 0 to 1, default 0.35. Below this, an instance is discarded as an unusable detection.

Outputs: bounded_instances (MASK - clean, exact, one per surviving instance) and report (STRING). Feed the masks into the audit sheet and the report into DOGMAMaskAuditGateV566's geometry_report so one string carries both the geometry verdict and the audit.

Install

comfy node install comfyui-dogma-nodes
# or
cd ComfyUI/custom_nodes
git clone https://github.com/axior/ComfyUI-DOGMA-Nodes
pip install -r ComfyUI-DOGMA-Nodes/requirements.txt

Restart, then load a v56.6-or-later graph. The scipy>=1.10 requirement is real here - this module does from scipy import ndimage for the connected-component labelling, so a hand-copied install without pip will import-fail. The SAM 3 model itself comes from the ComfyUI core SAM 3 nodes, which is a separate install with its own model and, on Windows, its own Triton headaches.

Gotchas

A SKIP is not an error message you can ignore. Because it fails soft, a mis-wired or mismatched run produces an empty mask and a report line, and the audit gate downstream turns that into zeroed masks and silence. Read the report when a category is empty.

min_score is your first dial, and it's quick. The default 0.35 is a reasonable cut but SAM 3's confidence distribution varies a lot by noun phrase - "vehicle" gives you confident boxes, "pedestrian" in a crowd often doesn't. If you're losing small distant instances, lower it and check the report's kept/total count; if you're keeping junk, raise it.

The guard can't fix a bad phrase. It cleans what the detector returned. If the detector returned three cars and one truck for "vehicles", you have four instances of a category you called vehicles, and this node will make all four tidy. Category planning is where that gets decided - see DOGMASemanticPlanV567.