DOGMA SAMSearch v56.7

This is the detector step of the v56.7 phase-3 pipeline, and it's the node that decides whether your category has anything to restore. It wraps ComfyUI's SAM 3 detection twice over: one pass on the whole frame, one pass over four overlapping local windows looking for the instances the first pass missed.

Why the second pass exists

Small objects in a large photograph are a known weak spot for promptable segmenters. The KB's SAM 3 panel calls it promptable concept segmentation and is honest about the ceiling; the community verdict on the SAM 3 agent pattern is blunter - the noun-phrase approach works for "blonde woman" and falls over on anything spatially specific.

DOGMA's answer isn't a better model, it's more views of the same model. In global mode you detect on the full frame, so the model sees everything at once and finds the big obvious stuff. In local_recovery mode you detect on four crops, each 64% of the frame, positioned at the four corners so they cover every pixel with overlap - the model gets a closer, less cluttered look, and the small car at the frame edge finally has enough pixels to register.

How the detection works

Both modes call ComfyUI core's SAM3_Detect the same way, and there are two opinionated choices in there:

• refine_iterations=0. No refinement pass. The docstring explains why: the refined mask is the one that pulls in coarse-mask pixels outside the box, and the guard downstream would rather clean raw detector output than fight refinement artefacts.
• individual_masks=True, with max_detections injected per query through the sam3_multi_cond conditioning metadata.

Queries come from the category via a small alias table: buildings tries "building" then "building facade"; vehicles tries "vehicle", "car", "bus", "truck"; people tries "person", "pedestrian"; road tries "road", "pavement"; vegetation tries "tree", "plant"; anything else tries itself. Global mode tries every alias; local mode falls back to the alternate noun only when the first one came back empty - a cheap way to stop four windows × four nouns from quadrupling your SAM calls.

Every detection then goes through the same cleanup as the v56.6 guard (clip to paired box, 8-connected speckle removal down to 0.5% of the biggest blob, no dilation, no hole filling), and this time the failure mode is a raised error rather than a silent skip: mismatched mask/box counts stop the run, because pairing them wrongly is worse than stopping.

Deduplication, and the rule that matters

Local recovery will find the same car twice. The deduplicate pass has an asymmetry worth knowing: it sorts candidates by area descending and discards a candidate only if 90% or more of its own area is already covered by something bigger. A small mask sitting wholly inside a large one is kept if it's small relative to it. That's what stops the recovery pass from deleting the exact instances it was added to find.

It also raises rather than truncates when the distinct count exceeds max_instances:

DOGMA: 61 distinct instances exceed the review limit 48. Increase max_instances; none were silently dropped.

You are expected to raise the limit or narrow the category, not to have instances vanish quietly.

Inputs and outputs

• image - single image, batch of one. Batches raise.
• model, clip - your model and the CLIP that SAM 3's text conditioning needs.
• category - STRING wire; canonicalised against the four groups, and inactive values (none, unused, n/a, absent) return an empty candidate bundle.
• mode - global or local_recovery. Local recovery requires the previous input and will raise without it.
• threshold - 0.05 to 0.9, default 0.25. The detector's score threshold; this is your main recall/precision dial.
• max_instances - 8 to 128, default 48.
• previous (optional) - DOGMA_REVIEW, the bundle from the first pass. Must match the category and the image shape, or it raises.
• after (optional) - STRING, an ordering wire.

Outputs: candidates (a DOGMA_CANDIDATES bundle: category, shape, cleaned items, previously accepted items, notes) and search_report - which is worth reading every time, because it tells you the mode, the number of SAM calls made, how many candidates were new, and how many were already approved.

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.7-era workflow - the README's line for the current release is update via Manager, restart, load V56.19. You need ComfyUI's own SAM 3 nodes (comfy_extras.nodes_sam3) available, which means the SAM 3 install is on you: model download, and on Windows the Triton conversation. The pack ships no models.

Gotchas

Local recovery is not free. Four windows, each potentially trying two nouns, is up to eight extra detector calls per category per image. That's the cost of finding the small stuff, and it's why the design keeps it as a second pass rather than the default mode.

threshold behaves differently in the two modes. In global mode a low threshold gives you confident context for cleaning; in local recovery a low threshold on a tight crop starts returning box-shaped junk that the diffuse-detection rule won't always catch. If recovery is adding rubbish, raise the threshold for that pass rather than lowering it.

Read the report's "new candidates" count. Global 2, recovery 0 means the category is genuinely rare in that frame. Global 2, recovery 14 means your image has small instances the full-frame pass can't see - which is the entire case for the two-pass design.