Badge Material Region Executor V1

What it is and why you'd reach for it

This is the compact version of the pack's material branch: one node that takes your region configuration and expands, at execution time, an entire chain of GPT-Image-2 material edits - up to four of them - and hands back the finished badge. Two sockets out, no subgraph to wire.

I'd point a first-time user at the visible channels instead, and the pack's own README agrees: Badge Material Region Executor V1 "remains registered for backward compatibility with older 8.5 drafts." But it's the node you'll inherit if you downloaded someone's 8.5 workflow, and it's genuinely instructive about what the four-channel version is doing, so it's worth understanding rather than deleting.

How it works

Preflight first, exactly like the channel node: groups from the material_region_set with no matched pixels, groups set to the default transparent_lacquer, groups below minimum_region_pixels, and groups missing a mask are skipped and logged with a reason. More active regions than max_regions raises Material API budget exceeded before GPT execution before anything is built.

Then it walks the active regions in order and, for each, expands three nodes: a native OpenAIGPTImageNodeV2 (1024×1024, opaque, Image 1 = your original base, mask = that region's mask, seed = the region's reroll_revision), a Badge Material Constraint V1 on the result, and a Badge Deterministic Composite that pastes the constrained result onto the running master.

The design detail that matters: current accumulates - region 2's composite takes region 1's output as previous_master - but every GPT call receives the original base_image as its reference, not the running master. That's why the report carries immutable_base_for_all_gpt_nodes: true and masked_reference_image_count: 1. Each region is edited against the same starting point, so region 3 never sees region 2's new material as context and can't cascade a reinterpretation. The chaining only happens in the compositing.

Cache behaviour is worth knowing before you press queue: each expanded child has a stable id derived from the region id (gpt_<region>, constraint_<region>, composite_<region>), so re-running after changing one region's material re-bills one call, not four.

Inputs and outputs that matter

base_image (single image only - batches raise), flat_image (colour reference for the constraint), height_map, material_region_set from Badge Material Region V1 (DAELab), quality (low/medium/high), max_regions (1–4), minimum_region_pixels (default 16).

Outputs: image only - the merged badge. report is JSON with active_region_count, maximum_region_count, immutable_base_for_all_gpt_nodes, masked_reference_image_count, and expanded / skipped arrays listing every child node id and every skip reason. If you want per-region masks for a report, you need the channel nodes; this one doesn't emit them.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/TeutonicMepheles/ComfyUI-DAELab-Custom-Nodes-Library

Restart ComfyUI. It requires ComfyUI's native GPT Image nodes to exist - the executor grafts OpenAIGPTImageNodeV2 into the graph rather than calling OpenAI itself, so it inherits their login and credit requirements. V3-schema node, so keep core updated. OpenCV is imported by the module and not declared in requirements.txt: pip install opencv-python-headless if it's absent from the menu.

Common issues

• Nothing seems to happen visually. report.expanded is empty. Read skipped - every group has a reason string (empty, transparent_lacquer, too_small, missing_mask).
• You can't see or re-roll one region. That's the trade this node makes. Rebuild with four GPT-Image-2 Material Region Channel V1 nodes and a Badge Material Region Merge V1 if you need the calls on the canvas.
• GPT masked editing requires exactly one immutable base image. A batch got into base_image. This node composes four regions into one result, so batch handling isn't defined.
• Overlap complains downstream. The internal composite would allow two overlapping regions to fight; if you route this output into a merge node, the merge's overlap check fires. Don't mix the two approaches in one graph.