Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(sway): the follow-through is the Sway layer — `video-sway`, `video-sway-inspect`, `sprite_gen.video.sway`, `sway_loop`; the old names run it and say their own name; a record under `sway` reads as one under `follow`, which is still the key written
Soohong Kim1cb5180ea0f5
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.pyindex 790cbeb..7e8087f 100644--- a/sprite_gen/_modules.py+++ b/sprite_gen/_modules.py@@ -32,6 +32,8 @@ MODULE_DOMAIN = {'align': 'video','follow': 'video','follow_inspect': 'video',+ 'sway': 'video',+ 'sway_inspect': 'video','set_sheet': 'video','stop': 'video','compare': 'video',@@ -105,8 +107,8 @@ DOMAIN_TITLE = dict(DOMAINS)PIPELINES: list[dict[str, object]] = [{"key": "A", "name": "atlas rows", "verbs": ["prepare", "gen", "gen-set", "extract", "compose-atlas", "curation"],"chain": "prepare → gen (or gen-set) → extract → compose-atlas; optional curation and recompose", "doc": "docs/run-contract.md"},- {"key": "B", "name": "video → loop", "verbs": ["video-canvas", "video", "video-prompt", "video-frames", "video-loop", "video-set", "video-cycle-align", "video-follow", "video-follow-inspect", "video-set-sheet", "video-stop", "handed-check"],- "chain": "video-canvas → video (or video-prompt + a video MCP) → video-frames → video-loop, or video-set; video-cycle-align across a set; video-follow for a soft part's follow-through (video-follow-inspect shows every cell of it and moves nothing); video-set-sheet lays a set's directions on one sheet on one ground line; video-stop cuts a walk or run's stop from its clip's start played backwards; handed-check for an item on one side", "doc": "docs/video-pipeline.md"},+ {"key": "B", "name": "video → loop", "verbs": ["video-canvas", "video", "video-prompt", "video-frames", "video-loop", "video-set", "video-cycle-align", "video-sway", "video-sway-inspect", "video-set-sheet", "video-stop", "handed-check"],+ "chain": "video-canvas → video (or video-prompt + a video MCP) → video-frames → video-loop, or video-set; video-cycle-align across a set; video-sway for a soft part's sway, the Sway layer (video-sway-inspect shows every cell of it and moves nothing; old names video-follow, video-follow-inspect); video-set-sheet lays a set's directions on one sheet on one ground line; video-stop cuts a walk or run's stop from its clip's start played backwards; handed-check for an item on one side", "doc": "docs/video-pipeline.md"},]TOOL_GROUPS: list[dict[str, object]] = [diff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex bed62f9..b9af80c 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -25,6 +25,8 @@ from sprite_gen.video import clip_prompt as video_promptfrom sprite_gen.video import align as video_alignfrom sprite_gen.video import follow as video_followfrom sprite_gen.video import follow_inspect as video_follow_inspect+from sprite_gen.video import sway as video_sway+from sprite_gen.video import sway_inspect as video_sway_inspectfrom sprite_gen.video import set_sheet as video_set_sheetfrom sprite_gen.video import stop as video_stopfrom sprite_gen.video import compare as video_compare@@ -385,16 +387,16 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callabvideo_align.add_arguments,video_align.run,),- "video-follow": (- "A soft part of a looping body follows the body's motion: an ellipse of the strip moved as a damped mass on the body's own bob (after video-cycle-align).",- video_follow.add_arguments,- video_follow.run,+ "video-sway": (+ "The Sway layer: a soft part of a looping body sways with the body's motion, an ellipse of the strip moved as a damped mass on the body's own bob (after video-cycle-align). Old name video-follow, still run.",+ video_sway.add_arguments,+ video_sway.run,),- # The same request as video-follow, answered by the same code, written down instead of over the loop.- "video-follow-inspect": (- "Where video-follow carries each region in every cell and what it would change there, with nothing moved: a record and two boards of every cell, for whoever says what is inside an ellipse.",- video_follow_inspect.add_arguments,- video_follow_inspect.run,+ # The same request as video-sway, answered by the same code, written down instead of over the loop.+ "video-sway-inspect": (+ "Where video-sway carries each region in every cell and what it would change there, with nothing moved: a record and two boards of every cell, for whoever says what is inside an ellipse. Old name video-follow-inspect, still run.",+ video_sway_inspect.add_arguments,+ video_sway_inspect.run,),"video-set-sheet": ("The directions of one set on one sheet: rows in compass order (S SW W NW N NE E SE), one cell holding every body box, one ground line under every cell, no row scaled; an optional centre picture stood on the same line at the rows' standing height.",@@ -455,6 +457,14 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab}+# Old verb names, kept: each parses its new verb's arguments and runs its own module's `run`, which does the same+# and says the old name in what it prints.+VERB_ALIASES: dict[str, tuple[str, Callable[..., int]]] = {+ "video-follow": ("video-sway", video_follow.run),+ "video-follow-inspect": ("video-sway-inspect", video_follow_inspect.run),+}++def command_domains() -> dict[str, list[str]]:"""Verbs grouped by domain, derived from each verb's `run` module — never hand-listed."""groups: dict[str, list[str]] = {d: [] for d in _modules.DOMAIN_ORDER}@@ -488,7 +498,8 @@ def _build_parser() -> argparse.ArgumentParser:)sub = parser.add_subparsers(dest="command", required=True, metavar="<tool>")for name, (description, add_args, _run) in COMMANDS.items():- sp = sub.add_parser(name, description=description)+ aliases = [old for old, (new, _old_run) in VERB_ALIASES.items() if new == name]+ sp = sub.add_parser(name, aliases=aliases, description=description)add_args(sp)return parser@@ -503,7 +514,7 @@ def main(argv: list[str] | None = None) -> int:kwargs = vars(args).copy()kwargs.pop("_retired_pp", None)command = kwargs.pop("command")- _description, _add_args, run_fn = COMMANDS[command]+ run_fn = VERB_ALIASES[command][1] if command in VERB_ALIASES else COMMANDS[command][2]return run_fn(**kwargs)diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex 056190e..dec5835 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -97,7 +97,7 @@ from sprite_gen._deps import npfrom sprite_gen.gen import handedness as handed_modfrom sprite_gen.spec.runio import atomic_write_textfrom sprite_gen.util.gif_utils import save_clean_gif-from sprite_gen.video import follow as follow_mod+from sprite_gen.video import sway as sway_modfrom sprite_gen.video import held as held_modfrom sprite_gen.video import legs as legs_modfrom sprite_gen.video import loop as loop_mod@@ -668,7 +668,7 @@ def origin_of(loop_dir: Path, meta_path: Path, meta: dict[str, Any]) -> dict[strstrip = cut_strip(loop_dir, meta_path, meta)if strip is None:return meta["cycle_align"].get("origin")- return follow_mod.cut_origin(strip.read_bytes(), meta)+ return sway_mod.cut_origin(strip.read_bytes(), meta)def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: list[Image.Image], fps: float,@@ -691,11 +691,11 @@ def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: liststanding_frame=int(meta.get("body_ref_frame") or 0))# what build_strip does not own (how the cut was anchored) is carried over as it was; a# follow-through moved the old cycle's cells, so it is cleared and the record says so- if "follow" in meta or (loop_dir / loop_mod.FOLLOW_SOURCE).exists():+ if loop_mod.sway_recorded(meta) or (loop_dir / loop_mod.FOLLOW_SOURCE).exists():record["follow_cleared"] = True(loop_dir / loop_mod.FOLLOW_SOURCE).unlink(missing_ok=True)# a loop one cycle of which was taken out (`--cycles` k > 1) no longer holds the steps it was counted with- merged = {**{k: v for k, v in meta.items() if k not in strip_meta and k not in ("cycle_align", "follow")+ merged = {**{k: v for k, v in meta.items() if k not in strip_meta and k not in ("cycle_align", *loop_mod.SWAY_RECORD_KEYS)and not (k == "steps" and "cycle_taken" in record)}, **strip_meta}if meta.get("foot_anchor") and meta.get("foot_anchor") != "feet":merged["foot_anchor"] = meta["foot_anchor"]diff --git a/sprite_gen/video/compare.py b/sprite_gen/video/compare.pyindex 5a50688..139bf3c 100644--- a/sprite_gen/video/compare.py+++ b/sprite_gen/video/compare.py@@ -21,7 +21,8 @@ from PIL import Imagefrom sprite_gen._deps import npfrom sprite_gen.spec.runio import atomic_write_text-from sprite_gen.video import evidence, follow, repair, rife+from sprite_gen.video import evidence, repair, rife, sway+from sprite_gen.video import loop as loop_modfrom sprite_gen.video.interpolation_quality import faultsMETRIC_VERSION = "same-sample-defects-v1"@@ -134,7 +135,7 @@ class Loop:return {"artifacts": self.artifacts, "frames": len(self.frames), "cell": list(self.frames[0].size),"timing": {"delay_ms": self.delay, "duration_ms": self.delay * len(self.frames) if self.delay else None},"source_cut": self.meta.get("source_cut"), "producer": self.source_report.get("producer"),- "gait": self.source_report.get("gait"), "follow": "follow" in self.meta,+ "gait": self.source_report.get("gait"), "follow": loop_mod.sway_recorded(self.meta),"pixels_sha256": evidence.digest(b"".join(f.tobytes() for f in self.frames))}@@ -147,7 +148,7 @@ def _measure(loop: Loop) -> dict[str, Any]:quality = [rife.smear(f, frames[k - 1], frames[(k + 1) % len(frames)]) for k, f in enumerate(frames)]body: dict[str, Any]try:- y, x, height, worn = follow.body_motion(frames)+ y, x, height, worn = sway.body_motion(frames)body = {"x_px": x.tolist(), "y_px": y.tolist(), "height_px": height, "worn_px": worn}except ValueError as exc:body = {"unknown": str(exc)}diff --git a/sprite_gen/video/follow.py b/sprite_gen/video/follow.pyindex ce58ede..29ed55d 100644--- a/sprite_gen/video/follow.py+++ b/sprite_gen/video/follow.py@@ -1,897 +1,51 @@# SPDX-License-Identifier: Apache-2.0-"""`sprite-gen video-follow` — a soft part of a looping body follows the body's motion.+"""`sprite_gen.video.follow` — the Sway layer (`sprite_gen.video.sway`) under its old name.-A clip model draws a walk's body moving, but a soft part that hangs off it (a chest, a belly,-a pouch on a strap) mostly moves with the body as one piece, even when the prompt asks it to-bounce: at sprite size it reads as rigid. This puts that follow-through back after the loop is-cut.--Each frame of the strip is a cell of one cycle. The body's motion is read off the cells: how far-each cell's body lies from the first cell's. The silhouette is worn down from a quarter to half-of its depth in the first cell, so what swings on the body — a tail, a ponytail, an ear, a sword-or a rod held up, the legs and arms — is worn away and the head and torso are left; each cell is-laid where it overlaps the first cell most, worn alike, a pixel counting once for every level it-is still in, and then laid again on what the cells so laid have in common: what more than half of-them have at one place, so a part as thick as the body that is elsewhere in another cell (ears as-wide as the head, up in one cell and on the face in the next) does not pull that cell onto itself.-(Read off the top of the body instead, the motion was whatever came to the top: a-tail tip or a raised sword made it jump by the part's whole swing from one cell to the next.) A part-hung on the body is a damped mass: its offset x from where the body carries it answers the body's own-acceleration, x'' + 2·ζ·ω·x' + ω²·x = −body''. The loop repeats, so the answer is the periodic-steady state, solved per harmonic of the cycle: no start-up, no kick at a foot strike, and the-last frame leads into the first. `--gain` scales that physical answer and nothing else; it is-not normalised to a target size.--The part is an ellipse in the first cell (`--region cx,cy,rx,ry`, cell pixels), carried with-the body's bob. Inside it every pixel is moved by the offset times a weight that is 1 at the-centre and falls to 0 at the rim (cos²); outside it no pixel changes. The move is sampled as-premultiplied bilinear colour, so an edge never picks up the colour under a transparent pixel.-A move so large that the weight's slope folds the picture over (offset × π / (2 · radius) ≥ 1)-is refused. `--on-fold lower` gives each region the largest gain that does not fold it instead-(the offset grows in a straight line with the gain, so that gain is known without a search), and-never one under 1, the mass as measured: a region too small for that is held — it does not move,-and the record names it — and the strip is refused only when every region is.--The strip as it was before is kept as `follow.source.png` beside it; running the command again-reads from there, so a second follow-through never moves a moved strip. `video-loop` (a new-cut) and `video-cycle-align` (a new cycle) remove it, and the alignment records that the-follow-through was cleared. docs/video-pipeline.md section 6.--The regions are where somebody looked: in the first cell of the strip they were read on. An alignment-turns a loop to start elsewhere, and its first cell is then another; read again there, the motion is-taken from another cell 0 and the regions land on another place of the body. `--read-on <sha256>` names-the strip (as cut, before any follow-through) the regions were read on. That strip is this loop's own —-`same`, read as ever — or the cut this loop was aligned from (`video-cycle-align` records it, with its-reading and where every new cell is from): then the cut's reading is carried to each cell from the cut's-cell it is, the regions stay where they were read, and the damped mass is solved on the new order, length-and frame time (`transported`). A cell the alignment made between two of the cut's, or one that is not-the cut's cell pixel for pixel (a crop or a scale changed, and nothing records how), has no reading to-carry: refused `uncertain`, never carried by the nearest whole cell. Any other strip is refused-`no-match`. Without `--read-on` nothing of this is read or written.--`--stretch-floor D` asks every region's move to leave each pixel at least D of its area. The weight's-steepest slope is π/2 over each radius, so a move (ox, oy) leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of it —-by the way the region moves, where the fold rule reads the smaller radius whichever way it moves. Each-region takes the largest gain, in steps of GAIN_STEP, that keeps the floor in every cell, and never one-above what the fold rule gave it: the floor only lowers. Under it the fold rule's handling stands (under 1-held, every region held refused; `--on-fold refuse` refuses). The record names the floor and its policy.--What carries a region is the lay of the body's outline (`carry_basis`): whose pixels are inside the-carried ellipse is not read, and nothing here moves a region on a guess of it.-"""+Kept so an old call gives the old result: every name of the Sway layer reads through this module, and the+entry points that say their command's name (`follow_loop`, `read_request`, `solve`, `fold_notes`, `run`,+`main`, ...) say `video-follow`, as they always did. `sprite-gen video-follow` runs this."""from __future__ import annotations-import argparse-import hashlib-import io-import json-import math-import os-import re-import shutil-import sys-import tempfile-from dataclasses import dataclass-from pathlib import Pathfrom typing import Any-from PIL import Image--from sprite_gen._deps import np-from sprite_gen.spec.runio import atomic_write_text-from sprite_gen.util.gif_utils import save_clean_gif-from sprite_gen.video import loop as loop_mod--VERB = "video-follow"-# How the motion is read and a region moved, by name. `video-follow-inspect` writes it beside what it read, so-# what somebody saw under one way of reading is not taken for another's: a change that gives the same strip,-# regions and settings another carry, offset or picture takes a new name.-POLICY = "common-lay/damped-mass/cos2-bilinear/1"-FREQ_DEFAULT = 2.4 # Hz: a slow, soft part-ZETA_DEFAULT = 0.6 # damping ratio: it lags and settles, with no ringing-GAIN_DEFAULT = 2.5 # times the physical answer-GAIN_MEASURED = 1.0 # the mass as measured: `--on-fold lower` does not go under it-GAIN_STEP = 0.01 # a lowered gain is a whole number of these, so the report's `gain` is the `--gain` to pass-ON_FOLD_MODES = ("refuse", "lower")-HARMONICS = 6 # of the cycle, for the body's motion: a step's shape, not its noise-ALPHA_SOLID = 128-WORN_FROM, WORN_TO = 0.25, 0.5 # of the body's depth in the first cell: the levels its silhouette is worn down to-SOURCE = loop_mod.FOLLOW_SOURCE-# How a reading made on the cut is carried to a loop aligned from it (`--read-on`): per whole cell of the cut, by the-# alignment's record of where each cell is from, and only to a cell that is that cell pixel for pixel.-TRANSPORT_POLICY = "cut-reading/whole-cell/1"-# How `--stretch-floor` reads a region's least area: the cos² weight's closed form, by direction, never above the-# fold rule's gain.-STRETCH_POLICY = "stretch-floor/cos2-direction/1"-# What carries a region into a cell: the lay of the body's outline. Whose pixels the carried ellipse holds is not read.-CARRY_BASIS = {"reading": "outline-lay", "region": "unverified"}-READ_ON = re.compile(r"[0-9a-f]{64}") # a strip's sha256, as `--read-on` names it---def parse_region(text: str) -> tuple[float, float, float, float]:- try:- cx, cy, rx, ry = (float(v) for v in text.split(","))- except ValueError as exc:- raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry (four numbers), got {text!r}") from exc- if rx <= 0 or ry <= 0:- raise argparse.ArgumentTypeError(f"--region radii must be positive, got {text!r}")- return cx, cy, rx, ry---def parse_read_on(text: str) -> str:- if not READ_ON.fullmatch(text):- raise argparse.ArgumentTypeError(f"--read-on wants the sha256 of the strip the regions were read on (64 lowercase "- f"hexadecimal digits), got {text!r}")- return text---def _run_depth(solid: np.ndarray, axis: int) -> np.ndarray:- """Per solid pixel, how far along `axis` the nearest clear pixel is (1 beside one; past the cell's edge is clear)."""- m = np.moveaxis(solid, axis, -1)- n = m.shape[-1]- at = np.broadcast_to(np.arange(n), m.shape)- before = np.maximum.accumulate(np.where(m, -1, at), axis=-1)- after = np.minimum.accumulate(np.where(m, n, at)[..., ::-1], axis=-1)[..., ::-1]- return np.moveaxis(np.where(m, np.minimum(at - before, after - at), 0), -1, axis)---def wear(solid: np.ndarray, r: int) -> np.ndarray:- """`solid` worn down by r: the pixels whose square of side 2·r + 1 around them is solid."""- return _run_depth(_run_depth(solid, 1) > r, 0) > r---def depth(solid: np.ndarray) -> int:- """How deep the body is at its deepest: the most it is worn down by and still has a pixel, plus one."""- lo, hi = 0, (min(solid.shape) + 1) // 2 # worn by lo something is left; worn by hi nothing is- if not solid.any():- return 0- while hi - lo > 1:- mid = (lo + hi) // 2- lo, hi = (mid, hi) if wear(solid, mid).any() else (lo, mid)- return lo + 1---def _levels(solid: np.ndarray, worn: range) -> tuple[np.ndarray, int, int] | None:- """`solid` worn down by each of `worn`, as one number per pixel: how many of those levels the pixel is still- in. Each level lies inside the one before, so level i is where that number is over i. Cut to the box of the- first level, with that box's top and left; None when nothing is left of `solid` worn down by the first."""- level = wear(solid, worn[0])- if not level.any():- return None- ys, xs = np.nonzero(level.any(axis=1))[0], np.nonzero(level.any(axis=0))[0]- level = level[ys[0]: ys[-1] + 1, xs[0]: xs[-1] + 1]- inside = level.astype(np.int32)- for _ in worn[1:]:- # Worn down by one more pixel: a square of side 2·r + 3 is one of side 2·r + 1 grown by one each way.- across = np.pad(level, 1)- level = across[1:-1, :-2] & across[1:-1, 1:-1] & across[1:-1, 2:]- down = np.pad(level, 1)- level = down[:-2, 1:-1] & down[1:-1, 1:-1] & down[2:, 1:-1]- inside += level- return inside, int(ys[0]), int(xs[0])---def _fft_length(n: int) -> int:- """The first length from n on with no prime factor over 5: an FFT of it is fast."""- while True:- m = n- for p in (2, 3, 5):- while m % p == 0:- m //= p- if m == 1:- return n- n += 1---def _overlay(onto: tuple[list[np.ndarray], int, int], levels: tuple[np.ndarray, int, int]) -> tuple[int, int]:- """The shift (dx, dy) of a cell from what it is laid on: where `onto` — per level a whole number at every- pixel, with its top and left — moved by it, lands on the cell's own levels most, the numbers that land on- the cell's pixels summed at every level and the levels summed."""- (a, ya, xa), (b, yb, xb) = onto, levels- # Long enough that no move wraps round (a.h + b.h - 1 each way, and so on), and fast.- height, width = a[0].shape[0] + b.shape[0] - 1, a[0].shape[1] + b.shape[1] - 1- shape = (_fft_length(height), _fft_length(width))- # overlap[i, j]: what of `onto` lands on the cell's same level moved by (j - (a.w - 1), i - (a.h - 1)),- # summed over the levels, for every move that meets.- spectrum = sum(np.fft.rfft2((b > i).astype(np.float64), shape) * np.fft.rfft2(la[::-1, ::-1].astype(np.float64), shape)- for i, la in enumerate(a))- # Sums of whole numbers are whole numbers: rounded, the FFT's own rounding (not the same on every machine)- # is gone, so a tie is a tie on every machine, and it goes to the move nearest none.- overlap = np.rint(np.fft.irfft2(spectrum, shape)[:height, :width]).astype(np.int64)- shifts = [(int(j) - (a[0].shape[1] - 1) + xb - xa, int(i) - (a[0].shape[0] - 1) + yb - ya)- for i, j in np.argwhere(overlap == overlap.max())]- return min(shifts, key=lambda s: (s[0] ** 2 + s[1] ** 2, s[1], s[0]))---def _common(levels: list[tuple[np.ndarray, int, int]], lays: list[tuple[int, int]],- count: int) -> tuple[list[np.ndarray], int, int] | None:- """What the cells' bodies have in common, each cell moved back by its lay: per level (`count` of them) and- pixel, how many more of the cells are in that level there than are not (none, where no more are), cut to- the box of what is left, with that box's top and left; None when no pixel is in more than half of the cells.-- The head and torso are in every cell at one place and count the whole number of cells. What swings and is- thick enough to outlast the wearing — an ear as wide as the head, up in some cells and flopped onto the- face in others; a leg forward and back — is at any one place in half of the cells or fewer, and counts- nothing. A thick part that keeps one place in most of the cells counts as the body does: outlines alone- do not tell the two apart."""- tops = [top - dy for (_, top, _), (_, dy) in zip(levels, lays)]- lefts = [left - dx for (_, _, left), (dx, _) in zip(levels, lays)]- top, left = min(tops), min(lefts)- height = max(t + inside.shape[0] for t, (inside, _, _) in zip(tops, levels)) - top- width = max(l + inside.shape[1] for l, (inside, _, _) in zip(lefts, levels)) - left- cells_in = np.zeros((count, height, width), np.int32)- level = np.arange(count)[:, None, None]- for (inside, _, _), t, l in zip(levels, tops, lefts):- cells_in[:, t - top: t - top + inside.shape[0], l - left: l - left + inside.shape[1]] += inside > level- more = np.maximum(0, 2 * cells_in - len(levels))- # Each level lies inside the one before, in every cell: the first level's box holds them all.- ys, xs = np.nonzero(more[0].any(axis=1))[0], np.nonzero(more[0].any(axis=0))[0]- if not len(ys):- return None- return list(more[:, ys[0]: ys[-1] + 1, xs[0]: xs[-1] + 1]), top + int(ys[0]), left + int(xs[0])---def body_motion(cells: list[Image.Image]) -> tuple[np.ndarray, np.ndarray, int, list[int]]:- """Per cell: how far its body lies from cell 0's, down and across (px); the body's height in cell 0,- and the first and last level its silhouette is worn down to.-- The top of the body is whatever comes to the top — a tail tip, a ponytail, an ear, a sword held- up — and read there the motion jumps from cell to cell. What swings on the body is thinner than- the body it swings on: worn down by a quarter of the body's depth it is gone, and what is left- is the head and torso. Each cell is laid where its silhouette, worn down by every whole number- of pixels from a quarter to half of that depth, overlaps cell 0's, worn alike, most, the- overlaps of every level summed: a pixel counts once for each level it is still in, so the- deepest of the body counts most and nothing that comes and goes outweighs it, and a torso that- is shallower in one cell (an arm swung away from it) still counts at its shallower levels.-- That lay answers to everything left in cell 0, and a part as thick as the body is left: where- ears as wide as the head stand up in cell 0 and flop onto the face in another cell, the cell- is laid ears on ears, the body tens of pixels off. So the cells are laid a second time, on what- they have in common as first laid (`_common`), and that lay, less cell 0's own, is the motion:- the ears are at one place in too few cells to count, and the cell lies head on head and torso- on torso."""- solids = []- for k, cell in enumerate(cells):- solid = np.asarray(cell.getchannel("A")) >= ALPHA_SOLID- if not solid.any():- raise ValueError(f"cell {k} has no solid body")- solids.append(solid)- ys = np.nonzero(solids[0].any(axis=1))[0]- height0 = int(ys[-1] - ys[0])- deepest = depth(solids[0])- first = int(WORN_FROM * deepest)- worn = range(first, max(first + 1, int(WORN_TO * deepest)))- levels = []- for k, solid in enumerate(solids):- level = _levels(solid, worn)- if level is None:- raise ValueError(f"cell {k} has no body as deep as a quarter of cell 0's ({worn[0]} px)")- levels.append(level)- inside0, top0, left0 = levels[0]- lays = [_overlay(([inside0 > i for i in range(len(worn))], top0, left0), level) for level in levels]- common = _common(levels, lays, len(worn))- if common is None:- raise ValueError("no part of the body is at one place in more than half of the cells")- lays = [_overlay(common, level) for level in levels]- dx0, dy0 = lays[0]- return (np.asarray([dy - dy0 for _, dy in lays], float), np.asarray([dx - dx0 for dx, _ in lays], float),- height0, [worn[0], worn[-1]])---def _cells(strip: Image.Image, n: int, w: int, h: int) -> list[Image.Image]:- return [strip.crop((k * w, 0, (k + 1) * w, h)) for k in range(n)]---def _cell_sha256(cell: Image.Image) -> str:- """One cell's pixels, RGBA row by row: a cell drawn alike is the same one, whatever wrote its file."""- return hashlib.sha256(cell.tobytes()).hexdigest()---def cut_origin(strip_bytes: bytes, meta: dict[str, Any]) -> dict[str, Any]:- """What `video-cycle-align` keeps of a loop's strip as cut when it first aligns it (`cycle_align.origin`), so a- follow-through whose regions were read on that cut can be carried to the aligned loop (`--read-on`): the strip's- sha256 (the file's bytes, as `--read-on` names it), its cell size, scale and crop origin, which frame of the- cycle each of its cells is (`sample_indices`), each cell's pixels by sha256, and the body's motion as read on- it (`reading`: per cell how far its body lies from cell 0's, across and down, by `POLICY`). A strip whose body- cannot be read keeps `reading` None and says why. Reads the bytes given and nothing else."""- strip = Image.open(io.BytesIO(strip_bytes)).convert("RGBA")- n, w, h = int(meta["frames"]), int(meta["w"]), int(meta["h"])- rect, samples = meta.get("source_rect"), meta.get("sample_indices")- origin: dict[str, Any] = {- "strip_sha256": hashlib.sha256(strip_bytes).hexdigest(), "frames": n, "w": w, "h": h, "scale": meta.get("scale"),- "crop_origin": None if rect is None else list(rect[:2]),- # A cut made before its strip recorded the frames it took holds every frame of its cycle, or it was subsampled- # and which ones is not known.- "sample_indices": list(samples) if samples is not None else (list(range(n)) if n == meta.get("cycle_frames") else None),- }- if strip.size != (w * n, h):- return origin | {"cells_sha256": None, "reading": None,- "reading_why": f"the strip is {strip.size[0]}x{strip.size[1]}, its meta says {w * n}x{h}"}- cells = _cells(strip, n, w, h)- origin["cells_sha256"] = [_cell_sha256(cell) for cell in cells]- try:- rows, cols, height0, worn = body_motion(cells)- except ValueError as exc:- return origin | {"reading": None, "reading_why": str(exc)}- origin["reading"] = {"policy": POLICY, "carry_px": [[c, r] for c, r in zip(cols.tolist(), rows.tolist())],- "body_px": height0, "body_worn_px": worn}- return origin---def read_on_relation(meta: dict[str, Any], strip_sha256: str, read_on: str, *, verb: str = VERB) -> str:- """How the strip the regions were read on (`read_on`) stands to this loop: its own strip as cut (`same`), or the- cut it was aligned from (`transported`); refused `no-match` otherwise."""- if read_on == strip_sha256:- return "same"- origin = (meta.get("cycle_align") or {}).get("origin")- if origin is not None and origin.get("strip_sha256") == read_on:- return "transported"- aligned_from = f"the cut it was aligned from ({origin['strip_sha256']})" if origin else "a cut it was aligned from (none is recorded)"- raise SystemExit(f"{verb}: --read-on {read_on}: no-match — the regions were read on a strip that is neither this loop's "- f"strip as cut ({strip_sha256}) nor {aligned_from}; locate them again on this strip")---def transported_motion(meta: dict[str, Any], cells: list[Image.Image], read_on: str, *,- verb: str = VERB) -> tuple[np.ndarray, np.ndarray, int, list[int], list[int]]:- """The cut's reading carried to `cells`, the strip of a loop aligned from the cut `read_on` names: per cell how far- the body of the cut's cell it is lies from the cut's cell 0 (down, then across, as `body_motion` gives them), the- body's height and wear as read on the cut, and which cell of the cut each cell is.-- The alignment records where each cell is from (`cycle_align.cells_from`). A cell made between two of the cut's- has no reading, and is not given its nearer one's; a cell the record calls the cut's must be that cell pixel for- pixel, so a crop, a scale or a drawing changed since — and not recorded as a transform — is caught here. Either- is refused `uncertain`."""- record = meta.get("cycle_align") or {}- origin, cells_from = record["origin"], record.get("cells_from")-- def uncertain(why: str) -> SystemExit:- return SystemExit(f"{verb}: --read-on {read_on} is the cut this loop was aligned from, but uncertain: {why}; the "- "reading is not carried — only a whole cell of the cut carries it, and none is taken by rounding")-- reading = origin.get("reading")- if reading is None:- raise uncertain(f"the cut's reading was not recorded ({origin.get('reading_why')})")- if reading.get("policy") != POLICY:- raise uncertain(f"the cut was read as {reading.get('policy')}, and this engine reads as {POLICY}")- if not isinstance(cells_from, list) or len(cells_from) != len(cells):- raise uncertain(f"the alignment records where {len(cells_from) if isinstance(cells_from, list) else 'no'} cells are "- f"from, and the strip has {len(cells)}")- for k, entry in enumerate(cells_from):- if "source" not in entry:- i, j = entry["between"]- raise uncertain(f"cell {k} is made between the cut's frames {i} and {j} (t {entry['t']:g})")- (w, h), rect = cells[0].size, meta.get("source_rect")- now = (w, h, meta.get("scale"), None if rect is None else list(rect[:2]))- then = (origin["w"], origin["h"], origin["scale"], origin["crop_origin"])- # A cut made before the strip recorded its crop says nothing of where it was cropped: there the cells' pixels- # below are the whole test, as they are for every cell anyway.- if now[:3] != then[:3] or (then[3] is not None and now[3] != then[3]):- raise uncertain(f"the cut's crop or scale changed (cells {then[0]}x{then[1]} at scale {then[2]} from {then[3]}, now "- f"{w}x{h} at scale {now[2]} from {now[3]}) and no transform is recorded")- frames, digests = origin["sample_indices"], origin["cells_sha256"]- cut_cells = []- for k, (cell, entry) in enumerate(zip(cells, cells_from)):- i = entry["source"]- if frames is None or i not in frames:- raise uncertain(f"cell {k} is frame {i} of the cut's cycle, which the cut's strip does not hold")- j = frames.index(i)- if _cell_sha256(cell) != digests[j]:- raise uncertain(f"cell {k} is not the cut's cell {j} as drawn: its pixels differ")- cut_cells.append(j)- carry = reading["carry_px"]- return (np.asarray([carry[j][1] for j in cut_cells], float), np.asarray([carry[j][0] for j in cut_cells], float),- int(reading["body_px"]), list(reading["body_worn_px"]), cut_cells)---def follow_offsets(motion: np.ndarray, fps: float, *, freq: float, zeta: float, gain: float) -> np.ndarray:- """The part's offset from where the body carries it, per cell, in the cycle's steady state."""- n = len(motion)- spectrum = np.fft.rfft(motion - motion.mean())- k = np.arange(len(spectrum))- spectrum[k > HARMONICS] = 0- omega = 2 * math.pi * fps / n * k # each harmonic's angular frequency- w = 2 * math.pi * freq- # x = H·y with y the body's position: x'' + 2ζw x' + w² x = −y'' ⇒ H = Ω² / (w² − Ω² + 2iζwΩ)- response = omega ** 2 / (w ** 2 - omega ** 2 + 2j * zeta * w * omega)- return gain * np.fft.irfft(spectrum * response, n)---def fold_ratio(reach: float, radius: float) -> float:- """How near a move of `reach` px is to folding a region whose smaller radius is `radius`: at 1- the steepest part of the weight (cos², slope π / (2 · radius)) stops the picture, past it the- picture runs backwards."""- return reach * math.pi / (2 * radius)---def gain_limit(reach_per_gain: float, radius: float) -> float | None:- """The gain at which a region of that radius folds; no gain folds it when the body is still."""- return 2 * radius / (math.pi * reach_per_gain) if reach_per_gain > 0 else None---def lowered_gain(gain: float, reach_per_gain: float, radius: float) -> float:- """The largest gain, in steps of GAIN_STEP and no more than `gain`, that `fold_ratio` passes."""- limit = gain_limit(reach_per_gain, radius)- if limit is None:- return gain- steps = math.ceil(limit / GAIN_STEP) - 1 # under the limit, never on it- # The step count is rounded from floats: the one test that decides is `fold_ratio` itself.- while steps > 0 and fold_ratio(steps * GAIN_STEP * reach_per_gain, radius) >= 1:- steps -= 1- return min(gain, round(steps * GAIN_STEP, 2))---def stretch_per_gain(radii: tuple[float, float], across: np.ndarray, down: np.ndarray) -> tuple[float, int]:- """How much of a pixel's area a region's move takes per unit of gain, at its worst cell, and that cell: the cos²- weight is steepest at π/2 over each radius, so a move (ox, oy) leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of the area- (`across`, `down`: the move at gain 1, per cell)."""- rx, ry = radii- per_cell = (math.pi / 2) * np.hypot(across / rx, down / ry)- k = int(np.argmax(per_cell))- return float(per_cell[k]), k---def floor_gain(gain: float, per_gain: float, floor: float) -> float:- """The largest gain, in steps of GAIN_STEP and no more than `gain`, whose move leaves `floor` of a pixel's area or- more (1 − gain · `per_gain` ≥ `floor`)."""- if per_gain <= 0 or 1 - gain * per_gain >= floor:- return gain- steps = math.floor((1 - floor) / per_gain / GAIN_STEP) + 1- # The step count is rounded from floats: the one test that decides is the area left at the gain written.- while steps > 0 and 1 - round(steps * GAIN_STEP, 2) * per_gain < floor:- steps -= 1- return min(gain, round(steps * GAIN_STEP, 2))---def _sample(premultiplied: np.ndarray, sx: np.ndarray, sy: np.ndarray) -> np.ndarray:- h, w = premultiplied.shape[:2]- x0 = np.clip(np.floor(sx).astype(int), 0, w - 2)- y0 = np.clip(np.floor(sy).astype(int), 0, h - 2)- fx = np.clip(sx - x0, 0, 1)[..., None]- fy = np.clip(sy - y0, 0, 1)[..., None]- a, b = premultiplied[y0, x0], premultiplied[y0, x0 + 1]- c, d = premultiplied[y0 + 1, x0], premultiplied[y0 + 1, x0 + 1]- return (a * (1 - fx) + b * fx) * (1 - fy) + (c * (1 - fx) + d * fx) * fy---def region_weight(xx: np.ndarray, yy: np.ndarray, region: tuple[float, float, float, float],- shift: tuple[float, float]) -> np.ndarray:- """Per pixel of a cell, how much of a region's move it takes: 1 at the centre of the ellipse carried by- `shift`, 0 at its rim (cos²) and outside it. The pixels a region covers are those where this is over 0."""- cx, cy, rx, ry = region- r = np.sqrt(((xx - cx - shift[0]) / rx) ** 2 + ((yy - cy - shift[1]) / ry) ** 2)- return np.where(r < 1, np.cos(r * math.pi / 2) ** 2, 0)---def move_field(xx: np.ndarray, yy: np.ndarray, moves: list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]],- shift: tuple[float, float]) -> tuple[np.ndarray, np.ndarray, np.ndarray] | None:- """Per pixel of a cell: whether a region of `moves`, carried by `shift`, covers it, and how far it is moved- across and down. None when no region covers a pixel of the cell."""- weights = []- for regions, _ in moves:- weight = np.zeros(xx.shape, np.float32)- for region in regions:- weight = np.maximum(weight, region_weight(xx, yy, region, shift))- weights.append(weight)- inside = np.logical_or.reduce([weight > 0 for weight in weights])- if not inside.any():- return None- largest = np.argmax(np.stack([math.hypot(*offset) * weight for (_, offset), weight in zip(moves, weights)]), axis=0)[None]- move_x = np.take_along_axis(np.stack([offset[0] * weight for (_, offset), weight in zip(moves, weights)]), largest, 0)[0]- move_y = np.take_along_axis(np.stack([offset[1] * weight for (_, offset), weight in zip(moves, weights)]), largest, 0)[0]- return inside, move_x, move_y---def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]],- shift: tuple[float, float]) -> Image.Image:- """`cell` with each group of regions moved by its own offset (dx, dy), their centres carried by `shift`.-- The groups' offsets are one motion times their gains, so where regions of different groups- overlap the larger move wins: the move is the largest of the groups' weighted moves, which is- nowhere steeper than the steepest group's own."""- src = np.asarray(cell.convert("RGBA"), dtype=np.float32)- h, w = src.shape[:2]- yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)- field = move_field(xx, yy, moves, shift)- if field is None:- return cell.copy()- inside, move_x, move_y = field- pm = src.copy()- pm[..., :3] *= pm[..., 3:4] / 255- moved = _sample(pm, xx - move_x, yy - move_y)- alpha = np.clip(np.round(moved[..., 3:4]), 0, 255)- # Colour is read back from the premultiplied mix, and none is kept where the coverage- # rounds to nothing (the WebP check refuses colour under alpha 0).- moved[..., :3] = np.where(alpha > 0, moved[..., :3] * 255 / np.maximum(moved[..., 3:4], 1e-3), 0)- moved[..., 3:4] = alpha- out = np.where(inside[..., None], np.clip(np.round(moved), 0, 255), src).astype(np.uint8)- return Image.fromarray(out, "RGBA")---@dataclass(frozen=True, eq=False)-class Request:- """A follow-through asked of a loop directory, read and checked; nothing is written by reading it."""-- loop_dir: Path- name: str- meta_path: Path- meta_bytes: bytes- meta: dict[str, Any]- regions: list[tuple[float, float, float, float]]- gain: float- freq: float- zeta: float- on_fold: str- read_on: str | None = None # the sha256 of the strip as cut the regions were read on; None: this strip's, as ever- stretch_floor: float | None = None # the least area a moved pixel keeps; None: the fold rule alone-- @property- def strip_path(self) -> Path:- return self.loop_dir / f"{self.name}.strip.png"-- @property- def source_path(self) -> Path:- return self.loop_dir / SOURCE---def read_request(loop_dir: Path, regions: list[tuple[float, float, float, float]], *, gain: float = GAIN_DEFAULT,- freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, on_fold: str = "refuse", verb: str = VERB,- read_on: str | None = None, stretch_floor: float | None = None) -> Request:- loop_dir = loop_dir.expanduser().resolve()- # The numbers go into the record, which is JSON, and into the cells' arithmetic: a numpy number from a- # caller (an int64 has no JSON form) is read as the float the command line gives, so every caller of the- # same numbers writes the same strip and record.- regions = [tuple(float(v) for v in region) for region in regions]- gain, freq, zeta = float(gain), float(freq), float(zeta)- metas = sorted(loop_dir.glob("*.strip.json"))- if len(metas) != 1:- raise SystemExit(f"{verb}: {loop_dir}: expected one <name>.strip.json from video-loop, found {len(metas)}")- meta_path = metas[0]- name = meta_path.name[: -len(".strip.json")]- meta_bytes = meta_path.read_bytes()- meta = json.loads(meta_bytes.decode("utf-8"))- if meta.get("kind") == "one-shot" or meta.get("loop") is False:- raise SystemExit(f"{verb}: a one-shot plays once; the follow-through is a loop's steady state")- if not regions:- raise SystemExit(f"{verb}: at least one --region cx,cy,rx,ry")- if gain < 0 or freq <= 0 or not 0 < zeta:- raise SystemExit(f"{verb}: --gain must be 0 or more, --freq and --zeta above 0")- if on_fold not in ON_FOLD_MODES:- raise SystemExit(f"{verb}: unknown --on-fold {on_fold!r}; expected one of {', '.join(ON_FOLD_MODES)}")- if read_on is not None and not READ_ON.fullmatch(str(read_on)):- raise SystemExit(f"{verb}: --read-on wants the sha256 of the strip the regions were read on (64 lowercase "- f"hexadecimal digits), got {read_on!r}")- if stretch_floor is not None:- stretch_floor = float(stretch_floor)- if not 0 <= stretch_floor < 1: # a NaN is neither- raise SystemExit(f"{verb}: --stretch-floor is the least area a moved pixel keeps, at least 0 and under 1; got {stretch_floor:g}")- return Request(loop_dir, name, meta_path, meta_bytes, meta, regions, gain, freq, zeta, on_fold,- None if read_on is None else str(read_on), stretch_floor)---@dataclass(frozen=True, eq=False)-class Answer:- """What a request comes to on a strip: the body's motion, each region's gain, and every cell's move.-- `video-follow` writes it over the loop; `video-follow-inspect` writes it down and changes nothing. Both- read the carry, the offsets and the moved cells here, and nowhere else."""-- request: Request- cells: list[Image.Image]- cols: np.ndarray # per cell, how far its body lies from cell 0's: across- rows: np.ndarray # and down- height0: int- worn: list[int]- requested: float- reach_requested: float- reach_per_gain: float- radii: list[float]- gains: list[float] # per region; 0 where it is held- held: list[bool]- ratios: list[float]- moves: dict[float, tuple[np.ndarray, np.ndarray]] # per gain a region moves by, the offset per cell: across, down- reaches: dict[float, float]- gain: float # the largest any region moves by; dx, dy and reach are that gain's- dx: np.ndarray- dy: np.ndarray- reach: float- groups: list[tuple[list[tuple[float, float, float, float]], tuple[np.ndarray, np.ndarray]]]- read_on: dict[str, Any] | None = None # how the strip the regions were read on stands to this one (`--read-on`)- stretch: dict[str, Any] | None = None # the floor asked, and what it did to each region (`--stretch-floor`)-- def carry(self, k: int) -> tuple[float, float]:- """How far cell k's body lies from cell 0's, across and down: every region's ellipse is carried by it. Carried- from the cut, the cells' motion is already from the cut's cell 0, where the regions were read."""- if self.read_on is not None and self.read_on["relation"] == "transported":- return self.cols[k], self.rows[k]- return self.cols[k] - self.cols[0], self.rows[k] - self.rows[0]-- def moves_in(self, k: int) -> list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]]:- """Cell k's groups of regions, each with its offset in that cell."""- return [(group, (mx[k], my[k])) for group, (mx, my) in self.groups]-- def moved(self, k: int) -> Image.Image:- return move_regions(self.cells[k], self.moves_in(k), self.carry(k))-- def record(self) -> dict[str, Any]:- """The follow-through as the strip's meta records it; `video-follow` adds its animations' checks."""- request, requested = self.request, self.requested- return {- "regions": [list(r) for r in request.regions], "gain": self.gain, "freq_hz": request.freq, "zeta": request.zeta,- "harmonics": HARMONICS,- "source": SOURCE, "body_px": self.height0, "body_worn_px": self.worn,- "body_bob_px": [round(float(np.ptp(self.cols)), 2), round(float(np.ptp(self.rows)), 2)],- "dx_px": np.round(self.dx, 2).tolist(), "dy_px": np.round(self.dy, 2).tolist(),- "reach_px": round(self.reach, 2),- "gain_requested": requested, "on_fold": request.on_fold,- "fold": {- "lowered": any(g != requested for g in self.gains), "ratio": round(max(self.ratios), 3),- "reach_requested_px": round(self.reach_requested, 2), "reach_per_gain_px": round(self.reach_per_gain, 3),- # Where the regions took gains of their own, each says the gain it moved by and whether it- # was held still (gain 0); where they all took one, the strip's `gain` is every region's.- "regions": [{"radius_px": radius, "ratio": round(ratio, 3),- "gain_limit": None if (limit := gain_limit(self.reach_per_gain, radius)) is None else round(limit, 3)}- | ({} if len(set(self.gains)) == 1 else {"gain": g, "held": hold})- for radius, ratio, g, hold in zip(self.radii, self.ratios, self.gains, self.held)],- },- } | ({} if self.read_on is None else {"read_on": self.read_on}) | ({} if self.stretch is None else {"stretch": self.stretch}) \- | ({} if self.read_on is None and self.stretch is None else {"carry_basis": dict(CARRY_BASIS)})-+from sprite_gen.video import sway as _sway-def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str = VERB,- strip_sha256: str | None = None) -> Answer:- """The answer to `request` on `strip`, the loop's strip as cut (an RGBA picture; `strip_name` names its file- in a refusal, `strip_sha256` is its file's, read where the request names the strip its regions were read on).- Reads nothing else and writes nothing."""- meta, regions = request.meta, request.regions- gain, freq, zeta, on_fold = request.gain, request.freq, request.zeta, request.on_fold- n, w, h = int(meta["frames"]), int(meta["w"]), int(meta["h"])- if strip.size != (w * n, h):- raise SystemExit(f"{verb}: {strip_name} is {strip.size[0]}x{strip.size[1]}, the strip meta says {w * n}x{h}; "- "cut the loop again (video-loop)")- cells = _cells(strip, n, w, h)- read_on = None- if request.read_on is not None:- if strip_sha256 is None:- raise ValueError("solve: a request with read_on needs the strip's sha256")- read_on = {"sha256": request.read_on, "relation": read_on_relation(meta, strip_sha256, request.read_on, verb=verb)}- for cx, cy, rx, ry in regions:- if not (0 <= cx < w and 0 <= cy < h):- raise SystemExit(f"{verb}: --region centre {cx:g},{cy:g} is outside the {w}x{h} cell")- fps = 1000.0 / float(meta["delay_ms"])- if read_on is not None and read_on["relation"] == "transported":- # The cut's own reading, cell for cell: the regions are where they were read, on the cut's cell 0, and the- # damped mass answers that motion in this loop's order, length and frame time.- rows, cols, height0, worn, cut_cells = transported_motion(meta, cells, request.read_on, verb=verb)- read_on |= {"policy": TRANSPORT_POLICY, "cut_cells": cut_cells}- else:- try:- rows, cols, height0, worn = body_motion(cells)- except ValueError as exc:- raise SystemExit(f"{verb}: {exc}") from exc- dy = follow_offsets(rows, fps, freq=freq, zeta=zeta, gain=gain)- dx = follow_offsets(cols, fps, freq=freq, zeta=zeta, gain=gain)- reach = float(np.max(np.hypot(dx, dy)))- radii = [min(rx, ry) for _, _, rx, ry in regions]- smallest = min(radii)- requested, reach_requested = gain, reach- # The offset is the gain times the answer at gain 1, so one move decides every gain.- reach_per_gain = float(np.max(np.hypot(follow_offsets(cols, fps, freq=freq, zeta=zeta, gain=1.0),- follow_offsets(rows, fps, freq=freq, zeta=zeta, gain=1.0))))- gains, held = [requested] * len(regions), [False] * len(regions)- if fold_ratio(reach, smallest) >= 1:- if on_fold == "refuse":- raise SystemExit(f"{verb}: a move of {reach:.1f} px folds a region of radius {smallest:g} px over itself; "- "lower --gain or give the region larger radii")- # A gain for each region: every part hangs on the same body and answers the same motion, but- # how far it moves before it folds is its own size, so a small part (an ear) does not hold a- # large one (a chest) back. A region that does not fold keeps the gain asked for.- folds = [fold_ratio(reach, radius) >= 1 for radius in radii]- gains = [lowered_gain(requested, reach_per_gain, radius) if fold else requested for radius, fold in zip(radii, folds)]- # One that would have to go under the mass as measured does not move at all; the strip is- # refused only when that is every region.- held = [fold and g < GAIN_MEASURED for fold, g in zip(folds, gains)]- if all(held):- k = radii.index(max(radii)) # the largest folds at the largest gain: if it is held, every region is- every = f" (the largest of {len(regions)} regions: every one folds)" if len(regions) > 1 else ""- raise SystemExit(f"{verb}: a move of {reach:.1f} px folds a region of radius {radii[k]:g} px over itself{every}, and "- f"--on-fold lower would have to go under --gain {GAIN_MEASURED:g} (the mass as measured moves "- f"{reach_per_gain:.1f} px; the largest gain that does not fold is {gains[k]:g}); give the region larger radii")- gains = [0.0 if hold else g for g, hold in zip(gains, held)]- stretch = None- if request.stretch_floor is not None:- gains, held, stretch = _keep_floor(request, radii, gains, held, (follow_offsets(cols, fps, freq=freq, zeta=zeta, gain=1.0),- follow_offsets(rows, fps, freq=freq, zeta=zeta, gain=1.0)), verb)- # One move per gain: a region's offset is its gain times the answer at gain 1. The strip's `gain`- # is the largest any region moves by, and `dx_px`/`dy_px` and `reach_px` are that gain's.- moves = {g: (follow_offsets(cols, fps, freq=freq, zeta=zeta, gain=g), follow_offsets(rows, fps, freq=freq, zeta=zeta, gain=g))- for g, hold in zip(gains, held) if not hold}- reaches = {g: float(np.max(np.hypot(*move))) for g, move in moves.items()}- gain = max(moves)- dx, dy = moves[gain]- reach = reaches[gain]- ratios = [0.0 if hold else fold_ratio(reaches[g], radius) for radius, g, hold in zip(radii, gains, held)]- groups = [([r for r, rg, hold in zip(regions, gains, held) if rg == g and not hold], move) for g, move in moves.items()]- return Answer(request, cells, cols, rows, height0, worn, requested, reach_requested, reach_per_gain, radii, gains, held,- ratios, moves, reaches, gain, dx, dy, reach, groups, read_on, stretch)+VERB = _sway.OLD_VERB+follow_loop = _sway.follow_loop+follow_offsets = _sway.follow_offsets-def _keep_floor(request: Request, radii: list[float], gains: list[float], held: list[bool],- move: tuple[np.ndarray, np.ndarray], verb: str) -> tuple[list[float], list[bool], dict[str, Any]]:- """The fold rule's gains (`gains`, 0 where `held`) lowered where a region's move would leave a pixel less than- `--stretch-floor` of its area (`move`: across and down per cell at gain 1), and the record of it. A region is never- raised; one the floor takes under GAIN_MEASURED is held as the fold rule holds one, and the strip is refused when- every region is — or, under `--on-fold refuse`, when the floor lowers any."""- floor, requested = request.stretch_floor, request.gain- per = [stretch_per_gain((rx, ry), *move) for _, _, rx, ry in request.regions]- floored = [floor_gain(requested, q, floor) for q, _ in per]- lowered = [g if hold else min(g, f) for g, f, hold in zip(gains, floored, held)]- by_floor = [not hold and g < rule for g, rule, hold in zip(lowered, gains, held)]- if any(by_floor) and request.on_fold == "refuse":- least = min(1 - requested * q for (q, _), by in zip(per, by_floor) if by)- raise SystemExit(f"{verb}: --gain {requested:g} leaves a moved pixel {least:.3f} of its area, under --stretch-floor {floor:g}; "- "lower --gain, pass --on-fold lower or give the region larger radii")- now_held = [hold or (by and g < GAIN_MEASURED) for hold, by, g in zip(held, by_floor, lowered)]- if all(now_held):- k = radii.index(max(radii))- raise SystemExit(f"{verb}: --stretch-floor {floor:g} leaves every region held: to keep it each would move under --gain "- f"{GAIN_MEASURED:g} (the mass as measured; the largest region at {lowered[k]:g}); lower the floor or give "- "the regions larger radii")- final = [0.0 if hold else g for g, hold in zip(lowered, now_held)]- return final, now_held, {- "policy": STRETCH_POLICY, "floor": floor,- "regions": [{"per_gain": round(q, 6), "least_cell": cell, "rule_gain": rule, "floor_gain": f, "gain": g, "held": hold,- "least_area": 1.0 if hold else round(1 - g * q, 4), "under_measured": not hold and g < GAIN_MEASURED}- for (q, cell), rule, f, g, hold in zip(per, gains, floored, final, now_held)],- }+def __getattr__(name: str) -> Any:+ return getattr(_sway, name)-def follow_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], *, gain: float = GAIN_DEFAULT,- freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, board: Path | None = None,- on_fold: str = "refuse", read_on: str | None = None, stretch_floor: float | None = None) -> dict[str, Any]:- request = read_request(loop_dir, regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on,- stretch_floor=stretch_floor)- loop_dir, name, meta_path, meta = request.loop_dir, request.name, request.meta_path, request.meta- strip_path = request.strip_path- source = request.source_path- if not source.exists():- shutil.copyfile(strip_path, source)- data = source.read_bytes()- answer = solve(request, Image.open(io.BytesIO(data)).convert("RGBA"), strip_name=source.name,- strip_sha256=hashlib.sha256(data).hexdigest())- cells = answer.cells- n, (w, h) = len(cells), cells[0].size- out = [answer.moved(k) for k in range(n)]- joined = Image.new("RGBA", (w * n, h), (0, 0, 0, 0))- for k, c in enumerate(out):- joined.alpha_composite(c, (k * w, 0))- delay_ms = max(20, round(float(meta["delay_ms"])))- gif_path, webp_path = loop_dir / f"{name}.gif", loop_dir / f"{name}.webp"- # Written and checked beside the loop first, each under its own name, and moved over the loop's files- # only once the record is written too: a run that fails on the way (an animation that fails its check, a- # record that does not serialise) leaves the strip, its animations and its record as they were. Staged as- # files, not as payloads in memory (runio.atomic_write_set): img2webp writes a file, and the check reads one.- stage = Path(tempfile.mkdtemp(prefix=".follow.", dir=loop_dir))- try:- staged = {path: stage / path.name for path in (strip_path, gif_path, webp_path, meta_path)}- joined.save(staged[strip_path])- save_clean_gif(out, staged[gif_path], duration_ms=delay_ms, loop=0, alpha_threshold=128)- loop_mod.write_webp(out, staged[webp_path], delay_ms=delay_ms, workdir=stage / ".webp-frames")- # a cell left as it was beside its twin (a filmed ghost given way to the frame beside it) is one frame of both- shown = loop_mod.shown_runs(out)- record = {- **answer.record(),- "gif": loop_mod.verify_animation(staged[gif_path], expect_frames=shown, check_stale=False),- "webp": loop_mod.verify_animation(staged[webp_path], expect_frames=shown, check_stale=True),- }- atomic_write_text(staged[meta_path], json.dumps({**meta, "follow": record}, indent=2) + "\n")- for path, written in staged.items(): # the record last, as it was written last- os.replace(written, path)- finally:- shutil.rmtree(stage, ignore_errors=True)- if board is not None:- _board(cells, out, answer.dy, board)- record["board"] = str(board)- return {"strip": str(strip_path), **record}+def read_request(*args: Any, **kwargs: Any) -> Any:+ return _sway.read_request(*args, **{"verb": VERB, **kwargs})-def _board(before: list[Image.Image], after: list[Image.Image], dy: np.ndarray, path: Path) -> None:- """Before and after, side by side on white, at the frames where the part sits lowest and highest."""- picks = [int(np.argmax(dy)), int(np.argmin(dy))]- w, h = before[0].size- board = Image.new("RGB", (w * 4 + 30, h), (128, 128, 128))- x = 0- for k in picks:- for cell in (before[k], after[k]):- ground = Image.new("RGBA", (w, h), (255, 255, 255, 255))- ground.alpha_composite(cell)- board.paste(ground.convert("RGB"), (x, 0))- x += w + 10- path.parent.mkdir(parents=True, exist_ok=True)- board.save(path)+def solve(*args: Any, **kwargs: Any) -> Any:+ return _sway.solve(*args, **{"verb": VERB, **kwargs})-def add_request_arguments(parser: argparse.ArgumentParser) -> None:- """What a follow-through is asked with; `video-follow-inspect` takes the same and is asked alike."""- parser.add_argument("--loop-dir", required=True, type=Path, help="a video-loop output directory (after video-cycle-align, if the set is aligned)")- parser.add_argument("--region", action="append", type=parse_region, required=True,- help="cx,cy,rx,ry: an ellipse over the soft part in the strip's first cell, in cell pixels (repeatable)")- parser.add_argument("--gain", type=float, default=GAIN_DEFAULT, help=f"times the physical answer (default {GAIN_DEFAULT:g}; 1 is the mass as measured, 0 leaves the strip as it was)")- parser.add_argument("--on-fold", choices=ON_FOLD_MODES, default="refuse",- help=f"a move that folds a region over itself: refuse (default), or lower — each region takes the largest gain that does "- f"not fold it, never under {GAIN_MEASURED:g} (the mass as measured): a region that would have to is held still and "- "named in the record, and the strip is refused only when every region is")- parser.add_argument("--freq", type=float, default=FREQ_DEFAULT, help=f"the part's own frequency in Hz (default {FREQ_DEFAULT:g})")- parser.add_argument("--zeta", type=float, default=ZETA_DEFAULT, help=f"damping ratio (default {ZETA_DEFAULT:g}: lags and settles, no ringing)")- parser.add_argument("--read-on", type=parse_read_on, default=None, metavar="SHA256",- help="the sha256 of the strip as cut (before any follow-through) the regions were read on: this loop's own is "- "read as without it (relation same); the cut this loop was aligned from (video-cycle-align records it) has "- "its reading carried cell for cell (transported); a made cell or a cell geometry nothing records is "- "refused uncertain, any other strip no-match. Without it nothing of this is read or written")- parser.add_argument("--stretch-floor", type=float, default=None, metavar="D",- help="the least area, 0 to under 1, a moved pixel keeps, read by the way each region moves: each region takes "- "the largest gain that keeps it, never above the fold rule's; under it the fold rule's handling stands "- f"(held under {GAIN_MEASURED:g}, every region held refused; --on-fold refuse refuses). No default: without "- "it the fold rule alone")+def read_on_relation(*args: Any, **kwargs: Any) -> str:+ return _sway.read_on_relation(*args, **{"verb": VERB, **kwargs})-def add_arguments(parser: argparse.ArgumentParser) -> None:- add_request_arguments(parser)- parser.add_argument("--board", type=Path, help="write a before/after picture at the frames where the part sits lowest and highest")+def transported_motion(*args: Any, **kwargs: Any) -> Any:+ return _sway.transported_motion(*args, **{"verb": VERB, **kwargs})def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:- """What to say of a record whose gain was lowered or whose regions were held, a line each."""- fold, notes = record["fold"], []- if "stretch" in record: # a floor was asked: each region says what lowered it, the fold or the floor- floor = record["stretch"]["floor"]- for (cx, cy, rx, ry), entry, folded in zip(record["regions"], record["stretch"]["regions"], fold["regions"]):- name = f"--region {cx:g},{cy:g},{rx:g},{ry:g}"- if entry["held"]:- why = (f"folds at --gain {folded['gain_limit']:g}" if entry["rule_gain"] == 0 else- f"keeps --stretch-floor {floor:g} only at --gain {entry['floor_gain']:g}")- notes.append(f"{verb}: {name} {why}, under {GAIN_MEASURED:g} (the mass as measured): it is held, and does not move")- elif entry["gain"] != record["gain_requested"]:- by = f"--stretch-floor {floor:g}" if entry["gain"] < entry["rule_gain"] else "the fold"- notes.append(f"{verb}: {name} moves at --gain {entry['gain']:g}, lowered from {record['gain_requested']:g} by {by}")- return notes- if "held" in fold["regions"][0]: # the regions took gains of their own- for (cx, cy, rx, ry), entry in zip(record["regions"], fold["regions"]):- name = f"--region {cx:g},{cy:g},{rx:g},{ry:g}"- if entry["held"]:- notes.append(f"{verb}: {name} folds at --gain {entry['gain_limit']:g}, under {GAIN_MEASURED:g} (the mass as measured): "- "it is held, and does not move")- elif entry["gain"] != record["gain_requested"]:- notes.append(f"{verb}: --gain {record['gain_requested']:g} folds {name} (a move of {fold['reach_requested_px']:g} px); "- f"lowered to --gain {entry['gain']:g} for it")- elif fold["lowered"]:- notes.append(f"{verb}: --gain {record['gain_requested']:g} folds a region (a move of {fold['reach_requested_px']:g} px); "- f"lowered to --gain {record['gain']:g}")- return notes+ return _sway.fold_notes(record, verb)def run(**kwargs: object) -> int:- result = follow_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), # type: ignore[arg-type]- gain=float(kwargs.get("gain", GAIN_DEFAULT)), freq=float(kwargs.get("freq", FREQ_DEFAULT)), # type: ignore[arg-type]- zeta=float(kwargs.get("zeta", ZETA_DEFAULT)), board=kwargs.get("board"), # type: ignore[arg-type]- on_fold=str(kwargs.get("on_fold") or "refuse"), read_on=kwargs.get("read_on"), # type: ignore[arg-type]- stretch_floor=kwargs.get("stretch_floor")) # type: ignore[arg-type]- fold = result["fold"]- own = "held" in fold["regions"][0] # the regions took gains of their own- for note in fold_notes(result):- print(note, file=sys.stderr)- print(json.dumps({k: result[k] for k in ("strip", "regions", "gain", "gain_requested", "on_fold", "body_bob_px", "reach_px")}- | ({"region_gains": [entry["gain"] for entry in fold["regions"]]} if own else {})- | ({"read_on": result["read_on"]["relation"]} if "read_on" in result else {})- | ({"stretch_floor": result["stretch"]["floor"]} if "stretch" in result else {})- | ({"board": result["board"]} if "board" in result else {}), ensure_ascii=False, indent=2))- return 0+ return _sway.run(**{"verb": VERB, **kwargs})def main(argv: list[str] | None = None) -> int:- parser = argparse.ArgumentParser(prog="sprite-gen video-follow", description=__doc__)- add_arguments(parser)- return run(**vars(parser.parse_args(argv)))+ return _sway.main(argv, verb=VERB)if __name__ == "__main__":diff --git a/sprite_gen/video/follow_inspect.py b/sprite_gen/video/follow_inspect.pyindex d23fb58..1831361 100644--- a/sprite_gen/video/follow_inspect.py+++ b/sprite_gen/video/follow_inspect.py@@ -1,409 +1,34 @@# SPDX-License-Identifier: Apache-2.0-"""`sprite-gen video-follow-inspect` — where a follow-through carries its regions in every cell, with nothing moved.+"""`sprite_gen.video.follow_inspect` — `sprite_gen.video.sway_inspect` under its old name.-`video-follow` is given an ellipse over a soft part in the strip's first cell and carries it with the body-into every other cell; inside the carried ellipse every pixel moves, whatever it is a picture of. For the-first cell somebody looked and said where the part is. For the others nobody did: an arm that swings across-a chest is inside the chest's ellipse in those cells, and moves with it. The engine does not read what a-pixel belongs to, and it does not guess it here either: every region is written `ownership: unknown` in-every cell, from its centre to its rim, the first cell included.--This command writes what somebody needs in order to look, and changes nothing. It takes what `video-follow`-takes, reads the loop as `video-follow` would (the strip as cut: `follow.source.png` where a follow-through-was already written, the strip itself where none was) and solves it with the same code (`follow.read_request`,-`follow.solve`). Into `--out-dir`, which is never the loop directory, it writes:--- `follow-inspect.json`, the record: what was read (the strip's and the meta's sha256, the regions, the- settings, the engine and the way it reads, and `input_id`, one sha256 over those); the follow-through as- `video-follow` would record it (`follow`); per cell how far the regions are carried (`carry_px`) and, per- region, the carried ellipse, its offset, how near that is to folding it, the least area of the source a- pixel of the moved cell takes (`jacobian_min`: 1 where nothing moves, 0 where the picture stops and one- pixel of the source is drawn across many, under 0 where it would run backwards), how many pixels the- ellipse covers and how many of them are body, and how many the move changes;-- `follow-inspect.source.png`, every cell of the strip as cut with each region's carried ellipse ringed;-- `follow-inspect.moved.png`, the same cells as `video-follow` would write them, ringed alike.--A move does three things to the picture, and the record (schema 2) writes each apart. It stretches it: the least-area a pixel takes (`jacobian_min`, D). It tilts a line: the move's steepest slope, |offset|·π/(2·smaller radius)-(`bend`, G, and `bend_deg` = atan G) — the old `fold_ratio` is this number, and at 1 a line tilts 45°. And where-two regions overlap, the larger move takes over across a curve and the slope jumps there: per pair, the largest-jump on that curve (`seams`: the norm of the difference of the two moves' gradients, and its angle). A floor on-the area (`--stretch-floor`) holds D up and lowers G and the seam only with it.--The two boards are apart so that whoever says what is inside an ellipse can read the cells as cut alone,-without the answer beside them. The record holds no path, no time and nothing of the machine: the same loop-asked the same way writes the same record. `input_id` does not change when `video-follow` is run on the loop-(it reads the strip as cut, and the meta without the `follow` record `video-follow` adds) and changes with-anything the answer is read from — a new cut, an alignment, a region, a setting, the engine. The boards'-`pixels_sha256` is over their pixels, so another PNG writer gives the same one; how the boards are drawn-(`--scale`, `--columns`) is no part of `input_id`. docs/video-pipeline.md section 6.-"""+Kept so an old call gives the old result: every name reads through this module, and the entry points say+`video-follow-inspect`, as they always did. `sprite-gen video-follow-inspect` runs this."""from __future__ import annotations-import argparse-import hashlib-import io-import json-import math-import sys-from importlib.metadata import PackageNotFoundError, version as package_versionfrom pathlib import Pathfrom typing import Any-from PIL import Image--from sprite_gen._deps import np-from sprite_gen.spec.runio import atomic_write_set-from sprite_gen.video import follow--VERB = "video-follow-inspect"-KIND = "video-follow-inspection"-SCHEMA_VERSION = 2 # 2: the bend and the seams beside the least area; the read_on and the stretch floor asked-RECORD, SOURCE_BOARD, MOVED_BOARD = "follow-inspect.json", "follow-inspect.source.png", "follow-inspect.moved.png"-UNKNOWN = "unknown" # what is inside a carried ellipse: the engine does not read it-SCALE_DEFAULT = 2 # board pixels per cell pixel: at 2 or more a ring covers no cell pixel whole-COLUMNS_DEFAULT = 8-PLACES = 4 # decimals of the offsets, ratios and areas: under what two machines' FFTs differ by-DEGREES = 2 # decimals of an angle-SEAM_STEP = 0.25 # px between the points along each row where a seam is looked for, before it is found by halving-SEAM_HALVINGS = 30-GROUND = (128, 128, 128) # under a cell's clear pixels-BETWEEN = (32, 32, 32) # between the cells, and under their numbers-INK = (255, 255, 255) # a cell's number-DARK = (0, 0, 0) # every other dash of a ring, so it shows on any colour-RINGS = ((255, 235, 0), (0, 255, 255), (255, 96, 0), (0, 255, 96), (255, 0, 200), (120, 160, 255)) # by region; they repeat-DASH = 2 # board pixels of a ring in its colour, then as many dark-GAP = 6 # board pixels between cells-DOT = 3 # board pixels per dot of a digit-PAD = 3 # above and under a cell's number-DIGITS = {- "0": ("###", "# #", "# #", "# #", "###"), "1": (" # ", "## ", " # ", " # ", "###"), "2": ("###", " #", "###", "# ", "###"),- "3": ("###", " #", "###", " #", "###"), "4": ("# #", "# #", "###", " #", " #"), "5": ("###", "# ", "###", " #", "###"),- "6": ("###", "# ", "###", "# #", "###"), "7": ("###", " #", " #", " #", " #"), "8": ("###", "# #", "###", "# #", "###"),- "9": ("###", "# #", "###", " #", "###"),-}---def _sha256(data: bytes) -> str:- return hashlib.sha256(data).hexdigest()---def _canonical(value: Any) -> bytes:- """One spelling of a JSON value: keys sorted, no spaces, ASCII."""- return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("ascii")---def _engine_version() -> str:- try:- return package_version("sprite-gen")- except PackageNotFoundError: # pragma: no cover - bare checkout- return "unknown"---def policy() -> dict[str, Any]:- """The way the motion is read and a region moved: its name and the numbers it is fixed by; the way a reading- is carried from a cut (`--read-on`) and a floor kept (`--stretch-floor`), by name."""- return {"name": follow.POLICY, "harmonics": follow.HARMONICS, "alpha_solid": follow.ALPHA_SOLID,- "worn": [follow.WORN_FROM, follow.WORN_TO], "gain_measured": follow.GAIN_MEASURED, "gain_step": follow.GAIN_STEP,- "weight": "cos2", "transport": follow.TRANSPORT_POLICY, "stretch_floor": follow.STRETCH_POLICY}---def _degrees(slope: float) -> float:- return round(math.degrees(math.atan(slope)), DEGREES)---def _weight_and_gradient(x: np.ndarray, y: np.ndarray, ellipse: tuple[float, float, float, float]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:- """A region's weight at points (x, y) — cos² of the ellipse's own radius, 0 at its rim and outside — and the- weight's gradient there, across and down."""- cx, cy, rx, ry = ellipse- u, v = (x - cx) / rx, (y - cy) / ry- r = np.hypot(u, v)- inside = r < 1- weight = np.where(inside, np.cos(r * math.pi / 2) ** 2, 0.0)- slope = np.where(inside & (r > 0), -(math.pi / 2) * np.sin(math.pi * r) / np.where(r > 0, r, 1.0), 0.0)- return weight, slope * u / rx, slope * v / ry---def seam(a: tuple[float, float, float, float], b: tuple[float, float, float, float], move_a: tuple[float, float],- move_b: tuple[float, float], one_gain: bool) -> tuple[float, list[float]] | None:- """Where two overlapping regions, carried into a cell and moved by their own offsets, meet: `video-follow` moves a- pixel by the larger of their weighted moves (by the larger weight where they move by one gain), so across the- curve where the two are equal the move's gradient jumps from one region's to the other's, and a straight line- bends there. The largest jump on that curve — the norm of the difference of the two gradients (each the offset- times its weight's gradient) — and the point it is at; None where no such curve is inside both.-- The curve is looked for along rows SEAM_STEP apart, between points SEAM_STEP apart inside both ellipses where the- larger move changes hands, and found there by halving."""- xs = np.arange(int((max(a[0] + a[2], b[0] + b[2]) - min(a[0] - a[2], b[0] - b[2])) / SEAM_STEP) + 1) * SEAM_STEP + min(a[0] - a[2], b[0] - b[2])- ys = np.arange(int((max(a[1] + a[3], b[1] + b[3]) - min(a[1] - a[3], b[1] - b[3])) / SEAM_STEP) + 1) * SEAM_STEP + min(a[1] - a[3], b[1] - b[3])- reach_a, reach_b = (1.0, 1.0) if one_gain else (math.hypot(*move_a), math.hypot(*move_b))-- def larger(x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:- wa, wb = _weight_and_gradient(x, y, a)[0], _weight_and_gradient(x, y, b)[0]- return reach_a * wa - reach_b * wb, (wa > 0) & (wb > 0)-- yy, xx = np.meshgrid(ys, xs, indexing="ij")- difference, both = larger(xx, yy)- above = difference > 0- rows, cols = np.nonzero(both[:, :-1] & both[:, 1:] & (above[:, :-1] != above[:, 1:]))- if not len(rows):- return None- lo, hi, y, left = xs[cols], xs[cols + 1], ys[rows], above[rows, cols]- for _ in range(SEAM_HALVINGS): # the two ellipses' common part is convex: every midpoint is inside both- mid = (lo + hi) / 2- same_side = (larger(mid, y)[0] > 0) == left- lo, hi = np.where(same_side, mid, lo), np.where(same_side, hi, mid)- x = (lo + hi) / 2- _, ax, ay = _weight_and_gradient(x, y, a)- _, bx, by = _weight_and_gradient(x, y, b)- (oax, oay), (obx, oby) = move_a, move_b- jump = np.sqrt((oax * ax - obx * bx) ** 2 + (oax * ay - obx * by) ** 2 + (oay * ax - oby * bx) ** 2 + (oay * ay - oby * by) ** 2)- k = int(np.argmax(jump))- return float(jump[k]), [round(float(x[k]), 3), round(float(y[k]), 3)]---def jacobian(move_x: np.ndarray, move_y: np.ndarray) -> np.ndarray:- """Per pixel of a moved cell, but for those on its edge, the area of the source it takes. The moved cell's- pixel p is read from the source at p less its move, so the area is read between p's neighbours on either- side, across and down, as half of how far apart those are read: 1 where nothing moves, 0 where the picture- stops, under 0 where it runs backwards. Between the neighbours on either side, not from p to the next pixel- one way: read one way, a round region a few pixels across reads steeper on the side it bulges to than its- weight is anywhere. One row and one column shorter than the cell at each edge."""- across_x, across_y = (move_x[1:-1, 2:] - move_x[1:-1, :-2]) / 2, (move_y[1:-1, 2:] - move_y[1:-1, :-2]) / 2- down_x, down_y = (move_x[2:, 1:-1] - move_x[:-2, 1:-1]) / 2, (move_y[2:, 1:-1] - move_y[:-2, 1:-1]) / 2- return (1 - across_x) * (1 - down_y) - down_x * across_y---def _least(area: np.ndarray | None, mask: np.ndarray) -> tuple[float, list[int] | None]:- """The least of `area` over the pixels of `mask`, and that pixel (x, y); 1 and no pixel where nothing moves- there."""- if area is None:- return 1.0, None- inner = mask[1:-1, 1:-1]- if not inner.any():- return 1.0, None- values = np.where(inner, area, np.inf)- y, x = divmod(int(np.argmin(values)), values.shape[1])- return float(values[y, x]), [x + 1, y + 1]---def _grown(mask: np.ndarray) -> np.ndarray:- """`mask` and the pixels beside it: above, under, left and right."""- grown = mask.copy()- grown[1:] |= mask[:-1]- grown[:-1] |= mask[1:]- grown[:, 1:] |= mask[:, :-1]- grown[:, :-1] |= mask[:, 1:]- return grown---def _tile(cell: Image.Image, masks: list[np.ndarray], scale: int) -> np.ndarray:- """A cell on the board: over the ground, `scale` board pixels to a cell pixel, each region's ring drawn on the- board pixels just outside its ellipse — inside an ellipse nothing is drawn but another region's ring."""- ground = Image.new("RGBA", cell.size, (*GROUND, 255))- ground.alpha_composite(cell)- tile = np.repeat(np.repeat(np.asarray(ground.convert("RGB")), scale, axis=0), scale, axis=1)- yy, xx = np.mgrid[0:tile.shape[0], 0:tile.shape[1]]- lit = (xx + yy) // DASH % 2 == 0- for i, mask in enumerate(masks):- covered = np.repeat(np.repeat(mask, scale, axis=0), scale, axis=1)- ring = _grown(covered) & ~covered- tile[ring & lit] = RINGS[i % len(RINGS)]- tile[ring & ~lit] = DARK- return tile---def _number(board: np.ndarray, text: str, x: int, y: int) -> None:- for char in text:- for row, dots in enumerate(DIGITS[char]):- for col, dot in enumerate(dots):- if dot == "#":- board[y + row * DOT: y + (row + 1) * DOT, x + col * DOT: x + (col + 1) * DOT] = INK- x += 4 * DOT---def _boards(tiles: list[list[np.ndarray]], columns: int) -> tuple[list[np.ndarray], list[list[int]]]:- """One board per list of tiles, all laid alike: the cells in order, `columns` to a row, each under its number- (cell 0 first). With them, per cell, the box (x0, y0, x1, y1) its picture takes on every board."""- n = len(tiles[0])- tile_h, tile_w = tiles[0][0].shape[:2]- label = 5 * DOT + 2 * PAD- across, down = min(n, columns), math.ceil(n / columns)- size = (GAP + down * (label + tile_h + GAP), GAP + across * (tile_w + GAP), 3)- boards = [np.full(size, BETWEEN, np.uint8) for _ in tiles]- boxes = []- for k in range(n):- x0 = GAP + (k % columns) * (tile_w + GAP)- y0 = GAP + (k // columns) * (label + tile_h + GAP) + label- boxes.append([x0, y0, x0 + tile_w, y0 + tile_h])- for board, cells in zip(boards, tiles):- _number(board, str(k), x0, y0 - label + PAD)- board[y0: y0 + tile_h, x0: x0 + tile_w] = cells[k]- return boards, boxes---def _png(board: np.ndarray) -> bytes:- data = io.BytesIO()- Image.fromarray(board).save(data, format="PNG")- return data.getvalue()+from sprite_gen.video import sway_inspect as _inspect+VERB = _inspect.OLD_VERB-def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], out_dir: Path, *,- gain: float = follow.GAIN_DEFAULT, freq: float = follow.FREQ_DEFAULT, zeta: float = follow.ZETA_DEFAULT,- on_fold: str = "refuse", scale: int = SCALE_DEFAULT, columns: int = COLUMNS_DEFAULT,- read_on: str | None = None, stretch_floor: float | None = None) -> dict[str, Any]:- """The record of what `video-follow` asked the same way does to the loop, written with its two boards into- `out_dir`. The loop directory is read and not written."""- request = follow.read_request(loop_dir, regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, verb=VERB,- read_on=read_on, stretch_floor=stretch_floor)- out_dir = out_dir.expanduser().resolve()- if out_dir == request.loop_dir or request.loop_dir in out_dir.parents:- raise SystemExit(f"{VERB}: --out-dir {out_dir} is in the loop directory; an inspection writes nothing there")- scale, columns = int(scale), int(columns)- if scale < 1 or columns < 1:- raise SystemExit(f"{VERB}: --scale and --columns must be 1 or more")- # The strip as cut, as `video-follow` reads it; it keeps one beside the loop on its first run, and this does not.- strip_path = request.source_path if request.source_path.exists() else request.strip_path- strip_bytes = strip_path.read_bytes()- answer = follow.solve(request, Image.open(io.BytesIO(strip_bytes)).convert("RGBA"), strip_name=strip_path.name, verb=VERB,- strip_sha256=_sha256(strip_bytes))- n, (w, h) = len(answer.cells), answer.cells[0].size- yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)- cells, source_tiles, moved_tiles = [], [], []- for k in range(n):- carry = answer.carry(k)- before, moved = np.asarray(answer.cells[k]), answer.moved(k)- changed = (before != np.asarray(moved)).any(axis=-1)- solid = before[..., 3] >= follow.ALPHA_SOLID- field = follow.move_field(xx, yy, answer.moves_in(k), carry)- area = None if field is None else jacobian(field[1], field[2])- masks = [follow.region_weight(xx, yy, region, carry) > 0 for region in request.regions]- entries, offsets = [], []- for i, ((cx, cy, rx, ry), radius, g, hold, mask) in enumerate(zip(request.regions, answer.radii, answer.gains,- answer.held, masks)):- dx, dy = (0.0, 0.0) if hold else (float(answer.moves[g][0][k]), float(answer.moves[g][1][k]))- offsets.append((dx, dy))- least, at = _least(area, mask)- bend = follow.fold_ratio(math.hypot(dx, dy), radius) # the move's steepest slope: G- entries.append({- "index": i, "ellipse": [round(cx + float(carry[0]), 6), round(cy + float(carry[1]), 6), rx, ry],- "offset_px": [round(dx, PLACES) + 0.0, round(dy, PLACES) + 0.0], "reach_px": round(math.hypot(dx, dy), PLACES),- "fold_ratio": round(bend, PLACES),- "jacobian_min": round(least, PLACES), "jacobian_min_at": at,- "bend": round(bend, PLACES), "bend_deg": _degrees(bend),- "ellipse_px": int(mask.sum()), "solid_px": int((mask & solid).sum()), "changed_px": int((mask & changed).sum()),- "ownership": UNKNOWN,- })- seams = []- moving = [i for i, hold in enumerate(answer.held) if not hold]- for i in moving:- for j in (j for j in moving if j > i):- found = seam(*(tuple(entries[m]["ellipse"]) for m in (i, j)), offsets[i], offsets[j], answer.gains[i] == answer.gains[j])- if found is not None:- seams.append({"regions": [i, j], "jump": round(found[0], PLACES), "deg": _degrees(found[0]), "at": found[1]})- cells.append({- "index": k, "carry_px": [float(carry[0]), float(carry[1])], "changed_px": int(changed.sum()),- "jacobian_min": 1.0 if area is None or not area.size else round(float(area.min()), PLACES), "regions": entries,- "seams": seams,- })- source_tiles.append(_tile(answer.cells[k], masks, scale))- moved_tiles.append(_tile(moved, masks, scale))- (source_board, moved_board), boxes = _boards([source_tiles, moved_tiles], columns)- for cell, box in zip(cells, boxes):- cell["box"] = box- source_png, moved_png = _png(source_board), _png(moved_board)- meta = request.meta- cut_sha256 = _sha256(_canonical({key: value for key, value in meta.items() if key != "follow"}))- inputs = {- "strip": {"file": strip_path.name, "sha256": _sha256(strip_bytes), "bytes": len(strip_bytes)},- # `sha256` is the file's as read; `cut_sha256` is the meta's without the `follow` record `video-follow`- # adds (one spelling: keys sorted, no spaces), so it is the same before and after a follow-through.- "meta": {"file": request.meta_path.name, "sha256": _sha256(request.meta_bytes), "bytes": len(request.meta_bytes),- "cut_sha256": cut_sha256, "follow_recorded": "follow" in meta},- "cut": {"frames": n, "w": w, "h": h, "delay_ms": float(meta["delay_ms"])},- "regions": [list(region) for region in request.regions],- "settings": {"gain": request.gain, "on_fold": request.on_fold, "freq_hz": request.freq, "zeta": request.zeta,- "read_on": request.read_on, "stretch_floor": request.stretch_floor},- "policy": policy(),- "engine": {"name": "sprite-gen", "version": _engine_version()},- }- input_id = _sha256(_canonical({- "schema_version": SCHEMA_VERSION, "engine": inputs["engine"], "policy": inputs["policy"],- "strip_sha256": inputs["strip"]["sha256"], "cut_sha256": cut_sha256,- "regions": inputs["regions"], "settings": inputs["settings"],- }))- pairs: dict[tuple[int, int], dict[str, Any]] = {}- for cell in cells: # per pair of regions, the largest seam of any cell, the first cell on a tie- for found in cell["seams"]:- key = tuple(found["regions"])- if key not in pairs or found["jump"] > pairs[key]["jump"]:- pairs[key] = {"regions": found["regions"], "jump": found["jump"], "deg": found["deg"], "cell": cell["index"], "at": found["at"]}- record = {- "kind": KIND, "schema_version": SCHEMA_VERSION, "input_id": input_id, "inputs": inputs,- "follow": answer.record(),- "carry_basis": dict(follow.CARRY_BASIS),- "regions": [{- "index": i, "ellipse": list(region), "radius_px": radius, "gain": g, "held": hold,- "gain_limit": None if (limit := follow.gain_limit(answer.reach_per_gain, radius)) is None else round(limit, 3),- "reach_px": max(cell["regions"][i]["reach_px"] for cell in cells),- "fold_ratio": max(cell["regions"][i]["fold_ratio"] for cell in cells),- "jacobian_min": min(cell["regions"][i]["jacobian_min"] for cell in cells),- "bend": max(cell["regions"][i]["bend"] for cell in cells), "bend_deg": max(cell["regions"][i]["bend_deg"] for cell in cells),- "changed_px": sum(cell["regions"][i]["changed_px"] for cell in cells),- "ring": list(RINGS[i % len(RINGS)]),- } for i, (region, radius, g, hold) in enumerate(zip(request.regions, answer.radii, answer.gains, answer.held))],- "seams": [pairs[key] for key in sorted(pairs)],- "cells": cells,- "boards": {- "scale": scale, "columns": columns, "size": [int(source_board.shape[1]), int(source_board.shape[0])],- "ground": list(GROUND),- "source": {"file": SOURCE_BOARD, "sha256": _sha256(source_png), "pixels_sha256": _sha256(source_board.tobytes())},- "moved": {"file": MOVED_BOARD, "sha256": _sha256(moved_png), "pixels_sha256": _sha256(moved_board.tobytes())},- },- }- out_dir.mkdir(parents=True, exist_ok=True)- # The boards and the record that names them, together: a run that fails on the way leaves `out_dir` as it was.- atomic_write_set({out_dir / SOURCE_BOARD: source_png, out_dir / MOVED_BOARD: moved_png,- out_dir / RECORD: json.dumps(record, ensure_ascii=False, indent=2) + "\n"})- return record+def __getattr__(name: str) -> Any:+ return getattr(_inspect, name)-def add_arguments(parser: argparse.ArgumentParser) -> None:- follow.add_request_arguments(parser)- parser.add_argument("--out-dir", required=True, type=Path,- help=f"where {RECORD}, {SOURCE_BOARD} and {MOVED_BOARD} are written; not the loop directory, which is only read")- parser.add_argument("--scale", type=int, default=SCALE_DEFAULT,- help=f"board pixels per cell pixel (default {SCALE_DEFAULT}; at 2 or more a ring covers no cell pixel whole)")- parser.add_argument("--columns", type=int, default=COLUMNS_DEFAULT, help=f"cells per row of a board (default {COLUMNS_DEFAULT})")+def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], out_dir: Path,+ **kwargs: Any) -> dict[str, Any]:+ return _inspect.inspect_loop(loop_dir, regions, out_dir, **{"verb": VERB, **kwargs})def run(**kwargs: object) -> int:- out_dir = Path(str(kwargs["out_dir"]))- record = inspect_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), out_dir, # type: ignore[arg-type]- gain=float(kwargs.get("gain", follow.GAIN_DEFAULT)), freq=float(kwargs.get("freq", follow.FREQ_DEFAULT)), # type: ignore[arg-type]- zeta=float(kwargs.get("zeta", follow.ZETA_DEFAULT)), on_fold=str(kwargs.get("on_fold") or "refuse"), # type: ignore[arg-type]- scale=int(kwargs.get("scale", SCALE_DEFAULT)), columns=int(kwargs.get("columns", COLUMNS_DEFAULT)), # type: ignore[call-overload]- read_on=kwargs.get("read_on"), stretch_floor=kwargs.get("stretch_floor")) # type: ignore[arg-type]- for note in follow.fold_notes(record["follow"], VERB):- print(note, file=sys.stderr)- out_dir = out_dir.expanduser().resolve()- print(json.dumps({- "record": str(out_dir / RECORD), "input_id": record["input_id"], "cells": len(record["cells"]),- "region_gains": [region["gain"] for region in record["regions"]],- "held": [region["index"] for region in record["regions"] if region["held"]],- "ownership": UNKNOWN,- "boards": {name: {"path": str(out_dir / record["boards"][name]["file"]), "pixels_sha256": record["boards"][name]["pixels_sha256"]}- for name in ("source", "moved")},- }, ensure_ascii=False, indent=2))- return 0+ return _inspect.run(**{"verb": VERB, **kwargs})def main(argv: list[str] | None = None) -> int:- parser = argparse.ArgumentParser(prog="sprite-gen video-follow-inspect", description=__doc__)- add_arguments(parser)- return run(**vars(parser.parse_args(argv)))+ return _inspect.main(argv, verb=VERB)if __name__ == "__main__":diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 93df3cc..90393b8 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -124,9 +124,18 @@ FACINGS = ("right", "left")# the kept one stale, so writing the cycle removes it: an alignment after a re-cut (say, once RIFE# is installed and the jumps are repaired) reads the new cut, not the old one.CYCLE_SOURCE_DIR = "cycle.source"-# The strip as it was before `video-follow` moved a region of it; a later follow-through reads-# from it, and a new cut or alignment removes it (docs/video-pipeline.md section 6).+# The strip as it was before `video-sway` (the Sway layer; old name `video-follow`) moved a region of it;+# a later sway reads from it, and a new cut or alignment removes it (docs/video-pipeline.md section 6).+# Its name, and the key the sway's record is written under, stay `follow` in this release: a consumer reads+# them by those names. The record is read under either key.FOLLOW_SOURCE = "follow.source.png"+SWAY_RECORD = "follow"+SWAY_RECORD_KEYS = ("sway", "follow")+++def sway_recorded(meta: dict) -> bool:+ """Whether a loop's strip sidecar carries a sway's record, under its new key or its old one."""+ return any(key in meta for key in SWAY_RECORD_KEYS)# A gait's period is a fact about the body, not about how long the clip runs: thediff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.pyindex 7e2b964..bdbff43 100644--- a/sprite_gen/video/source.py+++ b/sprite_gen/video/source.py@@ -149,7 +149,7 @@ def project(baseline: Any, source: Source) -> tuple[Projection | None, str | Nonm, report = baseline.meta, baseline.source_reportif report.get("kind") != "sprite-gen-video-loop-report" or report.get("status") != "passed":return None, "source-report-unverified"- if "follow" in m:+ if loop.sway_recorded(m):return None, "follow-source-warp-unverified"n = len(baseline.frames)cycle = report.get("cycle", {})diff --git a/sprite_gen/video/sway.py b/sprite_gen/video/sway.pynew file mode 100644index 0000000..5ca3f89--- /dev/null+++ b/sprite_gen/video/sway.py@@ -0,0 +1,915 @@+# SPDX-License-Identifier: Apache-2.0+"""`sprite-gen video-sway` — the Sway layer: a soft part of a looping body sways with the body's motion.++Its old name, `video-follow` (`sprite_gen.video.follow`, `follow_loop`), still runs it and gives the same+result. The loop's record of it is read under `sway` or `follow`; this release still writes it under+`follow`, and the strip as cut is still `follow.source.png`, the names a consumer reads them by.++A clip model draws a walk's body moving, but a soft part that hangs off it (a chest, a belly,+a pouch on a strap) mostly moves with the body as one piece, even when the prompt asks it to+bounce: at sprite size it reads as rigid. This puts that follow-through back after the loop is+cut.++Each frame of the strip is a cell of one cycle. The body's motion is read off the cells: how far+each cell's body lies from the first cell's. The silhouette is worn down from a quarter to half+of its depth in the first cell, so what swings on the body — a tail, a ponytail, an ear, a sword+or a rod held up, the legs and arms — is worn away and the head and torso are left; each cell is+laid where it overlaps the first cell most, worn alike, a pixel counting once for every level it+is still in, and then laid again on what the cells so laid have in common: what more than half of+them have at one place, so a part as thick as the body that is elsewhere in another cell (ears as+wide as the head, up in one cell and on the face in the next) does not pull that cell onto itself.+(Read off the top of the body instead, the motion was whatever came to the top: a+tail tip or a raised sword made it jump by the part's whole swing from one cell to the next.) A part+hung on the body is a damped mass: its offset x from where the body carries it answers the body's own+acceleration, x'' + 2·ζ·ω·x' + ω²·x = −body''. The loop repeats, so the answer is the periodic+steady state, solved per harmonic of the cycle: no start-up, no kick at a foot strike, and the+last frame leads into the first. `--gain` scales that physical answer and nothing else; it is+not normalised to a target size.++The part is an ellipse in the first cell (`--region cx,cy,rx,ry`, cell pixels), carried with+the body's bob. Inside it every pixel is moved by the offset times a weight that is 1 at the+centre and falls to 0 at the rim (cos²); outside it no pixel changes. The move is sampled as+premultiplied bilinear colour, so an edge never picks up the colour under a transparent pixel.+A move so large that the weight's slope folds the picture over (offset × π / (2 · radius) ≥ 1)+is refused. `--on-fold lower` gives each region the largest gain that does not fold it instead+(the offset grows in a straight line with the gain, so that gain is known without a search), and+never one under 1, the mass as measured: a region too small for that is held — it does not move,+and the record names it — and the strip is refused only when every region is.++The strip as it was before is kept as `follow.source.png` beside it; running the command again+reads from there, so a second follow-through never moves a moved strip. `video-loop` (a new+cut) and `video-cycle-align` (a new cycle) remove it, and the alignment records that the+follow-through was cleared. docs/video-pipeline.md section 6.++The regions are where somebody looked: in the first cell of the strip they were read on. An alignment+turns a loop to start elsewhere, and its first cell is then another; read again there, the motion is+taken from another cell 0 and the regions land on another place of the body. `--read-on <sha256>` names+the strip (as cut, before any follow-through) the regions were read on. That strip is this loop's own —+`same`, read as ever — or the cut this loop was aligned from (`video-cycle-align` records it, with its+reading and where every new cell is from): then the cut's reading is carried to each cell from the cut's+cell it is, the regions stay where they were read, and the damped mass is solved on the new order, length+and frame time (`transported`). A cell the alignment made between two of the cut's, or one that is not+the cut's cell pixel for pixel (a crop or a scale changed, and nothing records how), has no reading to+carry: refused `uncertain`, never carried by the nearest whole cell. Any other strip is refused+`no-match`. Without `--read-on` nothing of this is read or written.++`--stretch-floor D` asks every region's move to leave each pixel at least D of its area. The weight's+steepest slope is π/2 over each radius, so a move (ox, oy) leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of it —+by the way the region moves, where the fold rule reads the smaller radius whichever way it moves. Each+region takes the largest gain, in steps of GAIN_STEP, that keeps the floor in every cell, and never one+above what the fold rule gave it: the floor only lowers. Under it the fold rule's handling stands (under 1+held, every region held refused; `--on-fold refuse` refuses). The record names the floor and its policy.++What carries a region is the lay of the body's outline (`carry_basis`): whose pixels are inside the+carried ellipse is not read, and nothing here moves a region on a guess of it.+"""++from __future__ import annotations++import argparse+import hashlib+import io+import json+import math+import os+import re+import shutil+import sys+import tempfile+from dataclasses import dataclass+from pathlib import Path+from typing import Any++from PIL import Image++from sprite_gen._deps import np+from sprite_gen.spec.runio import atomic_write_text+from sprite_gen.util.gif_utils import save_clean_gif+from sprite_gen.video import loop as loop_mod++VERB = "video-sway"+OLD_VERB = "video-follow" # the old name, kept: it runs this and says its own name+# How the motion is read and a region moved, by name. `video-sway-inspect` writes it beside what it read, so+# what somebody saw under one way of reading is not taken for another's: a change that gives the same strip,+# regions and settings another carry, offset or picture takes a new name.+POLICY = "common-lay/damped-mass/cos2-bilinear/1"+FREQ_DEFAULT = 2.4 # Hz: a slow, soft part+ZETA_DEFAULT = 0.6 # damping ratio: it lags and settles, with no ringing+GAIN_DEFAULT = 2.5 # times the physical answer+GAIN_MEASURED = 1.0 # the mass as measured: `--on-fold lower` does not go under it+GAIN_STEP = 0.01 # a lowered gain is a whole number of these, so the report's `gain` is the `--gain` to pass+ON_FOLD_MODES = ("refuse", "lower")+HARMONICS = 6 # of the cycle, for the body's motion: a step's shape, not its noise+ALPHA_SOLID = 128+WORN_FROM, WORN_TO = 0.25, 0.5 # of the body's depth in the first cell: the levels its silhouette is worn down to+SOURCE = loop_mod.FOLLOW_SOURCE+# How a reading made on the cut is carried to a loop aligned from it (`--read-on`): per whole cell of the cut, by the+# alignment's record of where each cell is from, and only to a cell that is that cell pixel for pixel.+TRANSPORT_POLICY = "cut-reading/whole-cell/1"+# How `--stretch-floor` reads a region's least area: the cos² weight's closed form, by direction, never above the+# fold rule's gain.+STRETCH_POLICY = "stretch-floor/cos2-direction/1"+# What carries a region into a cell: the lay of the body's outline. Whose pixels the carried ellipse holds is not read.+CARRY_BASIS = {"reading": "outline-lay", "region": "unverified"}+READ_ON = re.compile(r"[0-9a-f]{64}") # a strip's sha256, as `--read-on` names it+++def parse_region(text: str) -> tuple[float, float, float, float]:+ try:+ cx, cy, rx, ry = (float(v) for v in text.split(","))+ except ValueError as exc:+ raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry (four numbers), got {text!r}") from exc+ if rx <= 0 or ry <= 0:+ raise argparse.ArgumentTypeError(f"--region radii must be positive, got {text!r}")+ return cx, cy, rx, ry+++def parse_read_on(text: str) -> str:+ if not READ_ON.fullmatch(text):+ raise argparse.ArgumentTypeError(f"--read-on wants the sha256 of the strip the regions were read on (64 lowercase "+ f"hexadecimal digits), got {text!r}")+ return text+++def _run_depth(solid: np.ndarray, axis: int) -> np.ndarray:+ """Per solid pixel, how far along `axis` the nearest clear pixel is (1 beside one; past the cell's edge is clear)."""+ m = np.moveaxis(solid, axis, -1)+ n = m.shape[-1]+ at = np.broadcast_to(np.arange(n), m.shape)+ before = np.maximum.accumulate(np.where(m, -1, at), axis=-1)+ after = np.minimum.accumulate(np.where(m, n, at)[..., ::-1], axis=-1)[..., ::-1]+ return np.moveaxis(np.where(m, np.minimum(at - before, after - at), 0), -1, axis)+++def wear(solid: np.ndarray, r: int) -> np.ndarray:+ """`solid` worn down by r: the pixels whose square of side 2·r + 1 around them is solid."""+ return _run_depth(_run_depth(solid, 1) > r, 0) > r+++def depth(solid: np.ndarray) -> int:+ """How deep the body is at its deepest: the most it is worn down by and still has a pixel, plus one."""+ lo, hi = 0, (min(solid.shape) + 1) // 2 # worn by lo something is left; worn by hi nothing is+ if not solid.any():+ return 0+ while hi - lo > 1:+ mid = (lo + hi) // 2+ lo, hi = (mid, hi) if wear(solid, mid).any() else (lo, mid)+ return lo + 1+++def _levels(solid: np.ndarray, worn: range) -> tuple[np.ndarray, int, int] | None:+ """`solid` worn down by each of `worn`, as one number per pixel: how many of those levels the pixel is still+ in. Each level lies inside the one before, so level i is where that number is over i. Cut to the box of the+ first level, with that box's top and left; None when nothing is left of `solid` worn down by the first."""+ level = wear(solid, worn[0])+ if not level.any():+ return None+ ys, xs = np.nonzero(level.any(axis=1))[0], np.nonzero(level.any(axis=0))[0]+ level = level[ys[0]: ys[-1] + 1, xs[0]: xs[-1] + 1]+ inside = level.astype(np.int32)+ for _ in worn[1:]:+ # Worn down by one more pixel: a square of side 2·r + 3 is one of side 2·r + 1 grown by one each way.+ across = np.pad(level, 1)+ level = across[1:-1, :-2] & across[1:-1, 1:-1] & across[1:-1, 2:]+ down = np.pad(level, 1)+ level = down[:-2, 1:-1] & down[1:-1, 1:-1] & down[2:, 1:-1]+ inside += level+ return inside, int(ys[0]), int(xs[0])+++def _fft_length(n: int) -> int:+ """The first length from n on with no prime factor over 5: an FFT of it is fast."""+ while True:+ m = n+ for p in (2, 3, 5):+ while m % p == 0:+ m //= p+ if m == 1:+ return n+ n += 1+++def _overlay(onto: tuple[list[np.ndarray], int, int], levels: tuple[np.ndarray, int, int]) -> tuple[int, int]:+ """The shift (dx, dy) of a cell from what it is laid on: where `onto` — per level a whole number at every+ pixel, with its top and left — moved by it, lands on the cell's own levels most, the numbers that land on+ the cell's pixels summed at every level and the levels summed."""+ (a, ya, xa), (b, yb, xb) = onto, levels+ # Long enough that no move wraps round (a.h + b.h - 1 each way, and so on), and fast.+ height, width = a[0].shape[0] + b.shape[0] - 1, a[0].shape[1] + b.shape[1] - 1+ shape = (_fft_length(height), _fft_length(width))+ # overlap[i, j]: what of `onto` lands on the cell's same level moved by (j - (a.w - 1), i - (a.h - 1)),+ # summed over the levels, for every move that meets.+ spectrum = sum(np.fft.rfft2((b > i).astype(np.float64), shape) * np.fft.rfft2(la[::-1, ::-1].astype(np.float64), shape)+ for i, la in enumerate(a))+ # Sums of whole numbers are whole numbers: rounded, the FFT's own rounding (not the same on every machine)+ # is gone, so a tie is a tie on every machine, and it goes to the move nearest none.+ overlap = np.rint(np.fft.irfft2(spectrum, shape)[:height, :width]).astype(np.int64)+ shifts = [(int(j) - (a[0].shape[1] - 1) + xb - xa, int(i) - (a[0].shape[0] - 1) + yb - ya)+ for i, j in np.argwhere(overlap == overlap.max())]+ return min(shifts, key=lambda s: (s[0] ** 2 + s[1] ** 2, s[1], s[0]))+++def _common(levels: list[tuple[np.ndarray, int, int]], lays: list[tuple[int, int]],+ count: int) -> tuple[list[np.ndarray], int, int] | None:+ """What the cells' bodies have in common, each cell moved back by its lay: per level (`count` of them) and+ pixel, how many more of the cells are in that level there than are not (none, where no more are), cut to+ the box of what is left, with that box's top and left; None when no pixel is in more than half of the cells.++ The head and torso are in every cell at one place and count the whole number of cells. What swings and is+ thick enough to outlast the wearing — an ear as wide as the head, up in some cells and flopped onto the+ face in others; a leg forward and back — is at any one place in half of the cells or fewer, and counts+ nothing. A thick part that keeps one place in most of the cells counts as the body does: outlines alone+ do not tell the two apart."""+ tops = [top - dy for (_, top, _), (_, dy) in zip(levels, lays)]+ lefts = [left - dx for (_, _, left), (dx, _) in zip(levels, lays)]+ top, left = min(tops), min(lefts)+ height = max(t + inside.shape[0] for t, (inside, _, _) in zip(tops, levels)) - top+ width = max(l + inside.shape[1] for l, (inside, _, _) in zip(lefts, levels)) - left+ cells_in = np.zeros((count, height, width), np.int32)+ level = np.arange(count)[:, None, None]+ for (inside, _, _), t, l in zip(levels, tops, lefts):+ cells_in[:, t - top: t - top + inside.shape[0], l - left: l - left + inside.shape[1]] += inside > level+ more = np.maximum(0, 2 * cells_in - len(levels))+ # Each level lies inside the one before, in every cell: the first level's box holds them all.+ ys, xs = np.nonzero(more[0].any(axis=1))[0], np.nonzero(more[0].any(axis=0))[0]+ if not len(ys):+ return None+ return list(more[:, ys[0]: ys[-1] + 1, xs[0]: xs[-1] + 1]), top + int(ys[0]), left + int(xs[0])+++def body_motion(cells: list[Image.Image]) -> tuple[np.ndarray, np.ndarray, int, list[int]]:+ """Per cell: how far its body lies from cell 0's, down and across (px); the body's height in cell 0,+ and the first and last level its silhouette is worn down to.++ The top of the body is whatever comes to the top — a tail tip, a ponytail, an ear, a sword held+ up — and read there the motion jumps from cell to cell. What swings on the body is thinner than+ the body it swings on: worn down by a quarter of the body's depth it is gone, and what is left+ is the head and torso. Each cell is laid where its silhouette, worn down by every whole number+ of pixels from a quarter to half of that depth, overlaps cell 0's, worn alike, most, the+ overlaps of every level summed: a pixel counts once for each level it is still in, so the+ deepest of the body counts most and nothing that comes and goes outweighs it, and a torso that+ is shallower in one cell (an arm swung away from it) still counts at its shallower levels.++ That lay answers to everything left in cell 0, and a part as thick as the body is left: where+ ears as wide as the head stand up in cell 0 and flop onto the face in another cell, the cell+ is laid ears on ears, the body tens of pixels off. So the cells are laid a second time, on what+ they have in common as first laid (`_common`), and that lay, less cell 0's own, is the motion:+ the ears are at one place in too few cells to count, and the cell lies head on head and torso+ on torso."""+ solids = []+ for k, cell in enumerate(cells):+ solid = np.asarray(cell.getchannel("A")) >= ALPHA_SOLID+ if not solid.any():+ raise ValueError(f"cell {k} has no solid body")+ solids.append(solid)+ ys = np.nonzero(solids[0].any(axis=1))[0]+ height0 = int(ys[-1] - ys[0])+ deepest = depth(solids[0])+ first = int(WORN_FROM * deepest)+ worn = range(first, max(first + 1, int(WORN_TO * deepest)))+ levels = []+ for k, solid in enumerate(solids):+ level = _levels(solid, worn)+ if level is None:+ raise ValueError(f"cell {k} has no body as deep as a quarter of cell 0's ({worn[0]} px)")+ levels.append(level)+ inside0, top0, left0 = levels[0]+ lays = [_overlay(([inside0 > i for i in range(len(worn))], top0, left0), level) for level in levels]+ common = _common(levels, lays, len(worn))+ if common is None:+ raise ValueError("no part of the body is at one place in more than half of the cells")+ lays = [_overlay(common, level) for level in levels]+ dx0, dy0 = lays[0]+ return (np.asarray([dy - dy0 for _, dy in lays], float), np.asarray([dx - dx0 for dx, _ in lays], float),+ height0, [worn[0], worn[-1]])+++def _cells(strip: Image.Image, n: int, w: int, h: int) -> list[Image.Image]:+ return [strip.crop((k * w, 0, (k + 1) * w, h)) for k in range(n)]+++def _cell_sha256(cell: Image.Image) -> str:+ """One cell's pixels, RGBA row by row: a cell drawn alike is the same one, whatever wrote its file."""+ return hashlib.sha256(cell.tobytes()).hexdigest()+++def cut_origin(strip_bytes: bytes, meta: dict[str, Any]) -> dict[str, Any]:+ """What `video-cycle-align` keeps of a loop's strip as cut when it first aligns it (`cycle_align.origin`), so a+ follow-through whose regions were read on that cut can be carried to the aligned loop (`--read-on`): the strip's+ sha256 (the file's bytes, as `--read-on` names it), its cell size, scale and crop origin, which frame of the+ cycle each of its cells is (`sample_indices`), each cell's pixels by sha256, and the body's motion as read on+ it (`reading`: per cell how far its body lies from cell 0's, across and down, by `POLICY`). A strip whose body+ cannot be read keeps `reading` None and says why. Reads the bytes given and nothing else."""+ strip = Image.open(io.BytesIO(strip_bytes)).convert("RGBA")+ n, w, h = int(meta["frames"]), int(meta["w"]), int(meta["h"])+ rect, samples = meta.get("source_rect"), meta.get("sample_indices")+ origin: dict[str, Any] = {+ "strip_sha256": hashlib.sha256(strip_bytes).hexdigest(), "frames": n, "w": w, "h": h, "scale": meta.get("scale"),+ "crop_origin": None if rect is None else list(rect[:2]),+ # A cut made before its strip recorded the frames it took holds every frame of its cycle, or it was subsampled+ # and which ones is not known.+ "sample_indices": list(samples) if samples is not None else (list(range(n)) if n == meta.get("cycle_frames") else None),+ }+ if strip.size != (w * n, h):+ return origin | {"cells_sha256": None, "reading": None,+ "reading_why": f"the strip is {strip.size[0]}x{strip.size[1]}, its meta says {w * n}x{h}"}+ cells = _cells(strip, n, w, h)+ origin["cells_sha256"] = [_cell_sha256(cell) for cell in cells]+ try:+ rows, cols, height0, worn = body_motion(cells)+ except ValueError as exc:+ return origin | {"reading": None, "reading_why": str(exc)}+ origin["reading"] = {"policy": POLICY, "carry_px": [[c, r] for c, r in zip(cols.tolist(), rows.tolist())],+ "body_px": height0, "body_worn_px": worn}+ return origin+++def read_on_relation(meta: dict[str, Any], strip_sha256: str, read_on: str, *, verb: str = VERB) -> str:+ """How the strip the regions were read on (`read_on`) stands to this loop: its own strip as cut (`same`), or the+ cut it was aligned from (`transported`); refused `no-match` otherwise."""+ if read_on == strip_sha256:+ return "same"+ origin = (meta.get("cycle_align") or {}).get("origin")+ if origin is not None and origin.get("strip_sha256") == read_on:+ return "transported"+ aligned_from = f"the cut it was aligned from ({origin['strip_sha256']})" if origin else "a cut it was aligned from (none is recorded)"+ raise SystemExit(f"{verb}: --read-on {read_on}: no-match — the regions were read on a strip that is neither this loop's "+ f"strip as cut ({strip_sha256}) nor {aligned_from}; locate them again on this strip")+++def transported_motion(meta: dict[str, Any], cells: list[Image.Image], read_on: str, *,+ verb: str = VERB) -> tuple[np.ndarray, np.ndarray, int, list[int], list[int]]:+ """The cut's reading carried to `cells`, the strip of a loop aligned from the cut `read_on` names: per cell how far+ the body of the cut's cell it is lies from the cut's cell 0 (down, then across, as `body_motion` gives them), the+ body's height and wear as read on the cut, and which cell of the cut each cell is.++ The alignment records where each cell is from (`cycle_align.cells_from`). A cell made between two of the cut's+ has no reading, and is not given its nearer one's; a cell the record calls the cut's must be that cell pixel for+ pixel, so a crop, a scale or a drawing changed since — and not recorded as a transform — is caught here. Either+ is refused `uncertain`."""+ record = meta.get("cycle_align") or {}+ origin, cells_from = record["origin"], record.get("cells_from")++ def uncertain(why: str) -> SystemExit:+ return SystemExit(f"{verb}: --read-on {read_on} is the cut this loop was aligned from, but uncertain: {why}; the "+ "reading is not carried — only a whole cell of the cut carries it, and none is taken by rounding")++ reading = origin.get("reading")+ if reading is None:+ raise uncertain(f"the cut's reading was not recorded ({origin.get('reading_why')})")+ if reading.get("policy") != POLICY:+ raise uncertain(f"the cut was read as {reading.get('policy')}, and this engine reads as {POLICY}")+ if not isinstance(cells_from, list) or len(cells_from) != len(cells):+ raise uncertain(f"the alignment records where {len(cells_from) if isinstance(cells_from, list) else 'no'} cells are "+ f"from, and the strip has {len(cells)}")+ for k, entry in enumerate(cells_from):+ if "source" not in entry:+ i, j = entry["between"]+ raise uncertain(f"cell {k} is made between the cut's frames {i} and {j} (t {entry['t']:g})")+ (w, h), rect = cells[0].size, meta.get("source_rect")+ now = (w, h, meta.get("scale"), None if rect is None else list(rect[:2]))+ then = (origin["w"], origin["h"], origin["scale"], origin["crop_origin"])+ # A cut made before the strip recorded its crop says nothing of where it was cropped: there the cells' pixels+ # below are the whole test, as they are for every cell anyway.+ if now[:3] != then[:3] or (then[3] is not None and now[3] != then[3]):+ raise uncertain(f"the cut's crop or scale changed (cells {then[0]}x{then[1]} at scale {then[2]} from {then[3]}, now "+ f"{w}x{h} at scale {now[2]} from {now[3]}) and no transform is recorded")+ frames, digests = origin["sample_indices"], origin["cells_sha256"]+ cut_cells = []+ for k, (cell, entry) in enumerate(zip(cells, cells_from)):+ i = entry["source"]+ if frames is None or i not in frames:+ raise uncertain(f"cell {k} is frame {i} of the cut's cycle, which the cut's strip does not hold")+ j = frames.index(i)+ if _cell_sha256(cell) != digests[j]:+ raise uncertain(f"cell {k} is not the cut's cell {j} as drawn: its pixels differ")+ cut_cells.append(j)+ carry = reading["carry_px"]+ return (np.asarray([carry[j][1] for j in cut_cells], float), np.asarray([carry[j][0] for j in cut_cells], float),+ int(reading["body_px"]), list(reading["body_worn_px"]), cut_cells)+++def sway_offsets(motion: np.ndarray, fps: float, *, freq: float, zeta: float, gain: float) -> np.ndarray:+ """The part's offset from where the body carries it, per cell, in the cycle's steady state."""+ n = len(motion)+ spectrum = np.fft.rfft(motion - motion.mean())+ k = np.arange(len(spectrum))+ spectrum[k > HARMONICS] = 0+ omega = 2 * math.pi * fps / n * k # each harmonic's angular frequency+ w = 2 * math.pi * freq+ # x = H·y with y the body's position: x'' + 2ζw x' + w² x = −y'' ⇒ H = Ω² / (w² − Ω² + 2iζwΩ)+ response = omega ** 2 / (w ** 2 - omega ** 2 + 2j * zeta * w * omega)+ return gain * np.fft.irfft(spectrum * response, n)+++def fold_ratio(reach: float, radius: float) -> float:+ """How near a move of `reach` px is to folding a region whose smaller radius is `radius`: at 1+ the steepest part of the weight (cos², slope π / (2 · radius)) stops the picture, past it the+ picture runs backwards."""+ return reach * math.pi / (2 * radius)+++def gain_limit(reach_per_gain: float, radius: float) -> float | None:+ """The gain at which a region of that radius folds; no gain folds it when the body is still."""+ return 2 * radius / (math.pi * reach_per_gain) if reach_per_gain > 0 else None+++def lowered_gain(gain: float, reach_per_gain: float, radius: float) -> float:+ """The largest gain, in steps of GAIN_STEP and no more than `gain`, that `fold_ratio` passes."""+ limit = gain_limit(reach_per_gain, radius)+ if limit is None:+ return gain+ steps = math.ceil(limit / GAIN_STEP) - 1 # under the limit, never on it+ # The step count is rounded from floats: the one test that decides is `fold_ratio` itself.+ while steps > 0 and fold_ratio(steps * GAIN_STEP * reach_per_gain, radius) >= 1:+ steps -= 1+ return min(gain, round(steps * GAIN_STEP, 2))+++def stretch_per_gain(radii: tuple[float, float], across: np.ndarray, down: np.ndarray) -> tuple[float, int]:+ """How much of a pixel's area a region's move takes per unit of gain, at its worst cell, and that cell: the cos²+ weight is steepest at π/2 over each radius, so a move (ox, oy) leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of the area+ (`across`, `down`: the move at gain 1, per cell)."""+ rx, ry = radii+ per_cell = (math.pi / 2) * np.hypot(across / rx, down / ry)+ k = int(np.argmax(per_cell))+ return float(per_cell[k]), k+++def floor_gain(gain: float, per_gain: float, floor: float) -> float:+ """The largest gain, in steps of GAIN_STEP and no more than `gain`, whose move leaves `floor` of a pixel's area or+ more (1 − gain · `per_gain` ≥ `floor`)."""+ if per_gain <= 0 or 1 - gain * per_gain >= floor:+ return gain+ steps = math.floor((1 - floor) / per_gain / GAIN_STEP) + 1+ # The step count is rounded from floats: the one test that decides is the area left at the gain written.+ while steps > 0 and 1 - round(steps * GAIN_STEP, 2) * per_gain < floor:+ steps -= 1+ return min(gain, round(steps * GAIN_STEP, 2))+++def _sample(premultiplied: np.ndarray, sx: np.ndarray, sy: np.ndarray) -> np.ndarray:+ h, w = premultiplied.shape[:2]+ x0 = np.clip(np.floor(sx).astype(int), 0, w - 2)+ y0 = np.clip(np.floor(sy).astype(int), 0, h - 2)+ fx = np.clip(sx - x0, 0, 1)[..., None]+ fy = np.clip(sy - y0, 0, 1)[..., None]+ a, b = premultiplied[y0, x0], premultiplied[y0, x0 + 1]+ c, d = premultiplied[y0 + 1, x0], premultiplied[y0 + 1, x0 + 1]+ return (a * (1 - fx) + b * fx) * (1 - fy) + (c * (1 - fx) + d * fx) * fy+++def region_weight(xx: np.ndarray, yy: np.ndarray, region: tuple[float, float, float, float],+ shift: tuple[float, float]) -> np.ndarray:+ """Per pixel of a cell, how much of a region's move it takes: 1 at the centre of the ellipse carried by+ `shift`, 0 at its rim (cos²) and outside it. The pixels a region covers are those where this is over 0."""+ cx, cy, rx, ry = region+ r = np.sqrt(((xx - cx - shift[0]) / rx) ** 2 + ((yy - cy - shift[1]) / ry) ** 2)+ return np.where(r < 1, np.cos(r * math.pi / 2) ** 2, 0)+++def move_field(xx: np.ndarray, yy: np.ndarray, moves: list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]],+ shift: tuple[float, float]) -> tuple[np.ndarray, np.ndarray, np.ndarray] | None:+ """Per pixel of a cell: whether a region of `moves`, carried by `shift`, covers it, and how far it is moved+ across and down. None when no region covers a pixel of the cell."""+ weights = []+ for regions, _ in moves:+ weight = np.zeros(xx.shape, np.float32)+ for region in regions:+ weight = np.maximum(weight, region_weight(xx, yy, region, shift))+ weights.append(weight)+ inside = np.logical_or.reduce([weight > 0 for weight in weights])+ if not inside.any():+ return None+ largest = np.argmax(np.stack([math.hypot(*offset) * weight for (_, offset), weight in zip(moves, weights)]), axis=0)[None]+ move_x = np.take_along_axis(np.stack([offset[0] * weight for (_, offset), weight in zip(moves, weights)]), largest, 0)[0]+ move_y = np.take_along_axis(np.stack([offset[1] * weight for (_, offset), weight in zip(moves, weights)]), largest, 0)[0]+ return inside, move_x, move_y+++def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]],+ shift: tuple[float, float]) -> Image.Image:+ """`cell` with each group of regions moved by its own offset (dx, dy), their centres carried by `shift`.++ The groups' offsets are one motion times their gains, so where regions of different groups+ overlap the larger move wins: the move is the largest of the groups' weighted moves, which is+ nowhere steeper than the steepest group's own."""+ src = np.asarray(cell.convert("RGBA"), dtype=np.float32)+ h, w = src.shape[:2]+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)+ field = move_field(xx, yy, moves, shift)+ if field is None:+ return cell.copy()+ inside, move_x, move_y = field+ pm = src.copy()+ pm[..., :3] *= pm[..., 3:4] / 255+ moved = _sample(pm, xx - move_x, yy - move_y)+ alpha = np.clip(np.round(moved[..., 3:4]), 0, 255)+ # Colour is read back from the premultiplied mix, and none is kept where the coverage+ # rounds to nothing (the WebP check refuses colour under alpha 0).+ moved[..., :3] = np.where(alpha > 0, moved[..., :3] * 255 / np.maximum(moved[..., 3:4], 1e-3), 0)+ moved[..., 3:4] = alpha+ out = np.where(inside[..., None], np.clip(np.round(moved), 0, 255), src).astype(np.uint8)+ return Image.fromarray(out, "RGBA")+++@dataclass(frozen=True, eq=False)+class Request:+ """A follow-through asked of a loop directory, read and checked; nothing is written by reading it."""++ loop_dir: Path+ name: str+ meta_path: Path+ meta_bytes: bytes+ meta: dict[str, Any]+ regions: list[tuple[float, float, float, float]]+ gain: float+ freq: float+ zeta: float+ on_fold: str+ read_on: str | None = None # the sha256 of the strip as cut the regions were read on; None: this strip's, as ever+ stretch_floor: float | None = None # the least area a moved pixel keeps; None: the fold rule alone++ @property+ def strip_path(self) -> Path:+ return self.loop_dir / f"{self.name}.strip.png"++ @property+ def source_path(self) -> Path:+ return self.loop_dir / SOURCE+++def read_request(loop_dir: Path, regions: list[tuple[float, float, float, float]], *, gain: float = GAIN_DEFAULT,+ freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, on_fold: str = "refuse", verb: str = VERB,+ read_on: str | None = None, stretch_floor: float | None = None) -> Request:+ loop_dir = loop_dir.expanduser().resolve()+ # The numbers go into the record, which is JSON, and into the cells' arithmetic: a numpy number from a+ # caller (an int64 has no JSON form) is read as the float the command line gives, so every caller of the+ # same numbers writes the same strip and record.+ regions = [tuple(float(v) for v in region) for region in regions]+ gain, freq, zeta = float(gain), float(freq), float(zeta)+ metas = sorted(loop_dir.glob("*.strip.json"))+ if len(metas) != 1:+ raise SystemExit(f"{verb}: {loop_dir}: expected one <name>.strip.json from video-loop, found {len(metas)}")+ meta_path = metas[0]+ name = meta_path.name[: -len(".strip.json")]+ meta_bytes = meta_path.read_bytes()+ meta = json.loads(meta_bytes.decode("utf-8"))+ if meta.get("kind") == "one-shot" or meta.get("loop") is False:+ raise SystemExit(f"{verb}: a one-shot plays once; the follow-through is a loop's steady state")+ if not regions:+ raise SystemExit(f"{verb}: at least one --region cx,cy,rx,ry")+ if gain < 0 or freq <= 0 or not 0 < zeta:+ raise SystemExit(f"{verb}: --gain must be 0 or more, --freq and --zeta above 0")+ if on_fold not in ON_FOLD_MODES:+ raise SystemExit(f"{verb}: unknown --on-fold {on_fold!r}; expected one of {', '.join(ON_FOLD_MODES)}")+ if read_on is not None and not READ_ON.fullmatch(str(read_on)):+ raise SystemExit(f"{verb}: --read-on wants the sha256 of the strip the regions were read on (64 lowercase "+ f"hexadecimal digits), got {read_on!r}")+ if stretch_floor is not None:+ stretch_floor = float(stretch_floor)+ if not 0 <= stretch_floor < 1: # a NaN is neither+ raise SystemExit(f"{verb}: --stretch-floor is the least area a moved pixel keeps, at least 0 and under 1; got {stretch_floor:g}")+ return Request(loop_dir, name, meta_path, meta_bytes, meta, regions, gain, freq, zeta, on_fold,+ None if read_on is None else str(read_on), stretch_floor)+++@dataclass(frozen=True, eq=False)+class Answer:+ """What a request comes to on a strip: the body's motion, each region's gain, and every cell's move.++ `video-follow` writes it over the loop; `video-follow-inspect` writes it down and changes nothing. Both+ read the carry, the offsets and the moved cells here, and nowhere else."""++ request: Request+ cells: list[Image.Image]+ cols: np.ndarray # per cell, how far its body lies from cell 0's: across+ rows: np.ndarray # and down+ height0: int+ worn: list[int]+ requested: float+ reach_requested: float+ reach_per_gain: float+ radii: list[float]+ gains: list[float] # per region; 0 where it is held+ held: list[bool]+ ratios: list[float]+ moves: dict[float, tuple[np.ndarray, np.ndarray]] # per gain a region moves by, the offset per cell: across, down+ reaches: dict[float, float]+ gain: float # the largest any region moves by; dx, dy and reach are that gain's+ dx: np.ndarray+ dy: np.ndarray+ reach: float+ groups: list[tuple[list[tuple[float, float, float, float]], tuple[np.ndarray, np.ndarray]]]+ read_on: dict[str, Any] | None = None # how the strip the regions were read on stands to this one (`--read-on`)+ stretch: dict[str, Any] | None = None # the floor asked, and what it did to each region (`--stretch-floor`)++ def carry(self, k: int) -> tuple[float, float]:+ """How far cell k's body lies from cell 0's, across and down: every region's ellipse is carried by it. Carried+ from the cut, the cells' motion is already from the cut's cell 0, where the regions were read."""+ if self.read_on is not None and self.read_on["relation"] == "transported":+ return self.cols[k], self.rows[k]+ return self.cols[k] - self.cols[0], self.rows[k] - self.rows[0]++ def moves_in(self, k: int) -> list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]]:+ """Cell k's groups of regions, each with its offset in that cell."""+ return [(group, (mx[k], my[k])) for group, (mx, my) in self.groups]++ def moved(self, k: int) -> Image.Image:+ return move_regions(self.cells[k], self.moves_in(k), self.carry(k))++ def record(self) -> dict[str, Any]:+ """The follow-through as the strip's meta records it; `video-follow` adds its animations' checks."""+ request, requested = self.request, self.requested+ return {+ "regions": [list(r) for r in request.regions], "gain": self.gain, "freq_hz": request.freq, "zeta": request.zeta,+ "harmonics": HARMONICS,+ "source": SOURCE, "body_px": self.height0, "body_worn_px": self.worn,+ "body_bob_px": [round(float(np.ptp(self.cols)), 2), round(float(np.ptp(self.rows)), 2)],+ "dx_px": np.round(self.dx, 2).tolist(), "dy_px": np.round(self.dy, 2).tolist(),+ "reach_px": round(self.reach, 2),+ "gain_requested": requested, "on_fold": request.on_fold,+ "fold": {+ "lowered": any(g != requested for g in self.gains), "ratio": round(max(self.ratios), 3),+ "reach_requested_px": round(self.reach_requested, 2), "reach_per_gain_px": round(self.reach_per_gain, 3),+ # Where the regions took gains of their own, each says the gain it moved by and whether it+ # was held still (gain 0); where they all took one, the strip's `gain` is every region's.+ "regions": [{"radius_px": radius, "ratio": round(ratio, 3),+ "gain_limit": None if (limit := gain_limit(self.reach_per_gain, radius)) is None else round(limit, 3)}+ | ({} if len(set(self.gains)) == 1 else {"gain": g, "held": hold})+ for radius, ratio, g, hold in zip(self.radii, self.ratios, self.gains, self.held)],+ },+ } | ({} if self.read_on is None else {"read_on": self.read_on}) | ({} if self.stretch is None else {"stretch": self.stretch}) \+ | ({} if self.read_on is None and self.stretch is None else {"carry_basis": dict(CARRY_BASIS)})+++def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str = VERB,+ strip_sha256: str | None = None) -> Answer:+ """The answer to `request` on `strip`, the loop's strip as cut (an RGBA picture; `strip_name` names its file+ in a refusal, `strip_sha256` is its file's, read where the request names the strip its regions were read on).+ Reads nothing else and writes nothing."""+ meta, regions = request.meta, request.regions+ gain, freq, zeta, on_fold = request.gain, request.freq, request.zeta, request.on_fold+ n, w, h = int(meta["frames"]), int(meta["w"]), int(meta["h"])+ if strip.size != (w * n, h):+ raise SystemExit(f"{verb}: {strip_name} is {strip.size[0]}x{strip.size[1]}, the strip meta says {w * n}x{h}; "+ "cut the loop again (video-loop)")+ cells = _cells(strip, n, w, h)+ read_on = None+ if request.read_on is not None:+ if strip_sha256 is None:+ raise ValueError("solve: a request with read_on needs the strip's sha256")+ read_on = {"sha256": request.read_on, "relation": read_on_relation(meta, strip_sha256, request.read_on, verb=verb)}+ for cx, cy, rx, ry in regions:+ if not (0 <= cx < w and 0 <= cy < h):+ raise SystemExit(f"{verb}: --region centre {cx:g},{cy:g} is outside the {w}x{h} cell")+ fps = 1000.0 / float(meta["delay_ms"])+ if read_on is not None and read_on["relation"] == "transported":+ # The cut's own reading, cell for cell: the regions are where they were read, on the cut's cell 0, and the+ # damped mass answers that motion in this loop's order, length and frame time.+ rows, cols, height0, worn, cut_cells = transported_motion(meta, cells, request.read_on, verb=verb)+ read_on |= {"policy": TRANSPORT_POLICY, "cut_cells": cut_cells}+ else:+ try:+ rows, cols, height0, worn = body_motion(cells)+ except ValueError as exc:+ raise SystemExit(f"{verb}: {exc}") from exc+ dy = sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=gain)+ dx = sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=gain)+ reach = float(np.max(np.hypot(dx, dy)))+ radii = [min(rx, ry) for _, _, rx, ry in regions]+ smallest = min(radii)+ requested, reach_requested = gain, reach+ # The offset is the gain times the answer at gain 1, so one move decides every gain.+ reach_per_gain = float(np.max(np.hypot(sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=1.0),+ sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=1.0))))+ gains, held = [requested] * len(regions), [False] * len(regions)+ if fold_ratio(reach, smallest) >= 1:+ if on_fold == "refuse":+ raise SystemExit(f"{verb}: a move of {reach:.1f} px folds a region of radius {smallest:g} px over itself; "+ "lower --gain or give the region larger radii")+ # A gain for each region: every part hangs on the same body and answers the same motion, but+ # how far it moves before it folds is its own size, so a small part (an ear) does not hold a+ # large one (a chest) back. A region that does not fold keeps the gain asked for.+ folds = [fold_ratio(reach, radius) >= 1 for radius in radii]+ gains = [lowered_gain(requested, reach_per_gain, radius) if fold else requested for radius, fold in zip(radii, folds)]+ # One that would have to go under the mass as measured does not move at all; the strip is+ # refused only when that is every region.+ held = [fold and g < GAIN_MEASURED for fold, g in zip(folds, gains)]+ if all(held):+ k = radii.index(max(radii)) # the largest folds at the largest gain: if it is held, every region is+ every = f" (the largest of {len(regions)} regions: every one folds)" if len(regions) > 1 else ""+ raise SystemExit(f"{verb}: a move of {reach:.1f} px folds a region of radius {radii[k]:g} px over itself{every}, and "+ f"--on-fold lower would have to go under --gain {GAIN_MEASURED:g} (the mass as measured moves "+ f"{reach_per_gain:.1f} px; the largest gain that does not fold is {gains[k]:g}); give the region larger radii")+ gains = [0.0 if hold else g for g, hold in zip(gains, held)]+ stretch = None+ if request.stretch_floor is not None:+ gains, held, stretch = _keep_floor(request, radii, gains, held, (sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=1.0),+ sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=1.0)), verb)+ # One move per gain: a region's offset is its gain times the answer at gain 1. The strip's `gain`+ # is the largest any region moves by, and `dx_px`/`dy_px` and `reach_px` are that gain's.+ moves = {g: (sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=g), sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=g))+ for g, hold in zip(gains, held) if not hold}+ reaches = {g: float(np.max(np.hypot(*move))) for g, move in moves.items()}+ gain = max(moves)+ dx, dy = moves[gain]+ reach = reaches[gain]+ ratios = [0.0 if hold else fold_ratio(reaches[g], radius) for radius, g, hold in zip(radii, gains, held)]+ groups = [([r for r, rg, hold in zip(regions, gains, held) if rg == g and not hold], move) for g, move in moves.items()]+ return Answer(request, cells, cols, rows, height0, worn, requested, reach_requested, reach_per_gain, radii, gains, held,+ ratios, moves, reaches, gain, dx, dy, reach, groups, read_on, stretch)+++def _keep_floor(request: Request, radii: list[float], gains: list[float], held: list[bool],+ move: tuple[np.ndarray, np.ndarray], verb: str) -> tuple[list[float], list[bool], dict[str, Any]]:+ """The fold rule's gains (`gains`, 0 where `held`) lowered where a region's move would leave a pixel less than+ `--stretch-floor` of its area (`move`: across and down per cell at gain 1), and the record of it. A region is never+ raised; one the floor takes under GAIN_MEASURED is held as the fold rule holds one, and the strip is refused when+ every region is — or, under `--on-fold refuse`, when the floor lowers any."""+ floor, requested = request.stretch_floor, request.gain+ per = [stretch_per_gain((rx, ry), *move) for _, _, rx, ry in request.regions]+ floored = [floor_gain(requested, q, floor) for q, _ in per]+ lowered = [g if hold else min(g, f) for g, f, hold in zip(gains, floored, held)]+ by_floor = [not hold and g < rule for g, rule, hold in zip(lowered, gains, held)]+ if any(by_floor) and request.on_fold == "refuse":+ least = min(1 - requested * q for (q, _), by in zip(per, by_floor) if by)+ raise SystemExit(f"{verb}: --gain {requested:g} leaves a moved pixel {least:.3f} of its area, under --stretch-floor {floor:g}; "+ "lower --gain, pass --on-fold lower or give the region larger radii")+ now_held = [hold or (by and g < GAIN_MEASURED) for hold, by, g in zip(held, by_floor, lowered)]+ if all(now_held):+ k = radii.index(max(radii))+ raise SystemExit(f"{verb}: --stretch-floor {floor:g} leaves every region held: to keep it each would move under --gain "+ f"{GAIN_MEASURED:g} (the mass as measured; the largest region at {lowered[k]:g}); lower the floor or give "+ "the regions larger radii")+ final = [0.0 if hold else g for g, hold in zip(lowered, now_held)]+ return final, now_held, {+ "policy": STRETCH_POLICY, "floor": floor,+ "regions": [{"per_gain": round(q, 6), "least_cell": cell, "rule_gain": rule, "floor_gain": f, "gain": g, "held": hold,+ "least_area": 1.0 if hold else round(1 - g * q, 4), "under_measured": not hold and g < GAIN_MEASURED}+ for (q, cell), rule, f, g, hold in zip(per, gains, floored, final, now_held)],+ }+++def sway_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], *, gain: float = GAIN_DEFAULT,+ freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, board: Path | None = None,+ on_fold: str = "refuse", read_on: str | None = None, stretch_floor: float | None = None,+ verb: str = VERB) -> dict[str, Any]:+ request = read_request(loop_dir, regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on,+ stretch_floor=stretch_floor, verb=verb)+ loop_dir, name, meta_path, meta = request.loop_dir, request.name, request.meta_path, request.meta+ strip_path = request.strip_path+ source = request.source_path+ if not source.exists():+ shutil.copyfile(strip_path, source)+ data = source.read_bytes()+ answer = solve(request, Image.open(io.BytesIO(data)).convert("RGBA"), strip_name=source.name,+ strip_sha256=hashlib.sha256(data).hexdigest(), verb=verb)+ cells = answer.cells+ n, (w, h) = len(cells), cells[0].size+ out = [answer.moved(k) for k in range(n)]+ joined = Image.new("RGBA", (w * n, h), (0, 0, 0, 0))+ for k, c in enumerate(out):+ joined.alpha_composite(c, (k * w, 0))+ delay_ms = max(20, round(float(meta["delay_ms"])))+ gif_path, webp_path = loop_dir / f"{name}.gif", loop_dir / f"{name}.webp"+ # Written and checked beside the loop first, each under its own name, and moved over the loop's files+ # only once the record is written too: a run that fails on the way (an animation that fails its check, a+ # record that does not serialise) leaves the strip, its animations and its record as they were. Staged as+ # files, not as payloads in memory (runio.atomic_write_set): img2webp writes a file, and the check reads one.+ stage = Path(tempfile.mkdtemp(prefix=".follow.", dir=loop_dir))+ try:+ staged = {path: stage / path.name for path in (strip_path, gif_path, webp_path, meta_path)}+ joined.save(staged[strip_path])+ save_clean_gif(out, staged[gif_path], duration_ms=delay_ms, loop=0, alpha_threshold=128)+ loop_mod.write_webp(out, staged[webp_path], delay_ms=delay_ms, workdir=stage / ".webp-frames")+ # a cell left as it was beside its twin (a filmed ghost given way to the frame beside it) is one frame of both+ shown = loop_mod.shown_runs(out)+ record = {+ **answer.record(),+ "gif": loop_mod.verify_animation(staged[gif_path], expect_frames=shown, check_stale=False),+ "webp": loop_mod.verify_animation(staged[webp_path], expect_frames=shown, check_stale=True),+ }+ # One record, under the key consumers read it by (loop_mod.SWAY_RECORD); one read under the other key goes.+ kept = {k: v for k, v in meta.items() if k not in loop_mod.SWAY_RECORD_KEYS or k == loop_mod.SWAY_RECORD}+ atomic_write_text(staged[meta_path], json.dumps({**kept, loop_mod.SWAY_RECORD: record}, indent=2) + "\n")+ for path, written in staged.items(): # the record last, as it was written last+ os.replace(written, path)+ finally:+ shutil.rmtree(stage, ignore_errors=True)+ if board is not None:+ _board(cells, out, answer.dy, board)+ record["board"] = str(board)+ return {"strip": str(strip_path), **record}+++def _board(before: list[Image.Image], after: list[Image.Image], dy: np.ndarray, path: Path) -> None:+ """Before and after, side by side on white, at the frames where the part sits lowest and highest."""+ picks = [int(np.argmax(dy)), int(np.argmin(dy))]+ w, h = before[0].size+ board = Image.new("RGB", (w * 4 + 30, h), (128, 128, 128))+ x = 0+ for k in picks:+ for cell in (before[k], after[k]):+ ground = Image.new("RGBA", (w, h), (255, 255, 255, 255))+ ground.alpha_composite(cell)+ board.paste(ground.convert("RGB"), (x, 0))+ x += w + 10+ path.parent.mkdir(parents=True, exist_ok=True)+ board.save(path)+++def add_request_arguments(parser: argparse.ArgumentParser) -> None:+ """What a sway is asked with; `video-sway-inspect` takes the same and is asked alike."""+ parser.add_argument("--loop-dir", required=True, type=Path, help="a video-loop output directory (after video-cycle-align, if the set is aligned)")+ parser.add_argument("--region", action="append", type=parse_region, required=True,+ help="cx,cy,rx,ry: an ellipse over the soft part in the strip's first cell, in cell pixels (repeatable)")+ parser.add_argument("--gain", type=float, default=GAIN_DEFAULT, help=f"times the physical answer (default {GAIN_DEFAULT:g}; 1 is the mass as measured, 0 leaves the strip as it was)")+ parser.add_argument("--on-fold", choices=ON_FOLD_MODES, default="refuse",+ help=f"a move that folds a region over itself: refuse (default), or lower — each region takes the largest gain that does "+ f"not fold it, never under {GAIN_MEASURED:g} (the mass as measured): a region that would have to is held still and "+ "named in the record, and the strip is refused only when every region is")+ parser.add_argument("--freq", type=float, default=FREQ_DEFAULT, help=f"the part's own frequency in Hz (default {FREQ_DEFAULT:g})")+ parser.add_argument("--zeta", type=float, default=ZETA_DEFAULT, help=f"damping ratio (default {ZETA_DEFAULT:g}: lags and settles, no ringing)")+ parser.add_argument("--read-on", type=parse_read_on, default=None, metavar="SHA256",+ help="the sha256 of the strip as cut (before any follow-through) the regions were read on: this loop's own is "+ "read as without it (relation same); the cut this loop was aligned from (video-cycle-align records it) has "+ "its reading carried cell for cell (transported); a made cell or a cell geometry nothing records is "+ "refused uncertain, any other strip no-match. Without it nothing of this is read or written")+ parser.add_argument("--stretch-floor", type=float, default=None, metavar="D",+ help="the least area, 0 to under 1, a moved pixel keeps, read by the way each region moves: each region takes "+ "the largest gain that keeps it, never above the fold rule's; under it the fold rule's handling stands "+ f"(held under {GAIN_MEASURED:g}, every region held refused; --on-fold refuse refuses). No default: without "+ "it the fold rule alone")+++def add_arguments(parser: argparse.ArgumentParser) -> None:+ add_request_arguments(parser)+ parser.add_argument("--board", type=Path, help="write a before/after picture at the frames where the part sits lowest and highest")+++def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:+ """What to say of a record whose gain was lowered or whose regions were held, a line each."""+ fold, notes = record["fold"], []+ if "stretch" in record: # a floor was asked: each region says what lowered it, the fold or the floor+ floor = record["stretch"]["floor"]+ for (cx, cy, rx, ry), entry, folded in zip(record["regions"], record["stretch"]["regions"], fold["regions"]):+ name = f"--region {cx:g},{cy:g},{rx:g},{ry:g}"+ if entry["held"]:+ why = (f"folds at --gain {folded['gain_limit']:g}" if entry["rule_gain"] == 0 else+ f"keeps --stretch-floor {floor:g} only at --gain {entry['floor_gain']:g}")+ notes.append(f"{verb}: {name} {why}, under {GAIN_MEASURED:g} (the mass as measured): it is held, and does not move")+ elif entry["gain"] != record["gain_requested"]:+ by = f"--stretch-floor {floor:g}" if entry["gain"] < entry["rule_gain"] else "the fold"+ notes.append(f"{verb}: {name} moves at --gain {entry['gain']:g}, lowered from {record['gain_requested']:g} by {by}")+ return notes+ if "held" in fold["regions"][0]: # the regions took gains of their own+ for (cx, cy, rx, ry), entry in zip(record["regions"], fold["regions"]):+ name = f"--region {cx:g},{cy:g},{rx:g},{ry:g}"+ if entry["held"]:+ notes.append(f"{verb}: {name} folds at --gain {entry['gain_limit']:g}, under {GAIN_MEASURED:g} (the mass as measured): "+ "it is held, and does not move")+ elif entry["gain"] != record["gain_requested"]:+ notes.append(f"{verb}: --gain {record['gain_requested']:g} folds {name} (a move of {fold['reach_requested_px']:g} px); "+ f"lowered to --gain {entry['gain']:g} for it")+ elif fold["lowered"]:+ notes.append(f"{verb}: --gain {record['gain_requested']:g} folds a region (a move of {fold['reach_requested_px']:g} px); "+ f"lowered to --gain {record['gain']:g}")+ return notes+++def run(**kwargs: object) -> int:+ verb = str(kwargs.get("verb") or VERB)+ result = sway_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), verb=verb, # type: ignore[arg-type]+ gain=float(kwargs.get("gain", GAIN_DEFAULT)), freq=float(kwargs.get("freq", FREQ_DEFAULT)), # type: ignore[arg-type]+ zeta=float(kwargs.get("zeta", ZETA_DEFAULT)), board=kwargs.get("board"), # type: ignore[arg-type]+ on_fold=str(kwargs.get("on_fold") or "refuse"), read_on=kwargs.get("read_on"), # type: ignore[arg-type]+ stretch_floor=kwargs.get("stretch_floor")) # type: ignore[arg-type]+ fold = result["fold"]+ own = "held" in fold["regions"][0] # the regions took gains of their own+ for note in fold_notes(result, verb):+ print(note, file=sys.stderr)+ print(json.dumps({k: result[k] for k in ("strip", "regions", "gain", "gain_requested", "on_fold", "body_bob_px", "reach_px")}+ | ({"region_gains": [entry["gain"] for entry in fold["regions"]]} if own else {})+ | ({"read_on": result["read_on"]["relation"]} if "read_on" in result else {})+ | ({"stretch_floor": result["stretch"]["floor"]} if "stretch" in result else {})+ | ({"board": result["board"]} if "board" in result else {}), ensure_ascii=False, indent=2))+ return 0+++def main(argv: list[str] | None = None, verb: str = VERB) -> int:+ parser = argparse.ArgumentParser(prog=f"sprite-gen {verb}", description=__doc__)+ add_arguments(parser)+ return run(**vars(parser.parse_args(argv)), verb=verb)+++# The old names, kept: the same functions, called as they always were (the old verb in what they say).+def follow_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], **kwargs: Any) -> dict[str, Any]:+ return sway_loop(loop_dir, regions, **{"verb": OLD_VERB, **kwargs})+++follow_offsets = sway_offsets+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/sprite_gen/video/sway_inspect.py b/sprite_gen/video/sway_inspect.pynew file mode 100644index 0000000..7b47789--- /dev/null+++ b/sprite_gen/video/sway_inspect.py@@ -0,0 +1,416 @@+# SPDX-License-Identifier: Apache-2.0+"""`sprite-gen video-sway-inspect` — where the Sway layer carries its regions in every cell, with nothing moved.++Its old name, `video-follow-inspect` (`sprite_gen.video.follow_inspect`), still runs it and writes the same+record. The record's file names and keys (`follow-inspect.json`, `follow`, `follow_recorded`) are unchanged.++`video-follow` is given an ellipse over a soft part in the strip's first cell and carries it with the body+into every other cell; inside the carried ellipse every pixel moves, whatever it is a picture of. For the+first cell somebody looked and said where the part is. For the others nobody did: an arm that swings across+a chest is inside the chest's ellipse in those cells, and moves with it. The engine does not read what a+pixel belongs to, and it does not guess it here either: every region is written `ownership: unknown` in+every cell, from its centre to its rim, the first cell included.++This command writes what somebody needs in order to look, and changes nothing. It takes what `video-follow`+takes, reads the loop as `video-follow` would (the strip as cut: `follow.source.png` where a follow-through+was already written, the strip itself where none was) and solves it with the same code (`sway.read_request`,+`sway.solve`). Into `--out-dir`, which is never the loop directory, it writes:++- `follow-inspect.json`, the record: what was read (the strip's and the meta's sha256, the regions, the+ settings, the engine and the way it reads, and `input_id`, one sha256 over those); the follow-through as+ `video-follow` would record it (`follow`); per cell how far the regions are carried (`carry_px`) and, per+ region, the carried ellipse, its offset, how near that is to folding it, the least area of the source a+ pixel of the moved cell takes (`jacobian_min`: 1 where nothing moves, 0 where the picture stops and one+ pixel of the source is drawn across many, under 0 where it would run backwards), how many pixels the+ ellipse covers and how many of them are body, and how many the move changes;+- `follow-inspect.source.png`, every cell of the strip as cut with each region's carried ellipse ringed;+- `follow-inspect.moved.png`, the same cells as `video-follow` would write them, ringed alike.++A move does three things to the picture, and the record (schema 2) writes each apart. It stretches it: the least+area a pixel takes (`jacobian_min`, D). It tilts a line: the move's steepest slope, |offset|·π/(2·smaller radius)+(`bend`, G, and `bend_deg` = atan G) — the old `fold_ratio` is this number, and at 1 a line tilts 45°. And where+two regions overlap, the larger move takes over across a curve and the slope jumps there: per pair, the largest+jump on that curve (`seams`: the norm of the difference of the two moves' gradients, and its angle). A floor on+the area (`--stretch-floor`) holds D up and lowers G and the seam only with it.++The two boards are apart so that whoever says what is inside an ellipse can read the cells as cut alone,+without the answer beside them. The record holds no path, no time and nothing of the machine: the same loop+asked the same way writes the same record. `input_id` does not change when `video-follow` is run on the loop+(it reads the strip as cut, and the meta without the `follow` record `video-follow` adds) and changes with+anything the answer is read from — a new cut, an alignment, a region, a setting, the engine. The boards'+`pixels_sha256` is over their pixels, so another PNG writer gives the same one; how the boards are drawn+(`--scale`, `--columns`) is no part of `input_id`. docs/video-pipeline.md section 6.+"""++from __future__ import annotations++import argparse+import hashlib+import io+import json+import math+import sys+from importlib.metadata import PackageNotFoundError, version as package_version+from pathlib import Path+from typing import Any++from PIL import Image++from sprite_gen._deps import np+from sprite_gen.spec.runio import atomic_write_set+from sprite_gen.video import loop as loop_mod+from sprite_gen.video import sway++VERB = "video-sway-inspect"+OLD_VERB = "video-follow-inspect" # the old name, kept: it runs this and says its own name+KIND = "video-follow-inspection"+SCHEMA_VERSION = 2 # 2: the bend and the seams beside the least area; the read_on and the stretch floor asked+RECORD, SOURCE_BOARD, MOVED_BOARD = "follow-inspect.json", "follow-inspect.source.png", "follow-inspect.moved.png"+UNKNOWN = "unknown" # what is inside a carried ellipse: the engine does not read it+SCALE_DEFAULT = 2 # board pixels per cell pixel: at 2 or more a ring covers no cell pixel whole+COLUMNS_DEFAULT = 8+PLACES = 4 # decimals of the offsets, ratios and areas: under what two machines' FFTs differ by+DEGREES = 2 # decimals of an angle+SEAM_STEP = 0.25 # px between the points along each row where a seam is looked for, before it is found by halving+SEAM_HALVINGS = 30+GROUND = (128, 128, 128) # under a cell's clear pixels+BETWEEN = (32, 32, 32) # between the cells, and under their numbers+INK = (255, 255, 255) # a cell's number+DARK = (0, 0, 0) # every other dash of a ring, so it shows on any colour+RINGS = ((255, 235, 0), (0, 255, 255), (255, 96, 0), (0, 255, 96), (255, 0, 200), (120, 160, 255)) # by region; they repeat+DASH = 2 # board pixels of a ring in its colour, then as many dark+GAP = 6 # board pixels between cells+DOT = 3 # board pixels per dot of a digit+PAD = 3 # above and under a cell's number+DIGITS = {+ "0": ("###", "# #", "# #", "# #", "###"), "1": (" # ", "## ", " # ", " # ", "###"), "2": ("###", " #", "###", "# ", "###"),+ "3": ("###", " #", "###", " #", "###"), "4": ("# #", "# #", "###", " #", " #"), "5": ("###", "# ", "###", " #", "###"),+ "6": ("###", "# ", "###", "# #", "###"), "7": ("###", " #", " #", " #", " #"), "8": ("###", "# #", "###", "# #", "###"),+ "9": ("###", "# #", "###", " #", "###"),+}+++def _sha256(data: bytes) -> str:+ return hashlib.sha256(data).hexdigest()+++def _canonical(value: Any) -> bytes:+ """One spelling of a JSON value: keys sorted, no spaces, ASCII."""+ return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("ascii")+++def _engine_version() -> str:+ try:+ return package_version("sprite-gen")+ except PackageNotFoundError: # pragma: no cover - bare checkout+ return "unknown"+++def policy() -> dict[str, Any]:+ """The way the motion is read and a region moved: its name and the numbers it is fixed by; the way a reading+ is carried from a cut (`--read-on`) and a floor kept (`--stretch-floor`), by name."""+ return {"name": sway.POLICY, "harmonics": sway.HARMONICS, "alpha_solid": sway.ALPHA_SOLID,+ "worn": [sway.WORN_FROM, sway.WORN_TO], "gain_measured": sway.GAIN_MEASURED, "gain_step": sway.GAIN_STEP,+ "weight": "cos2", "transport": sway.TRANSPORT_POLICY, "stretch_floor": sway.STRETCH_POLICY}+++def _degrees(slope: float) -> float:+ return round(math.degrees(math.atan(slope)), DEGREES)+++def _weight_and_gradient(x: np.ndarray, y: np.ndarray, ellipse: tuple[float, float, float, float]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:+ """A region's weight at points (x, y) — cos² of the ellipse's own radius, 0 at its rim and outside — and the+ weight's gradient there, across and down."""+ cx, cy, rx, ry = ellipse+ u, v = (x - cx) / rx, (y - cy) / ry+ r = np.hypot(u, v)+ inside = r < 1+ weight = np.where(inside, np.cos(r * math.pi / 2) ** 2, 0.0)+ slope = np.where(inside & (r > 0), -(math.pi / 2) * np.sin(math.pi * r) / np.where(r > 0, r, 1.0), 0.0)+ return weight, slope * u / rx, slope * v / ry+++def seam(a: tuple[float, float, float, float], b: tuple[float, float, float, float], move_a: tuple[float, float],+ move_b: tuple[float, float], one_gain: bool) -> tuple[float, list[float]] | None:+ """Where two overlapping regions, carried into a cell and moved by their own offsets, meet: `video-follow` moves a+ pixel by the larger of their weighted moves (by the larger weight where they move by one gain), so across the+ curve where the two are equal the move's gradient jumps from one region's to the other's, and a straight line+ bends there. The largest jump on that curve — the norm of the difference of the two gradients (each the offset+ times its weight's gradient) — and the point it is at; None where no such curve is inside both.++ The curve is looked for along rows SEAM_STEP apart, between points SEAM_STEP apart inside both ellipses where the+ larger move changes hands, and found there by halving."""+ xs = np.arange(int((max(a[0] + a[2], b[0] + b[2]) - min(a[0] - a[2], b[0] - b[2])) / SEAM_STEP) + 1) * SEAM_STEP + min(a[0] - a[2], b[0] - b[2])+ ys = np.arange(int((max(a[1] + a[3], b[1] + b[3]) - min(a[1] - a[3], b[1] - b[3])) / SEAM_STEP) + 1) * SEAM_STEP + min(a[1] - a[3], b[1] - b[3])+ reach_a, reach_b = (1.0, 1.0) if one_gain else (math.hypot(*move_a), math.hypot(*move_b))++ def larger(x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:+ wa, wb = _weight_and_gradient(x, y, a)[0], _weight_and_gradient(x, y, b)[0]+ return reach_a * wa - reach_b * wb, (wa > 0) & (wb > 0)++ yy, xx = np.meshgrid(ys, xs, indexing="ij")+ difference, both = larger(xx, yy)+ above = difference > 0+ rows, cols = np.nonzero(both[:, :-1] & both[:, 1:] & (above[:, :-1] != above[:, 1:]))+ if not len(rows):+ return None+ lo, hi, y, left = xs[cols], xs[cols + 1], ys[rows], above[rows, cols]+ for _ in range(SEAM_HALVINGS): # the two ellipses' common part is convex: every midpoint is inside both+ mid = (lo + hi) / 2+ same_side = (larger(mid, y)[0] > 0) == left+ lo, hi = np.where(same_side, mid, lo), np.where(same_side, hi, mid)+ x = (lo + hi) / 2+ _, ax, ay = _weight_and_gradient(x, y, a)+ _, bx, by = _weight_and_gradient(x, y, b)+ (oax, oay), (obx, oby) = move_a, move_b+ jump = np.sqrt((oax * ax - obx * bx) ** 2 + (oax * ay - obx * by) ** 2 + (oay * ax - oby * bx) ** 2 + (oay * ay - oby * by) ** 2)+ k = int(np.argmax(jump))+ return float(jump[k]), [round(float(x[k]), 3), round(float(y[k]), 3)]+++def jacobian(move_x: np.ndarray, move_y: np.ndarray) -> np.ndarray:+ """Per pixel of a moved cell, but for those on its edge, the area of the source it takes. The moved cell's+ pixel p is read from the source at p less its move, so the area is read between p's neighbours on either+ side, across and down, as half of how far apart those are read: 1 where nothing moves, 0 where the picture+ stops, under 0 where it runs backwards. Between the neighbours on either side, not from p to the next pixel+ one way: read one way, a round region a few pixels across reads steeper on the side it bulges to than its+ weight is anywhere. One row and one column shorter than the cell at each edge."""+ across_x, across_y = (move_x[1:-1, 2:] - move_x[1:-1, :-2]) / 2, (move_y[1:-1, 2:] - move_y[1:-1, :-2]) / 2+ down_x, down_y = (move_x[2:, 1:-1] - move_x[:-2, 1:-1]) / 2, (move_y[2:, 1:-1] - move_y[:-2, 1:-1]) / 2+ return (1 - across_x) * (1 - down_y) - down_x * across_y+++def _least(area: np.ndarray | None, mask: np.ndarray) -> tuple[float, list[int] | None]:+ """The least of `area` over the pixels of `mask`, and that pixel (x, y); 1 and no pixel where nothing moves+ there."""+ if area is None:+ return 1.0, None+ inner = mask[1:-1, 1:-1]+ if not inner.any():+ return 1.0, None+ values = np.where(inner, area, np.inf)+ y, x = divmod(int(np.argmin(values)), values.shape[1])+ return float(values[y, x]), [x + 1, y + 1]+++def _grown(mask: np.ndarray) -> np.ndarray:+ """`mask` and the pixels beside it: above, under, left and right."""+ grown = mask.copy()+ grown[1:] |= mask[:-1]+ grown[:-1] |= mask[1:]+ grown[:, 1:] |= mask[:, :-1]+ grown[:, :-1] |= mask[:, 1:]+ return grown+++def _tile(cell: Image.Image, masks: list[np.ndarray], scale: int) -> np.ndarray:+ """A cell on the board: over the ground, `scale` board pixels to a cell pixel, each region's ring drawn on the+ board pixels just outside its ellipse — inside an ellipse nothing is drawn but another region's ring."""+ ground = Image.new("RGBA", cell.size, (*GROUND, 255))+ ground.alpha_composite(cell)+ tile = np.repeat(np.repeat(np.asarray(ground.convert("RGB")), scale, axis=0), scale, axis=1)+ yy, xx = np.mgrid[0:tile.shape[0], 0:tile.shape[1]]+ lit = (xx + yy) // DASH % 2 == 0+ for i, mask in enumerate(masks):+ covered = np.repeat(np.repeat(mask, scale, axis=0), scale, axis=1)+ ring = _grown(covered) & ~covered+ tile[ring & lit] = RINGS[i % len(RINGS)]+ tile[ring & ~lit] = DARK+ return tile+++def _number(board: np.ndarray, text: str, x: int, y: int) -> None:+ for char in text:+ for row, dots in enumerate(DIGITS[char]):+ for col, dot in enumerate(dots):+ if dot == "#":+ board[y + row * DOT: y + (row + 1) * DOT, x + col * DOT: x + (col + 1) * DOT] = INK+ x += 4 * DOT+++def _boards(tiles: list[list[np.ndarray]], columns: int) -> tuple[list[np.ndarray], list[list[int]]]:+ """One board per list of tiles, all laid alike: the cells in order, `columns` to a row, each under its number+ (cell 0 first). With them, per cell, the box (x0, y0, x1, y1) its picture takes on every board."""+ n = len(tiles[0])+ tile_h, tile_w = tiles[0][0].shape[:2]+ label = 5 * DOT + 2 * PAD+ across, down = min(n, columns), math.ceil(n / columns)+ size = (GAP + down * (label + tile_h + GAP), GAP + across * (tile_w + GAP), 3)+ boards = [np.full(size, BETWEEN, np.uint8) for _ in tiles]+ boxes = []+ for k in range(n):+ x0 = GAP + (k % columns) * (tile_w + GAP)+ y0 = GAP + (k // columns) * (label + tile_h + GAP) + label+ boxes.append([x0, y0, x0 + tile_w, y0 + tile_h])+ for board, cells in zip(boards, tiles):+ _number(board, str(k), x0, y0 - label + PAD)+ board[y0: y0 + tile_h, x0: x0 + tile_w] = cells[k]+ return boards, boxes+++def _png(board: np.ndarray) -> bytes:+ data = io.BytesIO()+ Image.fromarray(board).save(data, format="PNG")+ return data.getvalue()+++def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], out_dir: Path, *,+ gain: float = sway.GAIN_DEFAULT, freq: float = sway.FREQ_DEFAULT, zeta: float = sway.ZETA_DEFAULT,+ on_fold: str = "refuse", scale: int = SCALE_DEFAULT, columns: int = COLUMNS_DEFAULT,+ read_on: str | None = None, stretch_floor: float | None = None, verb: str = VERB) -> dict[str, Any]:+ """The record of what `video-sway` asked the same way does to the loop, written with its two boards into+ `out_dir`. The loop directory is read and not written."""+ request = sway.read_request(loop_dir, regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, verb=verb,+ read_on=read_on, stretch_floor=stretch_floor)+ out_dir = out_dir.expanduser().resolve()+ if out_dir == request.loop_dir or request.loop_dir in out_dir.parents:+ raise SystemExit(f"{verb}: --out-dir {out_dir} is in the loop directory; an inspection writes nothing there")+ scale, columns = int(scale), int(columns)+ if scale < 1 or columns < 1:+ raise SystemExit(f"{verb}: --scale and --columns must be 1 or more")+ # The strip as cut, as `video-follow` reads it; it keeps one beside the loop on its first run, and this does not.+ strip_path = request.source_path if request.source_path.exists() else request.strip_path+ strip_bytes = strip_path.read_bytes()+ answer = sway.solve(request, Image.open(io.BytesIO(strip_bytes)).convert("RGBA"), strip_name=strip_path.name, verb=verb,+ strip_sha256=_sha256(strip_bytes))+ n, (w, h) = len(answer.cells), answer.cells[0].size+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)+ cells, source_tiles, moved_tiles = [], [], []+ for k in range(n):+ carry = answer.carry(k)+ before, moved = np.asarray(answer.cells[k]), answer.moved(k)+ changed = (before != np.asarray(moved)).any(axis=-1)+ solid = before[..., 3] >= sway.ALPHA_SOLID+ field = sway.move_field(xx, yy, answer.moves_in(k), carry)+ area = None if field is None else jacobian(field[1], field[2])+ masks = [sway.region_weight(xx, yy, region, carry) > 0 for region in request.regions]+ entries, offsets = [], []+ for i, ((cx, cy, rx, ry), radius, g, hold, mask) in enumerate(zip(request.regions, answer.radii, answer.gains,+ answer.held, masks)):+ dx, dy = (0.0, 0.0) if hold else (float(answer.moves[g][0][k]), float(answer.moves[g][1][k]))+ offsets.append((dx, dy))+ least, at = _least(area, mask)+ bend = sway.fold_ratio(math.hypot(dx, dy), radius) # the move's steepest slope: G+ entries.append({+ "index": i, "ellipse": [round(cx + float(carry[0]), 6), round(cy + float(carry[1]), 6), rx, ry],+ "offset_px": [round(dx, PLACES) + 0.0, round(dy, PLACES) + 0.0], "reach_px": round(math.hypot(dx, dy), PLACES),+ "fold_ratio": round(bend, PLACES),+ "jacobian_min": round(least, PLACES), "jacobian_min_at": at,+ "bend": round(bend, PLACES), "bend_deg": _degrees(bend),+ "ellipse_px": int(mask.sum()), "solid_px": int((mask & solid).sum()), "changed_px": int((mask & changed).sum()),+ "ownership": UNKNOWN,+ })+ seams = []+ moving = [i for i, hold in enumerate(answer.held) if not hold]+ for i in moving:+ for j in (j for j in moving if j > i):+ found = seam(*(tuple(entries[m]["ellipse"]) for m in (i, j)), offsets[i], offsets[j], answer.gains[i] == answer.gains[j])+ if found is not None:+ seams.append({"regions": [i, j], "jump": round(found[0], PLACES), "deg": _degrees(found[0]), "at": found[1]})+ cells.append({+ "index": k, "carry_px": [float(carry[0]), float(carry[1])], "changed_px": int(changed.sum()),+ "jacobian_min": 1.0 if area is None or not area.size else round(float(area.min()), PLACES), "regions": entries,+ "seams": seams,+ })+ source_tiles.append(_tile(answer.cells[k], masks, scale))+ moved_tiles.append(_tile(moved, masks, scale))+ (source_board, moved_board), boxes = _boards([source_tiles, moved_tiles], columns)+ for cell, box in zip(cells, boxes):+ cell["box"] = box+ source_png, moved_png = _png(source_board), _png(moved_board)++ meta = request.meta+ cut_sha256 = _sha256(_canonical({key: value for key, value in meta.items() if key not in loop_mod.SWAY_RECORD_KEYS}))+ inputs = {+ "strip": {"file": strip_path.name, "sha256": _sha256(strip_bytes), "bytes": len(strip_bytes)},+ # `sha256` is the file's as read; `cut_sha256` is the meta's without the `follow` record `video-follow`+ # adds (one spelling: keys sorted, no spaces), so it is the same before and after a follow-through.+ "meta": {"file": request.meta_path.name, "sha256": _sha256(request.meta_bytes), "bytes": len(request.meta_bytes),+ "cut_sha256": cut_sha256, "follow_recorded": loop_mod.sway_recorded(meta)},+ "cut": {"frames": n, "w": w, "h": h, "delay_ms": float(meta["delay_ms"])},+ "regions": [list(region) for region in request.regions],+ "settings": {"gain": request.gain, "on_fold": request.on_fold, "freq_hz": request.freq, "zeta": request.zeta,+ "read_on": request.read_on, "stretch_floor": request.stretch_floor},+ "policy": policy(),+ "engine": {"name": "sprite-gen", "version": _engine_version()},+ }+ input_id = _sha256(_canonical({+ "schema_version": SCHEMA_VERSION, "engine": inputs["engine"], "policy": inputs["policy"],+ "strip_sha256": inputs["strip"]["sha256"], "cut_sha256": cut_sha256,+ "regions": inputs["regions"], "settings": inputs["settings"],+ }))+ pairs: dict[tuple[int, int], dict[str, Any]] = {}+ for cell in cells: # per pair of regions, the largest seam of any cell, the first cell on a tie+ for found in cell["seams"]:+ key = tuple(found["regions"])+ if key not in pairs or found["jump"] > pairs[key]["jump"]:+ pairs[key] = {"regions": found["regions"], "jump": found["jump"], "deg": found["deg"], "cell": cell["index"], "at": found["at"]}+ record = {+ "kind": KIND, "schema_version": SCHEMA_VERSION, "input_id": input_id, "inputs": inputs,+ "follow": answer.record(),+ "carry_basis": dict(sway.CARRY_BASIS),+ "regions": [{+ "index": i, "ellipse": list(region), "radius_px": radius, "gain": g, "held": hold,+ "gain_limit": None if (limit := sway.gain_limit(answer.reach_per_gain, radius)) is None else round(limit, 3),+ "reach_px": max(cell["regions"][i]["reach_px"] for cell in cells),+ "fold_ratio": max(cell["regions"][i]["fold_ratio"] for cell in cells),+ "jacobian_min": min(cell["regions"][i]["jacobian_min"] for cell in cells),+ "bend": max(cell["regions"][i]["bend"] for cell in cells), "bend_deg": max(cell["regions"][i]["bend_deg"] for cell in cells),+ "changed_px": sum(cell["regions"][i]["changed_px"] for cell in cells),+ "ring": list(RINGS[i % len(RINGS)]),+ } for i, (region, radius, g, hold) in enumerate(zip(request.regions, answer.radii, answer.gains, answer.held))],+ "seams": [pairs[key] for key in sorted(pairs)],+ "cells": cells,+ "boards": {+ "scale": scale, "columns": columns, "size": [int(source_board.shape[1]), int(source_board.shape[0])],+ "ground": list(GROUND),+ "source": {"file": SOURCE_BOARD, "sha256": _sha256(source_png), "pixels_sha256": _sha256(source_board.tobytes())},+ "moved": {"file": MOVED_BOARD, "sha256": _sha256(moved_png), "pixels_sha256": _sha256(moved_board.tobytes())},+ },+ }+ out_dir.mkdir(parents=True, exist_ok=True)+ # The boards and the record that names them, together: a run that fails on the way leaves `out_dir` as it was.+ atomic_write_set({out_dir / SOURCE_BOARD: source_png, out_dir / MOVED_BOARD: moved_png,+ out_dir / RECORD: json.dumps(record, ensure_ascii=False, indent=2) + "\n"})+ return record+++def add_arguments(parser: argparse.ArgumentParser) -> None:+ sway.add_request_arguments(parser)+ parser.add_argument("--out-dir", required=True, type=Path,+ help=f"where {RECORD}, {SOURCE_BOARD} and {MOVED_BOARD} are written; not the loop directory, which is only read")+ parser.add_argument("--scale", type=int, default=SCALE_DEFAULT,+ help=f"board pixels per cell pixel (default {SCALE_DEFAULT}; at 2 or more a ring covers no cell pixel whole)")+ parser.add_argument("--columns", type=int, default=COLUMNS_DEFAULT, help=f"cells per row of a board (default {COLUMNS_DEFAULT})")+++def run(**kwargs: object) -> int:+ verb = str(kwargs.get("verb") or VERB)+ out_dir = Path(str(kwargs["out_dir"]))+ record = inspect_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), out_dir, # type: ignore[arg-type]+ gain=float(kwargs.get("gain", sway.GAIN_DEFAULT)), freq=float(kwargs.get("freq", sway.FREQ_DEFAULT)), # type: ignore[arg-type]+ zeta=float(kwargs.get("zeta", sway.ZETA_DEFAULT)), on_fold=str(kwargs.get("on_fold") or "refuse"), # type: ignore[arg-type]+ scale=int(kwargs.get("scale", SCALE_DEFAULT)), columns=int(kwargs.get("columns", COLUMNS_DEFAULT)), # type: ignore[call-overload]+ read_on=kwargs.get("read_on"), stretch_floor=kwargs.get("stretch_floor"), verb=verb) # type: ignore[arg-type]+ for note in sway.fold_notes(record["follow"], verb):+ print(note, file=sys.stderr)+ out_dir = out_dir.expanduser().resolve()+ print(json.dumps({+ "record": str(out_dir / RECORD), "input_id": record["input_id"], "cells": len(record["cells"]),+ "region_gains": [region["gain"] for region in record["regions"]],+ "held": [region["index"] for region in record["regions"] if region["held"]],+ "ownership": UNKNOWN,+ "boards": {name: {"path": str(out_dir / record["boards"][name]["file"]), "pixels_sha256": record["boards"][name]["pixels_sha256"]}+ for name in ("source", "moved")},+ }, ensure_ascii=False, indent=2))+ return 0+++def main(argv: list[str] | None = None, verb: str = VERB) -> int:+ parser = argparse.ArgumentParser(prog=f"sprite-gen {verb}", description=__doc__)+ add_arguments(parser)+ return run(**vars(parser.parse_args(argv)), verb=verb)+++if __name__ == "__main__":+ raise SystemExit(main())