Skip to content

armgit / viz3d

Public Imported from GitHub
0

An AI agent skill that turns any subject into a 3D film or app

viz3d 0.9.4: gates and references that work for technical looks

Nguyen Xuan An95b5650756df
diff --git a/plugins/visualize-in-3d/.claude-plugin/plugin.json b/plugins/visualize-in-3d/.claude-plugin/plugin.json
index 51a5c7d..0f82662 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.3",
+ "version": "0.9.4",
"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/SKILL.md b/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md
index a815a3a..b71643e 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md
@@ -27,7 +27,8 @@ Paths use `{{WORK_DIR}}` for the folder where projects live (the current directo
about 80 tool calls. Where it does not, run the passes one after another in this session, finish and check one
before starting the next, and re-read the plan file at the start of each.
4. **Downloads** (elevation, map data, models, reference images, sounds): name the source, count and rough size,
- and get the user's OK first.
+ and get the user's OK first. If the user approved downloads ahead or is away, take open files only (CC0, CC BY,
+ public domain, open data), list each in `CREDITS.md` and go on.
## 1. Pick the shape
@@ -83,8 +84,7 @@ rule with a check in `{{WORK_DIR}}/viz3d-lessons.md`, applied to this piece befo
## 6. Polish
-Give fixes to one more pass with "everything else is approved, change nothing else", then re-record. Publish only
-on the user's word.
+Give fixes to one more pass ("everything else is approved, change nothing else"), re-record, publish on the user's word.
## Rules
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/book.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/book.md
index 30f78db..da53b0f 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/references/book.md
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/book.md
@@ -42,6 +42,12 @@ Use three.js with no Blender. A lofted shell, boxes and a few extrusions read we
count, the worst offset and the worst offenders. It must report 0 above a 2 cm tolerance, and no sunken figure
either. Run it on the raw requested heights as well, to see how many rooms relied on the drop.
+- **Machines** (a watch, an engine, a pump). The rooms are stages of the power path: source, transmission, regulator,
+ output. Callouts name each part's job and its real speed or ratio from tooth counts or specs, and the parts move at
+ those ratios on one clock, with a speed control (real time and two faster steps) so slow parts are seen to move. A
+ case or frame is cut like a shell and stays round: at least 64 segments, never a faceted box. A plate is plain or
+ finished as the real part is (brass, perlage, stripes), never a dot grid. Figures are left out.
+
## Post pass
A full-screen pass turns the render into a plate.
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.md
index cc33b7a..054de38 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
@@ -13,7 +13,9 @@ seeded data to a real feed is a config change.
## Quick prototype
Skip Pass 1 and do not ask about Blender. Build everything in one pass in `{{WORK_DIR}}/<topic>/app` with the Pass 2 stack
-(Vite, React, React Three Fiber, drei, postprocessing with N8AO) and these cuts:
+(Vite, React, React Three Fiber, drei, postprocessing with N8AO) and these cuts. A named look's own rules win over
+steps 2 and 3: a Space-time cube draws lines and a map, a Point-cloud survey draws dots, a cutaway plate draws its
+plate, and none of them needs props or a dressed ground. Plain three.js without React is fine for those.
1. **One site, one process.** The topic file lists one site, four KPIs and three to five stages. Leave out the site
switcher and the film unless the user asks.
@@ -40,7 +42,10 @@ Skip Pass 1 and do not ask about Blender. Build everything in one pass in `{{WOR
the surroundings dressed to the card's density; every palette colour from the card; every model the right real
kind; 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. Measure brightness against the
+ <screenshot>`; it prints PASS or FAIL and the share of the largest flat colour. A look whose design is a flat
+ background (the paper of a cutaway plate or space-time cube, the void of a point cloud, white model) passes
+ `--ignore "<background hex>"`, and the rest of the frame must still pass. The subject named in the request
+ fills at least a third of the default view: a strait seen as a thin line between hills fails. 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 runs
at 60 fps, the page logs no errors, and `npm run build` gives a static folder that opens from any web server.
diff --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.md
index f74c4ac..70665d3 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
@@ -12,6 +12,14 @@ round, Copy the style, not the work.
Dribbble, Behance, ArtStation, Awwwards, Sketchfab, YouTube. Search by the look and the shape, not only the
subject: "isometric stylized water three.js", "cutaway diorama", "ops dashboard 3D". Prefer pieces with a live
page or a video, so you can study the motion and interaction too.
+ The reference must be in the same look as the build: a green LiDAR statue is no reference for a white-dot
+ strait map, and an off-look reference is worse than none. Search terms per look: Point-cloud survey "point cloud
+ terrain map white dots", "lidar city render"; Illustrated cutaway plate "cutaway illustration", "exploded view
+ engraving", a patent drawing; Space-time cube "space-time cube Hägerstrand", "time geography 3D". Fetch with a
+ browser User-Agent (`curl -L -A "Mozilla/5.0" ...`). Wikimedia Commons (`commons.wikimedia.org/w/api.php`) and the
+ Internet Archive hold public-domain plates and drawings; Commons rate-limits fast loops, so wait about 2 s
+ between calls and stop at about five tries. With no same-look reference after that, write the card from the
+ look's description in `looks.md`, skip compare-look and say so in the report.
3. **Let the user pick.** Show the candidates side by side with one line each on what each one brings. If the user
is away, pick the piece with the most engagement. Its camera and density must fit the subject. Say why.
4. A look from `looks.md` is still chosen for its rules (camera kind, UI, traps). Where the reference and the
@@ -62,7 +70,8 @@ shapes (`asset-sources.md`) instead of reshaping primitives toward them.
Each self-review round renders the build from the reference's camera (its angle and field of view, at a distance
where the subject fills the same share of the frame) at the same size and puts the two side by
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, or the hue moves more than 10 degrees. Darkness is
+<reference> <render>`: it fails when the median luminance or the saturation is more than 10% off, or the hue moves more than 10 degrees. A monochrome reference (an engraving, a line drawing) is compared on
+luminance only, by itself. 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
diff --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.py
index c4bdfa0..e823f1f 100644
--- 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.py
@@ -7,7 +7,8 @@ luminance and the mean saturation of each, then the render's ratio to the refere
when the median luminance or the mean saturation differs from the reference by more than the
tolerance, or when the median hue of the coloured pixels moves more than 10 degrees
(water and flowers mix into it, so a smaller shift is noise). Crop UI out of both images first
-when the UI covers much of either frame.
+when the UI covers much of either frame. A monochrome reference (mean saturation under 20, such
+as an engraving or a line drawing) is compared on luminance only.
"""
import argparse
@@ -16,8 +17,17 @@ import sys
from PIL import Image
+def open_on_white(image_path):
+ image = Image.open(image_path)
+ if image.mode in ("RGBA", "LA", "P"):
+ image = image.convert("RGBA")
+ background = Image.new("RGBA", image.size, (255, 255, 255, 255))
+ image = Image.alpha_composite(background, image)
+ return image.convert("RGB")
+
+
def measure(image_path):
- image = Image.open(image_path).convert("RGB")
+ image = open_on_white(image_path)
image.thumbnail((640, 640))
luminance = sorted(image.convert("L").tobytes())
hsv = image.convert("HSV").tobytes()
@@ -27,6 +37,7 @@ def measure(image_path):
count = len(luminance)
return {
"hue": coloured_hues[len(coloured_hues) // 2] * 360 / 255 if coloured_hues else 0,
+ "coloured_share": len(coloured_hues) / count,
"median": luminance[count // 2],
"p10": luminance[count // 10],
"p90": luminance[(9 * count) // 10],
@@ -50,12 +61,19 @@ def main():
)
brightness_ratio = render["median"] / max(reference["median"], 1)
saturation_ratio = render["saturation"] / max(reference["saturation"], 1)
+ monochrome_reference = reference["saturation"] < 20
+ if monochrome_reference:
+ print("monochrome reference: comparing luminance only")
failures = []
if abs(brightness_ratio - 1) > arguments.tolerance:
failures.append("darker" if brightness_ratio < 1 else "brighter")
- if abs(saturation_ratio - 1) > arguments.tolerance:
+ if not monochrome_reference and abs(saturation_ratio - 1) > arguments.tolerance:
failures.append("duller" if saturation_ratio < 1 else "more saturated")
- hue_shift = render["hue"] - reference["hue"]
+ # Hue is an angle: take the short way round, and skip it when either image is nearly colourless.
+ hue_shift = (render["hue"] - reference["hue"] + 180) % 360 - 180
+ hue_measurable = min(reference["coloured_share"], render["coloured_share"]) >= 0.02
+ if not hue_measurable or monochrome_reference:
+ hue_shift = 0
if abs(hue_shift) > 10:
failures.append(f"hue off by {hue_shift:+.0f} degrees")
verdict = "FAIL " + ", ".join(failures) if failures else "PASS"
diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/ground-share.py b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/ground-share.py
index 0565176..e93c126 100644
--- a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/ground-share.py
+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/ground-share.py
@@ -1,10 +1,12 @@
"""Report how much of a screenshot one flat colour covers.
-Usage: uv run --no-project --with pillow python ground-share.py <image> [--levels 24]
+Usage: uv run --no-project --with pillow python ground-share.py <image> [--levels 24] [--ignore "#f5f5eb"]
Each RGB channel is cut into `levels` steps, so near-identical colours fall in one bucket.
The script prints the largest bucket's share of the frame and its colour. The prototype
quality gate in references/live-embed.md fails when that share is over 0.25.
+--ignore (repeatable) leaves out a look's own flat background, such as the paper of a cutaway
+plate or the void of a point cloud, before measuring; the share is then of the remaining pixels.
"""
import argparse
@@ -14,16 +16,26 @@ from collections import Counter
from PIL import Image
-def largest_bucket_share(image_path, levels):
+def near(colour, other, distance=18):
+ return all(abs(a - b) <= distance for a, b in zip(colour, other))
+
+
+def parse_hex(text):
+ text = text.lstrip("#")
+ return tuple(int(text[index:index + 2], 16) for index in (0, 2, 4))
+
+
+def largest_bucket_share(image_path, levels, ignored=()):
image = Image.open(image_path).convert("RGB")
image.thumbnail((640, 640))
step = 256 // levels
raw_bytes = image.tobytes()
- pixel_count = len(raw_bytes) // 3
- buckets = Counter(
- (raw_bytes[index] // step, raw_bytes[index + 1] // step, raw_bytes[index + 2] // step)
- for index in range(0, len(raw_bytes), 3)
- )
+ pixels = [tuple(raw_bytes[index:index + 3]) for index in range(0, len(raw_bytes), 3)]
+ pixels = [pixel for pixel in pixels if not any(near(pixel, colour) for colour in ignored)]
+ pixel_count = max(len(pixels), 1)
+ buckets = Counter((red // step, green // step, blue // step) for red, green, blue in pixels)
+ if not buckets:
+ return 0.0, (0, 0, 0)
bucket, count = buckets.most_common(1)[0]
centre = tuple(channel * step + step // 2 for channel in bucket)
return count / pixel_count, centre
@@ -34,8 +46,10 @@ def main():
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("image")
parser.add_argument("--levels", type=int, default=24)
+ parser.add_argument("--ignore", action="append", default=[], help="a look's own background colour as hex")
arguments = parser.parse_args()
- share, colour = largest_bucket_share(arguments.image, arguments.levels)
+ ignored = [parse_hex(text) for text in arguments.ignore]
+ share, colour = largest_bucket_share(arguments.image, arguments.levels, ignored)
verdict = "FAIL" if share > 0.25 else "PASS"
print(f"{verdict} largest flat colour covers {share:.3f} of the frame, near #{colour[0]:02x}{colour[1]:02x}{colour[2]:02x}")