An AI agent skill that turns any subject into a 3D film or app
viz3d 0.9.2: match reference brightness, fix tone mapping enum trap, hero prop silhouettes
Nguyen Xuan Anbd6321a860b1
diff --git a/plugins/visualize-in-3d/.claude-plugin/plugin.json b/plugins/visualize-in-3d/.claude-plugin/plugin.jsonindex 905af76..07381ca 100644--- a/plugins/visualize-in-3d/.claude-plugin/plugin.json+++ b/plugins/visualize-in-3d/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "visualize-in-3d",- "version": "0.9.1",+ "version": "0.9.2","description": "Visualize anything in 3D: places, systems, objects, products, creatures, stories and events, as a documentary or action film, a showcase, a live three.js app with a dashboard, a lesson, an illustrated cutaway book or a playable game, in twelve looks across four families, built from real layouts and models made from real references.","author": {"name": "CodePawl",diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.mdindex 87d4018..cfb539b 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md@@ -37,7 +37,8 @@ Skip Pass 1 and do not ask about Blender. Build everything in one pass in `{{WORthe surroundings dressed to the card's density; every palette colour from the card; every model the right realkind; the side-by-side shows no gap in camera, palette, light or density. Fix and re-shoot until all pass.Measure the ground rule with `uv run --no-project --with pillow python {{SKILL_DIR}}/scripts/ground-share.py- <screenshot>`; it prints PASS or FAIL and the share of the largest flat colour.+ <screenshot>`; it prints PASS or FAIL and the share of the largest flat colour. Measure brightness against the+ reference with `scripts/compare-look.py` (`style-reference.md`, Compare each round).7. **Done when** the gates pass, the overview, a clicked unit with its card and each stage preset look right in screenshots, it runsat 60 fps, the page logs no errors, and `npm run build` gives a static folder that opens from any web server.From `self-review.md` run "Each round" and the generic faults that apply to a still view; the film checks applydiff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/style-reference.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/style-reference.mdindex bcb7861..f01c40e 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/style-reference.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/style-reference.md@@ -33,6 +33,8 @@ Write it into the plan file before anything is built. Each line is a value that| Camera | Angle from the ground in degrees, field of view, how much of the frame the subject fills || Palette | Five to eight colours sampled from the capture as hex, each with where it is used || Light | Direction and colour of the key light, softness and length of shadows, how dark the contact shadows are |+| Brightness | Median luminance and mean saturation of the capture, from `scripts/compare-look.py`; the tone mapping that keeps them |+| Hero props | Each object the viewer will name (a cherry tree, a narrowboat): two or three photos of the real thing and how the reference stylizes it || Materials | How each surface reads: painted, glossy, textured, flat; the roughness range || Density | What fills the frame around the subject and roughly what share of it; no empty ground left over || Shapes | Soft or hard edges, rounded or bevelled, stylized or real proportions |@@ -45,13 +47,26 @@ Turn every line into settings before the first render. That means camera values,and shadow settings, the material list, and the set dressing list that gives the density. Pick models that already have the card'sshapes (`asset-sources.md`) instead of reshaping primitives toward them.+- **Tone mapping.** A bright stylized or pastel reference uses Neutral (`ToneMappingMode.NEUTRAL`) or AgX. ACES+ darkens mid tones and turns pink into mauve, so keep it for cinematic looks. With `@react-three/postprocessing`,+ import `ToneMappingMode` from `postprocessing`. Never pass `THREE.ACESFilmicToneMapping`: it is 4, which that enum+ reads as UNCHARTED2, a much darker curve. Ambient occlusion darkens every grass blade, so keep N8AO near 0.8 and+ tint it with the ground's dark tone, not blue.+- **Hero props.** Build each one to its real silhouette first, then stylize it as the reference does. A cherry tree+ has a short dark trunk that forks low into spreading limbs, an umbrella crown wider than tall, blossoms in+ clusters with gaps that show the branches, white-pink on top and deeper pink inside, and petals on the ground. A+ dense round ball of one pink is not a cherry tree. Never let instance colours go above 1: they clip to flat.+## Compare each roundEach self-review round renders the build from the reference's camera (its angle and field of view, at a distancewhere the subject fills the same share of the frame) at the same size and puts the two side by-side in one image. Write the three biggest gaps, each tied to a card line ("ground is one flat colour, card says-grass with flowers and stones"), fix them, and render again. A round passes when no gap is about the card's camera,-palette, light or density. Show the user the side-by-side, not the render alone.+side in one image. Run `uv run --no-project --with pillow python {{SKILL_DIR}}/scripts/compare-look.py+<reference> <render>`: it fails when the median luminance or the saturation is more than 10% off. Darkness is+hard to judge by eye next to the scene you built, so trust the number. Crop each hero prop next to the real photo+too. Write the three biggest gaps, each tied to a card line ("ground is one flat colour, card says+grass with flowers and stones"), fix them, and render again. A round passes when compare-look prints PASS and no gap is+about the card's camera, palette, light, density or a hero prop's silhouette. Show the user the side-by-side, not the render alone.## Copy the style, not the workdiff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/compare-look.py b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/compare-look.pynew file mode 100644index 0000000..2b5ef5b--- /dev/null+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/compare-look.py@@ -0,0 +1,57 @@+"""Compare a render's brightness and colour strength with its style reference.++Usage: uv run --no-project --with pillow python compare-look.py <reference> <render> [--tolerance 0.10]++Both images are shrunk to 640 px. The script prints the median, 10th and 90th percentile+luminance and the mean saturation of each, then the render's ratio to the reference. It fails+when the median luminance or the mean saturation differs from the reference by more than the+tolerance. Crop UI out of both images first when the UI covers much of either frame.+"""++import argparse+import sys++from PIL import Image+++def measure(image_path):+ image = Image.open(image_path).convert("RGB")+ image.thumbnail((640, 640))+ luminance = sorted(image.convert("L").tobytes())+ saturation = image.convert("HSV").tobytes()[1::3]+ count = len(luminance)+ return {+ "median": luminance[count // 2],+ "p10": luminance[count // 10],+ "p90": luminance[(9 * count) // 10],+ "saturation": sum(saturation) / len(saturation),+ }+++def main():+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])+ parser.add_argument("reference")+ parser.add_argument("render")+ parser.add_argument("--tolerance", type=float, default=0.10)+ arguments = parser.parse_args()+ reference = measure(arguments.reference)+ render = measure(arguments.render)+ for name, values in (("reference", reference), ("render", render)):+ print(+ f"{name:9} luminance median {values['median']:3} p10 {values['p10']:3} p90 {values['p90']:3}"+ f" saturation {values['saturation']:.0f}"+ )+ brightness_ratio = render["median"] / max(reference["median"], 1)+ saturation_ratio = render["saturation"] / max(reference["saturation"], 1)+ failures = []+ if abs(brightness_ratio - 1) > arguments.tolerance:+ failures.append("darker" if brightness_ratio < 1 else "brighter")+ if abs(saturation_ratio - 1) > arguments.tolerance:+ failures.append("duller" if saturation_ratio < 1 else "more saturated")+ verdict = "FAIL " + ", ".join(failures) if failures else "PASS"+ print(f"{verdict}: brightness x{brightness_ratio:.2f}, saturation x{saturation_ratio:.2f} of the reference")+++if __name__ == "__main__":+ main()