DOGMA SAMSearchBounded v2

The first thing to understand about this node is what it is not trying to do. It is not going to find every instance of a category in your image. It's going to find a bounded, ranked, de-duplicated set of candidate masks and stop, and the pack is very deliberate about saying so in the report.

DOGMASAMSearchBounded v2 shipped with DOGMA 1.0.8 and is the ancestor of the whole search family in this pack - SAMCoherentSearch v1.0.9, SAMCoverage v1.0.10 and the lazy v1.0.11 are all descendants of the same skeleton. Reasonable place to start if you want to see the pattern with the fewest moving parts.

How it works

Per category, two modes. global searches the whole frame once per query. local_recovery searches four overlapping views instead - each 64% of the image's height and width, offset to the four corners, so every pixel is covered without ever downscaling a full scene into one pass. Recovery requires previous, and will not run if the earlier pass already approved anything: the point of recovery is fixing empty or partial results, not stacking masks forever.

The de-duplication step is the interesting part, and it's why this node exists rather than a bare SAM call. Candidates are ranked by score times the square root of their area, and a candidate is discarded if 90% or more of its pixels are already inside an existing mask's bounding box. That eats the classic text-SAM habit of returning the same object three times at slightly different scales - without needing to compare masks pixel-by-pixel.

Budgets are cumulative across the two passes. The masks you already accepted carry forward, the remaining budget is computed as max_instances minus what's been spent, and the spend count is written into the notes so a recovery pass can't quietly start over. When the cap is reached, the report says "Budget reached: other regions stay unchanged." Nothing is forced, nothing is deleted.

The inputs and outputs

• image - one image, single-frame. A batch raises.
• model / clip - the segmentation model and the text encoder used to embed the query noun.
• category - canonicalised on entry, so person and people behave identically and thread state correctly across passes.
• mode - global or local_recovery.
• threshold (0.25), max_instances (8 default here, max 32), max_queries (2), recovery_views (2).
• previous (DOGMA_REVIEW) - required for recovery, and checked: a mismatched category or image geometry raises rather than merging incompatible state.
• after - optional passthrough string used for ordering.
• candidates (DOGMA_CANDIDATES) → an audit node → DOGMA ReviewBatch v1.0.10.
• search_report (STRING) - SAM calls, candidates found, audit budget used, and the explicit "this is a bounded selection, not an exhaustive inventory."

Install

Manager → search DOGMA Nodes, or:

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

Restart. scipy>=1.10 is the pack's only pip dependency, but this node reaches into ComfyUI's SAM 3 implementation at execution time - you need a ComfyUI new enough to have it, and on Windows you'll want to be ready for the Triton requirement that SAM 3 drags in.

Tuning it, and the trap

Defaults are conservative on purpose: eight instances, two queries, two recovery views. If your category has a lot of small instances - a row of windows, a crowd, a street full of cars - the cap is what you'll hit first, and the report's "budget reached" line is your signal. Raise max_instances before you raise max_queries; more queries means more SAM calls over the same regions, while a bigger instance budget is what actually lets new candidates through.

The trap is the recovery pass. It is guarded: it needs a previous review, it refuses to run when something was already approved, and it reuses the same running budget. People who try to "just run it twice for more coverage" end up with the second pass doing nothing and a confusing report - which is the intended behaviour. If you want a search that deliberately reserves budget for a second pass regardless of what the first one approved, that's SAMCoverage v1.0.10's quarter-reserved design, not this one.