Skip to content

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.py
index 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.py
index 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_prompt
from sprite_gen.video import align as video_align
from sprite_gen.video import follow as video_follow
from 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_inspect
from sprite_gen.video import set_sheet as video_set_sheet
from sprite_gen.video import stop as video_stop
from sprite_gen.video import compare as video_compare
@@ -385,16 +387,16 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
video_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.py
index 056190e..dec5835 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -97,7 +97,7 @@ from sprite_gen._deps import np
from sprite_gen.gen import handedness as handed_mod
from sprite_gen.spec.runio import atomic_write_text
from 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_mod
from sprite_gen.video import held as held_mod
from sprite_gen.video import legs as legs_mod
from 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[str
strip = 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: list
standing_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.py
index 5a50688..139bf3c 100644
--- a/sprite_gen/video/compare.py
+++ b/sprite_gen/video/compare.py
@@ -21,7 +21,8 @@ from PIL import Image
from sprite_gen._deps import np
from 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_mod
from sprite_gen.video.interpolation_quality import faults
METRIC_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.py
index 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 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-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.py
index 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_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 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.py
index 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: the
diff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.py
index 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 | Non
m, report = baseline.meta, baseline.source_report
if 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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())