Skip to content

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/.gitignore
index 4afd02e..e8d6db8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,6 @@ samples/**/*.jpg
samples/**/*.jpeg
samples/**/*.webp
__pycache__/
+projects/
+work/
+samples/**/review/
diff --git a/package.json b/package.json
index 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.ts
index 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.ts
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.mjs
new file mode 100644
index 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.py
new file mode 100644
index 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.mjs
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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())