DOGMA Semantic Macro Crops v21 — Current + Original

What it is

DOGMASemanticMacroCropsV21 is the v10 idea with a second image input. You hand it the current master and a reference image - normally the original, un-restored source - and for every region crop it emits the aligned original crop of the exact same place, resized to the exact same size.

The class docstring is explicit about the guarantee: "Current crop and original reference are always the exact same spatial location after resizing source to master coordinates."

That second crop is not decoration. It's evidence. This pack's local edit prompts are built around a two-image idea - the current master crop is the spatial and photographic truth, and the original at the same position is identity evidence: real positions, real counts, real proportions, real colours. Models asked to "improve detail" on a soft region will happily invent a nicer window. Models allowed to look at what was actually there tend not to.

If you know the crop-and-stitch fix that circulates for edit models - crop the region, edit it, paste it back so the rest of the frame is bit-identical - this is the same trick with a reference welded on, scaled up to semantic regions.

How it works

Nearly identical to v10, with three differences worth knowing.

The proxy is bigger and the grouping is gentler. Analysis happens at 640px instead of 512, and group_radius defaults to 560 rather than 480. Same dilation-and-merge logic: dilate the union mask on the proxy, find connected components, expand by context_px, then merge the nearest pair repeatedly until the region count fits max_crops.

Oversize regions split along their long axis. Rather than the ownership-window tiling in v10, v21 checks whether a region exceeds max_source_side and, if so, slices it into ceil(long_edge / limit) pieces across whichever axis is longer, then re-merges nearest neighbours if that overshoots max_crops. Regions that fit are left whole. It keeps large context rather than carving tidy non-overlapping windows.

The model resolution is hard-capped at 2000. target_long_side has a 512–2000 range and the resize helper clamps to 2000 regardless - a deliberate ceiling from whoever burned themselves on a bigger value. It never upsamples a crop that's already smaller than the target.

Each region still gets an ownership mask (the region's own pixels inside the larger context crop) so a neighbouring crop's context doesn't get edited twice.

Inputs and outputs

Inputs: image (current master), reference_image (the original, resized to master coordinates), masks, and the same five budget knobs plus threshold - group_radius (560), context_px (192), max_source_side (3400), target_long_side (1920, capped at 2000), max_crops (8) and mask_threshold (0.5).

Outputs: crops (IMAGE list), reference_crops (IMAGE list, same order and geometry), crop_masks (MASK list), stitch (DOGMA_STITCH list for the paste step) and info (STRING).

Wire crops and reference_crops into whatever holds two images - an inpaint-conditioning node, a VLM that gets to look at both, or your model's reference input - and send crop_masks alongside so the edit stays local. stitch is what makes the result go back where it came from.

Install

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

Or ComfyUI Manager → DOGMA Nodes, then restart. Nothing to download: requirements.txt declares no external dependencies, and the pack leans on PyTorch, numpy and ComfyUI's own utilities.

Gotchas

• Alignment is assumed, not verified. If your reference isn't already in the current master's coordinate space - because a previous step cropped, offset or outpainted it - the reference crop will be of the wrong place and quietly useless. This is why the pack ships a dedicated "resize to reference scale" node and a crop-to-reference-scale node.
• The 2000px cap is silent. Set target_long_side to 2048 and you'll get 2000; the info string tells you what actually happened, so read it once.
• Crop count is a planning decision, not a limit you can ignore. Every crop is a full sampling pass with two image inputs attached, so max_crops: 8 on four sectors is up to 32 renders.
• No community threads exist for this pack, and the README doesn't cover the semantic detailer at all. The docstrings are the manual.