zwitschi
e2c2a0bf4c
Once an NPC reaches its intent waypoint it now does something instead of standing in an idle T-pose: - sit: the rig settles 0.34 m into a seat and the legs swing forward on the steps - photo/film: influencers and tourists raise their camera prop briefly (a sine pulse, so it reads as taking a shot rather than a permanently raised arm) - perform: performers sway the sign board they carry Pose selection lives in NpcAvatar.theater_pose() (intent + arrived); the math is in pure helpers (crouch_for_pose, prop_lift_for_pose, sway_for_pose) so it is headless-testable. Prop/leg nodes are captured at build time and animated from their rest offsets. Performers also get a hand-held board and post. Tests/docs - Headless suite 120 -> 127 (test_npc_theater.gd). - Verified visually with a staged sit/photo/perform lineup in front of the entrance. - README, TODO section moved to DONE, MEMORY. Version 0.2.7.
622 lines
26 KiB
Python
622 lines
26 KiB
Python
#!/usr/bin/env python3
|
|
"""Generate screen-design reference images for Step Line and compare captures.
|
|
|
|
This tool turns the screen descriptions that already live in `docs/`
|
|
(README screenshot captions, ADRs 0007-0010, PLAN.md, architecture.md, and the
|
|
HUD strings in `content/strings.en.json`) into reference "design" images, then
|
|
uses those images as the expected state to check the game's captured
|
|
screenshots against.
|
|
|
|
Two commands:
|
|
|
|
generate write one reference image per screen to docs/screens/designs/.
|
|
Two modes:
|
|
--ai realistic 3D game scenes and in-game screen designs via
|
|
the OpenRouter image API (default; requires
|
|
OPENROUTER_API_KEY, same as tools/asset_pipeline.py).
|
|
--draft deterministic wireframe sketches drawn with Pillow
|
|
(no network or API key; good for CI and layout checks).
|
|
|
|
compare compare docs/screenshots/*.png against the reference designs and
|
|
flag gross drift. Semantic composition is judged with coarse,
|
|
Pillow-only signals (aspect ratio, frame size, blank-frame
|
|
contrast, grayscale MAE, colour-histogram distance, edge density).
|
|
These catch "wrong screen / blank frame / wrong time of day"
|
|
regressions; they are NOT a pixel-exact or semantic match. A
|
|
vision-model pass is the documented next step (see PLAN.md).
|
|
|
|
Run from the repo root:
|
|
|
|
python3 tools/screen_designs.py generate
|
|
python3 tools/screen_designs.py generate --draft
|
|
python3 tools/screen_designs.py compare
|
|
"""
|
|
|
|
import argparse
|
|
import os
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
from PIL import Image, ImageChops, ImageDraw, ImageFilter, ImageOps, ImageStat
|
|
|
|
import generate_textures
|
|
|
|
ROOT = Path(__file__).resolve().parent.parent
|
|
DESIGNS_DIR = ROOT / "docs" / "screens" / "designs"
|
|
SCREENSHOTS_DIR = ROOT / "docs" / "screenshots"
|
|
|
|
# Reference "design" dimensions — match the capture tool and the README gallery.
|
|
WIDTH, HEIGHT = 1280, 720
|
|
ASPECT = 16 / 9
|
|
|
|
# Default image model for screen mockups (validated role-aware model, per
|
|
# MEMORY.md; seedream rejects small sizes and ignores transparency, so we use
|
|
# the model asset_pipeline.py already trusts for non-alpha roles).
|
|
DEFAULT_MODEL = "openai/gpt-5-image-mini"
|
|
|
|
# Shared art direction, appended to every prompt so the generated frames read
|
|
# as one coherent game. "scene" entries are first-person 3D world views;
|
|
# "ui" entries are in-game panels overlaid on a softened scene.
|
|
SCENE_STYLE = (
|
|
"rendered in a modern 3D game engine, first-person perspective, cinematic "
|
|
"lighting, physically based materials, soft shadows, ambient occlusion, "
|
|
"subtle depth of field, photorealistic detail, no watermark or UI clutter"
|
|
)
|
|
UI_STYLE = (
|
|
"clean modern in-game user interface, dark translucent panels, readable "
|
|
"sans-serif labels, consistent game UI colour theme, crisp vector text"
|
|
)
|
|
|
|
# Landscape source ratio requested from the API before cropping to 16:9.
|
|
# 3:2 is the validated non-square ratio for the default model (see MEMORY.md).
|
|
SOURCE_ASPECT = "3:2"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Screen catalogue. Each entry is grounded in a doc; `prompt` feeds --ai and
|
|
# `regions` feed --draft (normalised rects + a short label). `ref` names the
|
|
# captured screenshot, if one exists, so `compare` can pair them up.
|
|
# ---------------------------------------------------------------------------
|
|
|
|
SCREENS = [
|
|
{
|
|
"name": "venue_overview",
|
|
"kind": "scene",
|
|
"title": "Venue overview",
|
|
"source": "README screenshot 01",
|
|
"ref": "01-venue-overview.png",
|
|
"description": "First-person view from the guard post at the top of the "
|
|
"steps: Hollywood Boulevard entrance, wide concrete steps, "
|
|
"sidewalk, street lamps, planters, crosswalk, and building "
|
|
"signage/marquee under early-morning light.",
|
|
"prompt": (
|
|
"Realistic 3D first-person game scene: a security guard's view from "
|
|
"the top of wide concrete steps outside a grand Hollywood Boulevard "
|
|
"building entrance, early-morning golden light, sidewalk with street "
|
|
"lamps, planters, a crosswalk and distant pedestrians, detailed brick "
|
|
"facade with a striped awning and glowing marquee sign"),
|
|
"regions": [
|
|
(0.00, 0.55, 1.00, 1.00, "steps + sidewalk"),
|
|
(0.20, 0.08, 0.80, 0.60, "building facade / marquee"),
|
|
(0.05, 0.60, 0.20, 0.75, "street lamp"),
|
|
(0.78, 0.60, 0.95, 0.75, "street lamp"),
|
|
],
|
|
},
|
|
{
|
|
"name": "targeting_npc",
|
|
"kind": "scene",
|
|
"title": "Targeting an NPC",
|
|
"source": "README screenshot 02 · ADR-0008 cone focus + head ring",
|
|
"ref": "02-targeting-npc.png",
|
|
"description": "An approaching NPC is in the focus cone: a thin pale-gold "
|
|
"ring billboards around their head, a display name under "
|
|
"the ring, and the HUD shows a target line with the "
|
|
"interaction hint.",
|
|
"prompt": (
|
|
"Realistic 3D first-person game scene: a friendly pedestrian "
|
|
"standing on a city sidewalk, a thin pale-gold ring floating around "
|
|
"their head as a game selection marker, a small name label under the "
|
|
"ring, minimal HUD target text at the bottom, daytime"),
|
|
"regions": [
|
|
(0.35, 0.15, 0.65, 0.60, "NPC in focus"),
|
|
(0.44, 0.10, 0.56, 0.16, "head ring"),
|
|
(0.05, 0.85, 0.95, 0.95, "HUD: name + hint"),
|
|
],
|
|
},
|
|
{
|
|
"name": "access_inspection",
|
|
"kind": "ui",
|
|
"title": "Access inspection",
|
|
"source": "README screenshot 03 · ADR-0003 access verification",
|
|
"ref": "03-access-inspection.png",
|
|
"description": "An inspection panel shows the access artifact (wristband / "
|
|
"ID / ticket / credential / guest list) with its colour, "
|
|
"pattern, date, and event marking, plus allow and deny "
|
|
"prompts.",
|
|
"prompt": (
|
|
"Realistic 3D game screenshot with an in-game access inspection panel "
|
|
"overlaid: a centered card showing a wristband or ID credential with a "
|
|
"photo placeholder, colour band, date and event marking, and two "
|
|
"buttons labelled Allow and Deny, dark translucent panel over a "
|
|
"softly blurred city street background"),
|
|
"regions": [
|
|
(0.25, 0.10, 0.75, 0.90, "inspection panel"),
|
|
(0.30, 0.18, 0.70, 0.60, "artifact card"),
|
|
(0.30, 0.65, 0.48, 0.72, "allow"),
|
|
(0.52, 0.65, 0.70, 0.72, "deny"),
|
|
],
|
|
},
|
|
{
|
|
"name": "radio_report",
|
|
"kind": "ui",
|
|
"title": "Radio report",
|
|
"source": "README screenshot 04 · PLAN level 4 radio assistance",
|
|
"ref": "04-radio-report.png",
|
|
"description": "A radio dispatch panel with fields for location, "
|
|
"description, behaviour, whether weapons were seen, and "
|
|
"whether anyone is in immediate danger, plus a send action.",
|
|
"prompt": (
|
|
"Realistic 3D game screenshot with an in-game radio dispatch panel "
|
|
"overlaid: form fields for location, description, behaviour, a threat "
|
|
"assessment and whether anyone is in danger, and a Send button, dark "
|
|
"translucent panel over a softly blurred city street background"),
|
|
"regions": [
|
|
(0.30, 0.08, 0.70, 0.92, "radio panel"),
|
|
(0.34, 0.16, 0.66, 0.30, "location / description"),
|
|
(0.34, 0.34, 0.66, 0.56, "behaviour / weapons / danger"),
|
|
(0.42, 0.60, 0.58, 0.66, "send"),
|
|
],
|
|
},
|
|
{
|
|
"name": "late_night_avenue",
|
|
"kind": "scene",
|
|
"title": "Late night avenue",
|
|
"source": "README screenshot 05",
|
|
"ref": "05-late-night-avenue.png",
|
|
"description": "Night-time view down Hollywood Boulevard: street lamps "
|
|
"lit, marquee glowing, dark blue street, no flashlight.",
|
|
"prompt": (
|
|
"Realistic 3D first-person game scene at night: a dark Hollywood "
|
|
"Boulevard avenue receding into the distance, lit street lamps, a "
|
|
"glowing neon marquee sign, deep blue night sky, wet reflective "
|
|
"pavement, no flashlight"),
|
|
"regions": [
|
|
(0.00, 0.55, 1.00, 1.00, "dark avenue"),
|
|
(0.15, 0.25, 0.85, 0.55, "glowing marquee"),
|
|
(0.10, 0.45, 0.30, 0.70, "lit street lamp"),
|
|
(0.70, 0.45, 0.90, 0.70, "lit street lamp"),
|
|
],
|
|
},
|
|
{
|
|
"name": "night_flashlight",
|
|
"kind": "scene",
|
|
"title": "Night flashlight",
|
|
"source": "README screenshot 06",
|
|
"ref": "06-night-flashlight.png",
|
|
"description": "Night shift: the guard's flashlight beam cuts through the "
|
|
"dark toward the entrance, illuminating the steps and door.",
|
|
"prompt": (
|
|
"Realistic 3D first-person game scene at night: a flashlight beam "
|
|
"cutting through darkness toward a building entrance and steps, a "
|
|
"bright spotlight pool illuminating the door, dark surroundings and "
|
|
"deep shadows"),
|
|
"regions": [
|
|
(0.35, 0.30, 0.65, 0.80, "flashlight beam pool"),
|
|
(0.40, 0.20, 0.60, 0.35, "lit door"),
|
|
(0.00, 0.00, 1.00, 0.25, "dark sky"),
|
|
],
|
|
},
|
|
{
|
|
"name": "radial_menu",
|
|
"kind": "ui",
|
|
"title": "Radial action menu",
|
|
"source": "ADR-0009 · content/strings.en.json",
|
|
"ref": None,
|
|
"description": "A round doughnut menu centred on screen, 12 slices in "
|
|
"de-escalation order: Stop, Look, Point, No, Ask, Inspect, "
|
|
"Wand, Warn, Block, Reason, Recognize, Radio. The focused "
|
|
"person's display name sits in the centre.",
|
|
"prompt": (
|
|
"Realistic 3D game screenshot with an in-game radial action menu "
|
|
"overlaid: a round doughnut wheel centered on screen with twelve "
|
|
"labelled slices reading Stop, Look, Point, No, Ask, Inspect, Wand, "
|
|
"Warn, Block, Reason, Recognize, Radio, one slice highlighted, a name "
|
|
"in the center of the ring, over a softly blurred city street scene"),
|
|
"regions": [
|
|
(0.38, 0.12, 0.62, 0.88, "radial wheel (12 slices)"),
|
|
(0.46, 0.44, 0.54, 0.56, "name"),
|
|
(0.62, 0.12, 0.70, 0.20, "highlight"),
|
|
],
|
|
},
|
|
{
|
|
"name": "shift_review",
|
|
"kind": "ui",
|
|
"title": "Shift review",
|
|
"source": "PLAN reputation / shift review · architecture.md ShiftReview",
|
|
"ref": None,
|
|
"description": "End-of-shift performance review: access decisions, "
|
|
"escalation choices, incident list, battery and crowd "
|
|
"outcomes, and reputation/score feedback.",
|
|
"prompt": (
|
|
"Realistic 3D game end-of-shift review screen: a full-screen "
|
|
"performance summary panel listing incident decisions, escalation "
|
|
"choices, a reputation score, crowd reaction and battery use, with a "
|
|
"Continue button, dark themed game UI"),
|
|
"regions": [
|
|
(0.30, 0.06, 0.70, 0.94, "review panel"),
|
|
(0.36, 0.14, 0.64, 0.24, "score / reputation"),
|
|
(0.36, 0.28, 0.64, 0.70, "incident list"),
|
|
(0.42, 0.76, 0.58, 0.84, "continue"),
|
|
],
|
|
},
|
|
{
|
|
"name": "start_menu",
|
|
"kind": "ui",
|
|
"title": "Start menu",
|
|
"source": "MEMORY session shell (StartMenu, layer 20)",
|
|
"ref": None,
|
|
"description": "The boot screen: a venue-selection menu (Hollywood "
|
|
"Boulevard, The Joke Shop, TV Studio) before a shift.",
|
|
"prompt": (
|
|
"Realistic 3D game start menu screen: a game title and three venue "
|
|
"selection buttons labelled Hollywood Boulevard, The Joke Shop and TV "
|
|
"Studio, dark themed menu over a softly blurred city street backdrop"),
|
|
"regions": [
|
|
(0.25, 0.10, 0.75, 0.26, "title"),
|
|
(0.36, 0.36, 0.64, 0.44, "Hollywood Boulevard"),
|
|
(0.36, 0.48, 0.64, 0.56, "The Joke Shop"),
|
|
(0.36, 0.60, 0.64, 0.68, "TV Studio"),
|
|
],
|
|
},
|
|
{
|
|
"name": "pause_overlay",
|
|
"kind": "ui",
|
|
"title": "Pause overlay",
|
|
"source": "MEMORY session shell (PauseOverlay, layer 18)",
|
|
"ref": None,
|
|
"description": "Pause menu: resume, restart, settings, and quit-to-menu.",
|
|
"prompt": (
|
|
"Realistic 3D game pause menu overlay: buttons labelled Resume, "
|
|
"Restart, Settings and Quit to Menu, dark translucent overlay over a "
|
|
"paused, softly blurred city street scene"),
|
|
"regions": [
|
|
(0.38, 0.26, 0.62, 0.74, "pause menu"),
|
|
(0.42, 0.32, 0.58, 0.38, "Resume"),
|
|
(0.42, 0.42, 0.58, 0.48, "Restart"),
|
|
(0.42, 0.52, 0.58, 0.58, "Settings"),
|
|
(0.42, 0.62, 0.58, 0.68, "Quit to Menu"),
|
|
],
|
|
},
|
|
{
|
|
"name": "settings_panel",
|
|
"kind": "ui",
|
|
"title": "Settings",
|
|
"source": "MEMORY session shell (SettingsPanel, layer 22)",
|
|
"ref": None,
|
|
"description": "Settings: look sensitivity and HUD font scale controls.",
|
|
"prompt": (
|
|
"Realistic 3D game settings screen: sliders labelled look sensitivity "
|
|
"and HUD font scale, dark themed settings panel"),
|
|
"regions": [
|
|
(0.30, 0.16, 0.70, 0.84, "settings panel"),
|
|
(0.36, 0.30, 0.64, 0.40, "look sensitivity"),
|
|
(0.36, 0.46, 0.64, 0.56, "HUD font scale"),
|
|
],
|
|
},
|
|
{
|
|
"name": "emergency_radio",
|
|
"kind": "ui",
|
|
"title": "Emergency radio",
|
|
"source": "PLAN level 5 · strings radio.emergency_dispatched",
|
|
"ref": None,
|
|
"description": "Hold-to-confirm emergency radio panel with a confirmation "
|
|
"prompt and a cooldown indicator.",
|
|
"prompt": (
|
|
"Realistic 3D game emergency radio hold-to-confirm panel: a large "
|
|
"warning prompt with a hold progress bar and a cooldown label, red "
|
|
"accent, dark translucent overlay over a softly blurred city street "
|
|
"scene"),
|
|
"regions": [
|
|
(0.30, 0.28, 0.70, 0.72, "emergency panel"),
|
|
(0.36, 0.36, 0.64, 0.46, "confirm prompt"),
|
|
(0.38, 0.52, 0.62, 0.60, "hold progress"),
|
|
(0.36, 0.64, 0.64, 0.68, "cooldown"),
|
|
],
|
|
},
|
|
]
|
|
|
|
|
|
def resolve_path(value):
|
|
path = Path(value).expanduser()
|
|
return path if path.is_absolute() else ROOT / path
|
|
|
|
|
|
def _design_path(name):
|
|
return DESIGNS_DIR / f"{name}.png"
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Draft (wireframe) rendering — deterministic, offline.
|
|
# ---------------------------------------------------------------------------
|
|
|
|
def _draw_wireframe(screen, path):
|
|
image = Image.new("RGB", (WIDTH, HEIGHT), (24, 26, 38))
|
|
draw = ImageDraw.Draw(image)
|
|
title_font = generate_textures.font(52)
|
|
body_font = generate_textures.font(24)
|
|
label_font = generate_textures.font(26)
|
|
|
|
draw.text((40, 28), screen["title"], font=title_font, fill=(240, 240, 245))
|
|
draw.text((40, 98), screen["source"], font=body_font, fill=(150, 155, 175))
|
|
# wrap the description into a small caption block
|
|
words = screen["description"].split()
|
|
lines, line = [], ""
|
|
for word in words:
|
|
if draw.textlength(line + " " + word, font=body_font) < WIDTH - 80:
|
|
line = (line + " " + word).strip()
|
|
else:
|
|
lines.append(line)
|
|
line = word
|
|
lines.append(line)
|
|
for index, text in enumerate(lines[:4]):
|
|
draw.text((40, 132 + index * 30), text,
|
|
font=body_font, fill=(120, 125, 145))
|
|
|
|
for region in screen["regions"]:
|
|
x0, y0, x1, y1, label = region
|
|
box = (int(x0 * WIDTH), int(y0 * HEIGHT),
|
|
int(x1 * WIDTH), int(y1 * HEIGHT))
|
|
draw.rounded_rectangle(box, radius=10,
|
|
outline=(120, 130, 170), width=2)
|
|
cx = (box[0] + box[2]) / 2
|
|
cy = (box[1] + box[3]) / 2
|
|
draw.text((cx - draw.textlength(label, font=label_font) / 2,
|
|
cy - 14), label, font=label_font, fill=(170, 180, 210))
|
|
|
|
image.save(path)
|
|
shown = path.relative_to(ROOT) if path.is_relative_to(ROOT) else path
|
|
print(f"wrote {shown} {image.size}")
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# AI generation (reuses the OpenRouter backend from generate_textures).
|
|
# ---------------------------------------------------------------------------
|
|
|
|
def _compose_prompt(screen):
|
|
"""Append the shared art direction to a screen's content prompt."""
|
|
style = UI_STYLE if screen.get("kind") == "ui" else SCENE_STYLE
|
|
return f"{screen['prompt']}. {style}. 16:9 widescreen composition."
|
|
|
|
|
|
def _generate_ai(screen, model, request_size):
|
|
prompt = _compose_prompt(screen)
|
|
# Request a landscape source and crop to the 16:9 capture dimensions rather
|
|
# than a square that loses framing when centre-cropped.
|
|
image = generate_textures.generate_image(
|
|
prompt, model, request_size, transparent=False,
|
|
aspect_ratio=SOURCE_ASPECT)
|
|
image = ImageOps.fit(image, (WIDTH, HEIGHT),
|
|
method=Image.Resampling.LANCZOS)
|
|
if image.mode in ("RGBA", "LA", "P"):
|
|
image = image.convert("RGB")
|
|
path = _design_path(screen["name"])
|
|
path.parent.mkdir(parents=True, exist_ok=True)
|
|
image.save(path)
|
|
shown = path.relative_to(ROOT) if path.is_relative_to(ROOT) else path
|
|
print(f"wrote {shown} {image.size}")
|
|
|
|
|
|
def generate(args):
|
|
DESIGNS_DIR.mkdir(parents=True, exist_ok=True)
|
|
failed = []
|
|
for screen in SCREENS:
|
|
print(f"generating {screen['name']} ...")
|
|
try:
|
|
if args.draft:
|
|
_draw_wireframe(screen, _design_path(screen["name"]))
|
|
else:
|
|
_generate_ai(screen, args.model, args.request_size)
|
|
except SystemExit as exc:
|
|
failed.append(screen["name"])
|
|
print(f" FAILED {screen['name']}: {exc}", file=sys.stderr)
|
|
print("done")
|
|
if failed:
|
|
print(f"failed: {', '.join(failed)}", file=sys.stderr)
|
|
return 1
|
|
return 0
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Comparison metrics (Pillow only; no numpy/scikit-image dependency).
|
|
# ---------------------------------------------------------------------------
|
|
|
|
def _load_rgb(path):
|
|
with Image.open(path) as image:
|
|
image.load()
|
|
return image.convert("RGB")
|
|
|
|
|
|
def _grayscale(image):
|
|
return ImageOps.grayscale(image)
|
|
|
|
|
|
def _mae(left, right):
|
|
"""Mean absolute error between two same-size grayscale images, 0..255."""
|
|
left_gray = _grayscale(left).resize((256, 144))
|
|
right_gray = _grayscale(right).resize((256, 144))
|
|
diff = ImageChops.difference(left_gray, right_gray)
|
|
return ImageStat.Stat(diff).mean[0]
|
|
|
|
|
|
def _histogram_distance(left, right):
|
|
"""Normalised L1 distance between 3x256-bin colour histograms, 0..1."""
|
|
left_hist = left.resize((256, 144)).histogram()
|
|
right_hist = right.resize((256, 144)).histogram()
|
|
total = sum(left_hist)
|
|
if total == 0:
|
|
return 1.0
|
|
distance = sum(abs(a - b) for a, b in zip(left_hist, right_hist))
|
|
return distance / (2 * total)
|
|
|
|
|
|
def _edge_density(image):
|
|
"""Mean brightness of an edge-detected frame; higher = more detail."""
|
|
edges = _grayscale(image).filter(ImageFilter.FIND_EDGES)
|
|
return ImageStat.Stat(edges).mean[0]
|
|
|
|
|
|
def _contrast(image):
|
|
"""Standard deviation of grayscale brightness; low = near-blank frame."""
|
|
return ImageStat.Stat(_grayscale(image)).stddev[0]
|
|
|
|
|
|
def _aspect_ok(image, tolerance=0.12):
|
|
width, height = image.size
|
|
actual = width / height
|
|
return abs(actual - ASPECT) / ASPECT <= tolerance
|
|
|
|
|
|
def compare_screenshot(reference, capture):
|
|
"""Compare one capture against its reference design; return a dict report."""
|
|
ref = _load_rgb(reference)
|
|
cap = _load_rgb(capture)
|
|
width, height = cap.size
|
|
report = {
|
|
"capture": str(capture),
|
|
"reference": str(reference),
|
|
"size": [width, height],
|
|
}
|
|
|
|
errors, warnings = [], []
|
|
|
|
if width < WIDTH or height < HEIGHT:
|
|
errors.append(f"too small: {width}x{height}; minimum {WIDTH}x{HEIGHT}")
|
|
if not _aspect_ok(cap):
|
|
errors.append(f"wrong aspect ratio: {width / height:.3f}; "
|
|
f"expected about {ASPECT:.3f}")
|
|
|
|
contrast = _contrast(cap)
|
|
report["contrast"] = round(contrast, 1)
|
|
if contrast < 5.0:
|
|
errors.append(f"near-blank frame: contrast {contrast:.1f} below 5.0")
|
|
|
|
mae = _mae(ref, cap)
|
|
hist = _histogram_distance(ref, cap)
|
|
edge_ref = _edge_density(ref)
|
|
edge_cap = _edge_density(cap)
|
|
report["mae"] = round(mae, 1)
|
|
report["hist_distance"] = round(hist, 3)
|
|
report["edge_density_ref"] = round(edge_ref, 1)
|
|
report["edge_density_cap"] = round(edge_cap, 1)
|
|
|
|
# Coarse drift warnings (not hard failures: an AI mockup will never match a
|
|
# real render pixel-for-pixel, but a wildly different frame will still
|
|
# stand out on these signals).
|
|
if mae > 90:
|
|
warnings.append(
|
|
f"grayscale MAE {mae:.1f} is high (very different layout)")
|
|
if hist > 0.75:
|
|
warnings.append(f"colour histogram distance {hist:.3f} is high "
|
|
"(very different palette / time of day)")
|
|
edge_delta = abs(edge_cap - edge_ref)
|
|
report["edge_delta"] = round(edge_delta, 1)
|
|
if edge_delta > 18:
|
|
warnings.append(f"edge density differs by {edge_delta:.1f} "
|
|
"(very different amount of detail)")
|
|
|
|
report["quality"] = "bad" if errors else "good"
|
|
report["errors"] = errors
|
|
report["warnings"] = warnings
|
|
return report
|
|
|
|
|
|
def compare(args):
|
|
if not SCREENSHOTS_DIR.is_dir():
|
|
sys.exit(f"error: no screenshots directory at {SCREENSHOTS_DIR}; "
|
|
"run src/test/capture_screenshots.gd first")
|
|
captures = sorted(SCREENSHOTS_DIR.glob("*.png"))
|
|
if not captures:
|
|
sys.exit(f"error: no .png screenshots found in {SCREENSHOTS_DIR}")
|
|
|
|
refs = {screen["name"]: screen["ref"]
|
|
for screen in SCREENS if screen["ref"]}
|
|
results = []
|
|
for capture in captures:
|
|
name = capture.name
|
|
# find the screen whose ref matches this capture filename
|
|
design_name = next((n for n, ref in refs.items() if ref == name), None)
|
|
if design_name is None:
|
|
results.append({"capture": str(capture), "reference": None,
|
|
"errors": [f"no design reference for {name}"],
|
|
"warnings": [], "quality": "bad"})
|
|
continue
|
|
reference = _design_path(design_name)
|
|
if not reference.is_file():
|
|
results.append({"capture": str(capture),
|
|
"reference": str(reference),
|
|
"errors": [f"missing reference design "
|
|
f"({reference.name}); run generate first"],
|
|
"warnings": [], "quality": "bad"})
|
|
continue
|
|
results.append(compare_screenshot(reference, capture))
|
|
|
|
if args.json:
|
|
import json
|
|
print(json.dumps(results, indent=2))
|
|
else:
|
|
good_count = sum(r["quality"] == "good" for r in results)
|
|
for result in results:
|
|
ref = (Path(result["reference"]).name
|
|
if result.get("reference") else "-")
|
|
size = ("x".join(map(str, result["size"]))
|
|
if result.get("size") else "unreadable")
|
|
print(f"{result['quality'].upper():4} {result['capture']}")
|
|
print(f" ref={ref} size={size} "
|
|
f"mae={result.get('mae', '-')} "
|
|
f"hist={result.get('hist_distance', '-')}")
|
|
for message in result["errors"] + result["warnings"]:
|
|
print(f" - {message}")
|
|
print(f"Summary: {good_count} good, {len(results) - good_count} bad")
|
|
|
|
return 1 if any(r["quality"] == "bad" for r in results) else 0
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
|
|
def build_parser():
|
|
parser = argparse.ArgumentParser(
|
|
description="Generate and compare Step Line screen-design references.")
|
|
commands = parser.add_subparsers(dest="command", required=True)
|
|
|
|
gen = commands.add_parser(
|
|
"generate", help="write reference design images to docs/screens/designs/")
|
|
mode = gen.add_mutually_exclusive_group()
|
|
mode.add_argument("--draft", action="store_true",
|
|
help="draw deterministic wireframes (no API/network)")
|
|
mode.add_argument("--ai", action="store_true",
|
|
help="generate mockups via OpenRouter (default)")
|
|
gen.add_argument("--model", default=DEFAULT_MODEL)
|
|
gen.add_argument("--request-size", type=int,
|
|
default=generate_textures.GEN_SIZE)
|
|
gen.set_defaults(handler=generate, draft=False)
|
|
|
|
cmp = commands.add_parser(
|
|
"compare", help="compare docs/screenshots/*.png against the designs")
|
|
cmp.add_argument("--json", action="store_true")
|
|
cmp.set_defaults(handler=compare)
|
|
|
|
return parser
|
|
|
|
|
|
def main(argv=None):
|
|
args = build_parser().parse_args(argv)
|
|
try:
|
|
result = args.handler(args)
|
|
return result if isinstance(result, int) else 0
|
|
except (OSError, ValueError) as exc:
|
|
print(f"error: {exc}", file=sys.stderr)
|
|
return 2
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|