0x0funky/agent-sprite-forge / skills/video2dsprite
video2dsprite
VerifiedTurn one approved master still into a character's whole animated sprite set - one image-to-video clip per action (idle, walk, run, attack, jump, hurt, cast and so on), all from that still, generated through generate2dmedia route_media.py (the xAI API when a key is configured, else the local Grok CLI) - then gate each take, key it with a soft matte, register it to the master, pick loops or retime actions, finish (HD by default, pixel on request) and package fixed-canvas frames, alpha WebM, packed MP4 for iPhone and a PNG fallback with engine metadata and a JS runtime. Also processes a supplied clip. Use for character and creature animation, fluid motion and any video-to-sprite work. Not for FX, icon or prop sheets (generate2dsprite), maps or plate loops (generate2dmap), code-drawn animation (codeart2d, only on request) or calling a video API by itself (generate2dmedia).
scripts/sprite_set.py
View on GitHub#!/usr/bin/env python3
"""One approved still in, a whole game-ready sprite set out.
plan Read master.json (generate2dsprite.master.v1) and write a new set folder with
set_plan.json: one image-to-video clip per action and view, each a loop or a
one-shot with its own canvas and headroom (jump taller, attack wider), the end
frame pinned to the master for idle and attack, numeric QC gates, and the motion
prompt built from references/motion-prompts.md.
run Make every action: prepare_i2v_input.py input, motion prompt, generate2dmedia
route_media.py video, video2dsprite.py process --matte soft, the numeric QC
gates, automatic retakes with prompt fixes (up to --max-takes), register_clip.py
apply, gait_loop.py select (loops) or retime.py (one-shots), finish_frames.py
hd|pixel, engine_export.py package and verify. Every step is recorded in
set_state.json and takes.jsonl, so running it again resumes where it stopped.
review Contact sheet per action and take, a cast line-up and review.json, for the host
agent to LOOK at before it accepts anything.
accept Record the agent's semantic approval of one take; when that take is already
packaged, the review verdict is written into the package (engine_export.py
review: animation.json reviewStatus "accepted"), else the next run packages it
with --review.
retake Record a semantic rejection with a prompt fix; the next run makes a new take.
report One JSON with every action's route, takes, QC numbers, loop or timing and output
files.
set_state.json is shared by run, review, accept, retake and report: every read and write
happens under a lock on set_state.lock (forge_index.py scan takes it too), and a long run
merges the agent's decisions (accept, retake, review) from disk before every save, so an
accept or retake made while a run works is never lost. run takes --progress-file (or
FORGE_PROGRESS_FILE): one JSON line per stage for a host; stdout keeps its one summary line.
Exit codes: 0 done; 1 refused input or failed step, nothing usable (error: ... on stderr);
2 usage; 3 the run waits for a clip because no generation route exists (drop the clip into
the take's media folder named in the summary and run again); 4 run left the set incomplete
but packaged at least one action (the summary names each action's status and package).
"""
from __future__ import annotations
import argparse
import concurrent.futures
import contextlib
import json
import math
import os
import re
import shutil
import subprocess
import sys
import time
from dataclasses import dataclass
from fractions import Fraction
from pathlib import Path
from typing import Any, Callable, Sequence
import numpy as np
from PIL import Image, ImageDraw, ImageFont
HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
import forge_core # noqa: E402 (this skill's vendored copy)
import forge_matte # noqa: E402
import colour_lock # noqa: E402 (sibling: master colours for the colour gate)
import prepare_i2v_input as prep # noqa: E402 (sibling: opaque-master keying, stance anchor, prompt lint)
import register_clip # noqa: E402 (sibling: job geometry, the master as placed in the video)
TOOL_NAME = "sprite_set"
TOOL_VERSION = forge_core.FORGE_PACKAGE_VERSION
MASTER_SCHEMA = "generate2dsprite.master.v1"
PLAN_SCHEMA = "video2dsprite.sprite_set_plan.v1"
STATE_SCHEMA = "video2dsprite.sprite_set_state.v1"
TAKE_SCHEMA = "video2dsprite.sprite_set_take.v1"
QC_SCHEMA = "video2dsprite.sprite_set_qc.v1"
REVIEW_SCHEMA = "video2dsprite.sprite_set_review.v1"
REPORT_SCHEMA = "video2dsprite.sprite_set_report.v1"
STANDIN_SCHEMA = "video2dsprite.finish_standin.v1"
PLAN_FILE, STATE_FILE, TAKES_FILE = "set_plan.json", "set_state.json", "takes.jsonl"
LOCK_FILE = "set_state.lock" # forge_core.file_lock around every set_state.json read and write
REVIEW_VERDICT_SCHEMA = "video2dsprite.review_verdict.v1"
LIBRARY_FILE = HERE.parent / "references" / "motion-prompts.md"
SCRIPTS = {name: HERE / f"{name}.py" for name in
("prepare_i2v_input", "video2dsprite", "register_clip", "gait_loop", "retime", "engine_export")}
FINISH_SCRIPT = HERE / "finish_frames.py"
ROUTE_MEDIA = HERE.parents[1] / "generate2dmedia" / "scripts" / "route_media.py"
MEDIA_FAKE_ENV = "FORGE_ROUTE_MEDIA_FAKE" # tests: path of a fake media CLI (same argv and JSON line)
FINISH_ENV = "FORGE_FINISH_FRAMES" # 'standin' forces the private stand-in; a path names a finisher
EXIT_NO_ROUTE = 3
TOOL_TIMEOUT = 1800.0
DEFAULT_ACTIONS = ("idle", "walk", "run", "attack", "jump", "hurt")
VIEWS = ("side", "front", "back")
FINISHES = ("hd", "pixel", "hibit")
PALETTED = ("pixel", "hibit") # finishes that write one palette, binary alpha, nearest sampling
TARGET_HEIGHT = {"hd": 256, "pixel": 80, "hibit": 80} # finished body height in px for a hero
FINISH_STYLE = {"hd": "HD hand-drawn 2D game-art", "pixel": "16-bit pixel-art",
"hibit": "clean flat lineless cel-shaded 2D game-art"} # the 'keep the exact <style> look' words
HIBIT_OUTLINES = ("auto", "selective", "dark", "none") # or a #RRGGBB colour (finish_frames.py hibit --outline)
CLASS_HEIGHT = {"boss": 2.0} # cast rule: a boss is about twice the hero; mobs and spirits 1.0
HOVER_CLASSES = ("spirit", "ghost", "hover", "flying")
LUMA = np.array([0.299, 0.587, 0.114], np.float32)
QC_SUBJECT_PX = 112 # QC works on frames reduced to about this body height
GATE_IDS = ("area", "feet", "identity", "zoom", "turn", "edge", "background", "extra", "motion", "end-pose",
"colour", "timing", "loop", "registration", "keying")
# --------------------------------------------------------------------------- action and canvas presets
@dataclass(frozen=True)
class ActionPreset:
"""How one action is generated and cut."""
kind: str # loop | oneshot
loop_kind: str | None # gait_loop select --kind: gait | idle (hover for floating classes)
gait_state: str | None # gait_loop select --state: walk | run
prepare_action: str # prepare_i2v_input --action (its job records this template)
canvas: str # square | tall | wide
pin_last: bool # end frame pinned to the master when the route takes a last frame
lock: str # register_clip --lock: feet | none
airborne: bool # the feet leave the ground (the feet gate checks start and end only)
hit_tick: bool # one-shot with a hit event on its largest reach
returns_to_rest: bool # the clip starts and ends on the master pose
min_motion: float # pose change (share of the master area) that proves the action happened
retime_kind: str # retime.py --kind
ACTION_PRESETS: dict[str, ActionPreset] = {
"idle": ActionPreset("loop", "idle", None, "idle", "square", True, "feet", False, False, True, 0.006, "idle"),
"walk": ActionPreset("loop", "gait", "walk", "walk", "square", False, "feet", False, False, True, 0.05, "walk"),
"run": ActionPreset("loop", "gait", "run", "run", "square", False, "none", False, False, True, 0.06, "run"),
"attack": ActionPreset("oneshot", None, None, "attack", "wide", True, "feet", False, True, True, 0.03,
"attack"),
"jump": ActionPreset("oneshot", None, None, "attack", "tall", False, "feet", True, False, True, 0.08, "other"),
"hurt": ActionPreset("oneshot", None, None, "hurt", "square", False, "feet", False, False, True, 0.02, "hurt"),
"cast": ActionPreset("oneshot", None, None, "cast", "wide", False, "feet", False, False, True, 0.02, "cast"),
"guard": ActionPreset("oneshot", None, None, "guard", "square", False, "feet", False, False, True, 0.02,
"guard"),
"victory": ActionPreset("oneshot", None, None, "victory", "tall", False, "feet", False, False, False, 0.03,
"victory"),
"defeat": ActionPreset("oneshot", None, None, "defeat", "wide", False, "none", False, False, False, 0.04,
"defeat"),
}
# Game lengths of one-shots (the generator plays them in slow motion: a 6 s clip for a 0.7 s attack). retime.py
# --auto-oneshot cuts static holds, pins the keys (fraction of the length, hold ms) and compresses the rest.
# set_plan.json keeps a copy per action ("timing"), so a set can be tuned; mode "source" keeps the clip's speed.
ONESHOT_TIMING: dict[str, dict[str, Any]] = {
"attack": {"mode": "auto", "durationMs": 700, "keys": {"hit": {"at": 0.40, "holdMs": 80}}},
"jump": {"mode": "auto", "durationMs": 900, "keys": {"takeoff": {"at": 0.22}, "land": {"at": 0.72}}},
"hurt": {"mode": "auto", "durationMs": 500, "keys": {"peak": {"at": 0.30, "holdMs": 80}}},
"cast": {"mode": "auto", "durationMs": 900, "keys": {"peak": {"at": 0.45, "holdMs": 120}}},
"guard": {"mode": "auto", "durationMs": 700, "keys": {"peak": {"at": 0.35, "holdMs": 160}}},
"victory": {"mode": "source"},
"defeat": {"mode": "source"},
}
# Feet clauses that would freeze locomotion: a walk, run or jump never gets "feet stay planted"; its feet fix
# keeps the ground line instead (motion-prompts.md clause feet-ground-line).
PLANTED_CLAUSES = ("feet-planted",)
MOVING_FEET_CLAUSE = "feet-ground-line"
# sprite-gen per-state canvases: jump 3:4 with 34% headroom, attack 16:9; square keeps the master framing.
CANVAS_PRESETS = {"square": {"aspect": None, "headroom": None, "lead": 0.0},
"tall": {"aspect": (3, 4), "headroom": 0.34, "lead": 0.0},
"wide": {"aspect": (16, 9), "headroom": None, "lead": 0.06}}
BASE_GATES: dict[str, dict[str, Any]] = {
"area": {"min": 0.72, "max": 1.32, "maxBadShare": 0.1},
"feet": {"max": 0.05, "badFrames": 3, "mode": "all"},
# Identity: frame 0 must reproduce the master (start); afterwards the head is matched against the master and
# frame 0 at 3 scales and a turned or bobbing head only warns (min). Only a severe loss fails: more than half
# the frames under 0.30 (calibrated on the 2026-10-06 live run, where the old hard 0.5 floor rejected 18 of 24
# good takes and no real identity loss happened).
"identity": {"start": 0.8, "min": 0.5, "badFrames": 2, "severe": 0.30, "severeShare": 0.5,
"scales": [0.9, 1.0, 1.1]},
# Colour: a frame is bled when more than 2% of the body shows a hue no master colour at that height has
# (chroma > 0.05 and 0.06 or more from every master colour of the band, in OKLab a/b); the take fails when 15%
# of its frames are (live run: 29-41% on the six bled runs, at most 7% on the 24 good takes). Region drift (a
# part shifted, which the finish's colour lock undoes) only warns: over 0.03 in 40% of the frames.
"colour": {"foreign": 0.02, "badShare": 0.15, "drift": 0.03, "driftShare": 0.4},
# Timing (one-shots): the motion from onset to settle and the longest static hold inside it. Too slow warns
# while the set retimes one-shots (retime --auto-oneshot) and fails when it keeps the clip's speed.
"timing": {"maxSeconds": 2.0, "maxHoldSeconds": 0.5},
"zoom": {"max": 0.08},
"turn": {"enabled": True, "margin": 0.08, "run": 3},
"edge": {"px": 2},
"background": {"tolerance": 48.0, "maxImpure": 0.004, "badFrames": 2},
"extra": {"max": 0.015, "badFrames": 2},
"motion": {"min": 0.02},
"endPose": {"enabled": True, "min": 0.8},
"window": {"loopSeconds": 1.0},
}
# --------------------------------------------------------------------------- small helpers
def _ascii(text: Any) -> str:
return forge_core.ascii_text(str(text))
def _now() -> str:
return forge_core.utc_timestamp()
def _even(value: float) -> int:
return max(16, 2 * forge_core.round_half_up(value / 2))
_ABSOLUTE = re.compile(r"^(?:[A-Za-z]:[\\/]|[\\/]{2}|/)")
_EMBEDDED = re.compile(r"(?<![A-Za-z0-9])(?:[A-Za-z]:[\\/]|\\\\)[^\s\"'<>|*?]*")
def _last_part(path: str) -> str:
return re.split(r"[\\/]", path.rstrip("\\/"))[-1] or path
def _scrub(value: Any) -> Any:
"""A JSON value with every absolute path cut to its last component, also inside messages (written JSON
never holds one); keys starting with _ are dropped."""
if isinstance(value, dict):
return {str(key): _scrub(item) for key, item in value.items() if not str(key).startswith("_")}
if isinstance(value, (list, tuple)):
return [_scrub(item) for item in value]
if isinstance(value, str):
if _ABSOLUTE.match(value) and not any(char.isspace() for char in value):
return _last_part(value)
return _EMBEDDED.sub(lambda match: _last_part(match.group(0)), value)
if isinstance(value, np.generic):
return value.item()
return value
def _json_line(text: str) -> dict | None:
"""The last line of ``text`` that is a JSON object (every forge CLI prints one summary line)."""
for line in reversed(text.splitlines()):
line = line.strip()
if line.startswith("{") and line.endswith("}"):
try:
value = json.loads(line)
except ValueError:
continue
if isinstance(value, dict):
return value
return None
def _error_line(stderr: str) -> str:
lines = [line.strip() for line in stderr.splitlines() if line.strip()]
errors = [line for line in lines if line.startswith("error:")]
text = errors[-1] if errors else (lines[-1] if lines else "no output")
return text[6:].strip() if text.startswith("error:") else text
def _natural(path: Path) -> list:
return [int(part) if part.isdigit() else part.lower() for part in re.split(r"(\d+)", path.name)]
def _pngs(folder: Path) -> list[Path]:
return sorted((path for path in folder.glob("*.png") if path.is_file()), key=_natural)
def _ranges(frames: Sequence[int], limit: int = 8) -> str:
"""'3-7, 12, 20-21' for a sorted list of frame numbers."""
runs: list[list[int]] = []
for frame in sorted(set(int(f) for f in frames)):
if runs and frame == runs[-1][1] + 1:
runs[-1][1] = frame
else:
runs.append([frame, frame])
text = [f"{a}-{b}" if b > a else str(a) for a, b in runs[:limit]]
return ", ".join(text) + (f" and {len(runs) - limit} more runs" if len(runs) > limit else "")
def _round(value: Any, digits: int = 4) -> Any:
if isinstance(value, float):
return round(value, digits) if math.isfinite(value) else None
if isinstance(value, np.floating):
return _round(float(value), digits)
if isinstance(value, np.integer):
return int(value)
if isinstance(value, (list, tuple)):
return [_round(item, digits) for item in value]
if isinstance(value, dict):
return {key: _round(item, digits) for key, item in value.items()}
return value
def _move_aside(path: Path) -> Path:
"""Keep an unrecorded leftover (a crash between a tool's publish and the state save) beside the new run."""
for number in range(1, 1000):
target = path.with_name(f"{path.name}.orphan-{number}")
if not os.path.lexists(target):
os.replace(path, target)
return target
raise ValueError(f"too many orphaned copies of {path.name}; clean the folder")
def _write_new_json(path: Path, data: Any) -> None:
"""Publish a JSON file that must not exist yet (no-replace)."""
stage = path.with_name(f".{path.name}.{os.getpid()}.tmp")
try:
forge_core.write_json(stage, data, no_clobber=False)
forge_core.publish_file_no_replace(stage, path)
finally:
stage.unlink(missing_ok=True)
def _publish_png(image: Image.Image | np.ndarray, path: Path) -> None:
stage = path.with_name(f".{path.name}.{os.getpid()}.tmp")
try:
forge_core.save_png(image, stage)
forge_core.publish_file_no_replace(stage, path)
finally:
stage.unlink(missing_ok=True)
def _next_numbered(folder: Path, stem: str, suffix: str) -> Path:
for number in range(1, 10000):
candidate = folder / f"{stem}-{number:03d}{suffix}"
if not os.path.lexists(candidate):
return candidate
raise ValueError(f"no free {stem}-NNN{suffix} name in {folder.name}")
def _fps_value(text: Any) -> float:
return float(_fps_fraction(text))
def _fps_fraction(text: Any) -> Fraction:
"""A frame rate as an exact fraction: 24, "24/1", 12.5, "25/2" (floats are read from their shortest text)."""
if isinstance(text, Fraction):
rate = text
elif isinstance(text, bool):
raise ValueError(f"frame rate must be a number, got {text!r}")
elif isinstance(text, int):
rate = Fraction(text)
else:
try:
rate = Fraction(str(text).strip())
except (ValueError, ZeroDivisionError):
raise ValueError(f"frame rate must be a number or N/D, got {text!r}") from None
if rate <= 0:
raise ValueError(f"frame rate must be positive, got {text!r}")
return rate.limit_denominator(1000)
def _duration_arg(value: Any) -> str:
"""Clip seconds as route_media.py parses them (an int): the plan stores 6.0, the media CLI gets "6"."""
seconds = float(value)
return str(int(seconds)) if seconds.is_integer() else f"{seconds:g}"
# --------------------------------------------------------------------------- tools by path
class ToolFailure(RuntimeError):
"""A sibling CLI exited non-zero; ``message`` is its error line."""
def __init__(self, tool: str, code: int, message: str):
super().__init__(f"{tool} exited {code}: {message}")
self.tool, self.code, self.message = tool, code, message
def _child_env() -> dict[str, str]:
"""The child tools' environment; FORGE_PROGRESS_FILE is removed (the run reports their stages itself)."""
return {**forge_core.child_env_without_progress(), "PYTHONIOENCODING": "utf-8", "PYTHONDONTWRITEBYTECODE": "1"}
def _no_progress(*_args: Any, **_kwargs: Any) -> None:
"""The progress reporter of a runner without a host (forge_core.Progress has the same signature)."""
def run_tool(script: Path, args: Sequence[Any], *, timeout: float = TOOL_TIMEOUT,
label: str | None = None) -> tuple[dict, list[str]]:
"""Run a forge CLI by path; returns its one-line JSON summary and its warning lines."""
label = label or script.name
argv = [sys.executable, str(script), *(str(arg) for arg in args)]
try:
done = subprocess.run(argv, capture_output=True, timeout=timeout, env=_child_env(), check=False)
except subprocess.TimeoutExpired:
raise ToolFailure(label, -1, f"timed out after {timeout:g} s") from None
stdout = done.stdout.decode("utf-8", "replace")
stderr = done.stderr.decode("utf-8", "replace")
if done.returncode != 0:
raise ToolFailure(label, done.returncode, _error_line(stderr))
summary = _json_line(stdout)
if summary is None:
raise ToolFailure(label, 0, "printed no JSON summary line")
warnings = [line.strip()[8:].strip() for line in stderr.splitlines() if line.strip().startswith("warning:")]
return summary, warnings
# --------------------------------------------------------------------------- the prompt library
_FENCE = re.compile(r"^```(template|negatives|clauses|gatefix)(?:[ \t]+([A-Za-z0-9_-]+))?[ \t]*\r?\n(.*?)^```[ \t]*$",
re.M | re.S)
_PLACEHOLDER = re.compile(r"\{([a-z_]+)\}")
@dataclass(frozen=True)
class Library:
"""references/motion-prompts.md: per-action templates, negatives and the failure clause library."""
sha256: str
templates: dict[str, str]
negatives: dict[str, str]
clauses: dict[str, str]
gatefix: dict[str, list[str]]
def load_library(path: Path = LIBRARY_FILE) -> Library:
"""Parse the fenced ``template``/``negatives``/``clauses``/``gatefix`` blocks of motion-prompts.md."""
raw = Path(path).read_bytes()
text = raw.decode("utf-8-sig").replace("\r\n", "\n").replace("\r", "\n") # a CRLF checkout (core.autocrlf)
templates: dict[str, str] = {}
negatives: dict[str, str] = {}
clauses: dict[str, str] = {}
gatefix: dict[str, list[str]] = {}
for kind, name, body in _FENCE.findall(text):
if kind in ("template", "negatives"):
target = templates if kind == "template" else negatives
if not name or name in target:
raise ValueError(f"{Path(path).name}: every ```{kind} block needs one new action name")
target[name] = " ".join(body.split())
continue
for number, line in enumerate(body.splitlines(), 1):
if not line.strip() or line.lstrip().startswith("#"):
continue
ident, sep, value = line.partition("|")
ident, value = ident.strip(), " ".join(value.split())
if not sep or not re.fullmatch(r"[a-z0-9-]+", ident) or not value:
raise ValueError(f"{Path(path).name}: ```{kind} line {number} must be 'id | text'")
if kind == "clauses":
clauses[ident] = value
else:
gatefix[ident] = [item.strip() for item in value.split(",") if item.strip()]
missing = [action for action in ACTION_PRESETS if action not in templates]
unknown = sorted({ident for ids in gatefix.values() for ident in ids if ident not in clauses})
unmapped = [gate for gate in GATE_IDS if gate not in gatefix]
if missing or unknown or unmapped:
raise ValueError(f"{Path(path).name} is incomplete: templates missing for {missing}, unknown clause ids "
f"{unknown}, gates without a fix {unmapped}")
return Library(forge_core.sha256_bytes(raw), templates, negatives, clauses, gatefix)
def fill(text: str, words: dict[str, str]) -> str:
"""Replace {facing}, {toward}, {away}, {pos}, {key}, {style} and {action}; unknown names stay."""
return _PLACEHOLDER.sub(lambda match: words.get(match.group(1), match.group(0)), text)
def prompt_words(facing: str, key: str, style: str, pronoun: str, action: str) -> dict[str, str]:
lock = {"left": "LEFT", "right": "RIGHT", "front": "the viewer", "back": "away from the viewer"}[facing]
toward = {"left": "to the LEFT", "right": "to the RIGHT", "front": "toward the viewer",
"back": "away from the viewer"}[facing]
away = {"left": "to the RIGHT", "right": "to the LEFT", "front": "away from the viewer",
"back": "toward the viewer"}[facing]
return {"facing": lock, "toward": toward, "away": away, "pos": pronoun, "key": key_words(key)[0],
"style": style, "action": action}
def key_words(key: str) -> tuple[str, str]:
"""(colour word, background clause) for the flat key backdrop."""
if key == "magenta":
return "magenta", "solid flat pure magenta background only for the whole shot"
if key == "green":
return "green", "solid flat pure bright green background (#00FF00 green screen) only for the whole shot"
if key == "blue":
return "blue", "solid flat pure blue background (#0000FF) only for the whole shot"
return key, f"solid flat pure {key} background only for the whole shot"
def identity_phrase(recap: str) -> str:
"""'The same <recap>' without a doubled article or a closing full stop."""
text = " ".join(str(recap).split()).rstrip(" .")
text = re.sub(r"^(?:the same|a|an|the)\s+", "", text, flags=re.I)
return text
def moves_feet(entry: dict) -> bool:
"""Walks, runs and jumps: their feet must move, so no fix may ask for planted feet."""
return (entry.get("action") in ("walk", "run", "jump") or bool(entry.get("airborne"))
or entry.get("loopKind") == "gait")
def build_prompt(entry: dict, plan: dict, fixes: Sequence[str]) -> str:
"""The game-opus55 prompt shape: 'The same <identity>' + facing lock + ONE action + same start
and end pose + negatives and fix clauses + locked camera, flat key background, exact style."""
master = plan["masters"][entry["view"]]
key = plan["key"]
words = prompt_words(master["facing"], key, plan["style"], plan["pronoun"], entry["action"])
if moves_feet(entry): # an older state may still carry the planted-feet clause: never send it
planted = {" ".join(str(plan.get("clauses", {}).get(clause, "")).split()).lower() for clause in PLANTED_CLAUSES}
planted.discard("")
fixes = [fix for fix in fixes if " ".join(str(fix).split()).lower() not in planted]
parts = [f"The same {identity_phrase(master['identityRecap'])}, facing {words['facing']} the entire time and "
f"never turning around, {fill(entry['motion'], words).strip()}"]
if entry["returnsToRest"]:
parts.append("The clip starts AND ends in exactly the same pose as the still.")
seen = set()
for clause in [entry.get("negatives") or "", *fixes]:
text = fill(str(clause), words).strip()
if text and text.lower() not in seen:
seen.add(text.lower())
parts.append(text if text.endswith((".", "!", "?")) else text + ".")
parts.append(f"camera locked, no zoom, no pan; {key_words(key)[1]}; keep the exact {plan['style']} look, palette, "
"proportions and costume of the still; single continuous action.")
return " ".join(part.strip() for part in parts if part.strip()) + "\n"
def lint_findings(prompt: str, key: str) -> list[dict[str, str]]:
"""prepare_i2v_input lint, minus the numeric work region and timeline rules: the game-opus55 recipe
frames the clip by the input image and names one action instead."""
return [item for item in prep.lint_prompt(prompt, key if key in forge_matte.DECLARED_KEYS else None)
if item["rule"] not in ("missing-work-region", "missing-timeline")]
# --------------------------------------------------------------------------- the master
@dataclass(frozen=True)
class Master:
"""generate2dsprite.master.v1 plus the geometry measured on its padded PNG."""
json_path: Path
png_path: Path
data: dict
name: str
identity_recap: str
facing: str
finish: str
klass: str
key: str
key_rgb: tuple[int, int, int]
size: tuple[int, int]
box: tuple[int, int, int, int]
anchor: tuple[float, float]
area: int
framing: dict
style: str | None
def _parse_key(value: Any) -> tuple[str, tuple[int, int, int]]:
if isinstance(value, dict):
value = next((value[k] for k in ("color", "colour", "name", "hex", "rgb", "key") if value.get(k) is not None),
None)
if value is None:
return "magenta", forge_matte.DECLARED_KEYS["magenta"]
if isinstance(value, (list, tuple)) and len(value) == 3:
value = "#" + "".join(f"{int(channel):02x}" for channel in value)
text = str(value).strip().lower()
if text in forge_matte.DECLARED_KEYS:
return text, tuple(forge_matte.DECLARED_KEYS[text])
digits = text[1:] if text.startswith("#") else text
if not re.fullmatch(r"[0-9a-f]{6}", digits):
raise ValueError(f"master.json key must be magenta, green, blue, #rrggbb or [r, g, b]; got {value!r}")
rgb = tuple(int(digits[i:i + 2], 16) for i in (0, 2, 4))
for name, declared in forge_matte.DECLARED_KEYS.items():
if tuple(declared) == rgb:
return name, rgb
return "#" + digits, rgb
def _parse_facing(value: Any) -> str:
if isinstance(value, dict):
value = value.get("direction") or value.get("value") or value.get("facing")
text = str(value or "").strip().lower()
aliases = {"l": "left", "r": "right", "screen left": "left", "screen right": "right", "viewer": "front",
"toward the viewer": "front", "away": "back", "away from the viewer": "back"}
text = aliases.get(text, text)
if text not in ("left", "right", "front", "back"):
raise ValueError(f"master.json facing must be left, right, front or back; got {value!r}")
return text
def _parse_size(value: Any) -> tuple[int, int] | None:
if isinstance(value, (int, float)) and value > 0:
return int(value), int(value)
if isinstance(value, (list, tuple)) and len(value) == 2:
return int(value[0]), int(value[1])
if isinstance(value, dict) and "width" in value and "height" in value:
return int(value["width"]), int(value["height"])
if isinstance(value, str):
match = re.fullmatch(r"\s*(\d+)\s*[x,]\s*(\d+)\s*", value)
if match:
return int(match.group(1)), int(match.group(2))
return None
def _master_png_ref(data: dict, base: Path) -> tuple[Path, str | None]:
"""The padded master PNG named in master.json ``files`` (a dict or a list of {path, sha256})."""
found: list[tuple[str, str, str | None]] = []
def add(entry: Any, label: str) -> None:
if isinstance(entry, str):
found.append((label, entry, None))
elif isinstance(entry, dict) and isinstance(entry.get("path"), str):
found.append((" ".join(str(entry.get(k) or "") for k in ("role", "name", "kind")) + " " + label,
entry["path"], entry.get("sha256")))
elif isinstance(entry, dict) and label.lower().endswith(".png"): # {"master.png": {"sha256": ...}}
found.append((label, label, entry.get("sha256")))
files = data.get("files")
if isinstance(files, dict):
for name, entry in files.items():
add(entry, str(name))
elif isinstance(files, list):
for entry in files:
add(entry, "")
pngs = [item for item in found if item[1].lower().endswith(".png")]
if not pngs:
raise ValueError("master.json files names no PNG; it needs the padded master.png with its sha256")
def rank(item: tuple[str, str, str | None]) -> int:
words = (item[0] + " " + Path(item[1]).name).lower()
return 2 if "pad" in words else (1 if "master" in words else 0)
_, relative, digest = max(pngs, key=rank) # first of the best rank: padded, then master, then any PNG
path = Path(relative)
return (path if path.is_absolute() else base / path), digest
def load_master(path: Path) -> Master:
"""Read master.json, check the padded PNG's sha256, key an opaque master like prepare_i2v_input does
and measure the subject box, the stance anchor and the opaque area."""
path = Path(path)
try:
data = forge_core.read_json(path)
except ValueError as error:
raise ValueError(f"{path.name} is not valid JSON: {error}") from None
if not isinstance(data, dict) or data.get("schema") != MASTER_SCHEMA:
raise ValueError(f"{path.name} is not a {MASTER_SCHEMA} document")
recap = data.get("identity_recap")
if not isinstance(recap, str) or len(recap.split()) < 2:
raise ValueError(f"{path.name} needs identity_recap, the long identity phrase every motion prompt repeats")
png, digest = _master_png_ref(data, path.parent)
if not png.is_file():
raise ValueError(f"the master PNG {png.name} named in {path.name} is missing")
image, info = forge_core.load_rgba(png)
if digest and str(digest).lower() != info["sha256"]:
raise ValueError(f"{png.name} changed since {path.name} recorded it (sha256 mismatch)")
key, key_rgb = _parse_key(data.get("key"))
pixels = np.asarray(image)
if int(pixels[..., 3].min()) == 255:
pixels, _record = prep.key_opaque_master(pixels, key, False)
alpha = pixels[..., 3]
box = forge_core.subject_bbox(alpha)
if box is None:
raise ValueError(f"{png.name} has no subject after keying its {key} backdrop")
anchor = prep.measure_anchor(alpha, "stance")
finish = str(data.get("finish") or "hd").strip().lower()
if finish not in FINISHES:
raise ValueError(f"master.json finish must be hd or pixel; got {data.get('finish')!r}")
framing = data.get("framing") if isinstance(data.get("framing"), dict) else {}
stated = _parse_size(framing.get("canvas"))
if stated is not None and stated != (alpha.shape[1], alpha.shape[0]):
raise ValueError(f"{path.name} framing.canvas {list(stated)} does not match {png.name} "
f"({alpha.shape[1]}x{alpha.shape[0]}); the master.json is stale")
style = data.get("style") if isinstance(data.get("style"), str) and data.get("style").strip() else None
return Master(json_path=path, png_path=png, data=data, name=str(data.get("name") or path.parent.name or "sprite"),
identity_recap=recap, facing=_parse_facing(data.get("facing")), finish=finish,
klass=str(data.get("class") or "hero").strip().lower(), key=key, key_rgb=key_rgb,
size=(alpha.shape[1], alpha.shape[0]), box=box, anchor=(float(anchor[0]), float(anchor[1])),
area=int((alpha > 127).sum()), framing=framing, style=style)
# --------------------------------------------------------------------------- placement
def placement(master: Master, preset: str) -> dict:
"""The provider canvas of one action: the master placed by one recorded transform (prepare_i2v_input
--canvas --scale --root --anchor), its margin and the action padding that covers the whole video
footprint on the master canvas (so register_clip never clips motion)."""
spec = CANVAS_PRESETS[preset]
W0, H0 = master.size
x0, y0, x1, y1 = master.box
ax, ay = master.anchor
if spec["aspect"] is None:
width, height, scale, root = W0, H0, 1.0, (ax, ay)
else:
aw, ah = spec["aspect"]
height = H0
width = _even(H0 * aw / ah)
scale = 1.0
bottom = max(H0 - ay, 8.0)
root_y = ay
if spec["headroom"]:
top = spec["headroom"] * height
scale = min(1.0, (height - bottom - top) / max(1.0, ay - y0), (width - 16.0) / max(1.0, x1 - x0))
root_y = height - bottom
lead = {"left": 1.0, "right": -1.0}.get(master.facing, 0.0) * spec["lead"] * width
low, high = scale * (ax - x0) + 6.0, width - scale * (x1 - ax) - 6.0
root_x = min(max(width / 2 + lead, low), high) if low <= high else width / 2
root = (root_x, root_y)
offset = (root[0] - scale * ax, root[1] - scale * ay)
placed = (offset[0] + scale * x0, offset[1] + scale * y0, offset[0] + scale * x1, offset[1] + scale * y1)
gap = min(placed[0], placed[1], width - placed[2], height - placed[3])
if gap < 1:
raise ValueError(f"the master's subject touches the {preset} canvas edge ({width}x{height}); re-pad the master "
"with a free margin on every side")
margin = max(0, min(20, int(math.floor(gap)) - 3))
padding = [max(0, math.ceil(offset[0] / scale - 1e-9)), max(0, math.ceil(offset[1] / scale - 1e-9)),
max(0, math.ceil((width - offset[0]) / scale - W0 - 1e-9)),
max(0, math.ceil((height - offset[1]) / scale - H0 - 1e-9))]
return {"preset": preset, "canvas": [width, height], "scale": round(scale, 6),
"root": [round(root[0], 4), round(root[1], 4)], "anchor": [ax, ay],
"subjectBox": [round(value, 2) for value in placed], "margin": margin, "padding": padding,
"headroom": round(placed[1] / height, 4)}
# --------------------------------------------------------------------------- QC gates (numeric)
def _block_mean(array: np.ndarray, factor: int) -> np.ndarray:
"""Mean of factor x factor blocks (the trailing partial block is dropped), as float32."""
if factor <= 1:
return array.astype(np.float32)
height, width = (array.shape[0] // factor) * factor, (array.shape[1] // factor) * factor
cut = array[:height, :width].astype(np.float32)
return cut.reshape(height // factor, factor, width // factor, factor, *cut.shape[2:]).mean(axis=(1, 3))
@dataclass
class QcFrame:
"""One take frame reduced for the gates: alpha (0-255), luma over mid grey, raw RGB, the edge touch
measured at full resolution and, for the colour gate, the frame's colours (straight RGBA) reduced half
as much as the rest."""
alpha: np.ndarray
luma: np.ndarray
raw: np.ndarray | None
edge: bool
colour: np.ndarray | None = None
def _block_rgba(rgba: np.ndarray, factor: int) -> np.ndarray:
"""Straight-alpha RGBA reduced by factor x factor blocks on premultiplied colour (uint8)."""
if factor <= 1:
return np.asarray(rgba, np.uint8)
alpha = _block_mean(rgba[..., 3], factor)
premultiplied = _block_mean(rgba[..., :3].astype(np.float32) * (rgba[..., 3:4].astype(np.float32) / 255.0), factor)
rgb = np.where(alpha[..., None] > 0.5, premultiplied / np.maximum(alpha[..., None] / 255.0, 1e-6), 0.0)
return np.dstack([np.clip(rgb + 0.5, 0, 255), np.clip(alpha + 0.5, 0, 255)]).astype(np.uint8)
def qc_frame(rgba: np.ndarray, raw: np.ndarray | None, factor: int, edge_px: int, colour: bool = False) -> QcFrame:
alpha = rgba[..., 3]
band = max(1, int(edge_px))
edge = bool((alpha[:band] > 16).any() or (alpha[-band:] > 16).any()
or (alpha[:, :band] > 16).any() or (alpha[:, -band:] > 16).any())
weight = alpha.astype(np.float32) / 255.0
luma = (rgba[..., :3].astype(np.float32) @ LUMA) * weight + 128.0 * (1.0 - weight)
return QcFrame(_block_mean(alpha, factor), _block_mean(luma, factor),
None if raw is None else _block_mean(raw[..., :3], factor), edge,
_block_rgba(rgba, max(1, factor // 2)) if colour else None)
def _box_sum(values: np.ndarray, height: int, width: int) -> np.ndarray:
table = np.zeros((values.shape[0] + 1, values.shape[1] + 1), np.float64)
table[1:, 1:] = values.astype(np.float64).cumsum(0).cumsum(1)
return table[height:, width:] - table[:-height, width:] - table[height:, :-width] + table[:-height, :-width]
def _crop_padded(image: np.ndarray, left: int, top: int, width: int, height: int, fill: float) -> np.ndarray:
out = np.full((height, width), fill, np.float64)
x0, y0 = max(0, left), max(0, top)
x1, y1 = min(image.shape[1], left + width), min(image.shape[0], top + height)
if x0 < x1 and y0 < y1:
out[y0 - top:y1 - top, x0 - left:x1 - left] = image[y0:y1, x0:x1]
return out
def ncc_best(template: np.ndarray, image: np.ndarray, x0: int, y0: int, search: int) -> float | None:
"""Best zero-mean NCC of ``template`` with its top-left within +-search px of (x0, y0) in ``image``
(padded with the mid-grey backdrop); None for a flat template."""
height, width = template.shape
centred = template.astype(np.float64) - float(template.mean())
norm = math.sqrt(float((centred * centred).sum()))
if norm < 2.0 * math.sqrt(centred.size): # luma spread under 2 levels: nothing to match
return None
region = _crop_padded(image, x0 - search, y0 - search, width + 2 * search, height + 2 * search, 128.0)
windows = np.lib.stride_tricks.sliding_window_view(region, (height, width))
numerator = np.einsum("ijkl,kl->ij", windows, centred)
count = height * width
sums = _box_sum(region, height, width)
spread = np.sqrt(np.maximum(_box_sum(region * region, height, width) - sums * sums / count, 0.0))
return float((numerator / np.maximum(spread * norm, 1e-9)).max())
def _mask_stats(mask: np.ndarray) -> dict | None:
rows = np.flatnonzero(mask.any(axis=1))
if rows.size == 0:
return None
columns = np.flatnonzero(mask.any(axis=0))
box = (int(columns[0]), int(rows[0]), int(columns[-1]) + 1, int(rows[-1]) + 1)
try:
ground = forge_core.ground_row(mask, min_run=2)
except ValueError:
ground = box[3]
height = max(1, ground - box[1])
band = max(2, forge_core.round_half_up(0.04 * height))
try:
stance = float(forge_core.anchor_from_mask(mask, "stance", band_rows=band, min_run=2)[0])
except ValueError:
stance = (box[0] + box[2]) / 2
head_rows = mask[box[1]:box[1] + max(1, forge_core.round_half_up(0.35 * height))]
ys, xs = np.nonzero(head_rows)
top = (float(xs.mean()) + 0.5, float(ys.mean()) + 0.5 + box[1]) if xs.size else ((box[0] + box[2]) / 2, box[1])
return {"area": int(mask.sum()), "box": box, "ground": ground, "height": height, "stance": stance, "top": top}
def _extra_area(mask: np.ndarray, min_area: int) -> int:
"""Opaque area outside the largest component (components under ``min_area`` are specks)."""
labels, count = forge_core.label_components(mask)
if count <= 1:
return 0
areas = np.bincount(labels.ravel())[1:]
areas = areas[areas >= min_area]
return int(areas.sum() - areas.max()) if areas.size > 1 else 0
def _shift(mask: np.ndarray, dx: float, dy: float) -> np.ndarray:
dx, dy = forge_core.round_half_up(dx), forge_core.round_half_up(dy)
out = np.zeros_like(mask)
height, width = mask.shape
sx0, sx1, sy0, sy1 = max(0, -dx), min(width, width - dx), max(0, -dy), min(height, height - dy)
if sx0 < sx1 and sy0 < sy1:
out[sy0 + dy:sy1 + dy, sx0 + dx:sx1 + dx] = mask[sy0:sy1, sx0:sx1]
return out
def _iou(first: np.ndarray, second: np.ndarray) -> float:
union = int((first | second).sum())
return float((first & second).sum()) / union if union else 0.0
def _head_box(mask: np.ndarray, stats: dict) -> tuple[int, int, int, int] | None:
"""The top of the subject: its top 35%, as wide as its top 20% plus a 10% margin (register_clip qc)."""
x0, y0, x1, _ = stats["box"]
height = stats["height"]
crown = np.flatnonzero(mask[y0:y0 + max(1, forge_core.round_half_up(0.2 * height))].any(axis=0))
if crown.size == 0:
return None
margin = forge_core.round_half_up(0.1 * (crown[-1] + 1 - crown[0]))
hx0, hx1 = max(x0, int(crown[0]) - margin), min(x1, int(crown[-1]) + 1 + margin)
hy0, hy1 = y0, min(mask.shape[0], y0 + max(6, forge_core.round_half_up(0.35 * height)))
return (hx0, hy0, hx1, hy1) if hx1 - hx0 >= 6 and hy1 - hy0 >= 6 else None
def _runs(flags: Sequence[bool]) -> list[tuple[int, int]]:
"""[start, end) of every run of True."""
runs, start = [], None
for index, flag in enumerate(list(flags) + [False]):
if flag and start is None:
start = index
elif not flag and start is not None:
runs.append((start, index))
start = None
return runs
def _rolling_median(values: Sequence[float], window: int) -> np.ndarray:
data = np.asarray(values, np.float64)
half = max(0, window // 2)
return np.array([np.median(data[max(0, i - half):i + half + 1]) for i in range(data.size)])
def _scaled(template: np.ndarray, scale: float) -> tuple[np.ndarray, int, int]:
"""``template`` resized by ``scale`` (bilinear) and the offset that keeps it centred on the original."""
if abs(scale - 1.0) < 1e-9:
return template, 0, 0
height, width = template.shape
size = (max(4, forge_core.round_half_up(width * scale)), max(4, forge_core.round_half_up(height * scale)))
resized = np.asarray(Image.fromarray(np.asarray(template, np.float32), "F").resize(size, Image.Resampling.BILINEAR),
np.float64)
return resized, forge_core.round_half_up((width - size[0]) / 2), forge_core.round_half_up((height - size[1]) / 2)
def _timing_phases(steps: Sequence[float], fps: float) -> dict:
"""One-shot motion from the per-frame luma change (retime --auto-oneshot's rule): moving frames are at least
max(0.15, 20% of the 90th-percentile step) (3-frame mean); the action runs from the first to the last moving
frame and the longest still run inside it is the hold."""
values = np.asarray(steps, np.float64)
if values.size < 3:
return {"actionSeconds": 0.0, "holdSeconds": 0.0, "onset": None, "settle": None}
padded = np.concatenate([[values[min(1, values.size - 1)]], values, [values[-1]]])
smooth = (padded[:-2] + padded[1:-1] + padded[2:]) / 3.0
smooth[0] = 0.0
active = max(0.15, 0.2 * float(np.percentile(smooth[1:], 90)))
moving = np.flatnonzero(smooth >= active)
if moving.size == 0:
return {"actionSeconds": 0.0, "holdSeconds": 0.0, "onset": None, "settle": None}
onset, settle = int(moving[0]), int(moving[-1])
longest = run = 0
for index in range(onset, settle + 1):
run = run + 1 if smooth[index] < active else 0
longest = max(longest, run)
return {"actionSeconds": (settle - onset + 1) / fps, "holdSeconds": longest / fps, "onset": onset,
"settle": settle, "activeStep": active}
def evaluate_take(frames: Sequence[QcFrame], reference: QcFrame, *, key: str, gates: dict, fps: float,
facing: str, kind: str, airborne: bool, returns_to_rest: bool, hit_tick: bool,
master: Any = None, timing_mode: str | None = None) -> dict:
"""Score one keyed take against the master as the job placed it (both reduced alike).
Gates (game-opus55 take loop, recalibrated on the 2026-10-06 live run): opaque-area ratio to the master,
feet drift (runs: the half-second rolling median, so a flight phase is not drift), identity (frame 0
against the master; then the head against the master and frame 0 at three scales, a warning unless the
design is lost in most frames), camera push-in or zoom, turning around (mirrored head NCC and mirrored
silhouette), edge touch, flat background, detached extra objects, visible motion, colour (``master``:
colour_lock.master_colours of the placed master; hues the design does not have at that height), one-shot
timing (slow motion and long holds; warns while the set retimes one-shots, ``timing_mode`` "auto") and,
for one-shots, the return to the start pose. Returns the QC document with per-frame numbers, the failing
gate ids, readable reasons with frame numbers, the warnings and the longest usable window of frames that
pass every per-frame gate."""
count = len(frames)
if count < 2:
raise ValueError("a take needs at least two frames")
ref_mask = reference.alpha > 127.5
ref = _mask_stats(ref_mask)
if ref is None:
raise ValueError("the master does not land inside the video frame; check the job and the fit")
ref_area, ref_height = max(1, ref["area"]), max(1, ref["height"])
min_component = max(2, forge_core.round_half_up(0.001 * ref_area))
ref_extra = _extra_area(ref_mask, min_component)
head = _head_box(ref_mask, ref)
search = max(3, forge_core.round_half_up(0.15 * ref_height))
masks = [frame.alpha > 127.5 for frame in frames]
stats = [_mask_stats(mask) for mask in masks]
first = stats[0]
if first is None:
raise ValueError("frame 0 of the take is empty after keying")
width = masks[0].shape[1]
master_t = reference.luma[head[1]:head[3], head[0]:head[2]] if head else None
frame0_t = frames[0].luma[head[1]:head[3], head[0]:head[2]] if head else None
declared = key if key in forge_matte.DECLARED_KEYS else tuple(int(key[i:i + 2], 16) for i in (1, 3, 5))
declared_rgb = np.asarray(forge_matte.DECLARED_KEYS.get(key, declared), np.float32)
bg_tol = float(gates["background"]["tolerance"])
start_ncc = None
if master_t is not None:
start_ncc = ncc_best(master_t, frames[0].luma, head[0], head[1], 3)
id_scales = [float(value) for value in gates["identity"].get("scales", [1.0]) if abs(float(value) - 1.0) > 1e-9]
scaled_templates = ([_scaled(template, scale) for template in (master_t, frame0_t) for scale in id_scales]
if head else [])
rows: list[dict[str, Any]] = []
previous_luma = None
for frame, mask, st in zip(frames, masks, stats):
row: dict[str, Any] = {"edge": frame.edge}
row["step"] = 0.0 if previous_luma is None else float(np.abs(frame.luma - previous_luma).mean())
previous_luma = frame.luma
if master is not None and frame.colour is not None:
row.update(colour_lock.foreign_drift(frame.colour, master))
if st is None:
row.update(empty=True, area=0.0, feet=None, lift=None, pose=1.0, iou0=0.0, extra=0.0, reach=0.0,
direct=0.0, mirror=0.0, ncc=None, nccMaster=None, nccMirror=None, nccScaled=None)
else:
row["area"] = st["area"] / ref_area
row["feet"] = (st["ground"] - ref["ground"]) / ref_height
row["lift"] = (ref["ground"] - st["ground"]) / ref_height
row["height"] = st["height"] / max(1, first["height"])
row["pose"] = float((mask ^ masks[0]).sum()) / ref_area
row["iou0"] = _iou(mask, masks[0])
row["extra"] = max(0, _extra_area(mask, min_component) - ref_extra) / ref_area
if facing == "left":
reach = first["box"][0] - st["box"][0]
elif facing == "right":
reach = st["box"][2] - first["box"][2]
else:
reach = max(first["box"][0] - st["box"][0], st["box"][2] - first["box"][2])
row["reach"] = reach / ref_height
dy = st["ground"] - first["ground"]
row["direct"] = _iou(mask, _shift(masks[0], st["stance"] - first["stance"], dy))
row["mirror"] = _iou(mask, _shift(masks[0][:, ::-1], st["stance"] - (width - first["stance"]), dy))
if head:
shift = (forge_core.round_half_up(st["top"][0] - first["top"][0]),
forge_core.round_half_up(st["top"][1] - first["top"][1]))
centres = {(head[0], head[1]), (head[0] + shift[0], head[1] + shift[1])}
def best(template: np.ndarray, image: np.ndarray = frame.luma) -> float | None:
scores = [ncc_best(template, image, x, y, search) for x, y in centres]
scores = [score for score in scores if score is not None]
return max(scores) if scores else None
row["ncc"] = best(frame0_t)
row["nccMaster"] = best(master_t)
row["nccMirror"] = best(master_t[:, ::-1])
scores = [value for value in (row["ncc"], row["nccMaster"]) if value is not None]
for template, dx, dy in scaled_templates:
for x, y in centres:
value = ncc_best(template, frame.luma, x + dx, y + dy, search)
if value is not None:
scores.append(value)
row["nccScaled"] = max(scores) if scores else None
else:
row.update(ncc=None, nccMaster=None, nccMirror=None, nccScaled=None)
if frame.raw is not None:
covered = forge_core.dilate_square(frame.alpha > 2.0, 2)
background = ~covered
pixels = int(background.sum())
raw8 = np.clip(frame.raw + 0.5, 0, 255).astype(np.uint8)
estimate, _info = forge_matte.estimate_key(raw8, declared, ring=1)
if pixels:
distance = np.sqrt(((frame.raw[background] - estimate) ** 2).sum(axis=-1))
row["bg"] = float((distance > bg_tol).sum()) / pixels
else:
row["bg"] = 0.0
row["keyDrift"] = float(np.sqrt(((estimate - declared_rgb) ** 2).sum()))
rows.append(row)
gate_results: dict[str, dict[str, Any]] = {}
failures: list[str] = []
reasons: list[str] = []
warnings: list[str] = []
bad: dict[str, list[bool]] = {}
def record(gate: str, status: str, value: Any, threshold: Any, frames_bad: Sequence[int] = (),
reason: str | None = None) -> None:
gate_results[gate] = {"status": status, "value": _round(value), "threshold": _round(threshold),
"frames": [int(i) for i in frames_bad]}
if status == "fail":
failures.append(gate)
if reason:
reasons.append(f"{gate}: {reason}")
elif status == "warn" and reason:
warnings.append(f"{gate}: {reason}")
# area ratio against the master
area_gate = gates["area"]
ratios = [row["area"] for row in rows]
bad["area"] = [not (area_gate["min"] <= value <= area_gate["max"]) for value in ratios]
median = float(np.median(ratios))
share = sum(bad["area"]) / count
frames_bad = [i for i, flag in enumerate(bad["area"]) if flag]
ok = area_gate["min"] <= median <= area_gate["max"] and share <= area_gate["maxBadShare"]
record("area", "pass" if ok else "fail", {"median": median, "min": min(ratios), "max": max(ratios)},
[area_gate["min"], area_gate["max"]], frames_bad,
f"opaque area {median:.2f}x the master (band {area_gate['min']}-{area_gate['max']}); out of band in "
f"frames {_ranges(frames_bad)}")
# feet drift (airborne actions: only the calm start and end spans; "median": the half-second rolling median,
# so a run's flight phase is not drift while a run that wanders off the ground line still fails)
feet_gate = gates["feet"]
calm = max(2, forge_core.round_half_up(0.25 * fps))
checked = [True] * count
if feet_gate.get("mode") == "start-end" or airborne:
checked = [i < calm or i >= count - calm for i in range(count)]
drifts = [abs(row["feet"]) if row["feet"] is not None else 1.0 for row in rows]
if feet_gate.get("mode") == "median" and not airborne:
drifts = list(_rolling_median(drifts, max(3, forge_core.round_half_up(0.5 * fps)) | 1))
bad["feet"] = [check and drift > feet_gate["max"] for check, drift in zip(checked, drifts)]
frames_bad = [i for i, flag in enumerate(bad["feet"]) if flag]
worst = max((drift for check, drift in zip(checked, drifts) if check), default=0.0)
record("feet", "fail" if len(frames_bad) > feet_gate["badFrames"] else "pass", worst, feet_gate["max"],
frames_bad, f"feet drift up to {worst:.1%} of the body height (limit {feet_gate['max']:.0%}"
+ (", half-second median" if feet_gate.get("mode") == "median" else "") + f") in frames "
f"{_ranges(frames_bad)}")
# identity: frame 0 against the master (a hard gate); then the head against the master and frame 0 at the
# gate's scales, a warning for low frames and a failure only when the design is lost in most frames
id_gate = gates["identity"]
scores = [row.get("nccScaled", row.get("ncc")) for row in rows]
if start_ncc is None or all(value is None for value in scores):
record("identity", "skipped", None, id_gate["min"])
bad["identity"] = [False] * count
else:
severe = float(id_gate.get("severe", id_gate["min"]))
severe_share = float(id_gate.get("severeShare", 0.0))
low_frames = [i for i, value in enumerate(scores) if value is not None and value < id_gate["min"]]
lost = [i for i, value in enumerate(scores) if value is not None and value < severe]
low = min(value for value in scores if value is not None)
start_ok = start_ncc >= id_gate["start"]
if "severe" in id_gate:
failed = not start_ok or len(lost) > severe_share * count
flagged = set(lost)
else: # a plan written before the recalibration keeps its hard per-frame floor
failed = not start_ok or len(low_frames) > id_gate["badFrames"]
flagged = set(low_frames)
bad["identity"] = [i in flagged for i in range(count)]
status = "fail" if failed else ("warn" if len(low_frames) > id_gate["badFrames"] else "pass")
if not start_ok:
reason = f"frame 0 does not reproduce the master (head NCC {start_ncc:.2f} < {id_gate['start']})"
elif failed:
reason = (f"the head matches the master under {severe} in {len(lost)} of {count} frames ("
f"{_ranges(lost)}): the design is lost or the face is covered")
else:
reason = (f"the head matches the master only {low:.2f} (warning under {id_gate['min']}) in frames "
f"{_ranges(low_frames)}: a turned or bobbing head, or design drift; look at the sheet")
record("identity", status, {"start": start_ncc, "min": low, "lowFrames": len(low_frames),
"lostFrames": len(lost)},
{"start": id_gate["start"], "warn": id_gate["min"], "severe": severe, "severeShare": severe_share},
lost if failed else low_frames, reason)
# camera push-in or zoom
zoom_gate = gates["zoom"]
base_area = max(1, first["area"])
scales = [math.sqrt(max(row["area"], 0.0) * ref_area / base_area) for row in rows]
bad["zoom"] = [False] * count
if kind == "loop":
window = max(5, forge_core.round_half_up(fps))
smooth = _rolling_median(scales, window)
deviation = np.abs(smooth - 1.0)
limit = zoom_gate.get("loopMax", zoom_gate["max"] * 1.25)
over = np.flatnonzero(deviation > limit)
if over.size:
onset = int(over[0])
bad["zoom"] = [i >= onset for i in range(count)]
record("zoom", "fail" if over.size else "pass", float(deviation.max()), limit,
[int(i) for i in over], f"camera zoom: the body scale drifts {float(deviation.max()):.0%} from "
f"frame 0 (limit {limit:.0%}) from frame {int(over[0]) if over.size else 0}")
elif returns_to_rest:
span = list(range(max(1, count - max(3, forge_core.round_half_up(0.4 * fps))), count))
end_scale = float(np.median([scales[i] for i in span]))
end_height = float(np.median([rows[i].get("height", 1.0) for i in span]))
zoomed = (abs(end_scale - 1) > zoom_gate["max"] and abs(end_height - 1) > 0.75 * zoom_gate["max"]
and (end_scale - 1) * (end_height - 1) > 0)
record("zoom", "fail" if zoomed else "pass", {"endScale": end_scale, "endHeight": end_height},
zoom_gate["max"], span if zoomed else [],
f"camera push-in: the body comes back {end_scale:.2f}x the size of frame 0 at the end (frames "
f"{_ranges(span)})")
else:
record("zoom", "skipped", None, zoom_gate["max"])
# turning around: the mirrored head matches better and the silhouette agrees
turn_gate = gates["turn"]
bad["turn"] = [False] * count
if not turn_gate.get("enabled", True) or facing in ("front", "back"):
record("turn", "skipped", None, turn_gate["margin"])
else:
flags = []
for row in rows:
direct, mirror = row.get("nccMaster"), row.get("nccMirror")
silhouette = row["mirror"] >= row["direct"] - 0.02
if direct is not None and mirror is not None:
flags.append(mirror - direct > turn_gate["margin"] and silhouette)
else:
flags.append(row["mirror"] > row["direct"] + 0.1)
runs = [run for run in _runs(flags) if run[1] - run[0] >= turn_gate["run"]]
turned = sorted({i for a, b in runs for i in range(a, b)})
bad["turn"] = [i in set(turned) for i in range(count)]
evidence = max(((row.get("nccMirror") or 0) - (row.get("nccMaster") or 0) for row in rows), default=0.0)
record("turn", "fail" if runs else "pass", evidence, turn_gate["margin"], turned,
f"turned around in frames {_ranges(turned)} (the mirrored head matches {evidence:+.2f} better)")
# edge touch at full resolution
bad["edge"] = [row["edge"] for row in rows]
frames_bad = [i for i, flag in enumerate(bad["edge"]) if flag]
record("edge", "fail" if frames_bad else "pass", len(frames_bad), 0, frames_bad,
f"the subject touches the frame edge in frames {_ranges(frames_bad)} (cut by the generator: never pad)")
# background flatness (raw frames)
bg_gate = gates["background"]
if any("bg" in row for row in rows):
values = [row.get("bg", 0.0) for row in rows]
bad["background"] = [value > bg_gate["maxImpure"] for value in values]
frames_bad = [i for i, flag in enumerate(bad["background"]) if flag]
drift = max(row.get("keyDrift", 0.0) for row in rows)
record("background", "fail" if len(frames_bad) > bg_gate["badFrames"] else "pass",
{"worst": max(values), "keyDrift": drift}, bg_gate["maxImpure"], frames_bad,
f"background not flat in frames {_ranges(frames_bad)} (worst {max(values):.2%} of the backdrop off "
"the key)")
else:
bad["background"] = [False] * count
record("background", "skipped", None, bg_gate["maxImpure"])
# detached extra objects (dust, orbs, projectiles)
extra_gate = gates["extra"]
extras = [row["extra"] for row in rows]
bad["extra"] = [value > extra_gate["max"] for value in extras]
frames_bad = [i for i, flag in enumerate(bad["extra"]) if flag]
record("extra", "fail" if len(frames_bad) > extra_gate["badFrames"] else "pass", max(extras), extra_gate["max"],
frames_bad, f"extra objects detached from the body in frames {_ranges(frames_bad)} (worst "
f"{max(extras):.1%} of the body area)")
# the action happens
motion_gate = gates["motion"]
poses = [row["pose"] for row in rows]
peak = float(max(poses))
record("motion", "pass" if peak >= motion_gate["min"] else "fail", peak, motion_gate["min"], [],
f"no visible action (peak pose change {peak:.1%} of the body area, needs {motion_gate['min']:.1%})")
# one-shots return to the start pose
end_gate = gates["endPose"]
if end_gate.get("enabled", True) and returns_to_rest and kind == "oneshot":
tail = max(row["iou0"] for row in rows[-3:])
record("end-pose", "pass" if tail >= end_gate["min"] else "fail", tail, end_gate["min"],
[] if tail >= end_gate["min"] else list(range(count - 3, count)),
f"the clip does not return to the start pose (silhouette IoU {tail:.2f} with frame 0)")
else:
record("end-pose", "skipped", None, end_gate["min"])
# colour: hues the design does not have at that height (bleed); region drift only warns (the lock undoes it)
colour_gate = gates.get("colour") or BASE_GATES["colour"]
if any("foreign" in row for row in rows):
foreign = [float(row.get("foreign", 0.0)) for row in rows]
drifts_c = [float(row.get("drift", 0.0)) for row in rows]
bad["colour"] = [value > colour_gate["foreign"] for value in foreign]
frames_bad = [i for i, flag in enumerate(bad["colour"]) if flag]
drifted = [i for i, value in enumerate(drifts_c) if value > colour_gate["drift"]]
bled = len(frames_bad) > colour_gate["badShare"] * count
warned = len(drifted) > colour_gate["driftShare"] * count
record("colour", "fail" if bled else ("warn" if warned else "pass"),
{"foreignMax": max(foreign), "bledFrames": len(frames_bad), "driftMax": max(drifts_c),
"driftedFrames": len(drifted)},
{"foreign": colour_gate["foreign"], "badShare": colour_gate["badShare"],
"drift": colour_gate["drift"], "driftShare": colour_gate["driftShare"]},
frames_bad if bled else drifted,
(f"colours the master does not have (bleed or tint) on more than {colour_gate['foreign']:.0%} of the "
f"body in {len(frames_bad)} of {count} frames ({_ranges(frames_bad)})") if bled else
(f"design colours drift (up to {max(drifts_c):.3f} OKLab) in {len(drifted)} of {count} frames "
f"({_ranges(drifted)}); the finish's colour lock pulls them back, look at the sheet"))
if not bled:
bad["colour"] = [False] * count
else:
record("colour", "skipped", None, colour_gate["foreign"])
# one-shot timing: the generator's slow motion and frozen holds
timing_gate = gates.get("timing") or BASE_GATES["timing"]
if kind == "oneshot":
phases = _timing_phases([row["step"] for row in rows], fps)
slow = (phases["actionSeconds"] > timing_gate["maxSeconds"]
or phases["holdSeconds"] > timing_gate["maxHoldSeconds"])
status = "pass" if not slow else ("warn" if timing_mode == "auto" else "fail")
record("timing", status, {"actionSeconds": phases["actionSeconds"], "holdSeconds": phases["holdSeconds"]},
{"maxSeconds": timing_gate["maxSeconds"], "maxHoldSeconds": timing_gate["maxHoldSeconds"]}, [],
f"slow one-shot: {phases['actionSeconds']:.1f} s of motion (limit {timing_gate['maxSeconds']} s), "
f"a {phases['holdSeconds']:.1f} s static hold (limit {timing_gate['maxHoldSeconds']} s)"
+ ("; the set retimes it (retime --auto-oneshot)" if timing_mode == "auto" else ""))
else:
record("timing", "skipped", None, timing_gate["maxSeconds"])
# motion landmarks (take frame numbers) for retime: onset, settle, impact, cancel, takeoff, land
threshold = max(0.01, 0.5 * motion_gate["min"])
moving = [i for i, value in enumerate(poses) if value > threshold]
motion: dict[str, Any] = {"peak": peak, "peakFrame": int(np.argmax(poses)),
"onset": moving[0] if moving else None, "settle": moving[-1] if moving else None}
if moving and hit_tick:
impact = max(range(moving[0], moving[-1] + 1), key=lambda i: (rows[i]["reach"], -i))
motion["impact"] = int(impact)
after = [i for i in range(impact + 1, moving[-1] + 1) if poses[i] < 0.5 * poses[impact]]
motion["cancel"] = after[0] if after else None
if airborne:
lifted = [i for i, row in enumerate(rows) if row["lift"] is not None and row["lift"] > 0.03]
motion["takeoff"] = lifted[0] if lifted else None
motion["land"] = lifted[-1] + 1 if lifted and lifted[-1] + 1 < count else None
usable = [not any(bad[name][i] for name in bad) for i in range(count)]
window = None
runs = sorted(_runs(usable), key=lambda run: (run[1] - run[0], -run[0]), reverse=True)
if runs:
a, b = runs[0]
if kind == "loop":
if b - a >= max(8, forge_core.round_half_up(gates["window"]["loopSeconds"] * fps)):
window = [a, b]
elif moving and a <= max(0, moving[0] - 1) and b >= min(count, moving[-1] + 1):
window = [a, b]
per_frame = {name: [_round(row.get(name), 4) for row in rows]
for name in ("area", "feet", "lift", "pose", "iou0", "extra", "reach", "direct", "mirror", "ncc",
"nccMaster", "nccMirror", "nccScaled", "bg", "foreign", "drift", "step")}
per_frame["edge"] = [bool(row["edge"]) for row in rows]
per_frame["usable"] = usable
per_frame["bad"] = {name: [i for i, flag in enumerate(flags) if flag] for name, flags in bad.items()}
return {
"schema": QC_SCHEMA,
"status": "fail" if failures else "pass",
"failures": failures,
"reasons": reasons,
"warnings": warnings,
"gates": gate_results,
"frames": count,
"fps": _round(fps),
"usableWindow": window,
"usableFrames": int(sum(usable)),
"motion": _round(motion),
"reference": {"area": ref_area, "height": ref_height, "headBox": list(head) if head else None,
"search": search},
"perFrame": per_frame,
}
def qc_take(job_path: Path, clean_dir: Path, raw_dir: Path | None, *, key: str, gates: dict, fps: float,
facing: str, kind: str, airborne: bool, returns_to_rest: bool, hit_tick: bool,
timing_mode: str | None = None) -> dict:
"""Load a keyed take (video2dsprite process frames-clean and frames-raw) and the master as the job placed it
in the video, reduce both alike and run evaluate_take (the colour gate learns the master's colours from the
placed master)."""
clean = _pngs(clean_dir)
if len(clean) < 2:
raise ValueError(f"{clean_dir.name} holds {len(clean)} keyed frames; a take needs at least two")
raw = _pngs(raw_dir) if raw_dir is not None and raw_dir.is_dir() else []
if raw and len(raw) != len(clean):
raw = []
job = register_clip.load_job(job_path)
view = register_clip.load_master_view(job)
with Image.open(clean[0]) as probe:
size = probe.size
fit = register_clip.video_fit(job.canvas, size, "auto")
placed = register_clip.place_in_video(view, job, fit)
box = forge_core.subject_bbox(placed[..., 3], 127)
if box is None:
raise ValueError("the master does not land inside the video frame")
factor = max(1, forge_core.round_half_up((box[3] - box[1]) / QC_SUBJECT_PX))
edge_px = int(gates["edge"]["px"])
reference = qc_frame(placed, None, factor, edge_px)
try:
master = colour_lock.master_colours(placed)
except colour_lock.ColourLockError:
master = None
frames = []
for index, path in enumerate(clean):
rgba = np.asarray(Image.open(path).convert("RGBA"))
if (rgba.shape[1], rgba.shape[0]) != size:
raise ValueError(f"{path.name} is {rgba.shape[1]}x{rgba.shape[0]}; the take is {size[0]}x{size[1]}")
rgb = np.asarray(Image.open(raw[index]).convert("RGB")) if raw else None
frames.append(qc_frame(rgba, rgb, factor, edge_px, colour=master is not None))
result = evaluate_take(frames, reference, key=key, gates=gates, fps=fps, facing=facing, kind=kind,
airborne=airborne, returns_to_rest=returns_to_rest, hit_tick=hit_tick, master=master,
timing_mode=timing_mode)
result["reduction"] = factor
result["videoSize"] = list(size)
result["fitApplied"] = fit.applied
return result
# --------------------------------------------------------------------------- plan
def default_gates(action: str, preset: ActionPreset, klass: str, view: str) -> dict:
"""BASE_GATES tuned per action: runs bob in flight (the feet gate takes the half-second rolling median),
jumps leave the ground, hovering classes have no feet, front and back views cannot show a mirrored head,
loops and held endings skip the end pose, one-shots get their own time limits."""
gates = json.loads(json.dumps(BASE_GATES))
gates["motion"]["min"] = preset.min_motion
if action == "run":
gates["feet"]["max"] = 0.10
gates["feet"]["mode"] = "median"
if action in ("jump", "victory", "defeat", "cast", "guard"):
gates["timing"] = {"maxSeconds": 2.5, "maxHoldSeconds": 1.2 if action in ("cast", "guard") else 0.5}
if preset.airborne:
gates["feet"]["mode"] = "start-end"
if klass in HOVER_CLASSES:
gates["feet"]["max"] = max(gates["feet"]["max"], 0.08)
if view in ("front", "back"):
gates["turn"]["enabled"] = False
if preset.kind == "loop" or not preset.returns_to_rest:
gates["endPose"]["enabled"] = False
return gates
def oneshot_timing(entry: dict) -> dict:
"""The one-shot timing of a plan entry: its own "timing", else the action's default (ONESHOT_TIMING), else
the clip's own speed. Loops have none."""
if entry.get("kind") != "oneshot":
return {"mode": "loop"}
timing = entry.get("timing")
if isinstance(timing, dict) and timing.get("mode") in ("auto", "source"):
return timing
return json.loads(json.dumps(ONESHOT_TIMING.get(entry.get("action"), {"mode": "source"})))
def parse_oneshot_ms(text: str | None) -> dict[str, int]:
"""--oneshot-ms attack=600,jump=800 -> {"attack": 600, "jump": 800}."""
result: dict[str, int] = {}
for item in str(text or "").split(","):
if not item.strip():
continue
name, sep, value = item.partition("=")
name = name.strip().lower()
try:
millis = int(value)
except ValueError:
millis = 0
if not sep or name not in ACTION_PRESETS or ACTION_PRESETS[name].kind != "oneshot" or not 100 <= millis <= 10000:
raise ValueError(f"--oneshot-ms takes ACTION=MS for one-shot actions (100-10000 ms); got {item.strip()!r}")
result[name] = millis
return result
def _parse_list(text: str, allowed: Sequence[str], name: str) -> list[str]:
items = [item.strip().lower() for item in str(text).split(",") if item.strip()]
unknown = [item for item in items if item not in allowed]
if not items or unknown:
raise ValueError(f"{name} takes a comma list of {', '.join(allowed)}; got {text!r}")
return list(dict.fromkeys(items))
def _parse_view_masters(values: Sequence[str]) -> dict[str, Path]:
found = {}
for value in values or []:
view, sep, path = str(value).partition("=")
view = view.strip().lower()
if not sep or view not in VIEWS or not path.strip():
raise ValueError(f"--view-master needs VIEW=master.json with VIEW one of {', '.join(VIEWS)}; got {value!r}")
found[view] = Path(path.strip())
return found
def _master_record(master: Master, stage: Path, view: str) -> dict:
folder = stage / "master" / view
folder.mkdir(parents=True)
json_copy, png_copy = folder / "master.json", folder / master.png_path.name
shutil.copyfile(master.json_path, json_copy)
shutil.copyfile(master.png_path, png_copy)
return {"json": forge_core.file_ref(json_copy, stage), "png": forge_core.file_ref(png_copy, stage),
"sourceName": master.json_path.name, "name": master.name, "identityRecap": master.identity_recap,
"facing": master.facing, "finish": master.finish, "class": master.klass, "key": master.key,
"size": list(master.size), "subjectBox": list(master.box), "anchor": list(master.anchor),
"area": master.area, "framing": _scrub(master.framing)}
def cmd_plan(args: argparse.Namespace) -> dict:
"""Write a new set folder: master copies, set_plan.json (and nothing else; run does the work)."""
master = load_master(Path(args.master))
library = load_library(Path(args.library) if args.library else LIBRARY_FILE)
actions = _parse_list(args.actions, tuple(ACTION_PRESETS), "--actions")
views = _parse_list(args.views, VIEWS, "--views")
extra_masters = _parse_view_masters(args.view_master)
masters: dict[str, Master] = {}
for view in views:
if view in extra_masters:
masters[view] = load_master(extra_masters[view])
elif view == "side" or ("side" not in views and view == views[0]):
masters[view] = master # --master is the side still, or the first view's when side is not planned
else:
raise ValueError(f"the {view} view needs its own approved still: --view-master {view}=<master.json>")
if masters[view].key != master.key:
raise ValueError(f"every view must share one key colour; {view} uses {masters[view].key}, the master "
f"{master.key}")
finish = args.finish or master.finish
target = args.target_height or forge_core.round_half_up(TARGET_HEIGHT[finish] * CLASS_HEIGHT.get(master.klass, 1.0))
if target < 8:
raise ValueError("--target-height must be at least 8 px")
if args.frame_ms is not None and args.fps is not None:
raise ValueError("give --fps or --frame-ms, not both")
if args.frame_ms is not None:
try:
fps = Fraction(1000) / Fraction(str(args.frame_ms))
except (ValueError, ZeroDivisionError):
raise ValueError(f"--frame-ms must be a positive number of ms, got {args.frame_ms!r}") from None
elif args.fps is not None:
fps = _fps_fraction(args.fps)
else:
fps = Fraction(12) if finish in PALETTED else None
if fps is not None and not 1 <= fps <= 60:
raise ValueError("--fps must be 1-60 frames per second (--frame-ms 17-1000), or leave it out to keep the "
"clip's own rate")
if finish not in PALETTED and (args.colors is not None or args.outline is not None):
raise ValueError("--colors and --outline belong to the pixel finish or the hibit finish")
if args.colors is not None and args.palette:
raise ValueError("--colors learns a palette; drop it when --palette is given")
if args.colors is not None and not 2 <= args.colors <= (254 if finish == "hibit" else 255):
raise ValueError("--colors must be 2..255 (hibit: 2..254, the outline colour is one more)")
outline = args.outline
if outline is not None:
outline = outline.strip()
if finish == "pixel" and outline not in ("selective", "dark", "none"):
raise ValueError(f"pixel --outline must be selective, dark or none, got {outline!r}")
if finish == "hibit" and outline not in HIBIT_OUTLINES and not re.fullmatch(r"#?[0-9a-fA-F]{6}", outline):
raise ValueError(f"hibit --outline must be auto, selective, dark, none or #RRGGBB, got {outline!r}")
if finish == "hibit" and re.fullmatch(r"#?[0-9a-fA-F]{6}", outline):
outline = "#" + outline.lstrip("#").lower()
canvas = None
if args.canvas:
match = re.fullmatch(r"\s*(\d+)\s*[xX]\s*(\d+)\s*", args.canvas)
if not match or min(int(match.group(1)), int(match.group(2))) < 4:
raise ValueError(f"--canvas must be WIDTHxHEIGHT such as 48x64, got {args.canvas!r}")
canvas = [int(match.group(1)), int(match.group(2))]
canvas_anchor = None
if args.canvas_anchor:
match = re.fullmatch(r"\s*(\d+)\s*,\s*(\d+)\s*", args.canvas_anchor)
if not match or canvas is None:
raise ValueError("--canvas-anchor needs X,Y and a --canvas")
canvas_anchor = [int(match.group(1)), int(match.group(2))]
oneshot_ms = parse_oneshot_ms(args.oneshot_ms)
if not float(args.duration).is_integer():
raise ValueError("--duration must be whole seconds (route_media.py video takes an integer --duration)")
formats = _parse_list(args.formats, ("png", "webm", "packed"), "--formats")
if "png" not in formats:
formats.insert(0, "png")
style = args.style or master.style or FINISH_STYLE[finish]
entries_spec = [(view, action) for view in views for action in actions]
ref_action = "idle" if "idle" in actions else actions[0]
ref_view = "side" if "side" in views else views[0]
ref_id = ref_action if ref_view == "side" else f"{ref_view}-{ref_action}"
output = Path(args.output_dir)
with forge_core.staged_output(output) as stage:
records = {view: _master_record(item, stage, view) for view, item in masters.items()}
palette = None
if args.palette:
source = Path(args.palette)
if not source.is_file():
raise ValueError(f"--palette {source.name} does not exist")
target_path = stage / "master" / ("palette" + source.suffix.lower())
shutil.copyfile(source, target_path)
palette = forge_core.file_ref(target_path, stage)
matte_profile = None
if args.matte_profile: # one keying for every clip of the character (video2dsprite.py --matte-profile)
source = Path(args.matte_profile)
if not source.is_file():
raise ValueError(f"--matte-profile {source.name} does not exist")
target_path = stage / "master" / "matte-profile.json"
shutil.copyfile(source, target_path)
matte_profile = forge_core.file_ref(target_path, stage)
plan: dict[str, Any] = {
"schema": PLAN_SCHEMA,
"tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
"createdAt": _now(),
"name": master.name,
"class": master.klass,
"key": master.key,
"keyRgb": list(master.key_rgb),
"style": style,
"pronoun": args.pronoun,
"views": views,
"masters": records,
"generation": {"duration": args.duration, "resolution": args.resolution, "maxTakes": args.max_takes,
"jobs": args.jobs, "pinLastFrame": args.pin_last, "timeoutSeconds": args.gen_timeout},
# hibit: no colour lock (its one character palette, learned from the source pixels, pins the colours)
"finish": {"mode": finish, "targetHeight": int(target), "scaleRefAction": ref_id, "palette": palette,
"colors": args.colors, "outline": outline, "canvas": canvas, "canvasAnchor": canvas_anchor,
"colourLock": not args.no_colour_lock and finish != "hibit"},
"matteProfile": matte_profile,
"package": {"formats": formats, "tiers": args.tiers,
"fps": None if fps is None else (int(fps) if fps.denominator == 1 else float(fps)),
"frameMs": args.frame_ms},
"library": {"name": LIBRARY_FILE.name if not args.library else Path(args.library).name,
"sha256": library.sha256},
"clauses": library.clauses,
"gatefix": library.gatefix,
"actions": [],
}
for view, action in entries_spec:
preset = ACTION_PRESETS[action]
item = masters[view]
hover = item.klass in HOVER_CLASSES
pin = {"auto": preset.pin_last, "on": preset.returns_to_rest, "off": False}[args.pin_last]
entry = {
"id": action if view == "side" else f"{view}-{action}",
"action": action, "view": view, "kind": preset.kind,
"loopKind": ("hover" if hover and preset.loop_kind == "idle" else preset.loop_kind),
"gaitState": preset.gait_state, "prepareAction": preset.prepare_action,
"retimeKind": preset.retime_kind, "placement": placement(item, preset.canvas),
"pinLastFrame": bool(pin), "lock": "none" if hover else preset.lock, "airborne": preset.airborne,
"hitTick": preset.hit_tick, "returnsToRest": preset.returns_to_rest,
"motion": library.templates.get(f"{action}-hover", library.templates[action]) if hover
else library.templates[action],
"negatives": library.negatives.get(action, ""),
"gates": default_gates(action, preset, item.klass, view),
}
if preset.kind == "oneshot":
timing = ({"mode": "source"} if args.oneshot_timing == "source"
else json.loads(json.dumps(ONESHOT_TIMING.get(action, {"mode": "source"}))))
if timing.get("mode") == "auto" and action in oneshot_ms:
timing["durationMs"] = oneshot_ms[action]
entry["timing"] = timing
entry["prompt"] = build_prompt(entry, plan, [])
entry["lint"] = lint_findings(entry["prompt"], master.key)
plan["actions"].append(entry)
plan["estimate"] = {"clips": len(plan["actions"]), "maxClips": len(plan["actions"]) * args.max_takes,
"maxVideoSeconds": len(plan["actions"]) * args.max_takes * args.duration,
"note": "route_media.py prints and ledgers the real price of every clip"}
forge_core.write_json(stage / PLAN_FILE, _scrub(plan))
final = output.parent.resolve() / output.name
return {"output": str(final), "metadata": str(final / PLAN_FILE), "plan": str(final / PLAN_FILE),
"name": master.name, "finish": finish, "targetHeight": int(target),
"actions": [entry["id"] for entry in plan["actions"]],
"canvases": {entry["id"]: entry["placement"]["canvas"] for entry in plan["actions"]},
"pinned": [entry["id"] for entry in plan["actions"] if entry["pinLastFrame"]],
"maxClips": plan["estimate"]["maxClips"],
"lintWarnings": sum(len(entry["lint"]) for entry in plan["actions"])}
# --------------------------------------------------------------------------- finishing (seam)
def resolve_finisher() -> tuple[Path | None, str]:
"""finish_frames.py beside this script, or the private stand-in while it is not installed.
FORGE_FINISH_FRAMES=standin forces the stand-in; any other value names a finisher script."""
value = os.environ.get(FINISH_ENV, "").strip()
if value.lower() == "standin":
return None, "sprite_set stand-in"
if value:
path = Path(value)
if not path.is_file():
raise ValueError(f"{FINISH_ENV} names {path.name}, which does not exist")
return path, path.name
if FINISH_SCRIPT.is_file():
return FINISH_SCRIPT, FINISH_SCRIPT.name
return None, "sprite_set stand-in (finish_frames.py is not installed)"
def _palette_image(colours: np.ndarray) -> Image.Image:
"""A P-mode palette image for Image.quantize(palette=...); unused slots repeat the first colour."""
colours = np.asarray(colours, np.uint8).reshape(-1, 3)[:256]
flat = np.concatenate([colours, np.repeat(colours[:1], 256 - len(colours), axis=0)]).reshape(-1)
image = Image.new("P", (1, 1))
image.putpalette([int(value) for value in flat])
return image
def _load_palette(path: Path) -> np.ndarray:
if path.suffix.lower() == ".json":
data = forge_core.read_json(path)
values = data.get("colors") or data.get("colours") or data.get("palette") if isinstance(data, dict) else data
colours = [[int(str(value).lstrip("#")[i:i + 2], 16) for i in (0, 2, 4)] for value in values or []]
else:
rgba = np.asarray(forge_core.load_rgba(path)[0])
colours = np.unique(rgba[rgba[..., 3] > 0][:, :3], axis=0).tolist()
if not 1 <= len(colours) <= 256:
raise ValueError(f"palette {path.name} needs 1-256 colours; it has {len(colours)}")
return np.asarray(colours, np.uint8)
def standin_finish(mode: str, frames_dir: Path, out: Path, target_height: int, scale_ref: Path | None,
palette: Path | None, colours: int = 32) -> dict:
"""Private stand-in for finish_frames.py (same arguments, same one-line summary).
The rest pose is frame 0: scale = target height / its body height, or the scale reference's scale times
sqrt(rest-area ratio) clamped to +-3% (game-opus55 scale_ref). The output grid is pinned to the rest
stance anchor on the feet line and every frame is resampled with the premultiplied box filter; hd keeps
full colour and clean alpha, pixel binarises alpha at 0.5 and maps every frame to one palette (median
cut over all frames, or --palette) without dither."""
files = _pngs(frames_dir)
if not files:
raise ValueError(f"no PNG frames in {frames_dir.name}")
first = np.asarray(forge_core.load_rgba(files[0])[0])
rest = _mask_stats(first[..., 3] > 127)
if rest is None:
raise ValueError("the rest frame (frame 0) is empty")
band = max(2, forge_core.round_half_up(0.04 * rest["height"]))
fx, fy = forge_core.anchor_from_mask(first[..., 3] > 127, "stance", band_rows=band, min_run=2)
reference = None
if scale_ref is not None:
reference = forge_core.read_json(scale_ref)
if not isinstance(reference, dict) or reference.get("schema") != STANDIN_SCHEMA:
raise ValueError(f"--scale-ref {Path(scale_ref).name} is not a {STANDIN_SCHEMA} record")
correction = float(np.clip(math.sqrt(float(reference["restArea"]) / max(1, rest["area"])), 0.97, 1.03))
scale = float(reference["scale"]) * correction
else:
scale = target_height / rest["height"]
boxes = []
for path in files:
with Image.open(path) as image:
bbox = image.convert("RGBA").getchannel("A").getbbox()
if bbox:
boxes.append(bbox)
x0, y0 = min(box[0] for box in boxes), min(box[1] for box in boxes)
x1, y1 = max(box[2] for box in boxes), max(box[3] for box in boxes)
ax, ay = math.ceil((fx - x0) * scale) + 1, math.ceil((fy - y0) * scale) + 1
width = ax + max(0, math.ceil((x1 - fx) * scale)) + 1
height = ay + max(0, math.ceil((y1 - fy) * scale)) + 1
finished = []
for path in files:
pixels = np.asarray(forge_core.load_rgba(path)[0])
small = np.asarray(forge_core.resample_rgba(pixels, scale, "box", anchor_src=(fx, fy), anchor_dst=(ax, ay),
out_size=(width, height)))
if mode == "hd":
small = np.asarray(forge_core.alpha_hygiene(small, mode="floor", floor=4)[0])
else:
small = small.copy()
small[..., 3] = np.where(small[..., 3] >= 128, 255, 0).astype(np.uint8)
small[small[..., 3] == 0] = 0
finished.append(small)
palette_record = None
if mode in PALETTED:
if palette is not None:
table = _load_palette(palette)
source = {"file": Path(palette).name, "sha256": forge_core.sha256_file(palette)}
else:
opaque = np.concatenate([frame[frame[..., 3] == 255][:, :3] for frame in finished])
if opaque.size == 0:
raise ValueError("pixel finish: no opaque pixels to build a palette from")
step = max(1, len(opaque) // 200000)
strip = Image.fromarray(np.ascontiguousarray(opaque[::step]).reshape(1, -1, 3), "RGB")
quantised = strip.quantize(colors=colours, method=Image.Quantize.MEDIANCUT, dither=Image.Dither.NONE)
used = sorted(set(np.asarray(quantised).reshape(-1).tolist()))
table = np.asarray(quantised.getpalette()[:768], np.uint8).reshape(-1, 3)[used]
source = {"method": "median cut over every frame", "colours": colours}
lookup = _palette_image(table)
for frame in finished:
rgb = Image.fromarray(np.ascontiguousarray(frame[..., :3]), "RGB")
mapped = np.asarray(rgb.quantize(palette=lookup, dither=Image.Dither.NONE).convert("RGB"))
frame[..., :3] = np.where(frame[..., 3:] > 0, mapped, 0)
palette_record = {**source, "size": int(len(table)), "colors": ["#%02x%02x%02x" % tuple(int(v) for v in c)
for c in table]}
with forge_core.staged_output(out) as stage:
(stage / "frames").mkdir()
for index, frame in enumerate(finished):
forge_core.save_png(frame, stage / "frames" / f"frame_{index:06d}.png")
record = {"schema": STANDIN_SCHEMA, "tool": {"name": TOOL_NAME, "version": TOOL_VERSION,
"note": "stand-in until finish_frames.py is installed"},
"mode": mode, "targetHeight": int(target_height), "scale": scale,
"restHeight": rest["height"], "restArea": rest["area"], "sourceAnchor": [fx, fy],
"anchor": [ax, ay], "size": [width, height], "frames": len(finished),
"resampler": "box (premultiplied area)", "alpha": "floor 4" if mode == "hd" else "binary at 0.5",
"palette": palette_record,
"scaleRef": None if scale_ref is None else {"file": Path(scale_ref).name,
"sha256": forge_core.sha256_file(scale_ref)}}
forge_core.write_json(stage / "finish.json", record)
final = out.parent.resolve() / out.name
return {"output": str(final), "metadata": str(final / "finish.json"), "framesDir": str(final / "frames"),
"frames": len(finished), "mode": mode, "scale": scale, "anchor": [ax, ay], "size": [width, height]}
def rebind_selection(selection: Path, frames_dir: Path, expected: int, out: Path) -> dict:
"""Bind a forge-frame-selection made on the registered frames to the finished frames (one finished frame
per registered frame, same order): new sourceDirectory, sourceHashes and sourceFiles; indices, durations,
events and the loop policy are kept."""
document = forge_core.read_json(selection)
files = _pngs(frames_dir)
if len(files) != expected:
raise ValueError(f"the finisher wrote {len(files)} frames for {expected} registered frames; the set needs one "
"finished frame per registered frame")
start, end = int(document["start"]), int(document["endExclusive"])
with forge_core.staged_output(out) as stage:
rebound = dict(document)
rebound["sourceDirectory"] = forge_core.manifest_path(frames_dir, stage)
rebound["sourceHashes"] = [forge_core.sha256_file(files[i]) for i in range(start, end)]
rebound["sourceFiles"] = [files[i].name for i in range(start, end)]
rebound["reboundFrom"] = {"path": forge_core.manifest_path(selection, stage),
"sha256": forge_core.sha256_file(selection)}
rebound["method"] = f"{document.get('method', '')}; rebound 1:1 to the finished frames (sprite_set)".strip("; ")
forge_core.write_json(stage / "selection.json", rebound)
return {"selection": out / "selection.json", "frames": len(document.get("sourceIndices") or []),
"start": start, "endExclusive": end}
def _tick_grid(fps: Any) -> tuple[int, int]:
"""(tick Hz, ticks per frame): the 60 Hz forge grid when a frame is a whole number of 60 Hz ticks, else the
rate's own fraction (24 fps: 24 Hz x 1; 12.5 fps or 80 ms frames: 25 Hz x 2)."""
rate = _fps_fraction(fps)
per = Fraction(60) / rate
if per.denominator == 1:
return 60, int(per)
return int(rate.numerator), int(rate.denominator)
def _plan_fps(plan: dict) -> Fraction | None:
"""The package frame rate of a plan (an int, a float such as 12.5, or "25/2"), or None for the clip's own."""
value = (plan.get("package") or {}).get("fps")
return None if value in (None, 0) else _fps_fraction(value)
# --------------------------------------------------------------------------- the set runner
_CLIP_SUFFIXES = (".mp4", ".webm", ".mov", ".m4v")
_LAST_FRAME_WORDS = re.compile(r"last[-_ ]?frame|unrecognized arguments", re.I)
def verify_lags(package: Path) -> bool:
"""True when the package's verify-qa.json is bound to another animation.json than the one it holds."""
report = package / "verify-qa.json"
if not report.is_file():
return False
try:
bound = forge_core.read_json(report).get("manifestSha256")
except (OSError, ValueError, AttributeError):
return False
return bound != forge_core.sha256_file(package / "animation.json")
def _find_clip(media: Path) -> Path | None:
"""A clip already in the take's media folder (generated earlier, or dropped in by the user or host)."""
if not media.is_dir():
return None
clips = sorted((path for path in media.iterdir() if path.is_file() and path.suffix.lower() in _CLIP_SUFFIXES),
key=lambda path: (path.name != "clip.mp4", path.name))
return clips[0] if clips else None
class SetRunner:
"""set_plan.json + set_state.json: every verb after plan works through this."""
def __init__(self, plan_path: Path):
plan_path = Path(plan_path)
if plan_path.is_dir():
plan_path = plan_path / PLAN_FILE
if not plan_path.is_file():
raise ValueError(f"no {PLAN_FILE} at {plan_path.as_posix()}")
self.plan_path = plan_path.resolve()
self.root = self.plan_path.parent
try:
plan = forge_core.read_json(self.plan_path)
except ValueError as error:
raise ValueError(f"{PLAN_FILE} is not valid JSON: {error}") from None
if not isinstance(plan, dict) or plan.get("schema") != PLAN_SCHEMA:
raise ValueError(f"{self.plan_path.name} is not a {PLAN_SCHEMA} document")
self.plan = plan
self.entries = {entry["id"]: entry for entry in plan["actions"]}
self.plan_sha = forge_core.sha256_file(self.plan_path)
self.state_path = self.root / STATE_FILE
self.lock_path = self.root / LOCK_FILE
state = self._read_state() # under the set lock, like every read and write of set_state.json
if state is not None:
self.state = state
else:
self.state = {"schema": STATE_SCHEMA, "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
"plan": {"path": PLAN_FILE, "sha256": self.plan_sha}, "createdAt": _now(), "runs": 0,
"actions": {}, "review": None}
self.notes: list[str] = []
self.media_argv: list[str] | None = None
self.media_name = ""
self.progress: Any = _no_progress
# ----------------------------------------------------------------- bookkeeping
def rel(self, path: Path | str) -> str:
return forge_core.manifest_path(path, self.root)
def _read_state(self) -> dict | None:
"""set_state.json read under the set lock (re-entrant, so a caller may hold it already): a reader never
holds the file open while a writer replaces it (on Windows that replace would fail)."""
if not self.state_path.is_file():
return None
with forge_core.file_lock(self.lock_path):
state = forge_core.read_json(self.state_path)
if not isinstance(state, dict) or state.get("schema") != STATE_SCHEMA:
raise ValueError(f"{STATE_FILE} is not a {STATE_SCHEMA} document")
return state
def reload(self) -> None:
"""Read set_state.json again (it reads under the set lock; hold the lock yourself around a whole
read-modify-write)."""
state = self._read_state()
if state is not None:
self.state = state
def save(self) -> None:
"""Write set_state.json under the set lock, after merging the agent's decisions made on disk since this
copy was read (merge_disk), so a concurrent accept, retake or review is never overwritten."""
with forge_core.file_lock(self.lock_path):
self.merge_disk()
self.state["updatedAt"] = _now()
forge_core.write_json(self.state_path, _scrub(self.state), no_clobber=False)
def merge_disk(self) -> None:
"""Adopt what review, accept and retake wrote to set_state.json since this runner read it.
Those verbs are the agent's: they run under the lock and bump an action's agentRevision. When the
file's agentRevision of an action is ahead of this copy, the file's accepted, round, chosen, status and
message win, its fixes are added to ours and its per-take review verdicts are copied; the newer
review record wins too. Everything else (takes, stages, outputs) is this runner's own work and kept.
"""
try:
disk = self._read_state()
except ValueError:
return
if disk is None:
return
theirs_review, ours_review = disk.get("review"), self.state.get("review")
if isinstance(theirs_review, dict) and (not isinstance(ours_review, dict)
or str(theirs_review.get("at", "")) > str(ours_review.get("at", ""))):
self.state["review"] = theirs_review
for ident, theirs in (disk.get("actions") or {}).items():
if ident not in self.entries or not isinstance(theirs, dict):
continue
ours = self.state["actions"].get(ident)
if ours is None:
self.state["actions"][ident] = theirs
continue
if int(theirs.get("agentRevision", 0)) <= int(ours.get("agentRevision", 0)):
continue
ours["agentRevision"] = int(theirs.get("agentRevision", 0))
ours["accepted"] = theirs.get("accepted")
known = {(fix.get("id"), fix.get("text")) for fix in ours.get("fixes", [])}
ours["fixes"] = list(ours.get("fixes", [])) + [fix for fix in theirs.get("fixes", [])
if (fix.get("id"), fix.get("text")) not in known]
if int(theirs.get("round", 1)) != int(ours.get("round", 1)) or theirs.get("chosen") != ours.get("chosen"):
ours["round"] = int(theirs.get("round", 1))
ours["chosen"] = theirs.get("chosen")
ours["status"], ours["message"] = theirs.get("status"), theirs.get("message")
verdicts = {record.get("take"): record["review"] for record in theirs.get("takes", [])
if isinstance(record, dict) and "review" in record}
for record in ours.get("takes", []):
if record.get("take") in verdicts:
record["review"] = verdicts[record["take"]]
self.notes.append(f"{ident}: took the agent's accept or retake made during this run")
def astate(self, ident: str) -> dict:
if ident not in self.entries:
raise ValueError(f"no action {ident!r} in {PLAN_FILE}; it plans {', '.join(self.entries)}")
return self.state["actions"].setdefault(ident, {"status": "pending", "round": 1, "fixes": [], "job": None,
"takes": [], "chosen": None, "accepted": None,
"output": None, "message": None})
def take(self, ident: str, number: int) -> dict:
for record in self.astate(ident)["takes"]:
if record["take"] == number:
return record
raise ValueError(f"{ident} has no take {number}")
def order(self, only: Sequence[str] | None = None) -> list[str]:
ids = [entry["id"] for entry in self.plan["actions"]]
ref = self.plan["finish"].get("scaleRefAction")
if ref in ids:
ids.remove(ref)
ids.insert(0, ref)
if only:
unknown = [ident for ident in only if ident not in ids]
if unknown:
raise ValueError(f"--actions names {unknown}, not planned (planned: {', '.join(ids)})")
ids = [ident for ident in ids if ident in only]
return ids
def master(self, ident: str) -> dict:
return self.plan["masters"][self.entries[ident]["view"]]
def take_dir(self, ident: str, number: int) -> Path:
return self.root / "actions" / ident / "takes" / f"t{number:02d}"
def log_take(self, ident: str, record: dict) -> None:
"""Append the take's verdict to takes.jsonl once (an audit log; the state is the truth)."""
if record.get("logged"):
return
qc = record.get("qc") or {}
line = {"schema": TAKE_SCHEMA, "at": _now(), "action": ident, "take": record["take"],
"round": record["round"], "status": record["status"], "failures": record.get("failures", []),
"reasons": record.get("reasons", []), "badFrames": qc.get("badFrames", {}),
"usableWindow": qc.get("usableWindow"), "fixesUsed": record.get("fixes", []),
"fixNext": record.get("fixNext", []), "route": record.get("route"),
"prompt": record.get("prompt"), "clip": record.get("clip"), "message": record.get("message")}
with open(self.root / TAKES_FILE, "a", encoding="utf-8", newline="\n") as stream:
stream.write(json.dumps(_scrub(line), ensure_ascii=False, allow_nan=False) + "\n")
record["logged"] = True
def stage(self, record: dict, name: str, make: Callable[[Path], dict]) -> dict:
"""Run one tool step into <take>/<name> unless the state already records it (resume). A folder the
state does not know (a crash between publish and save) is kept aside as <name>.orphan-N."""
stages = record.setdefault("stages", {})
out = self.root / record["dir"] / name
done = stages.get(name)
if done and out.exists():
return done
if os.path.lexists(out):
self.notes.append(f"kept an unrecorded {self.rel(out)} aside as {_move_aside(out).name}")
started = time.perf_counter()
result = make(out)
result["dir"] = self.rel(out)
result["seconds"] = round(time.perf_counter() - started, 2)
stages[name] = _scrub(result)
self.save()
return stages[name]
def check_masters(self) -> None:
for view, record in self.plan["masters"].items():
for role in ("json", "png"):
path = self.root / record[role]["path"]
if not path.is_file() or forge_core.sha256_file(path) != record[role]["sha256"]:
raise ValueError(f"the {view} master {record[role]['path']} is missing or changed since the plan; "
"plan a new set for a new master")
# ----------------------------------------------------------------- jobs and prompts
def ensure_job(self, ident: str) -> dict:
st = self.astate(ident)
out = self.root / "actions" / ident / "job"
if st.get("job") and (out / "registration_job.json").is_file():
return st["job"]
if os.path.lexists(out):
self.notes.append(f"kept an unrecorded {self.rel(out)} aside as {_move_aside(out).name}")
entry, master = self.entries[ident], self.master(ident)
place = entry["placement"]
out.parent.mkdir(parents=True, exist_ok=True)
prompt_file = out.parent / f".prompt-{os.getpid()}.txt"
prompt_file.write_bytes(build_prompt(entry, self.plan, []).encode("utf-8"))
args = ["prepare", "--master", self.root / master["png"]["path"], "--action", entry["prepareAction"],
"--output-dir", out, "--canvas", "{},{}".format(*place["canvas"]),
"--root", "{!r},{!r}".format(*place["root"]), "--scale", repr(place["scale"]),
"--anchor", "{!r},{!r}".format(*place["anchor"]), "--key", self.plan["key"],
"--master-key", self.plan["key"], "--allow-key-conflict", "--margin", place["margin"],
"--action-padding", ",".join(str(v) for v in place["padding"]),
"--duration", self.plan["generation"]["duration"], "--facing", master["facing"],
"--subject", master["name"], "--prompt-file", prompt_file]
try:
summary, warnings = run_tool(SCRIPTS["prepare_i2v_input"], args)
finally:
prompt_file.unlink(missing_ok=True)
job = out / "registration_job.json"
st["job"] = {"dir": self.rel(out), "job": self.rel(job), "sha256": forge_core.sha256_file(job),
"input": self.rel(out / "input.png"), "referenceScale": summary.get("referenceScale"),
"keyColor": summary.get("keyColor"), "padding": summary.get("padding"),
"warnings": len(warnings)}
self.save()
return st["job"]
def open_take(self, ident: str) -> dict:
"""The take to work on: the unfinished one of this round, or a new take with the prompt and every fix."""
st = self.astate(ident)
last = st["takes"][-1] if st["takes"] else None
if last and last["round"] == st["round"] and last["status"] in ("open", "generated", "no-route"):
return last
number = len(st["takes"]) + 1
folder = self.take_dir(ident, number)
folder.mkdir(parents=True, exist_ok=True)
prompt = build_prompt(self.entries[ident], self.plan, [fix["text"] for fix in st["fixes"]])
payload = prompt.encode("utf-8")
path = folder / "prompt.txt"
if path.exists() and path.read_bytes() != payload:
_move_aside(path)
if not path.exists():
with open(path, "xb") as stream:
stream.write(payload)
record = {"take": number, "round": st["round"], "dir": self.rel(folder), "status": "open", "createdAt": _now(),
"prompt": {"path": self.rel(path), "sha256": forge_core.sha256_bytes(payload)},
"fixes": [fix["id"] for fix in st["fixes"]], "lint": lint_findings(prompt, self.plan["key"]),
"stages": {}}
st["takes"].append(record)
st["status"] = "generating"
self.save()
return record
# ----------------------------------------------------------------- generation
def resolve_media(self, override: str | None) -> None:
if override:
path = Path(override)
if not path.is_file():
raise ValueError(f"--media-cli {path.name} does not exist")
self.media_argv, self.media_name = [sys.executable, str(path.resolve())], path.name
return
fake = os.environ.get(MEDIA_FAKE_ENV, "").strip()
if fake and Path(fake).is_file():
self.media_argv, self.media_name = [sys.executable, str(Path(fake).resolve())], f"{MEDIA_FAKE_ENV}"
return
if ROUTE_MEDIA.is_file():
self.media_argv, self.media_name = [sys.executable, str(ROUTE_MEDIA)], "generate2dmedia/route_media.py"
return
self.media_argv, self.media_name = None, "generate2dmedia/route_media.py (not installed)"
def _call_media(self, args: Sequence[Any], timeout: float) -> dict:
argv = [*self.media_argv, *(str(arg) for arg in args)]
try:
done = subprocess.run(argv, capture_output=True, timeout=timeout, env=_child_env(), check=False)
except subprocess.TimeoutExpired:
return {"code": -1, "summary": None, "message": f"timed out after {timeout:g} s"}
stderr = done.stderr.decode("utf-8", "replace")
return {"code": done.returncode, "summary": _json_line(done.stdout.decode("utf-8", "replace")),
"message": _error_line(stderr) if done.returncode else ""}
def generate(self, ident: str, record: dict, timeout: float) -> dict:
"""One clip through the media CLI (a worker thread: no state changes here)."""
folder = self.root / record["dir"]
media = folder / "media"
clip = _find_clip(media)
if clip is not None:
return {"status": "ok", "route": record.get("route") or "supplied", "artifact": clip, "adopted": True,
"pinned": None}
if self.media_argv is None:
return {"status": "no-route", "message": f"{self.media_name}: no media CLI to generate with"}
if os.path.lexists(media):
_move_aside(media)
job = self.root / self.astate(ident)["job"]["dir"]
generation = self.plan["generation"]
base = ["video", "--prompt-file", folder / "prompt.txt", "--reference", job / "input.png",
"--duration", _duration_arg(generation["duration"]), "--resolution", generation["resolution"],
"--out-dir", media]
pin = bool(self.entries[ident]["pinLastFrame"])
result = self._call_media(base + (["--last-frame", job / "input.png"] if pin else []), timeout)
pin_note = None
if pin and result["code"] not in (0, EXIT_NO_ROUTE) and _LAST_FRAME_WORDS.search(result["message"] or ""):
if os.path.lexists(media):
_move_aside(media)
result = self._call_media(base, timeout)
pin, pin_note = False, "the route takes no last frame; generated without it"
if result["code"] == EXIT_NO_ROUTE:
return {"status": "no-route", "message": result["message"] or "no generation route (exit 3)"}
summary = result["summary"] or {}
if result["code"] != 0 or summary.get("status", "ok") != "ok":
return {"status": "error", "message": result["message"] or f"media CLI status {summary.get('status')!r}"}
named = Path(str(summary.get("artifact") or ""))
candidates = [named] if named.is_absolute() else [media / named, Path.cwd() / named]
artifact = next((path for path in candidates if str(named) not in ("", ".") and path.is_file()), None)
artifact = artifact or _find_clip(media)
if artifact is None:
return {"status": "error", "message": f"the media CLI reported {named.name or 'no artifact'}, which does "
"not exist"}
if media.resolve() not in artifact.resolve().parents: # keep the set self-contained
media.mkdir(parents=True, exist_ok=True)
copy = media / artifact.name
if not copy.exists():
shutil.copyfile(artifact, copy)
artifact = copy
flags = [summary.get(key) for key in ("lastFrame", "last_frame", "lastFrameUsed", "pinned")]
if pin and any(flag is False or (isinstance(flag, str) and flag.lower() in ("unsupported", "ignored", "no"))
for flag in flags):
pin, pin_note = False, "the route ignored the last frame"
return {"status": "ok", "route": summary.get("route"), "artifact": artifact, "summary": summary,
"pinned": pin, "pinNote": pin_note}
def record_generation(self, ident: str, record: dict, result: dict) -> str:
st = self.astate(ident)
folder = self.root / record["dir"]
if result["status"] == "ok":
clip = Path(result["artifact"])
record["clip"] = {"path": self.rel(clip), "sha256": forge_core.sha256_file(clip)}
record["route"] = _scrub(result.get("route")) or "unknown"
record["pinnedLastFrame"] = result.get("pinned")
if result.get("pinNote"):
record["pinNote"] = result["pinNote"]
route_file = folder / "route.json"
if not route_file.exists():
_write_new_json(route_file, _scrub({
"schema": "video2dsprite.sprite_set_route.v1", "action": ident, "take": record["take"],
"cli": self.media_name if not result.get("adopted") else "adopted clip",
"route": result.get("route"), "clip": record["clip"], "pinnedLastFrame": result.get("pinned"),
"pinNote": result.get("pinNote"), "summary": result.get("summary")}))
record["status"], record["message"] = "generated", None
self.save()
return "ok"
record["message"] = result["message"]
if result["status"] == "no-route":
record["status"] = "no-route"
st["status"] = "no-route"
st["message"] = (f"no generation route ({result['message']}); generate the clip with the host tool from "
f"{self.rel(self.root / st['job']['dir'] / 'input.png')} and "
f"{self.rel(folder / 'prompt.txt')}, save it as "
f"{self.rel(folder / 'media' / 'clip.mp4')} and run again")
self.save()
return "no-route"
record["status"] = "error"
st["status"] = "error"
st["message"] = f"take {record['take']}: {result['message']} (the next run tries again)"
self.log_take(ident, record)
self.save()
return "error"
# ----------------------------------------------------------------- per-take tools
def run_key(self, ident: str, record: dict, out: Path) -> dict:
job = self.root / self.astate(ident)["job"]["dir"]
args = ["process", "--video", self.root / record["clip"]["path"], "--output-dir", out, "--matte", "soft",
"--reference", job / "master.png", "--key", self.plan["key"], "--frame-counts", "8",
"--name", f"{ident}-t{record['take']:02d}"]
if self.plan.get("matteProfile"):
args += ["--matte-profile", self.root / self.plan["matteProfile"]["path"]]
summary, warnings = run_tool(SCRIPTS["video2dsprite"], args, label="video2dsprite.py process")
probe = (forge_core.read_json(out / "pipeline-meta.json").get("probe") or {})
return {"frames": summary.get("frames"), "fps": probe.get("fps_rational") or "24/1",
"size": [probe.get("width"), probe.get("height")], "matte": summary.get("matte"),
"warnings": warnings[:6]}
def run_qc(self, ident: str, record: dict) -> dict:
path = self.root / record["dir"] / "qc.json"
if record.get("qc") and path.is_file():
return record["qc"]
if os.path.lexists(path):
_move_aside(path)
entry, st = self.entries[ident], self.astate(ident)
keyed = self.root / record["stages"]["keyed"]["dir"]
document = qc_take(self.root / st["job"]["job"], keyed / "frames-clean", keyed / "frames-raw",
key=self.plan["key"], gates=entry["gates"], fps=_fps_value(record["stages"]["keyed"]["fps"]),
facing=self.master(ident)["facing"], kind=entry["kind"], airborne=entry["airborne"],
returns_to_rest=entry["returnsToRest"], hit_tick=entry["hitTick"],
timing_mode=oneshot_timing(entry).get("mode"))
document.update({"action": ident, "take": record["take"], "clip": record.get("clip"),
"job": {"path": st["job"]["job"], "sha256": st["job"]["sha256"]}})
_write_new_json(path, _scrub(document))
record["qc"] = {"file": self.rel(path), "status": document["status"], "failures": document["failures"],
"reasons": document["reasons"], "warnings": document.get("warnings", []),
"usableWindow": document["usableWindow"],
"usableFrames": document["usableFrames"], "frames": document["frames"],
"motion": document["motion"], "badFrames": document["perFrame"]["bad"],
"gates": {name: {"status": gate["status"], "value": gate["value"]}
for name, gate in document["gates"].items()}}
self.save()
return record["qc"]
def run_register(self, ident: str, record: dict, out: Path, window: Sequence[int] | None) -> dict:
entry, st = self.entries[ident], self.astate(ident)
keyed = self.root / record["stages"]["keyed"]["dir"]
height = self.master(ident)["size"][1]
args = ["apply", "--job", self.root / st["job"]["job"], "--frames", keyed / "frames-clean",
"--output-dir", out, "--clip", ident, "--max-anchor-error", f"{max(2.0, 0.004 * height):.3g}",
"--max-scale-error", "0.04"]
if entry["lock"] == "feet":
args += ["--lock", "feet"]
if window:
args += ["--range", f"{window[0]}:{window[1]}"]
summary, warnings = run_tool(SCRIPTS["register_clip"], args, label="register_clip.py apply")
return {"frames": summary["frames"], "sourceSize": summary["sourceSize"],
"sourceAnchor": summary["sourceAnchor"], "fit": summary.get("fitApplied"),
"range": list(window) if window else None,
"registration": self.rel(out / "registration.json"), "warnings": warnings[:6]}
def run_motion(self, ident: str, record: dict, out: Path, tag: str, window: Sequence[int] | None) -> dict:
"""Loops: gait_loop select. One-shots: retime over the motion window with ticks, the hit on the largest
reach (attacks), a cancel tick, and takeoff/land for airborne actions."""
entry = self.entries[ident]
registered = record["stages"]["registered" + tag]
frames = self.root / registered["dir"] / "frames"
fps_text = record["stages"]["keyed"]["fps"]
if entry["kind"] == "loop":
args = ["select", "--frames-dir", frames, "--fps", fps_text, "--output-dir", out,
"--kind", entry["loopKind"]]
if entry["loopKind"] == "gait":
args += ["--state", entry["gaitState"]]
summary, _ = run_tool(SCRIPTS["gait_loop"], args, label="gait_loop.py select")
selection = forge_core.read_json(out / "selection.json")
return {"tool": "gait_loop select", "selection": self.rel(out / "selection.json"),
"policy": summary["policy"], "start": summary["start"], "endExclusive": summary["endExclusive"],
"frames": summary["frames"], "confidence": summary.get("confidence"),
"durationMs": int(sum(selection["durations_ms"])), "fps": selection.get("fps")}
motion = record["qc"]["motion"]
offset = window[0] if window else 0
count = int(registered["frames"])
timing = oneshot_timing(entry)
if timing.get("mode") == "auto":
try:
return self.run_auto_oneshot(ident, record, out, frames, fps_text, motion, offset, count, timing)
except ToolFailure as failure: # never lose the take to the retimer: fall back to the clip's timing
self.notes.append(_ascii(f"{ident}: auto one-shot timing failed ({failure.message[:160]}); "
"kept the clip's own timing"))
if os.path.lexists(out):
_move_aside(out)
onset = motion.get("onset") if motion.get("onset") is not None else offset
settle = motion.get("settle") if motion.get("settle") is not None else offset + count - 1
start = max(0, min(count - 1, onset - 2 - offset))
end = max(start + 1, min(count, settle + 4 - offset))
if end - start < 4:
start, end = max(0, start - 2), min(count, end + 2)
source = _fps_value(fps_text)
target = _plan_fps(self.plan)
frames_out = end - start
if target and target < source:
frames_out = max(4, min(end - start, forge_core.round_half_up((end - start) * float(target) / source)))
hz, per = _tick_grid(target)
else:
hz, per = max(1, forge_core.round_half_up(source)), 1
def tick(frame: int | None) -> int | None:
if frame is None or not start <= frame - offset < end:
return None
position = forge_core.round_half_up((frame - offset - start) * (frames_out - 1) / max(1, end - start - 1))
return position * per
args = ["--frames-dir", frames, "--fps", fps_text, "--output-dir", out, "--kind", entry["retimeKind"],
"--range", f"{start}:{end}", "--ticks", frames_out * per, "--tick-hz", hz, "--policy", "oneshot"]
if frames_out < end - start:
args += ["--max-frames", frames_out]
impact = motion.get("impact")
if entry["hitTick"] and impact is not None and start <= impact - offset < end:
args += ["--impact-source", impact - offset]
events = []
for name, frame in (("cancel", motion.get("cancel")), ("custom:takeoff", motion.get("takeoff")),
("custom:land", motion.get("land"))):
position = tick(frame)
if position is not None and 0 < position < frames_out * per:
events.append(f"{name}@{position}t")
for event in events:
args += ["--event", event]
summary, _ = run_tool(SCRIPTS["retime"], args, label="retime.py")
selection = forge_core.read_json(out / "selection.json")
return {"tool": "retime", "selection": self.rel(out / "selection.json"), "policy": "oneshot",
"start": start, "endExclusive": end, "frames": summary["frames"], "durationMs": summary["durationMs"],
"impactMs": summary.get("impactMs"), "tickHz": hz, "events": selection.get("events", [])}
def run_auto_oneshot(self, ident: str, record: dict, out: Path, frames: Path, fps_text: str, motion: dict,
offset: int, count: int, timing: dict) -> dict:
"""retime.py --auto-oneshot over the registered frames: the game length and keys from the plan's timing,
the key source frames from the take's QC landmarks (impact, peak, takeoff, land; cancel as an event)."""
entry = self.entries[ident]
source = _fps_fraction(fps_text)
target = _plan_fps(self.plan)
rate = target if target and target < source else source
keys = timing.get("keys") or {}
landmarks = {"hit": motion.get("impact"), "peak": motion.get("peakFrame"), "takeoff": motion.get("takeoff"),
"land": motion.get("land")}
args = ["--frames-dir", frames, "--fps", fps_text, "--output-dir", out, "--kind", entry["retimeKind"],
"--range", f"0:{count}", "--auto-oneshot", "--duration", int(timing.get("durationMs", 700)),
"--output-fps", f"{rate.numerator}/{rate.denominator}"]
used = []
for name, spec in sorted(keys.items(), key=lambda item: float((item[1] or {}).get("at", 0))):
frame = landmarks.get(name)
if frame is None or not 0 <= frame - offset < count:
continue
if name == "hit" and not entry["hitTick"]:
continue
hold = int((spec or {}).get("holdMs", 0))
args += ["--key", f"{name}={frame - offset}@{float(spec['at']):g}" + (f"+{hold}" if hold else "")]
used.append(name)
cancel = motion.get("cancel")
if entry["hitTick"] and cancel is not None and 0 <= cancel - offset < count:
args += ["--event-source", f"cancel={cancel - offset}"]
summary, _ = run_tool(SCRIPTS["retime"], args, label="retime.py --auto-oneshot")
selection = forge_core.read_json(out / "selection.json")
hz, _per = _tick_grid(rate)
return {"tool": "retime --auto-oneshot", "selection": self.rel(out / "selection.json"), "policy": "oneshot",
"start": 0, "endExclusive": count, "frames": summary["frames"], "durationMs": summary["durationMs"],
"impactMs": summary.get("impactMs"), "tickHz": hz, "events": selection.get("events", []),
"timing": {"durationMs": int(timing.get("durationMs", 700)), "keys": used,
"auto": summary.get("auto")}}
def run_timed(self, ident: str, record: dict, out: Path, tag: str) -> dict:
"""A loop resampled to the plan's fps on the tick grid (retime --range over the gait_loop window)."""
entry = self.entries[ident]
motion = record["stages"]["motion" + tag]
frames = self.root / record["stages"]["registered" + tag]["dir"] / "frames"
fps_text = record["stages"]["keyed"]["fps"]
start, end = motion["start"], motion["endExclusive"]
target = _plan_fps(self.plan)
frames_out = max(4, forge_core.round_half_up((end - start) * float(target) / _fps_value(fps_text)))
hz, per = _tick_grid(target)
policy = motion["policy"] if motion["policy"] in ("cycle", "pingpong") else "cycle"
args = ["--frames-dir", frames, "--fps", fps_text, "--output-dir", out, "--kind", entry["retimeKind"],
"--range", f"{start}:{end}", "--max-frames", frames_out, "--ticks", frames_out * per,
"--tick-hz", hz, "--policy", policy]
summary, _ = run_tool(SCRIPTS["retime"], args, label="retime.py")
return {"tool": "retime", "selection": self.rel(out / "selection.json"), "policy": policy, "start": start,
"endExclusive": end, "frames": summary["frames"], "durationMs": summary["durationMs"], "tickHz": hz}
def needs_timed(self, ident: str, record: dict, tag: str) -> bool:
target = _plan_fps(self.plan)
motion = record["stages"].get("motion" + tag) or {}
if self.entries[ident]["kind"] != "loop" or not target:
return False
source = _fps_value(record["stages"]["keyed"]["fps"])
length = motion.get("endExclusive", 0) - motion.get("start", 0)
return target < source and forge_core.round_half_up(length * float(target) / source) < length
def cut(self, ident: str, record: dict, tag: str, window: Sequence[int] | None) -> dict:
"""Registration and the loop or timeline of one take (or of its usable window)."""
self.stage(record, "registered" + tag, lambda out: self.run_register(ident, record, out, window))
motion = self.stage(record, "motion" + tag, lambda out: self.run_motion(ident, record, out, tag, window))
if self.needs_timed(ident, record, tag):
return self.stage(record, "timed" + tag, lambda out: self.run_timed(ident, record, out, tag))
return motion
# ----------------------------------------------------------------- evaluation and retakes
def classify(self, ident: str, step: str, failure: Exception) -> str:
"""The gate a failed tool step stands for: keying, edge, registration, loop or motion."""
text = str(getattr(failure, "message", failure))
if step in ("keyed", "qc"):
return "keying"
if step == "registered":
return "edge" if re.search(r"video-edge-touch|canvas-overflow", text) else "registration"
return "loop" if self.entries[ident]["kind"] == "loop" else "motion"
def evaluate(self, ident: str, record: dict, max_takes: int) -> None:
"""Key the take, run the gates, then register and cut it; a failure rejects the take, adds the mapped
fix clauses to the next prompt and, once the round is spent, keeps the best take's usable window."""
st = self.astate(ident)
step = "keyed"
try:
self.stage(record, "keyed", lambda out: self.run_key(ident, record, out))
step = "qc"
qc = self.run_qc(ident, record)
if qc["status"] == "pass":
step = "registered"
self.stage(record, "registered", lambda out: self.run_register(ident, record, out, None))
step = "motion"
self.stage(record, "motion", lambda out: self.run_motion(ident, record, out, "", None))
if self.needs_timed(ident, record, ""):
self.stage(record, "timed", lambda out: self.run_timed(ident, record, out, ""))
record.update(status="kept", failures=[], reasons=[])
if record["round"] == st["round"]:
st["chosen"] = {"take": record["take"], "reason": "first take that passed every gate",
"window": None, "tag": ""}
st["status"], st["message"] = "chosen", None
else: # a retake asked for a new round while this take was made: it is kept, never chosen
self.notes.append(f"{ident}: take {record['take']} passed, but a retake started round "
f"{st['round']} meanwhile; it was not chosen")
else:
record.update(status="rejected", failures=list(qc["failures"]), reasons=list(qc["reasons"]))
except (ToolFailure, ValueError) as failure:
gate = self.classify(ident, step, failure)
message = failure.message if isinstance(failure, ToolFailure) else str(failure)
label = failure.tool if isinstance(failure, ToolFailure) else step
record.update(status="rejected", failures=[gate], reasons=[_ascii(f"{gate}: {label}: {message}")[:600]])
if record["status"] == "rejected":
self.add_fixes(ident, record)
self.log_take(ident, record)
self.save()
if record["status"] == "rejected":
decided = [t for t in st["takes"] if t["round"] == st["round"] and t["status"] in ("kept", "rejected")]
if len(decided) >= max_takes:
self.choose_best(ident)
else:
st["status"] = "retake"
self.save()
def add_fixes(self, ident: str, record: dict) -> None:
st = self.astate(ident)
wanted = []
for gate in record.get("failures", []):
wanted += self.plan["gatefix"].get(gate, [])
if moves_feet(self.entries[ident]): # a walk, run or jump never gets "feet stay planted"
wanted = [MOVING_FEET_CLAUSE if clause in PLANTED_CLAUSES else clause for clause in wanted]
present = {fix["id"] for fix in st["fixes"]}
added = []
for clause in dict.fromkeys(wanted):
text = self.plan["clauses"].get(clause)
if text is None and clause == MOVING_FEET_CLAUSE: # a plan from before the clause existed
text = load_library().clauses.get(clause)
if clause in present or text is None:
continue
st["fixes"].append({"id": clause, "text": text, "source": "auto", "take": record["take"],
"round": st["round"]})
added.append(clause)
record["fixNext"] = added
def choose_best(self, ident: str) -> None:
st = self.astate(ident)
if st.get("chosen"):
return
candidates = [t for t in st["takes"] if t["round"] == st["round"] and t["status"] == "rejected"
and (t.get("qc") or {}).get("usableWindow")]
candidates.sort(key=lambda t: (len(t.get("failures", [])),
-(t["qc"]["usableWindow"][1] - t["qc"]["usableWindow"][0]), t["take"]))
decided = sum(1 for t in st["takes"] if t["round"] == st["round"] and t["status"] in ("kept", "rejected"))
for record in candidates:
window = record["qc"]["usableWindow"]
tag = f"-w{window[0]}-{window[1]}"
try:
self.cut(ident, record, tag, window)
except (ToolFailure, ValueError) as failure:
record.setdefault("windowErrors", []).append(_ascii(str(failure))[:300])
self.save()
continue
st["chosen"] = {"take": record["take"], "window": list(window), "tag": tag,
"reason": f"best of {decided} failed takes: kept its usable frames {window[0]}-"
f"{window[1] - 1} ({', '.join(record.get('failures', []))} logged)"}
st["status"], st["message"] = "chosen", None
with open(self.root / TAKES_FILE, "a", encoding="utf-8", newline="\n") as stream:
stream.write(json.dumps(_scrub({"schema": TAKE_SCHEMA, "at": _now(), "action": ident,
"take": record["take"], "round": st["round"], "status": "best-window",
"usableWindow": window, "failures": record.get("failures", []),
"reasons": record.get("reasons", [])}), ensure_ascii=False) + "\n")
self.save()
return
st["status"] = "failed"
st["message"] = (f"no take of round {st['round']} passed or kept a usable window; retake with a fix "
"(sprite_set.py retake) or supply a clip")
self.save()
def wants_take(self, ident: str, max_takes: int, errors: dict[str, int]) -> bool:
st = self.astate(ident)
if st.get("chosen") or st["status"] == "failed" or errors.get(ident, 0) >= 2:
return False
last = st["takes"][-1] if st["takes"] else None
if last and last["round"] == st["round"] and last["status"] in ("open", "generated", "no-route"):
return True
decided = [t for t in st["takes"] if t["round"] == st["round"] and t["status"] in ("kept", "rejected")]
if len(decided) < max_takes:
return True
self.choose_best(ident)
return False
# ----------------------------------------------------------------- finishing, packaging, verify
def scale_ref_file(self, ident: str) -> Path | None:
ref = self.plan["finish"].get("scaleRefAction")
if not ref or ref == ident:
return None
chosen = (self.state["actions"].get(ref) or {}).get("chosen")
if chosen:
record = self.take(ref, chosen["take"])
finished = record.get("stages", {}).get("finished" + chosen.get("tag", ""))
if finished and finished.get("scaleRef"):
path = self.root / finished["scaleRef"]
if path.is_file():
return path
self.notes.append(f"{ident}: the scale reference {ref} has no finished frames; {ident} uses its own rest pose")
return None
def ref_palette_file(self, ident: str) -> Path | None:
"""Pixel sets without a plan palette: the palette the scale-reference action learned (palette.json in its
finish folder), so every action of the character shares one palette."""
ref = self.plan["finish"].get("scaleRefAction")
if not ref or ref == ident:
return None
chosen = (self.state["actions"].get(ref) or {}).get("chosen")
if not chosen:
return None
finished = self.take(ref, chosen["take"]).get("stages", {}).get("finished" + chosen.get("tag", ""))
if not finished:
return None
path = self.root / finished["dir"] / "palette.json"
return path if path.is_file() else None
def run_finish(self, ident: str, record: dict, out: Path, tag: str) -> dict:
finish = self.plan["finish"]
frames = self.root / record["stages"]["registered" + tag]["dir"] / "frames"
scale_ref = self.scale_ref_file(ident)
palette = self.root / finish["palette"]["path"] if finish.get("palette") else None
pixel = finish["mode"] in PALETTED
shared = self.ref_palette_file(ident) if pixel and palette is None else None
lock = None
if finish.get("colourLock", True) and finish["mode"] != "hibit": # hibit takes no colour lock
master = self.root / self.astate(ident)["job"]["dir"] / "master.png"
if master.is_file():
with Image.open(master) as image: # the keyed job master; an opaque one cannot be a lock master
keyed = image.convert("RGBA").getchannel("A").getextrema()[0] < 255
lock = master if keyed else None
if not keyed:
self.notes.append(f"{ident}: the job master has no transparency; finished without the colour lock")
script, name = resolve_finisher()
if script is None:
summary = standin_finish(finish["mode"], frames, out, int(finish["targetHeight"]), scale_ref,
palette or shared, colours=int(finish.get("colors") or 32))
else:
args = [finish["mode"], "--frames", frames, "--output-dir", out]
if scale_ref is not None: # finish_frames.py takes --scale-ref OR --target-height, never both
args += ["--scale-ref", scale_ref]
else:
args += ["--target-height", finish["targetHeight"]]
if palette is not None or shared is not None:
args += ["--palette", palette or shared]
elif pixel and finish.get("colors"):
args += ["--colors", int(finish["colors"])]
if pixel and finish.get("outline"):
args += ["--outline", finish["outline"]]
if finish.get("canvas"):
args += ["--canvas", "{}x{}".format(*finish["canvas"])]
if finish.get("canvasAnchor"):
args += ["--canvas-anchor", "{},{}".format(*finish["canvasAnchor"])]
if lock is not None:
args += ["--colour-lock", lock]
if self.entries[ident]["kind"] == "oneshot":
args += ["--loop-policy", "oneshot"]
summary, _ = run_tool(script, args, label=name)
frames_dir = None
for key in ("framesDir", "frames_dir"):
if isinstance(summary.get(key), str) and Path(summary[key]).is_dir():
frames_dir = Path(summary[key])
if frames_dir is None:
frames_dir = out / "frames" if (out / "frames").is_dir() and _pngs(out / "frames") else out
files = _pngs(frames_dir)
if not files:
raise ValueError(f"{name} wrote no PNG frames into {self.rel(out)}")
with Image.open(files[0]) as image:
size = list(image.size)
anchor = summary.get("anchor") or summary.get("sourceAnchor")
if not (isinstance(anchor, (list, tuple)) and len(anchor) == 2):
rest = np.asarray(forge_core.load_rgba(files[0])[0])[..., 3] > 127
stats = _mask_stats(rest)
band = max(2, forge_core.round_half_up(0.04 * stats["height"]))
anchor = list(forge_core.anchor_from_mask(rest, "stance", band_rows=band, min_run=2))
reference = next((summary[key] for key in ("scale_ref", "scaleRef", "metadata")
if isinstance(summary.get(key), str) and Path(summary[key]).is_file()), None)
return {"finisher": name, "mode": finish["mode"], "targetHeight": finish["targetHeight"],
"frames": len(files), "framesDir": self.rel(frames_dir), "size": size,
"anchor": [float(anchor[0]), float(anchor[1])], "scale": summary.get("scale"),
"scaleRef": self.rel(reference) if reference else None,
"scaleRefFrom": self.rel(scale_ref) if scale_ref else None}
def run_rebind(self, ident: str, record: dict, out: Path, tag: str) -> dict:
stages = record["stages"]
motion = stages.get("timed" + tag) or stages["motion" + tag]
finished = stages["finished" + tag]
result = rebind_selection(self.root / motion["selection"], self.root / finished["framesDir"],
int(stages["registered" + tag]["frames"]), out)
return {"selection": self.rel(result["selection"]), "from": motion["selection"], "frames": result["frames"]}
def run_package(self, ident: str, record: dict, out: Path, tag: str, crf: tuple[int, int] | None) -> dict:
stages = record["stages"]
finished, selection = stages["finished" + tag], stages["selection" + tag]
package = self.plan["package"]
width, height = finished["size"]
args = ["package", "--clean-dir", self.root / finished["framesDir"], "--selection",
self.root / selection["selection"], "--output-dir", out, "--name", ident,
"--formats", ",".join(package["formats"])]
if not self.plan["finish"].get("canvas"): # a requested cell canvas (--canvas) is kept as the cell
args.append("--crop-union")
args += ["--max-side", min(4096, max(width, height, 2)),
"--source-size", f"{width},{height}", "--source-anchor", "{!r},{!r}".format(*finished["anchor"]),
"--body-height-px", self.plan["finish"]["targetHeight"], "--key", self.plan["key"]]
if self.plan["finish"]["mode"] in PALETTED:
args += ["--pixel-art", "--sampling", "nearest"]
if package.get("tiers"):
args += ["--tiers", package["tiers"]]
if crf:
args += ["--crf-webm", crf[0], "--crf-packed", crf[1]]
accepted = self.accepted_for(ident, record["take"], tag)
verdict = None
if accepted is not None: # accepted before packaging: the package carries the verdict from the start
verdict = self.write_verdict(ident, record, tag,
forge_core.sha256_file(self.root / selection["selection"]))
args += ["--review", verdict]
summary, warnings = run_tool(SCRIPTS["engine_export"], args, label="engine_export.py package")
if verdict is not None:
accepted.update(verdict=forge_core.file_ref(verdict, self.root), reviewStatus=summary.get("reviewStatus"),
package=self.rel(out))
manifest = forge_core.read_json(out / "animation.json")
files = {"manifest": self.rel(out / "animation.json"), "qa": self.rel(out / "animation-qa.json"),
"provenance": self.rel(out / "provenance.json"),
"poster": self.rel(out / manifest["poster"]["file"]) if manifest.get("poster") else None,
"atlas": [self.rel(out / page["file"]) for page in (manifest.get("fallback") or {}).get("pages", [])],
"webm": self.rel(out / manifest["webm"]["file"]) if manifest.get("webm") else None,
"packed": self.rel(out / manifest["packedAlpha"]["file"]) if manifest.get("packedAlpha") else None,
"tiers": [self.rel(out / tier["file"]) for tier in manifest.get("mobilePackedAlpha") or []]}
return {"status": summary.get("status"), "reviewStatus": summary.get("reviewStatus"),
"frameCount": summary.get("frameCount"), "fps": summary.get("fps"),
"durationMs": summary.get("durationMs"), "loopPolicy": manifest.get("loopPolicy"),
"events": manifest.get("events", []), "impactMs": manifest.get("impactMs"),
"files": files, "crf": list(crf) if crf else None, "warnings": warnings[:6]}
def verify(self, record: dict, package_stage: str) -> dict:
package = self.root / record["stages"][package_stage]["dir"]
summary, _ = run_tool(SCRIPTS["engine_export"], ["verify", "--package", package],
label="engine_export.py verify")
return {"status": summary.get("status"), "report": self.rel(package / "verify-qa.json"),
"transports": summary.get("transports")}
# ----------------------------------------------------------------- the agent's verdict in the package
def accepted_for(self, ident: str, take: int, tag: str) -> dict | None:
"""The action's accept record when it accepts exactly this take and window (tag), else None."""
st = self.astate(ident)
accepted, chosen = st.get("accepted"), st.get("chosen") or {}
if (isinstance(accepted, dict) and accepted.get("take") == take and chosen.get("take") == take
and chosen.get("tag", "") == tag):
return accepted
return None
def write_verdict(self, ident: str, record: dict, tag: str, reviewed_sha256: str) -> Path:
"""A new review_verdict.v1 (status accepted) in the take folder, bound to ``reviewed_sha256`` (the
selection the package is cut by, or a package's inputDigest), with the reviewed sheet as evidence."""
accepted = self.astate(ident)["accepted"]
folder = self.root / record["dir"]
evidence = []
sheet = accepted.get("sheet") or {}
if sheet.get("path") and (self.root / sheet["path"]).is_file():
evidence.append({"path": forge_core.manifest_path(self.root / sheet["path"], folder),
"sha256": sheet.get("sha256")})
document = {"schema": REVIEW_VERDICT_SCHEMA, "status": "accepted", "issues": [], "evidence": evidence,
"reviewedSha256": reviewed_sha256, "reviewer": "agent (sprite_set.py accept)",
"note": accepted.get("note") or "", "acceptedAt": accepted.get("at")}
path = _next_numbered(folder, f"review-verdict{tag}", ".json")
_write_new_json(path, _scrub(document))
return path
def apply_accepted(self, ident: str) -> str | None:
"""Write the accept into the action's package when it holds the accepted take: a verdict bound to the
package's inputDigest, recorded by engine_export.py review (animation.json reviewStatus accepted, QA and
provenance re-bound, no re-encode). Returns the package's reviewStatus, or None when no package of the
accepted take exists yet (the run then packages it with --review)."""
st = self.astate(ident)
output = st.get("output") or {}
accepted = self.accepted_for(ident, output.get("take"), output.get("tag", "")) if output.get("package") \
else None
if accepted is None:
return None
package = self.root / output["package"]
manifest = forge_core.read_json(package / "animation.json")
if manifest.get("reviewStatus") == "accepted" and not verify_lags(package):
accepted.setdefault("reviewStatus", "accepted") # packaged with --review, or recorded before
accepted.setdefault("package", output["package"])
return "accepted"
# not recorded yet, or a review interrupted after animation.json (verify-qa.json still bound to the
# manifest before it): engine_export.py review records it, or re-binds verify-qa.json on a retry
record = self.take(ident, output["take"])
provenance = forge_core.read_json(package / "provenance.json")
path = self.write_verdict(ident, record, output.get("tag", ""), str(provenance.get("inputDigest")))
summary, _ = run_tool(SCRIPTS["engine_export"], ["review", "--package", package, "--review", path],
label="engine_export.py review")
accepted["verdict"] = forge_core.file_ref(path, self.root)
accepted["reviewStatus"] = summary.get("reviewStatus")
accepted["package"] = output["package"]
stage = next((record["stages"][name] for name in ("package-r2" + output.get("tag", ""),
"package" + output.get("tag", ""))
if name in record.get("stages", {}) and record["stages"][name].get("dir") == output["package"]),
None)
if stage is not None:
stage["reviewStatus"] = summary.get("reviewStatus")
return summary.get("reviewStatus")
def post_process(self, ident: str) -> None:
"""Finish, rebind, package and verify the chosen take (or its usable window); an accept of that take is
written into its package."""
st = self.astate(ident)
chosen = st.get("chosen")
if not chosen:
return
output = st.get("output") or {}
if (st["status"] in ("done", "done-warn") and output.get("take") == chosen["take"]
and output.get("tag") == chosen.get("tag", "")):
self.review_into_package(ident)
return
record = self.take(ident, chosen["take"])
tag, window = chosen.get("tag", ""), chosen.get("window")
label = f"{ident} t{record['take']:02d}{tag}"
try:
if "keyed" not in record.get("stages", {}):
raise ValueError(f"take {record['take']} was never keyed; run review only on evaluated takes")
if not record.get("qc"):
self.run_qc(ident, record)
self.cut(ident, record, tag, window)
self.progress("finish", None, None, f"{label}: finish_frames.py {self.plan['finish']['mode']}")
self.stage(record, "finished" + tag, lambda out: self.run_finish(ident, record, out, tag))
self.stage(record, "selection" + tag, lambda out: self.run_rebind(ident, record, out, tag))
package_stage = "package" + tag
self.progress("package", None, None, f"{label}: engine_export.py package")
self.stage(record, package_stage, lambda out: self.run_package(ident, record, out, tag, None))
verify_key = "verify" + tag
video = set(self.plan["package"]["formats"]) & {"webm", "packed"} or self.plan["package"].get("tiers")
if not video:
record["stages"][verify_key] = {"status": "skipped", "reason": "png-only package: nothing to decode"}
elif not record["stages"].get(verify_key):
self.progress("verify", None, None, f"{label}: engine_export.py verify")
try:
record["stages"][verify_key] = self.verify(record, package_stage)
except ToolFailure as first:
package_stage = "package-r2" + tag
self.stage(record, package_stage, lambda out: self.run_package(ident, record, out, tag, (18, 12)))
try:
record["stages"][verify_key] = {**self.verify(record, package_stage),
"retry": _ascii(first.message)[:300]}
except ToolFailure as second:
record["stages"][verify_key] = {"status": "fail", "message": _ascii(second.message)[:400],
"package": record["stages"][package_stage]["dir"]}
verify = record["stages"][verify_key]
package_stage = "package-r2" + tag if "package-r2" + tag in record["stages"] else "package" + tag
package = record["stages"][package_stage]
st["output"] = {"take": record["take"], "tag": tag, "package": package["dir"],
"manifest": package["files"]["manifest"], "verify": verify.get("status")}
st["status"] = "done" if verify.get("status") in ("pass", "skipped") else "done-warn"
st["message"] = None if st["status"] == "done" else f"verify failed: {verify.get('message')}"
except (ToolFailure, ValueError) as failure:
st["status"] = "post-error"
st["message"] = _ascii(str(failure))[:500]
self.save() # merges an accept made while this action was packaged
if st["status"] in ("done", "done-warn"):
self.review_into_package(ident)
def review_into_package(self, ident: str) -> None:
"""apply_accepted under the set lock, for a run: an accept recorded after (or while) the package was made
still reaches animation.json. A failure is a note, never a lost package."""
with forge_core.file_lock(self.lock_path):
self.merge_disk()
try:
status = self.apply_accepted(ident)
except (ToolFailure, ValueError) as failure:
self.notes.append(_ascii(f"{ident}: the accept could not be written into the package "
f"({str(failure)[:200]}); run sprite_set.py accept again"))
return
if status is not None:
self.save()
# ----------------------------------------------------------------- the whole run
def run(self, only: Sequence[str] | None, *, max_takes: int, jobs: int, stagger: float, media_cli: str | None,
timeout: float) -> tuple[dict, int]:
self.check_masters()
if self.state["plan"].get("sha256") != self.plan_sha:
self.notes.append(f"{PLAN_FILE} changed since the last run; later takes use the edited plan")
self.state["plan"]["sha256"] = self.plan_sha
self.state["runs"] = int(self.state.get("runs", 0)) + 1
self.save()
self.resolve_media(media_cli)
order = self.order(only)
progress = self.progress
progress("start", 0, len(order), f"run {self.state['runs']}: {', '.join(order)}")
for number, ident in enumerate(order):
progress("job", number, len(order), f"{ident}: registration job and i2v input")
self.ensure_job(ident)
errors: dict[str, int] = {}
generated = 0
blocked = False
while not blocked:
batch = [ident for ident in order if self.wants_take(ident, max_takes, errors)]
if not batch:
break
records = {ident: self.open_take(ident) for ident in batch}
pending = [ident for ident in batch if records[ident]["status"] in ("open", "no-route")]
results: dict[str, dict] = {}
if pending:
progress("generate", 0, len(pending),
", ".join(f"{ident} t{records[ident]['take']:02d}" for ident in pending))
with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, min(jobs, len(pending)))) as pool:
futures = {}
for number, ident in enumerate(pending):
if number and stagger > 0 and jobs > 1:
time.sleep(stagger)
futures[ident] = pool.submit(self.generate, ident, records[ident], timeout)
for number, (ident, future) in enumerate(futures.items(), 1):
results[ident] = future.result()
progress("generate", number, len(pending),
f"{ident} t{records[ident]['take']:02d}: {results[ident]['status']}")
for ident in batch:
record = records[ident]
if ident in results:
outcome = self.record_generation(ident, record, results[ident])
if outcome == "no-route":
blocked = True
continue
if outcome == "error":
errors[ident] = errors.get(ident, 0) + 1
continue
generated += 0 if results[ident].get("adopted") else 1
if record["status"] == "generated":
progress("evaluate", None, None, f"{ident} t{record['take']:02d}: key, QC gates, register, cut")
self.evaluate(ident, record, max_takes)
progress("evaluate", None, None, f"{ident} t{record['take']:02d}: {record['status']}")
for number, ident in enumerate(order):
progress("post", number, len(order), f"{ident}: finish, package, verify")
self.post_process(ident)
summary, code = self.summary(order, generated)
progress("done", len(order), len(order), f"set {summary['status']}")
return summary, code
def current_package(self, ident: str) -> str | None:
"""The action's package folder when it holds the chosen take and window; None after a retake or an accept
of another take (output then names the earlier package, which no longer stands for the action)."""
st = self.astate(ident)
output, chosen = st.get("output") or {}, st.get("chosen") or {}
if output.get("package") and chosen and output.get("take") == chosen.get("take") \
and output.get("tag", "") == chosen.get("tag", ""):
return output["package"]
return None
def summary(self, order: Sequence[str], generated: int) -> tuple[dict, int]:
actions = {}
for ident in order:
st = self.astate(ident)
actions[ident] = {"status": st["status"], "takes": len(st["takes"]),
"chosen": (st.get("chosen") or {}).get("take"),
"accepted": bool(st.get("accepted")),
"package": self.current_package(ident),
"message": st.get("message")}
statuses = {item["status"] for item in actions.values()}
if statuses <= {"done"}:
status, code = "complete", 0
elif "no-route" in statuses and not statuses & {"failed", "post-error", "error", "generating", "retake"}:
status, code = "waiting-for-clips", EXIT_NO_ROUTE
elif statuses <= {"done", "done-warn"}:
status, code = "complete-with-warnings", 0
elif statuses & {"done", "done-warn"}: # some actions are packaged: published, but the set failed
status, code = "incomplete", forge_core.EXIT_PUBLISHED_FAIL
else:
status, code = "incomplete", 1
summary = {"output": str(self.root), "plan": str(self.plan_path), "state": str(self.state_path),
"status": status, "generated": generated, "media": self.media_name,
"finisher": resolve_finisher()[1], "actions": actions,
"needsReview": [ident for ident, item in actions.items() if not item["accepted"]],
"notes": [_ascii(note) for note in self.notes[:12]]}
return summary, code
# --------------------------------------------------------------------------- review sheets
GREY, PANEL, INK, BAD = (118, 118, 118), (32, 36, 44), (236, 236, 236), (235, 60, 60)
LETTERS = {"area": "A", "feet": "F", "identity": "I", "zoom": "Z", "turn": "T", "edge": "E", "background": "B",
"extra": "X", "colour": "C"}
CHECKLIST = ("the same character, face, colours and costume as the master in every frame",
"facing {facing} the whole time; never turned around or toward the camera",
"the {action} really happens, once, and reads at game size",
"no extra objects: dust, orbs, sparks, projectiles, trails, text or a second weapon",
"nothing covers the face; the weapon keeps its shape and length",
"loops close without a jump; one-shots start and end on the rest pose")
_FONT: list[ImageFont.ImageFont] = []
def _font() -> ImageFont.ImageFont:
if not _FONT:
_FONT.append(ImageFont.load_default())
return _FONT[0]
def _thumb(source: Image.Image | np.ndarray, size: int) -> Image.Image:
rgba = (source if isinstance(source, Image.Image) else Image.fromarray(np.asarray(source))).convert("RGBA")
factor = min(1.0, size / max(rgba.size))
if factor < 1.0:
out = (max(1, forge_core.round_half_up(rgba.width * factor)),
max(1, forge_core.round_half_up(rgba.height * factor)))
rgba = forge_core.resample_rgba(rgba, factor, "box", out_size=out)
tile = Image.new("RGB", rgba.size, GREY)
tile.paste(rgba, (0, 0), rgba)
return tile
def _fit_lines(lines: Sequence[str], width: int) -> list[str]:
"""Wrap header lines to ``width`` px of the review font (measured, so nothing is clipped)."""
measure = ImageDraw.Draw(Image.new("RGB", (1, 1)))
fitted = []
for text in lines:
words, line = _ascii(text).split(" "), ""
for word in words:
trial = f"{line} {word}" if line else word
if line and measure.textlength(trial, font=_font()) > width:
fitted.append(line)
line = " " + word
else:
line = trial
fitted.append(line)
return fitted
def _grid(header: Sequence[str], tiles: Sequence[tuple[Image.Image, str, bool]], columns: int = 6) -> Image.Image:
cell_w = max(tile.width for tile, _, _ in tiles)
cell_h = max(tile.height for tile, _, _ in tiles) + 14
rows = math.ceil(len(tiles) / columns)
width = max(min(columns, len(tiles)) * (cell_w + 10) + 10, 760)
header = _fit_lines(header, width - 16)
head = 14 * len(header) + 12
sheet = Image.new("RGB", (width, head + rows * (cell_h + 10) + 6), PANEL)
draw = ImageDraw.Draw(sheet)
for number, line in enumerate(header):
draw.text((8, 6 + 14 * number), line, fill=INK, font=_font())
for index, (tile, label, flagged) in enumerate(tiles):
row, column = divmod(index, columns)
x, y = 10 + column * (cell_w + 10), head + row * (cell_h + 10)
sheet.paste(tile, (x, y))
if flagged:
draw.rectangle([x - 2, y - 2, x + tile.width + 1, y + tile.height + 1], outline=BAD, width=2)
draw.text((x, y + tile.height + 2), _ascii(label), fill=BAD if flagged else INK, font=_font())
return sheet
def take_sheet(runner: SetRunner, ident: str, record: dict) -> Image.Image:
"""Contact sheet of one take: the input still, evenly spaced frames and the first frame of every failing
run, each labelled with its frame number and the letters of the gates it fails."""
files = _pngs(runner.root / record["stages"]["keyed"]["dir"] / "frames-clean")
count = len(files)
qc = record.get("qc") or {}
bad = {gate: set(frames) for gate, frames in (qc.get("badFrames") or {}).items()}
letters = {i: "".join(code for gate, code in LETTERS.items() if i in bad.get(gate, set())) for i in range(count)}
picks = {forge_core.round_half_up(i * (count - 1) / 13) for i in range(14)} if count > 1 else {0}
for frames in bad.values():
for start, _ in _runs([i in frames for i in range(count)]):
picks.add(start)
tiles = [(_thumb(Image.open(runner.root / runner.astate(ident)["job"]["input"]), 150), "input (master)", False)]
for index in sorted(picks)[:29]:
with Image.open(files[index]) as image:
tiles.append((_thumb(image, 150), f"#{index} {letters[index]}".strip(), bool(letters[index])))
facing = runner.master(ident)["facing"]
words = {"facing": prompt_words(facing, runner.plan["key"], "", "", ident)["facing"],
"action": runner.entries[ident]["action"]}
header = [f"{runner.plan['name']} / {ident} / take {record['take']} (round {record['round']}) / "
f"{record['status']} / route {record.get('route') or '-'} / {count} frames"]
failing = [f"{gate}={item['status']}" for gate, item in (qc.get("gates") or {}).items() if item["status"] != "pass"]
header.append("gates not passing: " + (", ".join(failing) if failing else "none"))
header += [str(reason) for reason in qc.get("reasons", [])[:6]]
header += [f"warning: {warning}" for warning in qc.get("warnings", [])[:4]]
if qc.get("usableWindow"):
header.append(f"usable frames {qc['usableWindow'][0]}-{qc['usableWindow'][1] - 1} of {count}")
header.append("red: A area F feet I identity Z zoom T turned E edge B background X extra objects C colour bleed")
header.append("LOOK FOR: " + "; ".join(fill(item, words) for item in CHECKLIST))
return _grid(header, tiles)
def final_sheet(runner: SetRunner, ident: str, record: dict, tag: str) -> Image.Image | None:
"""The played frames of the finished clip at game scale (x3 nearest for pixel art), on the feet line."""
stages = record.get("stages", {})
finished, selection = stages.get("finished" + tag), stages.get("selection" + tag)
if not finished or not selection:
return None
files = _pngs(runner.root / finished["framesDir"])
document = forge_core.read_json(runner.root / selection["selection"])
played = list(document["sourceIndices"])
zoom = 3 if runner.plan["finish"]["mode"] in PALETTED else (2 if max(finished["size"]) < 96 else 1)
anchor_y = forge_core.round_half_up(finished["anchor"][1] * zoom)
tiles = []
for index in list(dict.fromkeys(played))[:24]:
with Image.open(files[index]) as image:
rgba = image.convert("RGBA")
if zoom > 1:
rgba = rgba.resize((rgba.width * zoom, rgba.height * zoom), Image.Resampling.NEAREST)
tile = Image.new("RGB", rgba.size, GREY)
tile.paste(rgba, (0, 0), rgba)
ImageDraw.Draw(tile).line([0, min(anchor_y, tile.height - 1), tile.width, min(anchor_y, tile.height - 1)],
fill=(0, 220, 255))
tiles.append((tile, f"src {index}", False))
events = ", ".join(f"{event['name']}@{event['atMs']}ms" for event in document.get("events", []))
header = [f"{runner.plan['name']} / {ident} / take {record['take']} finished ({runner.plan['finish']['mode']}, "
f"x{zoom}) / {len(played)} frames, {sum(document['durations_ms'])} ms, {document['loopPolicy']}",
"events: " + (events or "none") + " / cyan line: feet anchor"]
return _grid(header, tiles, columns=8)
def _rest_frames(runner: SetRunner, prefix: str = "") -> list[tuple[str, np.ndarray, list[float]]]:
items = []
for ident in runner.order():
st = runner.astate(ident)
chosen = st.get("chosen")
if not chosen:
continue
record = runner.take(ident, chosen["take"])
finished = record.get("stages", {}).get("finished" + chosen.get("tag", ""))
if not finished:
continue
files = _pngs(runner.root / finished["framesDir"])
if files:
items.append((prefix + ident, np.asarray(forge_core.load_rgba(files[0])[0]), finished["anchor"]))
return items
def lineup_sheet(runner: SetRunner, peers: Sequence[SetRunner]) -> tuple[Image.Image, dict] | None:
"""Cast line-up: the finished rest frame of every action (and of every peer set) on one feet line, at x1 and
x3, with body height and opaque area so one character keeps one height and the cast keeps its ratios."""
items = _rest_frames(runner)
for peer in peers:
items += _rest_frames(peer, peer.plan["name"] + "/")
if not items:
return None
rows, measures = [], {}
for label, rgba, _anchor in items:
stats = _mask_stats(rgba[..., 3] > 127)
measures[label] = {"heightPx": stats["height"] if stats else 0, "areaPx": stats["area"] if stats else 0}
for zoom in (1, 3):
above = max(forge_core.round_half_up(anchor[1] * zoom) for _, _, anchor in items)
below = max(rgba.shape[0] * zoom - forge_core.round_half_up(anchor[1] * zoom) for _, rgba, anchor in items)
width = sum(rgba.shape[1] * zoom + 16 for _, rgba, _ in items) + 16
row = Image.new("RGB", (max(width, 320), above + below + 34), GREY)
draw = ImageDraw.Draw(row)
x = 16
for label, rgba, anchor in items:
image = Image.fromarray(rgba)
if zoom > 1:
image = image.resize((image.width * zoom, image.height * zoom), Image.Resampling.NEAREST)
row.paste(image, (x, above - forge_core.round_half_up(anchor[1] * zoom)), image)
text = f"{label} h{measures[label]['heightPx']}" if zoom == 1 else label
draw.text((x, above + below + 6), _ascii(text), fill=INK, font=_font())
x += image.width + 16
draw.line([0, above, row.width, above], fill=(0, 220, 255))
rows.append(row)
header = [f"cast line-up: {runner.plan['name']} ({runner.plan['class']}), finish {runner.plan['finish']['mode']}, "
f"target height {runner.plan['finish']['targetHeight']} px; rows x1 and x3; cyan line: feet",
"one character keeps one body height; mobs no taller than the hero; a boss about 2x the hero"]
width = max(row.width for row in rows)
sheet = Image.new("RGB", (width, 14 * len(header) + 12 + sum(row.height + 8 for row in rows)), PANEL)
draw = ImageDraw.Draw(sheet)
for number, line in enumerate(header):
draw.text((8, 6 + 14 * number), _ascii(line), fill=INK, font=_font())
y = 14 * len(header) + 12
for row in rows:
sheet.paste(row, (0, y))
y += row.height + 8
return sheet, measures
def cmd_review(args: argparse.Namespace) -> dict:
runner = SetRunner(Path(args.plan))
peers = [SetRunner(Path(peer)) for peer in args.peer or []]
folder = runner.root / "review"
sheets = []
for ident in runner.order():
st = runner.astate(ident)
chosen = st.get("chosen") or {}
for record in st["takes"]:
if "keyed" not in record.get("stages", {}):
continue
path = folder / ident / f"t{record['take']:02d}-sheet.png"
path.parent.mkdir(parents=True, exist_ok=True)
if not path.is_file():
_publish_png(take_sheet(runner, ident, record), path)
item = {"action": ident, "take": record["take"], "round": record["round"], "status": record["status"],
"chosen": chosen.get("take") == record["take"],
"accepted": (st.get("accepted") or {}).get("take") == record["take"],
"failures": record.get("failures", []), "reasons": record.get("reasons", []),
"usableWindow": (record.get("qc") or {}).get("usableWindow"),
"sheet": forge_core.file_ref(path, runner.root), "final": None}
tag = chosen.get("tag", "") if item["chosen"] else None
if tag is not None:
final = folder / ident / f"t{record['take']:02d}{tag}-final.png"
if not final.is_file():
image = final_sheet(runner, ident, record, tag)
if image is not None:
_publish_png(image, final)
if final.is_file():
item["final"] = forge_core.file_ref(final, runner.root)
sheets.append(item)
folder.mkdir(parents=True, exist_ok=True)
lineup = None
made = lineup_sheet(runner, peers)
if made is not None:
image, measures = made
path = _next_numbered(folder, "lineup", ".png")
_publish_png(image, path)
lineup = {**forge_core.file_ref(path, runner.root), "scales": [1, 3], "measures": measures}
document = {
"schema": REVIEW_SCHEMA, "createdAt": _now(), "set": runner.plan["name"],
"instructions": ("Look at EVERY sheet (Read in Claude Code, view_image in Codex) before accept or retake. "
"Numbers cannot see identity, facing, extra objects or a covered face."),
"checklist": list(CHECKLIST), "sheets": sheets, "lineup": lineup,
"next": ["sprite_set.py accept --plan <set>/set_plan.json --action <action> --take <n>",
"sprite_set.py retake --plan <set>/set_plan.json --action <action> --fix <clause id or text>"],
}
path = _next_numbered(folder, "review", ".json")
_write_new_json(path, _scrub(document))
with forge_core.file_lock(runner.lock_path): # a fresh read: a run may have saved while the sheets were drawn
runner.reload()
runner.state["review"] = {"latest": runner.rel(path), "at": _now()}
runner.save()
return {"output": str(folder.resolve()), "metadata": str(path.resolve()), "review": str(path.resolve()),
"sheets": [str((runner.root / item["sheet"]["path"]).resolve()) for item in sheets],
"finals": [str((runner.root / item["final"]["path"]).resolve()) for item in sheets if item["final"]],
"lineup": str((runner.root / lineup["path"]).resolve()) if lineup else None,
"look": "open and look at every sheet, the finals and the lineup before accept"}
# --------------------------------------------------------------------------- accept, retake, report
def _parse_window(text: str | None) -> list[int] | None:
if not text:
return None
match = re.fullmatch(r"\s*(\d+)\s*:\s*(\d+)\s*", text)
if not match or int(match.group(2)) <= int(match.group(1)):
raise ValueError(f"--window needs START:END (0-based take frames, END exclusive); got {text!r}")
return [int(match.group(1)), int(match.group(2))]
@contextlib.contextmanager
def locked_runner(plan: Any):
"""A SetRunner read fresh under the set lock, held until the block ends (the agent's verbs: every
read-modify-write of set_state.json happens inside one lock, so a concurrent run merges it, never loses it)."""
path = Path(plan)
plan_path = path / PLAN_FILE if path.is_dir() else path
if not plan_path.is_file():
raise ValueError(f"no {PLAN_FILE} at {plan_path.as_posix()}")
with forge_core.file_lock(plan_path.resolve().parent / LOCK_FILE):
yield SetRunner(plan_path)
def cmd_accept(args: argparse.Namespace) -> dict:
with locked_runner(args.plan) as runner:
return _accept(runner, args)
def _accept(runner: SetRunner, args: argparse.Namespace) -> dict:
st = runner.astate(args.action)
record = runner.take(args.action, args.take)
if "keyed" not in record.get("stages", {}):
raise ValueError(f"{args.action} take {args.take} was never keyed; there is nothing to look at or accept")
latest = (runner.state.get("review") or {}).get("latest")
if not latest or not (runner.root / latest).is_file():
raise ValueError("run sprite_set.py review and LOOK at the contact sheets before accepting")
review = forge_core.read_json(runner.root / latest)
sheet = next((item for item in review.get("sheets", [])
if item["action"] == args.action and item["take"] == args.take), None)
if sheet is None:
raise ValueError(f"the latest review has no sheet for {args.action} take {args.take}; run review again and "
"look at it")
sheet_path = runner.root / sheet["sheet"]["path"]
if not sheet_path.is_file() or forge_core.sha256_file(sheet_path) != sheet["sheet"]["sha256"]:
raise ValueError("the reviewed contact sheet is missing or changed; run review again and look at it")
frames = int(record["stages"]["keyed"].get("frames") or 0)
window = _parse_window(args.window)
if window and frames and window[1] > frames:
raise ValueError(f"--window ends after the take's {frames} frames")
chosen = st.get("chosen") or {}
if window is None and record["status"] != "kept":
if chosen.get("take") == args.take:
window = chosen.get("window")
else:
window = (record.get("qc") or {}).get("usableWindow")
if window is None:
raise ValueError(f"{args.action} take {args.take} failed the gates without a usable window; pass "
"--window START:END to keep the frames you checked")
tag = "" if window is None else f"-w{window[0]}-{window[1]}"
if chosen.get("take") != args.take or chosen.get("tag", "") != tag:
st["chosen"] = {"take": args.take, "window": window, "tag": tag,
"reason": "accepted by the agent after looking at the review"}
st["status"], st["message"] = "chosen", None
previous = st.get("accepted") or {}
st["accepted"] = {"take": args.take, "window": window, "note": args.note or "", "at": _now(), "review": latest,
"sheet": sheet["sheet"]}
if previous.get("take") == args.take and previous.get("window") == window: # the same take accepted again
st["accepted"].update({key: previous[key] for key in ("verdict", "reviewStatus", "package") if key in previous})
st["agentRevision"] = int(st.get("agentRevision", 0)) + 1
review_error = None
try:
review_status = runner.apply_accepted(args.action) # the package of this take, when it exists already
except (ToolFailure, ValueError) as failure: # the accept still counts; the next run retries the package
review_status, review_error = None, _ascii(str(failure))[:300]
print(f"warning: the accept is recorded, but its package could not be updated: {review_error}",
file=sys.stderr)
runner.save()
done = st["status"] in ("done", "done-warn")
package = (st.get("output") or {}).get("package") if review_status else None
summary = {"output": str(runner.root), "metadata": str(runner.state_path), "action": args.action,
"take": args.take, "accepted": True, "window": window, "status": st["status"],
"reviewStatus": review_status, "package": str((runner.root / package).resolve()) if package else None,
"next": None if done and review_status else "run sprite_set.py run to finish and package the accepted "
"take (the package records the verdict)"}
if review_error:
summary["reviewError"] = review_error
return summary
def cmd_retake(args: argparse.Namespace) -> dict:
with locked_runner(args.plan) as runner:
return _retake(runner, args)
def _retake(runner: SetRunner, args: argparse.Namespace) -> dict:
st = runner.astate(args.action)
fixes = []
for value in args.fix:
text = " ".join(str(value).split())
if not text:
raise ValueError("--fix needs a clause id from motion-prompts.md or the clause text")
if text in PLANTED_CLAUSES and moves_feet(runner.entries.get(args.action, {})):
text = MOVING_FEET_CLAUSE # a walk, run or jump keeps its feet moving on the ground line
if text not in runner.plan["clauses"]: # a plan from before the clause existed
fixes.append({"id": text, "text": load_library().clauses[text]})
continue
if text in runner.plan["clauses"]:
fixes.append({"id": text, "text": runner.plan["clauses"][text]})
else:
fixes.append({"id": "agent", "text": text})
chosen = st.get("chosen")
if chosen:
runner.take(args.action, chosen["take"])["review"] = {"verdict": "retake", "at": _now(),
"fixes": [fix["id"] for fix in fixes]}
st["round"] = int(st.get("round", 1)) + 1
known = {fix["text"].lower() for fix in st["fixes"]}
for fix in fixes:
if fix["text"].lower() not in known:
st["fixes"].append({**fix, "source": "agent", "round": st["round"]})
known.add(fix["text"].lower())
st.update(chosen=None, accepted=None, status="pending", message=None)
st["agentRevision"] = int(st.get("agentRevision", 0)) + 1
with open(runner.root / TAKES_FILE, "a", encoding="utf-8", newline="\n") as stream:
stream.write(json.dumps(_scrub({"schema": TAKE_SCHEMA, "at": _now(), "action": args.action,
"take": chosen["take"] if chosen else None, "round": st["round"],
"status": "retake-requested", "fixNext": [fix["id"] for fix in fixes],
"reasons": [fix["text"] for fix in fixes]}), ensure_ascii=False) + "\n")
runner.save()
return {"output": str(runner.root), "metadata": str(runner.state_path), "action": args.action,
"round": st["round"], "fixes": [fix["id"] for fix in fixes], "status": "pending",
"next": "run sprite_set.py run to generate the retake"}
def build_report(runner: SetRunner) -> dict:
"""Every action's route, takes, QC numbers, loop or timing and output files (relative paths only)."""
actions = []
for ident in runner.order():
st, entry = runner.astate(ident), runner.entries[ident]
takes = []
for record in st["takes"]:
qc = record.get("qc") or {}
takes.append({"take": record["take"], "round": record["round"], "status": record["status"],
"route": record.get("route"), "pinnedLastFrame": record.get("pinnedLastFrame"),
"prompt": record.get("prompt"), "fixes": record.get("fixes", []),
"clip": record.get("clip"), "failures": record.get("failures", []),
"reasons": record.get("reasons", []), "message": record.get("message"),
"qc": {"file": qc.get("file"), "gates": qc.get("gates"),
"usableWindow": qc.get("usableWindow"),
"usableFrames": qc.get("usableFrames"), "frames": qc.get("frames"),
"motion": qc.get("motion")} if qc else None})
chosen, output = st.get("chosen"), st.get("output") or {}
loop = timing = outputs = finish = None
if chosen:
record = runner.take(ident, chosen["take"])
stages, tag = record.get("stages", {}), chosen.get("tag", "")
motion = stages.get("timed" + tag) or stages.get("motion" + tag)
package = stages.get("package-r2" + tag) or stages.get("package" + tag)
finished = stages.get("finished" + tag)
if motion and entry["kind"] == "loop":
loop = {key: motion.get(key) for key in ("tool", "policy", "start", "endExclusive", "frames",
"durationMs", "confidence", "selection")}
elif motion:
timing = {key: motion.get(key) for key in ("tool", "start", "endExclusive", "frames", "durationMs",
"impactMs", "tickHz", "events", "selection")}
if package:
outputs = {**package["files"], "package": package["dir"], "status": package.get("status"),
"fps": package.get("fps"), "frameCount": package.get("frameCount"),
"durationMs": package.get("durationMs"), "loopPolicy": package.get("loopPolicy"),
"verify": (stages.get("verify" + tag) or {}).get("status"),
"registration": (stages.get("registered" + tag) or {}).get("registration")}
if finished:
finish = {key: finished.get(key) for key in ("finisher", "mode", "targetHeight", "scale", "size",
"anchor", "scaleRefFrom")}
actions.append({"id": ident, "action": entry["action"], "view": entry["view"], "kind": entry["kind"],
"status": st["status"], "message": st.get("message"),
"canvas": entry["placement"]["canvas"], "pinLastFrame": entry["pinLastFrame"],
"route": next((t["route"] for t in reversed(takes) if t.get("route")), None),
"chosen": chosen, "accepted": st.get("accepted"), "fixes": st.get("fixes", []),
"takes": takes, "loop": loop, "timing": timing, "finish": finish, "outputs": outputs})
statuses = {item["status"] for item in actions}
status = ("complete" if statuses <= {"done"} else
"complete-with-warnings" if statuses <= {"done", "done-warn"} else "incomplete")
return {"schema": REPORT_SCHEMA, "tool": {"name": TOOL_NAME, "version": TOOL_VERSION}, "createdAt": _now(),
"name": runner.plan["name"], "class": runner.plan["class"], "status": status,
"plan": {"path": PLAN_FILE, "sha256": runner.plan_sha}, "finish": runner.plan["finish"],
"package": runner.plan["package"], "accepted": [item["id"] for item in actions if item["accepted"]],
"needsReview": [item["id"] for item in actions if not item["accepted"]],
"review": runner.state.get("review"), "actions": actions}
def cmd_report(args: argparse.Namespace) -> dict:
runner = SetRunner(Path(args.plan))
report = _scrub(build_report(runner))
if args.output:
path = Path(args.output)
if os.path.lexists(path):
raise ValueError(f"{path.name} already exists; reports are never overwritten")
path.parent.mkdir(parents=True, exist_ok=True)
else:
folder = runner.root / "reports"
folder.mkdir(exist_ok=True)
path = _next_numbered(folder, "report", ".json")
_write_new_json(path, report)
return {"output": str(path.resolve()), "metadata": str(path.resolve()), "status": report["status"],
"actions": {item["id"]: item["status"] for item in report["actions"]},
"needsReview": report["needsReview"]}
# --------------------------------------------------------------------------- CLI
def _positive_int(low: int, high: int) -> Callable[[str], int]:
def parse(text: str) -> int:
try:
value = int(text)
except ValueError:
raise argparse.ArgumentTypeError(f"needs a whole number {low}-{high}; got {text!r}") from None
if not low <= value <= high:
raise argparse.ArgumentTypeError(f"needs a whole number {low}-{high}; got {text!r}")
return value
return parse
def _seconds(low: float, high: float) -> Callable[[str], float]:
def parse(text: str) -> float:
try:
value = float(text)
except ValueError:
raise argparse.ArgumentTypeError(f"needs seconds {low:g}-{high:g}; got {text!r}") from None
if not (math.isfinite(value) and low <= value <= high):
raise argparse.ArgumentTypeError(f"needs seconds {low:g}-{high:g}; got {text!r}")
return value
return parse
def cmd_run(args: argparse.Namespace) -> tuple[dict, int]:
runner = SetRunner(Path(args.plan))
runner.progress = args.progress
generation = runner.plan["generation"]
only = [item.strip() for item in args.actions.split(",") if item.strip()] if args.actions else None
return runner.run(only, max_takes=args.max_takes or int(generation["maxTakes"]),
jobs=args.jobs or int(generation["jobs"]), stagger=args.stagger, media_cli=args.media_cli,
timeout=args.timeout or float(generation.get("timeoutSeconds") or 1200))
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="sprite_set.py", description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
sub = parser.add_subparsers(dest="command", required=True)
pl = sub.add_parser("plan", help="write a new set folder with set_plan.json from an approved master.json",
description="Read master.json (generate2dsprite.master.v1) and write a new set folder: "
"master copies and set_plan.json with one clip per action and view.")
pl.add_argument("--master", required=True, help="master.json (generate2dsprite.master.v1); its padded PNG is "
"found through its files entry and checked by sha256")
pl.add_argument("--output-dir", required=True, help="new set folder (refused if it exists)")
pl.add_argument("--actions", default=",".join(DEFAULT_ACTIONS),
help=f"comma list from {', '.join(ACTION_PRESETS)} (default {','.join(DEFAULT_ACTIONS)})")
pl.add_argument("--views", default="side", help="comma list of side, front, back (default side)")
pl.add_argument("--view-master", action="append", default=[], metavar="VIEW=FILE",
help="master.json of another view (front or back); repeatable")
pl.add_argument("--finish", choices=FINISHES, help="hd (full colour), pixel (one palette) or hibit (hi-bit pixel "
"art from flat lineless art); default: the master's finish, "
"else hd")
pl.add_argument("--target-height", type=_positive_int(8, 4096),
help="finished body height in px (default hd 256, pixel and hibit 80; a boss twice that)")
pl.add_argument("--fps",
help="playback rate of the finished frames: 1-60, fractions allowed (12.5 or 25/2); default: the "
"clip's own rate for hd, 12 for pixel and hibit")
pl.add_argument("--frame-ms", type=float,
help="exact frame time instead of --fps, such as 80 (12.5 fps on a 25 Hz tick grid)")
pl.add_argument("--colors", type=int,
help="pixel and hibit without --palette: palette size learned by the scale-reference action and "
"shared by every action (default pixel 32, hibit 16)")
pl.add_argument("--outline",
help="1 px outline: pixel selective (default), dark or none; hibit auto (default: a colour taken "
"from the sprite), #RRGGBB, selective, dark or none (finish_frames.py --outline)")
pl.add_argument("--canvas", help="fixed cell WIDTHxHEIGHT for every finished frame, such as 48x64")
pl.add_argument("--canvas-anchor", help="X,Y of the anchor inside the --canvas cell")
pl.add_argument("--no-colour-lock", action="store_true",
help="do not lock the finished colours to the master (finish_frames.py --colour-lock, on by "
"default for hd and pixel sets; hibit never locks)")
pl.add_argument("--oneshot-timing", choices=("auto", "source"), default="auto",
help="one-shots: auto (default) retimes the slow clip to game length (attack 0.7 s with the hit "
"at 40%%, jump 0.9 s, hurt 0.5 s, cast 0.9 s; retime.py --auto-oneshot); source keeps the "
"clip's speed")
pl.add_argument("--oneshot-ms", help="one-shot game lengths, such as attack=600,jump=800 (ms)")
pl.add_argument("--formats", default="png,webm,packed", help="engine_export formats (default png,webm,packed)")
pl.add_argument("--tiers", help="engine_export mobile tiers: actor, prop, fx or NAME:EDGE@FPS (default none)")
pl.add_argument("--duration", type=_seconds(2, 30), default=6.0, help="clip seconds (default 6)")
pl.add_argument("--resolution", default="720p", help="generation resolution (default 720p)")
pl.add_argument("--max-takes", type=_positive_int(1, 10), default=3,
help="automatic takes per action and round (default 3)")
pl.add_argument("--jobs", type=_positive_int(1, 16), default=3, help="clips generated at once (default 3)")
pl.add_argument("--pin-last", choices=("auto", "on", "off"), default="auto",
help="pin the end frame to the master: auto = idle and attack (default), on = every action "
"that returns to rest, off; the route must take a last frame")
pl.add_argument("--gen-timeout", type=_seconds(30, 7200), default=1200.0,
help="seconds one generation may take (default 1200)")
pl.add_argument("--style", help="the 'keep the exact <style> look' words (default from the finish)")
pl.add_argument("--pronoun", default="their", help="possessive in the templates: his, her, its, their (default)")
pl.add_argument("--palette", help="pixel finish: shared palette PNG or JSON for the whole cast")
pl.add_argument("--matte-profile",
help="character matte profile (video2dsprite.character_profile.v1) passed to every clip's keying, "
"e.g. to pin despill 'all' when the generator tints the subject with the key")
pl.add_argument("--library", help="motion-prompts.md to read (default: this skill's references copy)")
pl.set_defaults(func=cmd_plan)
rn = sub.add_parser("run", help="generate, check, retake, register, cut, finish, package and verify (resumable)",
description="Make every planned action; running it again resumes from set_state.json.")
rn.add_argument("--plan", required=True, help="set_plan.json (or its set folder)")
rn.add_argument("--actions", help="comma list of action ids to work on (default: every planned action)")
rn.add_argument("--max-takes", type=_positive_int(1, 10), help="override the plan's takes per round")
rn.add_argument("--jobs", type=_positive_int(1, 16), help="override the plan's parallel generations")
rn.add_argument("--stagger", type=_seconds(0, 60), default=2.0,
help="seconds between parallel generation starts (default 2)")
rn.add_argument("--media-cli", help="media CLI script to call instead of generate2dmedia/scripts/route_media.py "
"(same arguments and JSON line)")
rn.add_argument("--timeout", type=_seconds(30, 7200), help="override the plan's generation timeout")
rn.add_argument("--progress-file",
help=f"append one JSON line per stage (start, job, generate N of M, evaluate, post, finish, "
f"package, verify, done) to this file for a host (default: ${forge_core.PROGRESS_ENV}, "
"else none); stdout is unchanged")
rv = sub.add_parser("review", help="contact sheets per take, finished strips, a cast line-up and review.json",
description="Write the review images; the agent must look at every one before accept.")
rv.add_argument("--plan", required=True, help="set_plan.json (or its set folder)")
rv.add_argument("--peer", action="append", default=[], help="another set (plan or folder) for the cast line-up")
rv.set_defaults(func=cmd_review)
ac = sub.add_parser("accept", help="record the agent's approval of one take after looking at its sheet")
ac.add_argument("--plan", required=True, help="set_plan.json (or its set folder)")
ac.add_argument("--action", required=True, help="action id")
ac.add_argument("--take", required=True, type=_positive_int(1, 999), help="take number")
ac.add_argument("--window", help="START:END take frames to keep (END exclusive) for a take that failed a gate")
ac.add_argument("--note", help="what was checked")
ac.set_defaults(func=cmd_accept)
rt = sub.add_parser("retake", help="reject an action semantically; the next run makes a new take with the fix")
rt.add_argument("--plan", required=True, help="set_plan.json (or its set folder)")
rt.add_argument("--action", required=True, help="action id")
rt.add_argument("--fix", required=True, action="append",
help="clause id from motion-prompts.md (for example never-turn) or the clause text; repeatable")
rt.set_defaults(func=cmd_retake)
rp = sub.add_parser("report", help="one JSON with routes, takes, QC numbers, loops or timing and output files")
rp.add_argument("--plan", required=True, help="set_plan.json (or its set folder)")
rp.add_argument("--output", help="new report file (default <set>/reports/report-NNN.json)")
rp.set_defaults(func=cmd_report)
return parser
def _run(argv: Sequence[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.command == "run":
args.progress = forge_core.Progress(TOOL_NAME, args.progress_file)
try:
summary, code = cmd_run(args)
except BaseException as error:
args.progress("error", None, None, str(error) or type(error).__name__)
raise
print(json.dumps(summary, ensure_ascii=True))
if code == EXIT_NO_ROUTE:
print(_ascii("error: no generation route; the summary names the media folders that wait for a clip"),
file=sys.stderr)
return EXIT_NO_ROUTE
if code:
failing = [f"{ident} {item['status']}" + (f" ({item['message']})" if item.get("message") else "")
for ident, item in summary["actions"].items() if item["status"] not in ("done", "done-warn")]
message = "the set is incomplete: " + "; ".join(failing)
if code == forge_core.EXIT_PUBLISHED_FAIL: # the packaged actions are usable; the summary names them
packaged = [ident for ident, item in summary["actions"].items()
if item["status"] in ("done", "done-warn")]
print(_ascii(f"error: {message} (packaged: {', '.join(packaged)})"), file=sys.stderr)
return code
raise ValueError(message)
return 0
print(json.dumps(args.func(args), ensure_ascii=True))
return 0
def main(argv: Sequence[str] | None = None) -> int:
"""Usage errors exit 2; refused input or a failed step prints error: ... and exits 1; exit 3 means the run
waits for a clip because no generation route exists; a run that packaged some actions but left others
failed prints its summary and error: ... and exits 4 (forge_core.EXIT_PUBLISHED_FAIL; D26, D27;
forge_core.run_cli)."""
return forge_core.run_cli(_run, argv, expected=forge_core.CLI_EXPECTED_ERRORS + (ToolFailure,))
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |