Badge Height Reference Align V1 (DAELab)

What it is and why you'd reach for it

A height map is only useful if it's registered to the artwork. Two pixels of drift between your colour-matched height tiers and your design silhouette and the model renders a badge where the raised rim sits slightly inside the edge - a defect that reads as sloppy stamping and is nearly impossible to diagnose from the output alone, because the render looks fine, just subtly wrong.

Badge Height Reference Align V1 is a pre-flight check with a repair pass. It registers the six-level height map to the design foreground, snaps the height values back to legal tiers after warping, conforms the height support to the design silhouette, then scores the result on three axes and refuses to continue if any of them fails. It is explicitly designed to run before the GPT call, which is where you want your validation if the call costs credits.

How it works

First, validation: the map's values must be in {0, 0.2, 0.4, 0.6, 0.8, 1.0} to within 1e-4, or you get height_map contains values outside {0,.2,.4,.6,.8,1}. Bicubic resampling upstream is the usual culprit.

Then registration: the design foreground and the height map's solid area (anything > 0) are aligned with an affine matrix, and the height map is warped nearest and re-quantized to the nearest fifth - so warping can't manufacture a 0.37. Two numbers get recorded: the pre-repair IoU (how bad it was) and the post-repair IoU (after conforming). If the pre-repair IoU is below 0.80 the node treats the alignment as fundamentally broken rather than fixable.

The repair is a support conform: the solid region of the conformed height map is made to match the design foreground, so every badge pixel has a height and no non-badge pixel does. Then three gates:

• minimum_iou (default 0.985) on the conformed solid area versus the design silhouette - tight, because after conforming this should be near-perfect,
• maximum_boundary_error_px (default 1.5) on the outline distance,
• maximum_unmatched_percent (default 0.5) on unmatched pixels within the foreground.

enforce (default true) turns failures into a raised error containing the full JSON report. Turn it off and you get the same information as valid: false with the data passed through - useful for a dry run, dangerous to leave off.

Inputs and outputs that matter

design_foreground_mask from the canvas node, height_map and unmatched_mask from the height layer node. The three thresholds are already tuned; the only one I'd ever touch is maximum_unmatched_percent, and only to make it stricter.

Outputs: aligned_height is the mask that every downstream stage should consume - it's the registered, quantized, conformed version. aligned_height_image shows it. aligned_unmatched is the unmatched mask in aligned coordinates, which is what Badge Render Prompt Builder wants for its coverage check. contour_iou, boundary_error_px and valid are the three numbers into a switch or report. report is the JSON with both pre- and post-repair metrics, the thresholds, and the legal-level list.

Install

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

Restart ComfyUI. This is a V3-schema node - an out-of-date ComfyUI gives you No module named 'comfy_api' and you fix that by updating core. OpenCV is a real dependency here (registration and morphology) and the pack's requirements.txt doesn't list it: pip install opencv-python-headless if the node is missing.

Common issues

• Height reference alignment failed before GPT execution with observed_iou around 0.97. The height map is a pixel or two out. That's the node working; the render it just saved you from would have had a floating rim.
• Repair can't save it (pre-repair IoU < 0.80). The height map is a different shape from the design - wrong file, or generated from a different source drawing. Fix the input.
• legal_height_max_error complains. A blur, a resize, or a composite of two maps introduced intermediate values. Height maps are categorical data; treat them like masks, not like images.
• valid: false but the pipeline keeps going. You turned enforce off. It's a debug switch - the name is enforce for a reason.