Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor
Add command-line tools for building projects with a coding agent
shinshin86fcc00758c7de
diff --git a/.gitignore b/.gitignoreindex 4afd02e..e8d6db8 100644--- a/.gitignore+++ b/.gitignore@@ -10,3 +10,6 @@ samples/**/*.jpgsamples/**/*.jpegsamples/**/*.webp__pycache__/+projects/+work/+samples/**/review/diff --git a/package.json b/package.jsonindex 590542c..b28509a 100644--- a/package.json+++ b/package.json@@ -6,9 +6,11 @@"scripts": {"dev": "vite --host 127.0.0.1","test": "vitest run",- "lint": "eslint src tests e2e",+ "lint": "eslint src tests e2e tools/*.mjs","build": "tsc --noEmit && vite build",- "e2e": "playwright test"+ "e2e": "playwright test",+ "validate-rig": "node --experimental-strip-types tools/validate-rig.mjs",+ "render-poses": "node --experimental-strip-types tools/render-poses.mjs"},"dependencies": {"react": "^19.1.0",diff --git a/src/rig/validate.ts b/src/rig/validate.tsindex 5f87c93..d51c069 100644--- a/src/rig/validate.ts+++ b/src/rig/validate.ts@@ -41,7 +41,7 @@ const unit: Check = (v, p, e) => {number(v, p, e);if (typeof v === 'number' && (v < 0 || v > 1)) e.push(`${p}: must be between 0 and 1`);};-const schema = object({+const schema = (draft: boolean) => object({version: (v, p, e) => { if (v !== 1) e.push(`${p}: only version 1 is supported`); },image: object({ width: integer, height: integer }),head: object({ ...ellipseFields, shiftX: number, shiftY: number, pivotX: number,@@ -53,7 +53,7 @@ const schema = object({jaw: object({ ...ellipseFields, band }) }),buns: object({ bunL: ellipse, bunR: ellipse }, ['bunL', 'bunR']),eyes: array(object({ opening: polygon, roi: polygon, x0: number, x1: number,- top: array(number, 24, 24), bot: array(number, 24, 24) }), 2, 2),+ top: array(number, 24, 24), bot: array(number, 24, 24) }, draft ? ['x0', 'x1', 'top', 'bot'] : []), 2, 2),mouth: object({ cx: number, cy: number, angle: number, halfLen: positive, bow: number,area: object({ ...ellipseFields, angle: number }) }),cheeks: array(point, 2, 2),@@ -70,12 +70,18 @@ const schema = object({view: object({ padTop: number, padSide: number, gazeCenter: point }, ['gazeCenter']),}, ['buns', 'strands', 'accessories', 'hand']);-export function validateRig(value: unknown): string[] {+export function validateRig(value: unknown, options: { draft?: boolean } = {}): string[] {const errors: string[] = [];- schema(value, 'rig', errors);+ schema(options.draft ?? false)(value, 'rig', errors);if (errors.length) return errors;const rig = value as Rig;rig.eyes.forEach((eye, i) => {+ const curves = ['x0', 'x1', 'top', 'bot'] as const;+ if (options.draft && curves.every(key => eye[key] === undefined)) return;+ if (curves.some(key => eye[key] === undefined)) {+ errors.push(`rig.eyes[${i}]: supply all x0/x1/top/bot fields or omit all in a draft`);+ return;+ }if (eye.x0 >= eye.x1) errors.push(`rig.eyes[${i}].x1: must exceed x0`);if (eye.top.some((y, k) => y > eye.bot[k])) errors.push(`rig.eyes[${i}].top: must not exceed bottom curve`);});diff --git a/tests/rig.test.ts b/tests/rig.test.tsindex 08b7964..e01170e 100644--- a/tests/rig.test.ts+++ b/tests/rig.test.ts@@ -29,3 +29,14 @@ test('rejects nonfinite values, zero radii and degenerate strands', () => {rig.strands![0].nodes[1] = rig.strands![0].nodes[0];expect(validateRig(rig).join()).toContain('rig.strands[0].nodes');});+test('draft validation permits omitted generated curves without weakening complete rigs', () => {+ const draft = structuredClone(fixture) as Record<string, unknown>;+ draft.eyes = fixture.eyes.map(({ opening, roi }) => ({ opening, roi }));+ expect(validateRig(draft, { draft: true })).toEqual([]);+ expect(validateRig(draft).join()).toContain('rig.eyes[0].top');+ const partial = structuredClone(draft) as { eyes: Record<string, unknown>[] };+ partial.eyes[0].x0 = 400;+ expect(validateRig(partial, { draft: true }).join()).toContain('supply all');+ partial.eyes[0].opening = [[1, 2], [3, 4]];+ expect(validateRig(partial, { draft: true }).join()).toContain('rig.eyes[0].opening');+});diff --git a/tools/agent_common.py b/tools/agent_common.pynew file mode 100644index 0000000..c08ff44--- /dev/null+++ b/tools/agent_common.py@@ -0,0 +1,173 @@+"""Local image-tool helpers. Coordinates always refer to source-image pixels."""++import json+import math+from pathlib import Path++from PIL import Image, ImageDraw, ImageFont++ROOT = Path(__file__).resolve().parent.parent+++def inside_repo(path):+ path = Path(path).resolve()+ if not path.is_relative_to(ROOT):+ raise ValueError("output must stay inside the repository")+ return path+++def project_image(project):+ project = inside_repo(project)+ with Image.open(project / "source.png") as image:+ if image.format != "PNG":+ raise ValueError("source.png must be a PNG")+ return image.convert("RGBA")+++def read_rig(project, filename=None):+ project = inside_repo(project)+ path = project / (+ filename+ or ("rig.json" if (project / "rig.json").exists() else "rig.draft.json")+ )+ return json.loads(path.read_text(encoding="utf-8"))+++def save_image(image, path):+ path = inside_repo(path)+ path.parent.mkdir(parents=True, exist_ok=True)+ image.save(path)+++def save_json(value, path):+ path = inside_repo(path)+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(+ json.dumps(value, indent=2, allow_nan=False) + "\n", encoding="utf-8"+ )+++def font(size=16):+ return ImageFont.load_default(size=size)+++def region_arg(text):+ try:+ values = [int(n) for n in text.split(",")]+ except ValueError as error:+ raise ValueError(+ "region must be x0,y0,x1,y1 in integer source pixels"+ ) from error+ if len(values) != 4 or values[0] >= values[2] or values[1] >= values[3]:+ raise ValueError("region must have positive area: x0,y0,x1,y1")+ return values+++def grid_image(image, region=None, step=50):+ if step <= 0:+ raise ValueError("grid step must be positive")+ w, h = image.size+ x0, y0, x1, y1 = region or (0, 0, w, h)+ if not 0 <= x0 < x1 <= w or not 0 <= y0 < y1 <= h:+ raise ValueError("region must be inside the source image")+ grey = Image.new("RGBA", image.size, (145, 145, 145, 255))+ grey.alpha_composite(image)+ crop = grey.convert("RGB").crop((x0, y0, x1, y1))+ width = min(1200, max(900, crop.width))+ scale = width / crop.width+ crop = crop.resize((width, round(crop.height * scale)), Image.Resampling.NEAREST)+ left, top = 64, 38+ result = Image.new("RGB", (crop.width + left, crop.height + top), "#eeeef2")+ result.paste(crop, (left, top))+ draw = ImageDraw.Draw(result)+ label_font = font(14)+ spacing = step * scale+ x_stride = max(1, math.ceil(48 / spacing))+ y_stride = max(1, math.ceil(18 / spacing))+ for x in range(math.ceil(x0 / step) * step, x1, step):+ px = left + round((x - x0) * scale)+ major = (x // step) % 5 == 0+ draw.line(+ (px, top, px, result.height),+ fill="#494f5c" if major else "#737987",+ width=2 if major else 1,+ )+ if (x // step) % x_stride == 0:+ draw.text((px + 2, 15), str(x), font=label_font, fill="#171b23")+ for y in range(math.ceil(y0 / step) * step, y1, step):+ py = top + round((y - y0) * scale)+ major = (y // step) % 5 == 0+ draw.line(+ (left, py, result.width, py),+ fill="#494f5c" if major else "#737987",+ width=2 if major else 1,+ )+ if (y // step) % y_stride == 0:+ draw.text((3, py - 6), str(y), font=label_font, fill="#171b23")+ draw.text((3, 3), "source px", font=font(12), fill="#171b23")+ return result, lambda p: (left + (p[0] - x0) * scale, top + (p[1] - y0) * scale)+++EYE_VARIANTS = ("eyes_closed", "eyes_half", "eyes_smile")+MOUTH_VARIANTS = ("mouth_a", "mouth_a_half", "mouth_i", "mouth_o")+++def edit_masks(rig, size):+ """RGBA edit-mask convention: transparent pixels may change; opaque pixels stay."""+ import cv2+ import numpy as np++ w, h = size+ if len(rig.get("eyes", [])) != 2:+ raise ValueError("rig.eyes must contain two eyes")+ eye_regions = []+ for i, eye in enumerate(rig["eyes"]):+ points = np.asarray(eye["roi"], dtype=np.float32)+ if (+ points.ndim != 2+ or points.shape[1] != 2+ or len(points) < 3+ or not np.isfinite(points).all()+ or cv2.contourArea(points) <= 0+ ):+ raise ValueError(+ f"rig.eyes[{i}].roi: expected a finite polygon with positive area"+ )+ mask = np.zeros((h, w), np.uint8)+ cv2.fillPoly(mask, [np.rint(points).astype(np.int32)], 1)+ eye_regions.append(cv2.dilate(mask, np.ones((9, 9), np.uint8)))+ if np.any(eye_regions[0] & eye_regions[1]):+ raise ValueError(+ "dilated eye ROIs overlap; separate them before requesting variants"+ )+ mouth = np.zeros((h, w), np.uint8)+ area = rig["mouth"]["area"]+ if (+ not all(np.isfinite(area[k]) for k in ("cx", "cy", "rx", "ry"))+ or min(area["rx"], area["ry"]) <= 0+ or not np.isfinite(area.get("angle", 0))+ ):+ raise ValueError(+ "rig.mouth.area: expected a finite ellipse with positive radii"+ )+ cv2.ellipse(+ mouth,+ (round(area["cx"]), round(area["cy"])),+ (round(area["rx"]), round(area["ry"])),+ math.degrees(area.get("angle", 0)),+ 0,+ 360,+ 1,+ -1,+ )+ mouth = cv2.dilate(mouth, np.ones((9, 9), np.uint8))+ return eye_regions, mouth+++def rgba_mask(region):+ import numpy as np++ result = np.zeros((*region.shape, 4), np.uint8)+ result[..., :3] = 255+ result[..., 3] = np.where(region, 0, 255)+ return Image.fromarray(result)diff --git a/tools/build-sprites.py b/tools/build-sprites.pynew file mode 100644index 0000000..6184655--- /dev/null+++ b/tools/build-sprites.py@@ -0,0 +1,164 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4", "numpy", "opencv-python-headless"]+# ///+"""Validate local full-size drawings and cut engine-compatible feathered sprites."""++import argparse+import hashlib+import json+import sys+import tempfile+from pathlib import Path++import cv2+import numpy as np+from agent_common import (+ EYE_VARIANTS,+ MOUTH_VARIANTS,+ edit_masks,+ inside_repo,+ project_image,+ read_rig,+)+from PIL import Image+++def load_mask(path, size):+ with Image.open(path) as image:+ if image.size != size:+ raise ValueError(f"{path.name}: mask size must match source.png")+ alpha = np.array(image.convert("RGBA"))[..., 3]+ if np.any((alpha != 0) & (alpha != 255)):+ raise ValueError(+ f"{path.name}: use a binary alpha edit mask (0 editable, 255 protected)"+ )+ return (alpha == 0).astype(np.uint8)+++def regions(project, rig, size, name):+ mask_path = project / "variant-requests" / name / "mask.png"+ legacy = (+ project+ / "variant-masks"+ / ("eyes_edit_mask.png" if name in EYE_VARIANTS else "mouth_edit_mask.png")+ )+ if mask_path.exists() or legacy.exists():+ region = load_mask(mask_path if mask_path.exists() else legacy, size)+ if name in EYE_VARIANTS:+ count, labels = cv2.connectedComponents(region)+ if count != 3:+ raise ValueError(+ f"{name}: expected two separate eye mask regions, got {count - 1}"+ )+ components = sorted(+ range(1, count), key=lambda i: np.where(labels == i)[1].mean()+ )+ return [(labels == i).astype(np.uint8) for i in components]+ return [region]+ eyes, mouth = edit_masks(rig, size)+ return eyes if name in EYE_VARIANTS else [mouth]+++def visible(image):+ value = image.astype(np.float32)+ value[..., :3] *= value[..., 3, None] / 255+ return value+++def build(project, output=None, tolerance=8):+ project = inside_repo(project)+ if not np.isfinite(tolerance) or not 0 <= tolerance <= 255:+ raise ValueError("tolerance must be between 0 and 255")+ source_image, rig = project_image(project), read_rig(project)+ source = np.array(source_image)+ if rig["image"] != {"width": source_image.width, "height": source_image.height}:+ raise ValueError("rig.image must match source.png")+ images, meta = {}, {}+ for name in (*EYE_VARIANTS, *MOUTH_VARIANTS):+ path = project / "variants" / f"{name}.png"+ if not path.exists():+ print(f"Skipping missing variant: {name}")+ continue+ with Image.open(path) as image:+ if image.format != "PNG" or image.size != source_image.size:+ raise ValueError(+ f"{name}: expected PNG size {source_image.width} x {source_image.height}, got {image.size}"+ )+ variant = np.array(image.convert("RGBA"))+ parts = regions(project, rig, source_image.size, name)+ region = np.maximum.reduce(parts)+ if not np.any(region) or np.all(region):+ raise ValueError(+ f"{name}: edit mask must contain a nonempty, bounded region"+ )+ delta = np.abs(visible(variant) - visible(source)).max(axis=-1)[region == 0]+ maximum, mean = float(delta.max(initial=0)), float(delta.mean())+ changed = int(np.count_nonzero(delta > tolerance))+ print(+ f"{name}: outside-mask max {maximum:.3f}/255, mean {mean:.6f}/255, {changed} pixels over tolerance {tolerance:g}"+ )+ if changed:+ raise ValueError(+ f"{name}: rejected outside-mask changes; preserve source pixels outside the edit region"+ )+ for i, part in enumerate(parts):+ weight = np.clip(cv2.distanceTransform(part, cv2.DIST_L2, 5) / 4, 0, 1)+ ys, xs = np.where(weight > 0)+ if not len(xs):+ raise ValueError(f"{name}: empty sprite mask")+ x0, y0, x1, y1 = xs.min(), ys.min(), xs.max() + 1, ys.max() + 1+ crop = variant[y0:y1, x0:x1].copy()+ crop[..., 3] = (crop[..., 3] * weight[y0:y1, x0:x1]).astype(np.uint8)+ layer = f"{name}_{i}" if name in EYE_VARIANTS else name+ images[layer] = crop+ meta[layer] = [int(x0), int(y0), int(x1 - x0), int(y1 - y0)]+ if not images:+ print("No variants available; existing sprites were left unchanged.")+ return+ output = inside_repo(output or project / "built/sprites")+ output.parent.mkdir(parents=True, exist_ok=True)+ with tempfile.TemporaryDirectory(+ prefix=".build-sprites-", dir=output.parent+ ) as temporary:+ stage = Path(temporary)+ for name, crop in images.items():+ Image.fromarray(crop).save(stage / f"{name}.png")+ build_id = hashlib.sha1(+ b"".join((stage / f"{name}.png").read_bytes() for name in sorted(meta))+ ).hexdigest()[:10]+ (stage / "sprites.json").write_text(+ json.dumps({"build": build_id, "layers": meta}, indent=2) + "\n",+ encoding="utf-8",+ )+ output.mkdir(exist_ok=True)+ for filename in [*(f"{name}.png" for name in meta), "sprites.json"]:+ (stage / filename).replace(output / filename)+ print(f"Built {len(meta)} sprites; build {build_id}.")+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("project", type=Path)+ parser.add_argument(+ "--out",+ type=Path,+ help="Alternate output inside the repository (for reference comparisons)",+ )+ parser.add_argument(+ "--tolerance",+ type=float,+ default=8,+ help="Maximum outside-mask premultiplied RGBA channel difference, 0..255 (default: 8)",+ )+ args = parser.parse_args()+ try:+ build(args.project, args.out, args.tolerance)+ except (OSError, ValueError, KeyError, TypeError, cv2.error) as error:+ print(f"build-sprites: {error}", file=sys.stderr)+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tools/grid.py b/tools/grid.pynew file mode 100644index 0000000..f210cc1--- /dev/null+++ b/tools/grid.py@@ -0,0 +1,32 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4"]+# ///+"""Draw a readable grid labelled in original source-image coordinates."""++import argparse+import sys+from pathlib import Path++from agent_common import grid_image, project_image, region_arg, save_image+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("project", type=Path)+ parser.add_argument("--region", type=region_arg)+ parser.add_argument("--step", type=int, default=50)+ parser.add_argument("--out", type=Path, required=True)+ args = parser.parse_args()+ try:+ result, _ = grid_image(project_image(args.project), args.region, args.step)+ save_image(result, args.out)+ print(f"Grid written: {args.out}; all labels are source pixels.")+ except (OSError, ValueError) as error:+ print(f"grid: {error}", file=sys.stderr)+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tools/new-project.py b/tools/new-project.pynew file mode 100644index 0000000..d337dcf--- /dev/null+++ b/tools/new-project.py@@ -0,0 +1,124 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4"]+# ///+"""Create a private local project skeleton; its empty eye polygons must be traced."""++import argparse+import json+import re+import shutil+import sys+from pathlib import Path++from agent_common import ROOT, inside_repo, save_json+from PIL import Image+++def create(source, name, force=False):+ if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]*", name):+ raise ValueError("name must use letters, digits, hyphens or underscores")+ with Image.open(source) as image:+ if image.format != "PNG":+ raise ValueError("input must be a PNG")+ image.load()+ w, h = image.size+ if "A" not in image.getbands() and "transparency" not in image.info:+ print(+ "Warning: no alpha channel; a transparent background is recommended.",+ file=sys.stderr,+ )+ if h < 800:+ print(+ "Warning: image is less than 800 px tall; eye details may be difficult to trace.",+ file=sys.stderr,+ )+ project = inside_repo(ROOT / "projects" / name)+ if not project.is_relative_to((ROOT / "projects").resolve()):+ raise ValueError(+ "project must stay inside projects/; redirected paths are not allowed"+ )+ if project.exists() and not force:+ raise ValueError(+ "project already exists; use --force to replace source and draft (other files are retained)"+ )+ if (project / "source.png").resolve() == source.resolve():+ raise ValueError("input is already this project's source.png")+ template = json.loads((ROOT / "samples/miko-qipao/rig.json").read_text())+ ellipse = lambda x, y, rx, ry: {+ "cx": w * x,+ "cy": h * y,+ "rx": w * rx,+ "ry": h * ry,+ }+ rig = {+ "version": 1,+ "image": {"width": w, "height": h},+ "head": {+ **ellipse(0.5, 0.3, 0.3, 0.3),+ "shiftX": 0,+ "shiftY": 0,+ "pivotX": w / 2,+ "pivotY": h * 0.55,+ "maxRoll": 0.15,+ "weightBand": [h * 0.5, h * 0.65],+ "turnBand": [h * 0.5, h * 0.7],+ },+ "body": {+ "pivotX": w / 2,+ "pivotY": h,+ "maxRoll": 0.035,+ "breathBand": [h * 0.6, h],+ "rollBand": [h * 0.5, h],+ "chest": ellipse(0.5, 0.75, 0.3, 0.25),+ "shoulders": [],+ },+ "face": {+ name: ellipse(0.5, 0.35, 0.04, 0.03)+ for name in ("nose", "mouth", "eyeA", "eyeB", "earL", "earR", "brow", "jaw")+ },+ "eyes": [{"opening": [], "roi": []} for _ in range(2)],+ "mouth": {+ "cx": w / 2,+ "cy": h * 0.45,+ "angle": 0,+ "halfLen": w * 0.04,+ "bow": 0,+ "area": {**ellipse(0.5, 0.45, 0.06, 0.03), "angle": 0},+ },+ "cheeks": [[w * 0.4, h * 0.4], [w * 0.6, h * 0.4]],+ "mesh": template["mesh"],+ "view": template["view"],+ }+ for part in ("brow", "jaw"):+ rig["face"][part]["band"] = [h * 0.4, h * 0.45]+ # Retain engine defaults, but no example illustration's gaze origin.+ rig["view"].pop("gazeCenter", None)+ (project / "work").mkdir(parents=True, exist_ok=True)+ shutil.copyfile(source, project / "source.png")+ save_json(rig, project / "rig.draft.json")+ print(+ f"Created projects/{name}/ ({w} x {h}). Trace the empty eyes and place every required region before building."+ )+ if force:+ print(+ "Existing generated layers/variants were retained; rebuild and review before use."+ )+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("image", type=Path)+ parser.add_argument("name")+ parser.add_argument("--force", action="store_true")+ args = parser.parse_args()+ try:+ create(args.image, args.name, args.force)+ except (OSError, ValueError) as error:+ print(f"new-project: {error}", file=sys.stderr)+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tools/overlay.py b/tools/overlay.pynew file mode 100644index 0000000..e2f6b3a--- /dev/null+++ b/tools/overlay.py@@ -0,0 +1,184 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4"]+# ///+"""Review rig regions and node indices on a source image using editor part colours."""++import argparse+import math+import re+import sys+from pathlib import Path++from agent_common import ROOT, font, grid_image, project_image, read_rig, save_image+from PIL import Image, ImageDraw+++def geometry(rig):+ shapes = []++ def add(group, path, points, closed=False):+ shapes.append((group, path, points, closed))++ def walk(value, path, group):+ key = path.split(".")[-1]+ if isinstance(value, dict):+ if all(k in value for k in ("cx", "cy", "rx", "ry")):+ angle = value.get("angle", 0)+ points = []+ for i in range(64):+ theta = i * math.tau / 64+ x, y = value["rx"] * math.cos(theta), value["ry"] * math.sin(theta)+ points.append(+ [+ value["cx"] + x * math.cos(angle) - y * math.sin(angle),+ value["cy"] + x * math.sin(angle) + y * math.cos(angle),+ ]+ )+ add(group, path, points, True)+ add(group, path + ".centre", [[value["cx"], value["cy"]]])+ if all(k in value for k in ("cx", "cy", "halfLen", "angle")):+ angle = value["angle"]+ points = []+ for i in range(33):+ s = i / 16 - 1+ x = s * value["halfLen"]+ y = value.get("bow", 0) * (1 - s * s)+ points.append(+ [+ value["cx"] + x * math.cos(angle) - y * math.sin(angle),+ value["cy"] + x * math.sin(angle) + y * math.cos(angle),+ ]+ )+ add(group, path + ".line", points)+ if all(k in value for k in ("pivotX", "pivotY")):+ add(group, path + ".pivot", [[value["pivotX"], value["pivotY"]]])+ if all(k in value for k in ("x0", "y0", "x1", "y1")):+ x0, y0, x1, y1 = (value[k] for k in ("x0", "y0", "x1", "y1"))+ add(group, path, [[x0, y0], [x1, y0], [x1, y1], [x0, y1]], True)+ if "pivot" in value and "tip" in value:+ add(group, path + ".axis", [value["pivot"], value["tip"]])+ for key, child in value.items():+ walk(child, path + "." + key, group)+ elif isinstance(value, list) and value:+ if all(+ isinstance(p, list)+ and len(p) == 2+ and all(isinstance(n, (int, float)) for n in p)+ for p in value+ ):+ if group == "cheeks":+ for i, point in enumerate(value):+ add(group, f"{path}.{i}", [point])+ else:+ add(+ group,+ path,+ value,+ key in ("opening", "roi", "outline", "background"),+ )+ elif len(value) == 2 and all(isinstance(n, (int, float)) for n in value):+ if key.endswith("Band") or key in ("band", "jawRange"):+ for i, position in enumerate(value):+ points = (+ [[position, 0], [position, rig["image"]["height"]]]+ if key in ("fingerXBand", "jawRange")+ else [[0, position], [rig["image"]["width"], position]]+ )+ add(group, f"{path}.{i}", points)+ else:+ add(group, path, [value])+ elif key == "box" and len(value) == 4:+ x0, y0, x1, y1 = value+ add(group, path, [[x0, y0], [x1, y0], [x1, y1], [x0, y1]], True)+ elif key not in ("top", "bot"):+ for i, child in enumerate(value):+ walk(child, f"{path}.{i}", group)++ for group, value in rig.items():+ if group not in ("version", "image"):+ walk(value, group, group)+ if "gazeCenter" not in rig["view"]:+ add(+ "view",+ "view.gazeCenter (head centre)",+ [[rig["head"]["cx"], rig["head"]["cy"]]],+ )+ return shapes+++def overlay(project, rig_name, part, zoom, output):+ image, rig = project_image(project), read_rig(project, rig_name)+ if rig["image"] != {"width": image.width, "height": image.height}:+ raise ValueError("rig.image must match source.png")+ colours_text = (+ (ROOT / "src/editor/parts.ts")+ .read_text()+ .split("PART_COLORS:")[1]+ .split("export const SECTIONS")[0]+ )+ colours = dict(re.findall(r"(\w+): '(#[0-9a-fA-F]+)'", colours_text))+ if part and part.split(".")[0] not in colours:+ raise ValueError("unknown part; use " + ", ".join(colours))+ shapes = [+ s+ for s in geometry(rig)+ if not part or s[1] == part or s[1].startswith(part + ".")+ ]+ if not shapes:+ raise ValueError("selected part has no placed geometry")+ if zoom:+ points = [p for _, _, pts, _ in shapes for p in pts]+ xs, ys = zip(*points)+ region = (+ max(0, math.floor(min(xs) - 20)),+ max(0, math.floor(min(ys) - 20)),+ min(image.width, math.ceil(max(xs) + 20)),+ min(image.height, math.ceil(max(ys) + 20)),+ )+ result, transform = grid_image(image, region, 10)+ else:+ bg = Image.new("RGBA", image.size, (145, 145, 145, 255))+ bg.alpha_composite(image)+ result = bg.convert("RGB")+ transform = lambda p: p+ draw = ImageDraw.Draw(result)+ for group, label, points, closed in shapes:+ mapped = [transform(p) for p in points]+ color = colours[group]+ if len(mapped) > 1:+ draw.line(mapped + ([mapped[0]] if closed else []), fill=color, width=2)+ # Ellipse sampling has no user node indices; polylines do.+ sampled_ellipse = len(points) in (33, 64)+ for i, (x, y) in enumerate(mapped if not sampled_ellipse else mapped[:1]):+ draw.ellipse((x - 3, y - 3, x + 3, y + 3), fill=color, outline="white")+ text = label if i == 0 else str(i)+ tx, ty = (+ max(0, min(result.width - 180, x + 5)),+ max(0, min(result.height - 18, y - 18)),+ )+ bounds = draw.textbbox((tx, ty), text, font=font(13))+ draw.rectangle(bounds, fill="white")+ draw.text((tx, ty), text, fill=color, font=font(13))+ save_image(result, output)+ print(f"Overlay written: {output}")+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("project", type=Path)+ parser.add_argument("--rig")+ parser.add_argument("--part")+ parser.add_argument("--zoom", action="store_true")+ parser.add_argument("--out", type=Path, required=True)+ args = parser.parse_args()+ try:+ overlay(args.project, args.rig, args.part, args.zoom, args.out)+ except (OSError, ValueError, KeyError, TypeError) as error:+ print(f"overlay: {error}", file=sys.stderr)+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tools/render-poses.mjs b/tools/render-poses.mjsnew file mode 100644index 0000000..344a129--- /dev/null+++ b/tools/render-poses.mjs@@ -0,0 +1,147 @@+import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises';+import { resolve, relative, dirname, basename } from 'node:path';+import { fileURLToPath } from 'node:url';+import { createServer } from 'vite';+import { chromium } from '@playwright/test';+import { validateRig } from '../src/rig/validate.ts';++const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const poses = [+ ['rest', {}], ['eyes-half', { eyeLOpen: 0.5, eyeROpen: 0.5 }],+ ['eyes-closed', { eyeLOpen: 0, eyeROpen: 0 }], ['mouth-open', { mouthOpen: 1 }],+ ['turn-left', { angleX: -30 }], ['turn-right', { angleX: 30 }],+ ['look-up', { angleY: 15 }], ['look-down', { angleY: -15 }],+ ['tilt-left', { angleZ: -15 }], ['tilt-right', { angleZ: 15 }],+ ['body-left', { bodyAngleZ: -8 }], ['body-right', { bodyAngleZ: 8 }],+];++async function main() {+ const args = process.argv.slice(2);+ if (args.includes('--help')) {+ console.log('Usage: npm run render-poses -- <project>');+ return;+ }+ if (args.length !== 1) throw new Error('Usage: npm run render-poses -- <project>');+ const project = await realpath(resolve(args[0]));+ if (relative(root, project).startsWith('..')) throw new Error('project must stay inside the repository');+ const rig = JSON.parse(await readFile(resolve(project, 'rig.json'), 'utf8'));+ const errors = validateRig(rig);+ if (errors.length) throw new Error(errors.join('\n'));+ const built = await realpath(resolve(project, 'built'));+ if (relative(project, built).startsWith('..')) throw new Error('built folder must stay inside the project');+ const assets = {};+ async function asset(name) {+ const path = await realpath(resolve(built, name));+ if (relative(built, path).startsWith('..')) throw new Error(`asset escapes built folder: ${name}`);+ assets[name] = `data:${name.endsWith('.png') ? 'image/png' : 'application/json'};base64,${(await readFile(path)).toString('base64')}`;+ }+ await asset('layers.json');+ const layers = JSON.parse(await readFile(resolve(built, 'layers.json'), 'utf8'));+ await Promise.all(['base', 'hairmask', ...Object.keys(layers.layers)].map(name => asset(`${name}.png`)));+ try {+ await asset('sprites/sprites.json');+ } catch (error) {+ if (error.code !== 'ENOENT') throw error;+ console.log('Optional drawn sprites absent; reviewing generated eye/mouth layers.');+ }+ if (assets['sprites/sprites.json']) {+ const sprites = JSON.parse(await readFile(resolve(built, 'sprites/sprites.json'), 'utf8'));+ await Promise.all(Object.keys(sprites.layers).map(name => asset(`sprites/${name}.png`)));+ }+ const server = await createServer({ root, configFile: false, publicDir: false, appType: 'custom', cacheDir: 'node_modules/.vite-pose-review', optimizeDeps: { noDiscovery: true, entries: [] },+ plugins: [{ name: 'pose-review-page', configureServer(server) {+ server.middlewares.use((req, res, next) => {+ if (req.url !== '/__pose_review__') return next();+ res.setHeader('Content-Type', 'text/html');+ res.end('<!doctype html><html><body style="margin:0"><canvas id="avatar"></canvas></body></html>');+ });+ } }],+ server: { host: '127.0.0.1', port: 0, strictPort: false, hmr: false, watch: null, preTransformRequests: false }, logLevel: 'error' });+ let browser;+ try {+ await server.listen();+ const address = server.httpServer.address();+ const origin = `http://127.0.0.1:${address.port}`;+ browser = await chromium.launch();+ const page = await browser.newPage({ viewport: { width: Math.ceil(rig.image.width * 1.2), height: Math.ceil(rig.image.height * 1.1) }, deviceScaleFactor: 1 });+ const browserErrors = [];+ page.on('pageerror', error => browserErrors.push(error.message));+ // Only the local code server may be contacted; private images use data URLs.+ await page.route('**/*', route => new URL(route.request().url()).origin === origin ? route.continue() : route.abort());+ await page.goto(`${origin}/__pose_review__`);+ const result = await page.evaluate(async ({ rig, assets, poses }) => {+ const { createMeshAvatar } = await import('/src/engine/index.ts');+ const { PARAMS } = await import('/src/engine/rig.js');+ const canvas = document.getElementById('avatar');+ const width = Math.ceil(rig.image.width * 1.2), height = Math.ceil(rig.image.height * 1.1);+ canvas.style.width = `${width}px`; canvas.style.height = `${height}px`;+ const defaults = Object.fromEntries(PARAMS.map(p => [p.id, p.def]));+ const pictures = [];+ async function avatar() {+ const av = await createMeshAvatar(canvas, { rig, assets, manual: true, padTop: 0.1, padSide: 0.1 });+ av.setAutoIdle(false); av.setAutoMotion(false); av.setParameters(defaults);+ return av;+ }+ for (const [name, values] of poses) {+ const av = await avatar();+ av.setParameters({ ...defaults, ...values }); av.advance(1, 60);+ pictures.push([name, canvas.toDataURL()]); av.destroy();+ }+ const av = await avatar();+ av.setParameters({ ...defaults, angleX: 30 }); av.advance(0.2, 60);+ av.setParameters(defaults);+ for (const [i, seconds] of [0.05, 0.08, 0.12, 0.15, 0.2, 0.3].entries()) {+ av.advance(seconds, 60); pictures.push([`hair-sway-${i}`, canvas.toDataURL()]);+ }+ av.destroy();+ const scale = Math.min(width / (rig.image.width * 1.2), height / (rig.image.height * 1.1));+ const ox = (width - rig.image.width * scale) / 2, oy = height - rig.image.height * scale;+ const bounds = points => {+ const xs = points.map(p => p[0]), ys = points.map(p => p[1]);+ const margin = 80;+ const x = Math.max(0, Math.floor(ox + (Math.min(...xs) - margin) * scale));+ const y = Math.max(0, Math.floor(oy + (Math.min(...ys) - margin) * scale));+ return [x, y, Math.min(width - x, Math.ceil((Math.max(...xs) - Math.min(...xs) + margin * 2) * scale)),+ Math.min(height - y, Math.ceil((Math.max(...ys) - Math.min(...ys) + margin * 2) * scale))];+ };+ const eyes = bounds(rig.eyes.flatMap(e => e.roi));+ const m = rig.mouth.area;+ const mouth = bounds([[m.cx - m.rx, m.cy - m.ry], [m.cx + m.rx, m.cy + m.ry]]);+ const crops = [];+ const sheet = document.createElement('canvas'); sheet.width = 1200; sheet.height = Math.ceil(pictures.length / 4) * 390;+ const ctx = sheet.getContext('2d'); ctx.fillStyle = '#dedfe5'; ctx.fillRect(0, 0, sheet.width, sheet.height);+ for (const [i, [name, url]] of pictures.entries()) {+ const img = new Image(); img.src = url; await img.decode();+ const x = (i % 4) * 300, y = Math.floor(i / 4) * 390;+ const k = Math.min(288 / width, 350 / height);+ ctx.drawImage(img, x + (300 - width * k) / 2, y + 30, width * k, height * k);+ ctx.fillStyle = '#171b23'; ctx.font = '16px sans-serif'; ctx.fillText(name, x + 8, y + 22);+ for (const [part, rect] of [['eyes', eyes], ['mouth', mouth]]) {+ const crop = document.createElement('canvas'); crop.width = 1000; crop.height = Math.round(rect[3] / rect[2] * 1000);+ const context = crop.getContext('2d'); context.fillStyle = '#919191'; context.fillRect(0, 0, crop.width, crop.height);+ context.imageSmoothingEnabled = false; context.drawImage(img, ...rect, 0, 0, crop.width, crop.height);+ crops.push([`${name}-${part}`, crop.toDataURL()]);+ }+ }+ // Label last so all thumbnails have a consistently readable header.+ for (const [i, [name]] of pictures.entries()) {+ const x = (i % 4) * 300, y = Math.floor(i / 4) * 390;+ ctx.fillStyle = '#dedfe5'; ctx.fillRect(x, y, 300, 30);+ ctx.fillStyle = '#171b23'; ctx.font = '16px sans-serif'; ctx.fillText(name, x + 8, y + 22);+ }+ return { images: [...pictures, ...crops, ['contact-sheet', sheet.toDataURL()]], width, height, cropBounds: { eyes, mouth }, padTop: 0.1, padSide: 0.1 };+ }, { rig, assets, poses });+ if (browserErrors.length) throw new Error(browserErrors.join('\n'));+ const review = resolve(project, 'review'); await mkdir(review, { recursive: true });+ if (relative(project, await realpath(review)).startsWith('..')) throw new Error('review folder must stay inside the project');+ for (const [name, url] of result.images) await writeFile(resolve(review, `${name}.png`), Buffer.from(url.split(',')[1], 'base64'));+ const { images, ...metadata } = result;+ await writeFile(resolve(review, 'poses.json'), JSON.stringify({ ...metadata, project: basename(project), fixedFps: 60, poseSeconds: 1, poses: poses.map(([name, parameters]) => ({ name, parameters })), hairFrames: 6, files: images.map(([name]) => `${name}.png`) }, null, 2) + '\n');+ console.log(`Rendered ${poses.length + 6} poses, eye/mouth crops and contact-sheet.png in ${relative(root, review)}/`);+ } finally {+ await browser?.close();+ await server.close();+ }+}++main().catch(error => { console.error(`render-poses: ${error.message}`); process.exitCode = 1; });diff --git a/tools/test_agent_tools.py b/tools/test_agent_tools.pynew file mode 100644index 0000000..0744db4--- /dev/null+++ b/tools/test_agent_tools.py@@ -0,0 +1,160 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4", "numpy", "opencv-python-headless"]+# ///+"""Test calibration scoring, private project boundaries and variant rejection."""++import importlib.util+import json+import subprocess+import sys+import tempfile+import unittest+from pathlib import Path++from agent_common import ROOT, edit_masks, grid_image+from PIL import Image+++def module(filename):+ spec = importlib.util.spec_from_file_location(+ filename.replace("-", "_"), ROOT / "tools" / f"{filename}.py"+ )+ result = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(result)+ return result+++sprites = module("build-sprites")+new = module("new-project")+++class AgentToolsTest(unittest.TestCase):+ def setUp(self):+ (ROOT / "projects").mkdir(exist_ok=True)+ self.temporary = tempfile.TemporaryDirectory(+ prefix="tool-check-", dir=ROOT / "projects"+ )+ self.addCleanup(self.temporary.cleanup)+ self.project = Path(self.temporary.name)+ image = Image.new("RGBA", (100, 100), (210, 190, 175, 255))+ image.save(self.project / "source.png")+ self.rig = {+ "image": {"width": 100, "height": 100},+ "eyes": [+ {"roi": [[10, 20], [30, 20], [30, 40], [10, 40]]},+ {"roi": [[60, 20], [80, 20], [80, 40], [60, 40]]},+ ],+ "mouth": {"area": {"cx": 50, "cy": 65, "rx": 15, "ry": 8, "angle": 0}},+ }+ (self.project / "rig.json").write_text(json.dumps(self.rig))++ def cli(self, name, *args):+ return subprocess.run(+ [sys.executable, str(ROOT / "tools" / f"{name}.py"), *map(str, args)],+ capture_output=True,+ text=True,+ check=False,+ )++ def test_calibration_round_trip_and_bad_or_missing_answers(self):+ folder = self.project / "calibration"+ self.assertEqual(self.cli("vision-check", "make", folder).returncode, 0)+ # This is an automated scorer test, not the agent's visual calibration.+ key = json.loads((folder / ".key.json").read_text())+ answer = self.project / "answer.json"+ answer.write_text(json.dumps(key))+ self.assertEqual(+ self.cli("vision-check", "score", folder, answer).returncode, 0+ )+ key["1"][0] += 40+ answer.write_text(json.dumps(key))+ result = self.cli("vision-check", "score", folder, answer)+ self.assertEqual(result.returncode, 1)+ self.assertIn("FAIL", result.stdout)+ key.pop("1")+ answer.write_text(json.dumps(key))+ self.assertEqual(+ self.cli("vision-check", "score", folder, answer).returncode, 1+ )++ def test_grid_region_dimensions_and_invalid_input(self):+ with Image.open(self.project / "source.png") as image:+ result, transform = grid_image(image, [10, 20, 50, 60], 5)+ self.assertEqual(result.size, (964, 938))+ self.assertEqual(transform([10, 20]), (64, 38))+ with self.assertRaises(ValueError):+ grid_image(image, step=0)+ with self.assertRaises(ValueError):+ grid_image(image, [-1, 0, 50, 60])++ def test_new_project_warns_and_refuses_replacement_or_unsafe_names(self):+ name = self.project.name + "-new"+ created = ROOT / "projects" / name+ # Keep cleanup confined to this test's freshly created directory.+ self.addCleanup(module_cleanup, created)+ rgb = self.project / "opaque.png"+ Image.new("RGB", (100, 100)).save(rgb)+ result = self.cli("new-project", rgb, name)+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertIn("no alpha", result.stderr)+ self.assertIn("800", result.stderr)+ before = (created / "rig.draft.json").read_bytes()+ self.assertEqual(self.cli("new-project", rgb, name).returncode, 1)+ self.assertEqual((created / "rig.draft.json").read_bytes(), before)+ with self.assertRaises(ValueError):+ new.create(rgb, "../escape")+ wrong = self.project / "source.jpg"+ Image.new("RGB", (100, 100)).save(wrong)+ self.assertEqual(self.cli("new-project", wrong, name, "--force").returncode, 1)++ def test_variants_cover_only_regions_and_missing_variants_are_clean(self):+ eyes, mouth = edit_masks(self.rig, (100, 100))+ self.assertEqual(int(eyes[0][30, 20]), 1)+ self.assertEqual(int(eyes[1][30, 70]), 1)+ self.assertEqual(int(eyes[0][65, 50]), 0)+ self.assertEqual(int(mouth[65, 50]), 1)+ self.assertEqual(int(mouth[30, 20]), 0)+ result = self.cli("variant-requests", self.project)+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertEqual(+ len(list((self.project / "variant-requests").glob("*/mask.png"))), 7+ )+ self.assertEqual(self.cli("build-sprites", self.project).returncode, 0)+ self.assertFalse((self.project / "built").exists())+ self.rig["eyes"][0]["roi"] = []+ with self.assertRaisesRegex(ValueError, r"eyes\[0\].roi"):+ edit_masks(self.rig, (100, 100))++ def test_size_and_outside_changes_reject_without_replacing_outputs(self):+ variants = self.project / "variants"+ variants.mkdir()+ path = variants / "mouth_a.png"+ with Image.open(self.project / "source.png") as image:+ valid = image.copy()+ valid.putpixel((50, 65), (30, 0, 0, 255))+ valid.save(path)+ sprites.build(self.project)+ metadata = self.project / "built/sprites/sprites.json"+ before = metadata.read_bytes()+ self.assertEqual(json.loads(before)["layers"]["mouth_a"][2] > 0, True)+ invalid = valid.copy()+ invalid.putpixel((0, 0), (0, 0, 0, 255))+ invalid.save(path)+ with self.assertRaisesRegex(ValueError, "outside-mask"):+ sprites.build(self.project)+ self.assertEqual(metadata.read_bytes(), before)+ Image.new("RGBA", (99, 100)).save(path)+ with self.assertRaisesRegex(ValueError, "size"):+ sprites.build(self.project)+ self.assertEqual(metadata.read_bytes(), before)+++def module_cleanup(path):+ import shutil++ shutil.rmtree(path)+++if __name__ == "__main__":+ unittest.main()diff --git a/tools/validate-rig.mjs b/tools/validate-rig.mjsnew file mode 100644index 0000000..7a37ba5--- /dev/null+++ b/tools/validate-rig.mjs@@ -0,0 +1,21 @@+import { readFile } from 'node:fs/promises';+import { basename } from 'node:path';+import { validateRig } from '../src/rig/validate.ts';++const args = process.argv.slice(2);+const files = args.filter(arg => arg !== '--draft');+if (files.length !== 1 || args.includes('--help')) {+ console.log('Usage: npm run validate-rig -- <rig.json|rig.draft.json> [--draft]');+ process.exit(args.includes('--help') ? 0 : 1);+}+try {+ const draft = args.includes('--draft') || /(^|[._-])draft([._-]|$)/i.test(basename(files[0]));+ const errors = validateRig(JSON.parse(await readFile(files[0], 'utf8')), { draft });+ if (errors.length) {+ errors.forEach(error => console.error(error));+ process.exitCode = 1;+ } else console.log(`Valid ${draft ? 'draft' : 'complete'} rig: ${basename(files[0])}`);+} catch (error) {+ console.error(`validate-rig: ${error.message}`);+ process.exitCode = 1;+}diff --git a/tools/variant-requests.py b/tools/variant-requests.pynew file mode 100644index 0000000..fa0773e--- /dev/null+++ b/tools/variant-requests.py@@ -0,0 +1,96 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4", "numpy", "opencv-python-headless"]+# ///+"""Prepare local edit masks and instructions for optional drawn eye/mouth variants."""++import argparse+import sys+from pathlib import Path++from agent_common import (+ EYE_VARIANTS,+ MOUTH_VARIANTS,+ edit_masks,+ inside_repo,+ project_image,+ read_rig,+ rgba_mask,+ save_image,+)++CHANGES = {+ "eyes_closed": "Close both eyes naturally, using one clean upper lash line per eye. Remove all visible iris and eye white. Keep the eyebrows unchanged.",+ "eyes_half": "Draw both eyes half closed, with the upper lids halfway down. Keep the iris visible only below the upper lid and preserve the original gaze.",+ "eyes_smile": "Draw both eyes closed in a gentle smiling upward arc, with clean lashes and no visible iris or eye white. Keep the eyebrows unchanged.",+ "mouth_a": "Open the mouth in the Japanese vowel あ (a): a natural vertically open mouth, with a subtle tongue and upper teeth.",+ "mouth_a_half": "Draw the Japanese vowel あ (a) at half openness: a smaller, gently open mouth.",+ "mouth_i": "Draw the Japanese vowel い (i): a wide, narrow open smile with subtle upper teeth.",+ "mouth_o": "Draw the Japanese vowel お (o): a small rounded open mouth.",+}+++def generate(project):+ project = inside_repo(project)+ image, rig = project_image(project), read_rig(project)+ if rig["image"] != {"width": image.width, "height": image.height}:+ raise ValueError("rig.image must match source.png")+ eyes, mouth = edit_masks(rig, image.size)+ output = project / "variant-requests"+ output.mkdir(exist_ok=True)+ names = (*EYE_VARIANTS, *MOUTH_VARIANTS)+ for name in names:+ folder = output / name+ save_image(+ rgba_mask((eyes[0] | eyes[1]) if name in EYE_VARIANTS else mouth),+ folder / "mask.png",+ )+ prompt = (+ f"Edit the supplied source.png, exactly {image.width} x {image.height} pixels.\n\n"+ + CHANGES[name]+ + "\n\n"+ "Only fully transparent pixels (alpha = 0) in the supplied mask.png are editable; "+ "opaque pixels are protected. Preserve the original drawing style, line weight, "+ "skin colour, head pose, hair, accessories, clothing and transparent background. "+ "Return a full-size RGBA PNG, not a crop. Pixels outside the edit region must be "+ "identical to source.png, including alpha. Do not resize, shift, recolour or redraw "+ "the rest of the image. Keep all changes at least 4 pixels inside the mask edge "+ "so sprite feathering blends into the unchanged source.\n"+ )+ (folder / "prompt.md").write_text(prompt, encoding="utf-8")+ (output / "README.md").write_text(+ "# Drawn variant requests\n\n"+ f"Required output size: **{image.width} x {image.height}** pixels, RGBA PNG.\n\n"+ "For each variant below, supply `../source.png`, the variant's `mask.png`, and its "+ "`prompt.md` to an image editor you trust. Transparent mask pixels may change; opaque "+ "mask pixels must stay identical. Generating these files is a separate action: this "+ "command uploads nothing. If the image must stay local, use a local editor.\n\n"+ + "\n".join(+ f"- `{name}/mask.png` + `{name}/prompt.md` → `../variants/{name}.png`"+ for name in names+ )+ + "\n\nCreate the `variants/` directory in the project and save each full-size result there. "+ "Then run `uv run tools/build-sprites.py projects/<name>` from the repository root. "+ "It measures outside-mask changes and rejects shifted or redrawn images. Missing "+ "variants are skipped. Review the resulting poses again.\n",+ encoding="utf-8",+ )+ print(+ f"Prepared {len(names)} variant requests in {project.relative_to(project.parents[1])}/variant-requests/"+ )+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("project", type=Path)+ args = parser.parse_args()+ try:+ generate(args.project)+ except (OSError, ValueError, KeyError, TypeError) as error:+ print(f"variant-requests: {error}", file=sys.stderr)+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tools/vision-check.py b/tools/vision-check.pynew file mode 100644index 0000000..22111e0--- /dev/null+++ b/tools/vision-check.py@@ -0,0 +1,110 @@+# /// script+# requires-python = ">=3.10"+# dependencies = ["pillow>=10.4"]+# ///+"""Make and score a visual coordinate-reading calibration. Do not read the key before answering."""++import argparse+import json+import math+import random+import statistics+import sys+from pathlib import Path++from agent_common import font, inside_repo, save_image, save_json+from PIL import Image, ImageDraw+++def make(directory):+ directory = inside_repo(directory)+ if (directory / "check.png").exists() or (directory / ".key.json").exists():+ raise ValueError("calibration already exists; choose a new directory")+ rng = random.SystemRandom()+ scale = 3+ image = Image.new("RGB", (1000 * scale, 1000 * scale), "#e9ebef")+ draw = ImageDraw.Draw(image)+ for _ in range(6000):+ x, y = rng.randrange(3000), rng.randrange(3000)+ draw.point((x, y), fill=rng.choice(("#dde0e6", "#f5f5f7")))+ positions = []+ while len(positions) < 12:+ p = [rng.uniform(45, 920), rng.uniform(45, 945)]+ if all(math.dist(p, q) > 140 for q in positions):+ positions.append(p)+ key = {}+ for i, (x, y) in enumerate(positions, 1):+ x, y = round(x, 2), round(y, 2)+ key[str(i)] = [x, y]+ cx, cy = x * scale, y * scale+ r = 7 * scale+ draw.ellipse(+ (cx - r, cy - r, cx + r, cy + r), fill="#1d2534", outline="white", width=3+ )+ draw.line((cx - 11 * scale, cy, cx + 11 * scale, cy), fill="#cb2258", width=3)+ draw.line((cx, cy - 11 * scale, cx, cy + 11 * scale), fill="#cb2258", width=3)+ draw.text(+ (cx + 15 * scale, cy - 13 * scale),+ str(i),+ font=font(24 * scale),+ fill="#131b27",+ )+ save_image(+ image.resize((1000, 1000), Image.Resampling.LANCZOS), directory / "check.png"+ )+ save_json(key, directory / ".key.json")+ print(+ f"Read {directory.relative_to(inside_repo('.')) if directory.is_relative_to(inside_repo('.')) else directory.name}/check.png (1000 x 1000)."+ )+ print(+ 'Write marker centres in source pixels, origin top-left, as JSON: {"1": [x, y], ..., "12": [x, y]}.'+ )+ print("Do not inspect .key.json. Pass: median error <= 4 px and maximum <= 10 px.")+++def score(directory, answer):+ key = json.loads((inside_repo(directory) / ".key.json").read_text())+ answers = json.loads(Path(answer).read_text())+ if not isinstance(answers, dict) or set(answers) != set(key):+ raise ValueError("answer must contain exactly the numbered marker keys")+ errors = []+ for name, point in key.items():+ value = answers[name]+ if (+ not isinstance(value, list)+ or len(value) != 2+ or any(type(n) not in (int, float) or not math.isfinite(n) for n in value)+ ):+ raise ValueError(f"marker {name}: expected [finite x, finite y]")+ error = math.dist(point, value)+ errors.append(error)+ print(f"marker {name}: {error:.2f} px")+ median, maximum = statistics.median(errors), max(errors)+ passed = median <= 4 and maximum <= 10+ print(+ f"median {median:.2f} px; max {maximum:.2f} px; {'PASS' if passed else 'FAIL'}"+ )+ return 0 if passed else 1+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ sub = parser.add_subparsers(dest="command", required=True)+ sub.add_parser("make").add_argument("directory", type=Path)+ scorer = sub.add_parser("score")+ scorer.add_argument("directory", type=Path)+ scorer.add_argument("answer", type=Path)+ args = parser.parse_args()+ try:+ return (+ score(args.directory, args.answer)+ if args.command == "score"+ else make(args.directory) or 0+ )+ except (OSError, ValueError, TypeError) as error:+ print(f"vision-check: {error}", file=sys.stderr)+ return 1+++if __name__ == "__main__":+ sys.exit(main())