Badge 8.7 Material Diagnostics (DAELab)

What this is for

Per-call image editing has an annoying failure mode that doesn't look like a failure: the call succeeds, you get an image back, and the region you asked to be glitter is... basically what it was. You paid for it. You only notice when the badge is on a render at 2× and the "glitter" is one subtle highlight.

Badge 8.7 Material Diagnostics is the node that catches that before it reaches your output folder. It takes the four stages of a material edit - the base you started from, the raw model candidate, the color-corrected candidate, and the final composite - plus the mask, measures whether anything actually changed, and refuses to pass along a result that didn't.

It's not a quality judge. Its own report literally says material_appearance=requires_visual_review. What it does is catch the mechanical duds: black holes where the model returned nothing, transparent pixels inside an opaque material, a composite identical to the base, spill outside the mask, and a couple of "too flat to see" thresholds.

How it works

For each image in the batch and each stage, it measures the mean and 95th-percentile absolute pixel change inside the mask, the fraction of pixels that moved by at least 2/255, the median lightness shift, and - the important one - outside_max, the largest change outside the mask. It also hunts for "glints": pixels brighter than the base by more than 0.12 that are also brighter than a locally blurred luminance by 0.04. That's the glitter check.

On the raw candidate it additionally computes how much of the selected area came back near-black (max channel < 0.03 where the base had something) and how much came back semi-transparent. Both of those are known model-return artifacts, not artistic choices.

policy_json is where the thresholds live, and it's ordinary JSON. Keys the code reads: minimum_visible_mean, minimum_visible_p95, minimum_added_highlight_fraction, maximum_raw_black_fraction, maximum_raw_transparent_fraction, material_id, and enforce_visibility. Anything you don't set defaults to zero - or to 1.0 for the two maximums, i.e. permissive.

save_stages decides whether the evidence lands on disk. Off, you get the report string and nothing else. On, it writes every stage as a PNG plus report.json under output/Badge87/diagnostics/<uuid>/, which is what you want when you're arguing with yourself about whether the glitter call did anything.

The inputs that matter

Four images and a mask, no defaults, so wire them in order: base (pre-edit), raw (model output before correction, alpha included if you have it), corrected (after your color/optics pass), composite (after the deterministic mask splice), mask.

Then policy_json - that's the field you actually configure. enforce_visibility is the switch that turns checks into errors: with it true, a failing sample raises 局部材质效果未达到可见变化检查 and your graph stops instead of writing a dud. Leave it false while you're tuning.

Outputs are the composite passed straight through, so the node slots inline at the end of a material chain, and a STRING report as JSON with per-sample stages, checks and a visibility_passed flag. There's also a badge87_material_diagnostics UI payload the pack's front end reads.

Install

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

Needs scipy (used for the blur-based glint detection). It's not in the pack's requirements file because ComfyUI core normally brings it. If it isn't there:

ComfyUI/python_embeded/python.exe -m pip install scipy

Where people get burned

Setting thresholds tighter than the material can deliver. Transparent clear lacquer over an already-glossy region genuinely changes very little - the pack's docs note that the default stopped forcing a lightness pullback precisely because it made lacquer invisible. If you crank minimum_visible_mean up, you'll get errors on results that are correct.

outside_max is byte-exact, not "approximately". If your composite came from anything other than a strict mask splice, the check fails and the failure is real: it means the region outside your selection changed, which is the one thing the whole badge pipeline is built to prevent.

Finally, raw must be the model output, not the corrected image. Feed the same tensor into raw and corrected and the black-hole and transparency checks become meaningless. It won't complain - it'll just tell you everything is fine.