Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(sway): the Sway layer on a cycle's frames at their own size (--frames, --out), on the breath (--breathe, --lag), a region moved whole (its flat share) and across apart from down (--gain-across); a cell no region moves is the cell as it was
Soohong Kim21ee376c8bf8
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex f105da8..5290791 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -382,7 +382,7 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callabvideo_align.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.",+ "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), or of a cycle's frames at their own size (--frames, --out); on the breath, late behind the Breathe layer's chest (--breathe). Old name video-follow, still run.",video_sway.add_arguments,video_sway.run,),diff --git a/sprite_gen/effects/anatomy.py b/sprite_gen/effects/anatomy.pyindex 582f54f..8a8b2c0 100644--- a/sprite_gen/effects/anatomy.py+++ b/sprite_gen/effects/anatomy.py@@ -94,6 +94,15 @@ class Anatomy:"face": list(self.face) if self.face else None,"warnings": list(self.warnings)}+ @classmethod+ def from_dict(cls, data: dict) -> "Anatomy":+ """`as_dict` 가 쓴 한 벌을 다시 읽는다 (breathe.json 의 resolved.anatomy) — 잰 자리(`origin`, `neck_span`)는 실리지+ 않으니 없다."""+ keys = ("width", "height", "axis_x", "neck_row", "neck_source", "rigid_row", "rigid_source", "basis_row",+ "torso_half", "max_half", "torso_source")+ return cls(**{k: data[k] for k in keys}, face=tuple(data["face"]) if data.get("face") else None,+ warnings=tuple(data.get("warnings") or ()))+# ── 실루엣 ──────────────────────────────────────────────────────────diff --git a/sprite_gen/video/sway.py b/sprite_gen/video/sway.pyindex 0e09b5a..35d786f 100644--- a/sprite_gen/video/sway.py+++ b/sprite_gen/video/sway.py@@ -62,6 +62,26 @@ held, every region held refused; `--on-fold refuse` refuses). The record names tWhat carries a region is the lay of the body's outline (`carry_basis`): whose pixels are inside thecarried ellipse is not read, and nothing here moves a region on a guess of it.++A strip holds 64 cells and 32,000 px across at most, so a cycle of large frames is cut down to fit it. `--frames+<folder> --out <new folder>` sways a cycle's frames themselves — a loop's `cycle/`, or what `sprite-gen breathe` wrote+from it — at their own size and count, into a new folder of the same frames under the same names and `sway.json`, as+`sprite-gen breathe` writes one. It is the same ask answered by the same code, cell for cell (`solve_cells`): a strip+cut from those frames at scale 1 with none left out, its regions moved by its crop origin, moves its cells as these+are moved, at the frame time its meta writes — rounded to hundredths of a ms, as `--fps` is read here.++A breathing idle's head stays where it is and its body moves a pixel or two: read off the outline, that motion is+whole-pixel steps, and the damped mass answers their jerks, not the breath. `--breathe <breathe.json>` sways the part+on the breath instead: the Breathe layer's record of the breath the frames were given (`sprite-gen breathe` writes it+beside them), its phases checked against those its config gives. The chest rises lift × w; the part rises as far, late+by `--lag` of a breath (the time warp the Breathe layer's shoulders are late by), and lies the difference behind:+offset = gain × lift × (w − w late), against the way the chest rises. Where the breath rests the offset is 0 — the first+cell, and where the loop closes — and a cell whose every offset is 0 is the cell as it was, byte for byte.++A region's fifth number, flat, is the share of the way from its centre to its rim that moves in full — the Breathe+layer's chest weight (`breathe.flat_cos2`) — so a large part moves as one piece instead of pressed in at its middle;+the fold rule and the floor read it by the radius left (1 − flat of it). `--gain-across` moves across by a gain of its+own; a gain the fold rule or the floor lowers lowers both in proportion."""from __future__ import annotations@@ -83,6 +103,10 @@ from typing import Anyfrom PIL import Imagefrom sprite_gen._deps import np+from sprite_gen.curate.curation import BREATHE_SMOOTH_SHAPE_RANGES, state_breathe+from sprite_gen.effects import breathe as breathe_mod+from sprite_gen.effects.anatomy import Anatomy+from sprite_gen.frames import folder as folder_modfrom sprite_gen.spec.runio import atomic_write_textfrom sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.video import loop as loop_mod@@ -94,9 +118,15 @@ OLD_VERB = "video-follow" # the old name, kept: it runs this and says its own n# 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"+BREATH_POLICY = "common-lay/breath-late/cos2-bilinear/1" # the offset from the breath (`--breathe`), not the body's motionFREQ_DEFAULT = 2.4 # Hz: a slow, soft partZETA_DEFAULT = 0.6 # damping ratio: it lags and settles, with no ringingGAIN_DEFAULT = 2.5 # times the physical answer+BREATH_GAIN_DEFAULT = 1.0 # times the breath's rise less the part's own, late by --lag: under the breath's own rise+LAG_DEFAULT = 0.15 # of one breath: the part peaks this much of a breath after the chest+LAG_MAX = 1 / math.pi # at it the late breath's time stops; past it, it runs backwards (breathe.smooth_shoulder_wave)+FLAT_RANGE = BREATHE_SMOOTH_SHAPE_RANGES["chest_flat"] # a region's flat share: the Breathe layer's chest_flat, one weight+FRAMES_RECORD = "sway.json" # beside the frames `--frames ... --out` writesGAIN_MEASURED = 1.0 # the mass as measured: `--on-fold lower` does not go under itGAIN_STEP = 0.01 # a lowered gain is a whole number of these, so the report's `gain` is the `--gain` to passON_FOLD_MODES = ("refuse", "lower")@@ -115,14 +145,43 @@ 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]:+def parse_region(text: str) -> tuple[float, ...]:+ try:+ values = [float(v) for v in text.split(",")]+ except ValueError as exc:+ raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry[,flat] (four or five numbers), got {text!r}") from exc+ if len(values) not in (4, 5):+ raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry[,flat] (four or five numbers), got {text!r}")try:- cx, cy, rx, ry = (float(v) for v in text.split(","))+ return region_of(values)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+ raise argparse.ArgumentTypeError(f"--region {text!r}: {exc}") from exc+++def region_of(values) -> tuple[float, ...]:+ """A region as the engine reads it: cx, cy, rx, ry, and its flat share where it has one. A flat share of 0 is no+ flat share: the region is read, moved and recorded as one of four numbers."""+ values = [float(v) for v in values]+ if values[2] <= 0 or values[3] <= 0:+ raise ValueError(f"radii must be positive, got {values[2]:g},{values[3]:g}")+ if len(values) == 5:+ if not FLAT_RANGE[0] <= values[4] <= FLAT_RANGE[1]: # a NaN is not+ raise ValueError(f"flat is the share of the way from the centre to the rim that moves in full, "+ f"{FLAT_RANGE[0]:g} to {FLAT_RANGE[1]:g}; got {values[4]:g}")+ if values[4] == 0:+ values = values[:4]+ return tuple(values)+++def flat_of(region: tuple[float, ...]) -> float:+ """A region's flat share: the share of the way from its centre to its rim that moves in full (0: none)."""+ return region[4] if len(region) > 4 else 0.0+++def region_radius(region: tuple[float, ...]) -> float:+ """The radius the fold rule reads a region by: its smaller radius, less its flat share — the weight falls from 1 to 0+ over what is left, and steepest there."""+ return min(region[2], region[3]) * (1 - flat_of(region))def parse_read_on(text: str) -> str:@@ -427,12 +486,13 @@ def lowered_gain(gain: float, reach_per_gain: float, radius: float) -> float: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]:+def stretch_per_gain(radii: tuple[float, float], across: np.ndarray, down: np.ndarray, flat: float = 0.0) -> 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)."""+ (`across`, `down`: the move at gain 1, per cell); a region with a flat share falls over what is left of each radius,+ 1 − flat of it, and leaves 1 − (π/2)/(1 − flat)·hypot(ox/rx, oy/ry)."""rx, ry = radii- per_cell = (math.pi / 2) * np.hypot(across / rx, down / ry)+ per_cell = (math.pi / 2) / (1 - flat) * np.hypot(across / rx, down / ry)k = int(np.argmax(per_cell))return float(per_cell[k]), k@@ -460,13 +520,14 @@ def _sample(premultiplied: np.ndarray, sx: np.ndarray, sy: np.ndarray) -> np.ndareturn (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],+def region_weight(xx: np.ndarray, yy: np.ndarray, region: tuple[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+ `shift` — and over its flat share of the way to the rim, where it has one — 0 at its rim (cos²) and outside it:+ the Breathe layer's chest weight (`breathe.flat_cos2`). The pixels a region covers are those where this is over 0."""+ cx, cy, rx, ry = region[:4]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)+ return breathe_mod.flat_cos2(r, flat_of(region))def move_field(xx: np.ndarray, yy: np.ndarray, moves: list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]],@@ -494,7 +555,10 @@ def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, fThe groups' offsets are one motion times their gains, so where regions of different groupsoverlap the larger move wins: the move is the largest of the groups' weighted moves, which is- nowhere steeper than the steepest group's own."""+ nowhere steeper than the steepest group's own. Where every offset is 0 the cell is as it was, byte for+ byte — the colour under its clear pixels too, which a move clears."""+ if all(dx == 0 and dy == 0 for _, (dx, dy) in moves):+ return cell.copy()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)@@ -514,22 +578,154 @@ def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, freturn Image.fromarray(out, "RGBA")+@dataclass(frozen=True, eq=False)+class Breath:+ """The breath a sway follows (`--breathe`): the Breathe layer's record of it — `sprite-gen breathe` writes+ breathe.json beside the frames it breathed — read and checked, and how late the part follows it (`--lag`)."""++ path: Path+ sha256: str # of the record's bytes+ phases: list[float] # per cell, the breath's phase+ beat: dict[str, Any] # the breath count, or the cell of each in-breath's peak+ lift: float # px the chest rises at the top of an in-breath (breathe.smooth_lift)+ heading: float # degrees from straight up the chest rises toward (its chest_dir)+ lag: float # of one breath++ def unit(self) -> tuple[np.ndarray, np.ndarray]:+ """Per cell, the part's offset from where the breath carries it at gain 1, across and down: the chest rises+ `lift` × w (breathe.smooth_wave), the part as far late by `lag` (the time warp the Breathe layer's shoulders are+ late by, breathe.smooth_shoulder_wave), and the part lies the difference behind, against the way the chest+ rises. 0 where the breath rests — its first cell, and where the loop closes."""+ share = np.asarray([breathe_mod.smooth_wave(p) - breathe_mod.smooth_shoulder_wave(p, self.lag) for p in self.phases])+ heading = math.radians(self.heading)+ return self.lift * share * -math.sin(heading) + 0.0, self.lift * share * math.cos(heading)++ def record(self) -> dict[str, Any]:+ return {"kind": "breath", "breathe_sha256": self.sha256, "lag": self.lag, "lift_px": round(self.lift, 4),+ "heading_deg": self.heading, **self.beat}+++def read_breath(path: Path, lag: float | None, *, verb: str = VERB) -> Breath:+ """The breath of a Breathe layer's record (breathe.json): a smooth breath, whose phases are the ones its config+ gives after the sidecar's checks (`state_breathe`, `breathe.fit_breathe_pattern`), whose chest rises as the anatomy it+ was baked with says. A record written by hand for a breath made elsewhere is read alike and must say the same."""+ lag = LAG_DEFAULT if lag is None else float(lag)+ if not 0 < lag < LAG_MAX: # a NaN is not+ raise SystemExit(f"{verb}: --lag is the share of a breath the part is late by, above 0 and under 1/π ({LAG_MAX:.4f}): at "+ f"1/π the late breath stops, past it it runs backwards; got {lag:g}")+ path = Path(path).expanduser()+ try:+ data = path.read_bytes()+ report = json.loads(data.decode("utf-8"))+ except (OSError, ValueError) as exc:+ raise SystemExit(f"{verb}: --breathe {path}: not read ({exc})") from exc+ if not (isinstance(report, dict) and isinstance(report.get("config"), dict) and isinstance(report.get("phases"), list)+ and isinstance((report.get("resolved") or {}).get("anatomy"), dict)):+ raise SystemExit(f"{verb}: --breathe {path}: not a Breathe layer's record — sprite-gen breathe writes config, phases "+ "and resolved.anatomy into breathe.json")+ mode = report["config"].get("mode") or "pixel"+ if mode != "smooth":+ raise SystemExit(f"{verb}: --breathe {path}: a {mode} breath — the part follows a smooth breath, which rests at the "+ "first cell (a pixel breath's travelling wave moves it)")+ try:+ cfg = state_breathe({"states": {"frames": {"breathe": report["config"]}}}, "frames")+ except SystemExit as exc:+ raise SystemExit(f"{verb}: --breathe {path}: its config is refused as a sidecar's would be — {exc}") from exc+ phases = report["phases"]+ if report.get("frames") != len(phases):+ raise SystemExit(f"{verb}: --breathe {path}: it says {report.get('frames')} frames and holds {len(phases)} phases")+ if breathe_mod.fit_breathe_pattern(len(phases), cfg) != phases:+ raise SystemExit(f"{verb}: --breathe {path}: its phases are not the ones its config gives for {len(phases)} cells "+ "(breathe.fit_breathe_pattern) — the record was changed after it was written")+ try:+ anatomy = Anatomy.from_dict(report["resolved"]["anatomy"])+ except (KeyError, TypeError) as exc:+ raise SystemExit(f"{verb}: --breathe {path}: its resolved.anatomy is not one sprite-gen breathe writes ({exc})") from exc+ beat = {"breath_peaks": list(cfg["breath_peaks"])} if cfg.get("breath_peaks") else {"breaths": cfg["breaths"]}+ return Breath(path, hashlib.sha256(data).hexdigest(), [float(p) for p in phases], beat,+ breathe_mod.smooth_lift(anatomy, cfg), float(cfg["chest_dir"]), lag)+++@dataclass(frozen=True, eq=False)+class Ask:+ """What a sway is asked, read and checked: the regions and how they move. What it is asked of — a loop's strip+ (`Request`) or a folder of a cycle's frames (`sway_frames`) — is apart from it."""++ regions: list[tuple[float, ...]]+ gain: float+ freq: float | None # the damped mass's; None on the breath+ zeta: float | None+ 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+ gain_across: float | None = None # the gain across asked; None: --gain, across as down+ breath: Breath | None = None # the breath the part follows; None: the body's motion, answered by the damped mass++ @property+ def across(self) -> float:+ """The across move's gain over the down move's: `--gain-across` over `--gain`, 1 without it."""+ return 1.0 if self.gain_across is None or self.gain == 0 else self.gain_across / self.gain++ @property+ def policy(self) -> str:+ return POLICY if self.breath is None else BREATH_POLICY+++def read_ask(regions: list[tuple[float, ...]], *, gain: float | None = None, freq: float | None = None,+ zeta: float | None = None, on_fold: str = "refuse", read_on: str | None = None,+ stretch_floor: float | None = None, breathe: Path | None = None, lag: float | None = None,+ gain_across: float | None = None, verb: str = VERB) -> Ask:+ """A sway's ask, read and checked. A number left out (None) is its default: the damped mass's gain, freq and zeta,+ or, on the breath (`breathe`), the breath's gain and lag."""+ # 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.+ try:+ regions = [region_of(region) for region in regions]+ except ValueError as exc:+ raise SystemExit(f"{verb}: --region {exc}") from exc+ if not regions:+ raise SystemExit(f"{verb}: at least one --region cx,cy,rx,ry")+ if breathe is None and lag is not None:+ raise SystemExit(f"{verb}: --lag is how late the part follows the breath; it needs --breathe")+ if breathe is not None and (freq is not None or zeta is not None):+ raise SystemExit(f"{verb}: --freq and --zeta are the damped mass's; on the breath (--breathe) the part is late by --lag")+ gain = (GAIN_DEFAULT if breathe is None else BREATH_GAIN_DEFAULT) if gain is None else float(gain)+ if breathe is None:+ freq = FREQ_DEFAULT if freq is None else float(freq)+ zeta = ZETA_DEFAULT if zeta is None else float(zeta)+ if gain < 0 or (breathe is None and (freq <= 0 or not 0 < zeta)):+ raise SystemExit(f"{verb}: --gain must be 0 or more, --freq and --zeta above 0")+ if gain_across is not None:+ gain_across = float(gain_across)+ if not gain_across >= 0: # a NaN is not+ raise SystemExit(f"{verb}: --gain-across must be 0 or more")+ if gain == 0 and gain_across != 0:+ raise SystemExit(f"{verb}: --gain 0 leaves the cells as they were, and --gain-across is read against it")+ 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}")+ breath = None if breathe is None else read_breath(breathe, lag, verb=verb)+ return Ask(regions, gain, freq, zeta, on_fold, None if read_on is None else str(read_on), stretch_floor, gain_across,+ breath)++@dataclass(frozen=True, eq=False)class Request:- """A follow-through asked of a loop directory, read and checked; nothing is written by reading it."""+ """A sway asked of a loop directory, read and checked; nothing is written by reading it."""loop_dir: Pathname: strmeta_path: Pathmeta_bytes: bytesmeta: 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+ ask: Ask@propertydef strip_path(self) -> Path:@@ -540,15 +736,11 @@ class Request: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:+def read_request(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: float | None = None,+ freq: float | None = None, zeta: float | None = None, on_fold: str = "refuse", verb: str = VERB,+ read_on: str | None = None, stretch_floor: float | None = None, breathe: Path | None = None,+ lag: float | None = None, gain_across: 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)}")@@ -558,31 +750,19 @@ def read_request(loop_dir: Path, regions: list[tuple[float, float, float, float]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)+ ask = read_ask(regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on, stretch_floor=stretch_floor,+ breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)+ return Request(loop_dir, name, meta_path, meta_bytes, meta, ask)@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.+ """What an ask comes to on a cycle's cells: 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."""+ `video-sway` writes it over the loop or into a new folder of frames; `video-sway-inspect` writes it down and+ changes nothing. All of them read the carry, the offsets and the moved cells here, and nowhere else."""- request: Request+ ask: Askcells: list[Image.Image]cols: np.ndarray # per cell, how far its body lies from cell 0's: acrossrows: np.ndarray # and down@@ -601,7 +781,7 @@ class Answer:dx: np.ndarraydy: np.ndarrayreach: float- groups: list[tuple[list[tuple[float, float, float, float]], tuple[np.ndarray, np.ndarray]]]+ groups: list[tuple[list[tuple[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`)@@ -612,24 +792,28 @@ class Answer: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]]]:+ def moves_in(self, k: int) -> list[tuple[list[tuple[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+ def record(self, source: str = SOURCE) -> dict[str, Any]:+ """The sway as the strip's meta records it, `source` the strip as cut kept beside it (`video-sway` adds its+ animations' checks); a frames folder's records it alike, the folder its source."""+ ask, requested = self.ask, self.requested+ drive = ({"freq_hz": ask.freq, "zeta": ask.zeta, "harmonics": HARMONICS} if ask.breath is None+ else {"drive": ask.breath.record()})+ across = ({} if ask.gain_across is None else+ {"gain_across": round(self.gain * ask.across, 4), "gain_across_requested": ask.gain_across})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,+ "regions": [list(r) for r in ask.regions], "gain": self.gain, **across, **drive,+ "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,+ "gain_requested": requested, "on_fold": ask.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),@@ -647,43 +831,80 @@ class Answer: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+ in a refusal, `strip_sha256` is its file's, read where the request names the strip its regions were read on): its+ cells answered as any cycle's cells are (`solve_cells`), at the frame time its meta records. Reads nothing else and+ writes nothing."""+ meta, ask = request.meta, request.askn, 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 ask.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":+ read_on = {"sha256": ask.read_on, "relation": read_on_relation(meta, strip_sha256, ask.read_on, verb=verb)}++ def transported() -> tuple[np.ndarray, np.ndarray, int, list[int]]:# 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}+ rows, cols, height0, worn, cut_cells = transported_motion(meta, cells, ask.read_on, verb=verb)+ read_on.update(policy=TRANSPORT_POLICY, cut_cells=cut_cells)+ return rows, cols, height0, worn++ carried = read_on is not None and read_on["relation"] == "transported"+ return solve_cells(ask, cells, float(meta["delay_ms"]), verb=verb, read_on=read_on,+ read_body=transported if carried else None)+++def _unit_move(ask: Ask, rows: np.ndarray, cols: np.ndarray, frame_ms: float | None) -> tuple[np.ndarray, np.ndarray]:+ """Per cell, the part's offset at gain 1, across and down, the across times its share of the gain (`Ask.across`):+ on the breath its offset from the breath (`Breath.unit`), or else the damped mass's answer to the body's motion at+ the cells' frame time."""+ if ask.breath is not None:+ across, down = ask.breath.unit()+ else:+ fps = 1000.0 / frame_ms+ across = sway_offsets(cols, fps, freq=ask.freq, zeta=ask.zeta, gain=1.0)+ down = sway_offsets(rows, fps, freq=ask.freq, zeta=ask.zeta, gain=1.0)+ return ask.across * across, down+++def solve_cells(ask: Ask, cells: list[Image.Image], frame_ms: float | None, *, verb: str = VERB,+ read_on: dict[str, Any] | None = None, read_body: Any = None) -> Answer:+ """The answer to `ask` on a cycle's cells (RGBA pictures of one size, in order; `frame_ms` one frame's time, which+ the damped mass alone reads): a loop's strip cut into its cells (`solve`), or a folder of the cycle's frames+ (`sway_frames`) — one answer, whatever the cells came from. The body's motion is read on the cells (`body_motion`)+ unless `read_body` gives it (a reading carried from the cut, `--read-on`). Reads nothing else and writes nothing."""+ regions, gain, on_fold = ask.regions, ask.gain, ask.on_fold+ w, h = cells[0].size+ for cx, cy, *_ 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")+ if ask.breath is not None and len(ask.breath.phases) != len(cells):+ raise SystemExit(f"{verb}: --breathe {ask.breath.path} breathes {len(ask.breath.phases)} cells and there are "+ f"{len(cells)} to sway: the part follows the breath cell for cell")+ if read_body is not None:+ rows, cols, height0, worn = read_body()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)+ across, down = _unit_move(ask, rows, cols, frame_ms)++ def move(g: float) -> tuple[np.ndarray, np.ndarray]:+ """The offset per cell at gain g, across and down: g times the move at gain 1."""+ return g * across, g * down++ dx, dy = move(gain)reach = float(np.max(np.hypot(dx, dy)))- radii = [min(rx, ry) for _, _, rx, ry in regions]+ radii = [region_radius(region) for region 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))))+ reach_per_gain = float(np.max(np.hypot(across, down)))gains, held = [requested] * len(regions), [False] * len(regions)if fold_ratio(reach, smallest) >= 1:if on_fold == "refuse":@@ -705,35 +926,33 @@ def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str =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)+ if ask.stretch_floor is not None:+ gains, held, stretch = _keep_floor(ask, radii, gains, held, (across, down), 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()}+ moves = {g: move(g) for g, hold in zip(gains, held) if not hold}+ reaches = {g: float(np.max(np.hypot(*offset))) for g, offset 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,+ groups = [([r for r, rg, hold in zip(regions, gains, held) if rg == g and not hold], offset) for g, offset in moves.items()]+ return Answer(ask, 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],+def _keep_floor(ask: Ask, 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 neverraised; one the floor takes under GAIN_MEASURED is held as the fold rule holds one, and the strip is refused whenevery 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]+ floor, requested = ask.stretch_floor, ask.gain+ per = [stretch_per_gain((region[2], region[3]), *move, flat=flat_of(region)) for region in ask.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":+ if any(by_floor) and ask.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")@@ -752,12 +971,13 @@ def _keep_floor(request: Request, radii: list[float], gains: list[float], 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,+def sway_loop(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: float | None = None,+ freq: float | None = None, zeta: float | None = None, board: Path | None = None,on_fold: str = "refuse", read_on: str | None = None, stretch_floor: float | None = None,+ breathe: Path | None = None, lag: float | None = None, gain_across: 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)+ stretch_floor=stretch_floor, breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)loop_dir, name, meta_path, meta = request.loop_dir, request.name, request.meta_path, request.metastrip_path = request.strip_pathsource = request.source_path@@ -804,6 +1024,42 @@ def sway_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]],return {"strip": str(strip_path), **record}+def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fps: float | None = None,+ gain: float | None = None, freq: float | None = None, zeta: float | None = None,+ board: Path | None = None, on_fold: str = "refuse", read_on: str | None = None,+ stretch_floor: float | None = None, breathe: Path | None = None, lag: float | None = None,+ gain_across: float | None = None, verb: str = VERB) -> dict[str, Any]:+ """The sway of a folder of a cycle's frames — a loop's `cycle/`, or what `sprite-gen breathe` wrote from it — at their+ own size and count, past the strip's caps on cells and width: the same frames under the same names, the regions+ (in frame pixels) moved, and `sway.json` beside them, written whole into a new folder (`frames.folder`); the frames+ folder is read and not written. Cell for cell it is the strip's sway (`solve_cells`): a strip cut from these frames+ at scale 1, none left out, its regions moved by its crop origin, at the frame time its meta writes (`frame_ms` of+ `--fps`), moves its cells as these are moved."""+ ask = read_ask(regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on, stretch_floor=stretch_floor,+ breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)+ if ask.read_on is not None:+ raise SystemExit(f"{verb}: --read-on names the strip as cut that the regions were read on; frames are read as they are")+ if ask.breath is not None and fps is not None:+ raise SystemExit(f"{verb}: --fps is the damped mass's frame time; on the breath (--breathe) the part keeps the breath's beat")+ frames = Path(frames)+ folder = folder_mod.open_frames(frames, Path(out), verb)+ cells = folder.images+ frame_ms = None+ if ask.breath is None:+ frame_ms = folder_mod.cycle_frame_ms(frames, len(cells), fps, verb)+ if frame_ms is None:+ raise SystemExit(f"{verb}: --frames {frames}: the damped mass answers the body's motion in time — give --fps (a "+ "video-loop cycle/ folder has its own in the loop's strip meta), or sway on the breath (--breathe)")+ answer = solve_cells(ask, cells, frame_ms, verb=verb)+ moved = [answer.moved(k) for k in range(len(cells))]+ record = {"frames": len(cells), "frame_ms": frame_ms, **answer.record(source=str(frames))}+ folder_mod.publish(folder, moved, FRAMES_RECORD, record)+ if board is not None:+ _board(cells, moved, answer.dy, board)+ record["board"] = str(board)+ return {"out": str(folder.out), **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))]@@ -820,18 +1076,37 @@ def _board(before: list[Image.Image], after: list[Image.Image], dy: np.ndarray,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)")+LOOP_DIR_HELP = "a video-loop output directory (after video-cycle-align, if the set is aligned)"+++def add_request_arguments(parser: argparse.ArgumentParser, *, loop_dir: bool = True) -> None:+ """What a sway is asked with; `video-sway-inspect` takes the same of a loop directory and is asked alike+ (`video-sway` puts `--loop-dir` beside `--frames` itself)."""+ if loop_dir:+ parser.add_argument("--loop-dir", required=True, type=Path, help=LOOP_DIR_HELP)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)")+ help="cx,cy,rx,ry[,flat]: an ellipse over the soft part in the first cell, in cell pixels (repeatable); flat, "+ f"{FLAT_RANGE[0]:g} to {FLAT_RANGE[1]:g}, is the share of the way from its centre to its rim that moves in "+ "full, the Breathe layer's chest_flat (0 or left out: the weight falls from the centre)")+ parser.add_argument("--gain", type=float, default=None,+ help=f"times the physical answer (default {GAIN_DEFAULT:g}; 1 is the mass as measured, 0 leaves the strip as it "+ f"was); on the breath (--breathe), times the breath's rise less the part's own (default {BREATH_GAIN_DEFAULT:g})")+ parser.add_argument("--gain-across", type=float, default=None,+ help="the gain across, apart from --gain, which is then the gain down (default: --gain); a region whose gain "+ "--on-fold lower or --stretch-floor lowers moves across lowered in the same proportion")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("--freq", type=float, default=None, help=f"the part's own frequency in Hz (default {FREQ_DEFAULT:g})")+ parser.add_argument("--zeta", type=float, default=None, help=f"damping ratio (default {ZETA_DEFAULT:g}: lags and settles, no ringing)")+ parser.add_argument("--breathe", type=Path, default=None, metavar="BREATHE.JSON",+ help="sway on the breath: the record sprite-gen breathe writes beside the frames it breathed (smooth). The part "+ "follows the chest's rise late by --lag instead of answering the body's motion as a damped mass: its offset is "+ "gain x the chest's rise x (w - w late), against the way the chest rises, 0 where the breath rests (the "+ "first cell). The record's phases must be the ones its config gives, one for each cell swayed")+ parser.add_argument("--lag", type=float, default=None,+ help=f"on the breath: the share of a breath the part peaks after the chest, above 0 and under 1/π (default {LAG_DEFAULT:g})")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 "@@ -845,7 +1120,17 @@ def add_request_arguments(parser: argparse.ArgumentParser) -> None:def add_arguments(parser: argparse.ArgumentParser) -> None:- add_request_arguments(parser)+ where = parser.add_mutually_exclusive_group(required=True)+ where.add_argument("--loop-dir", type=Path, help=LOOP_DIR_HELP)+ where.add_argument("--frames", type=Path,+ help="a folder of a cycle's frames (*.png in name order, one size: a video-loop cycle/, or what sprite-gen "+ "breathe wrote from it), swayed at their own size and count into --out — past the strip's caps on cells "+ "and width; the regions are in frame pixels")+ parser.add_argument("--out", type=Path, help=f"with --frames: a new folder for the swayed frames (same names) and {FRAMES_RECORD}")+ parser.add_argument("--fps", type=float, default=None,+ help="with --frames: their rate, for the damped mass (a video-loop cycle/ folder has its own in the loop's strip "+ "meta); a frame's time is rounded to hundredths of a ms, as a strip's meta writes it")+ add_request_arguments(parser, loop_dir=False)parser.add_argument("--board", type=Path, help="write a before/after picture at the frames where the part sits lowest and highest")@@ -854,8 +1139,8 @@ def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:fold, notes = record["fold"], []if "stretch" in record: # a floor was asked: each region says what lowered it, the fold or the floorfloor = 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}"+ for region, entry, folded in zip(record["regions"], record["stretch"]["regions"], fold["regions"]):+ name = "--region " + ",".join(f"{v:g}" for v in region)if entry["held"]:why = (f"folds at --gain {folded['gain_limit']:g}" if entry["rule_gain"] == 0 elsef"keeps --stretch-floor {floor:g} only at --gain {entry['floor_gain']:g}")@@ -865,8 +1150,8 @@ def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:notes.append(f"{verb}: {name} moves at --gain {entry['gain']:g}, lowered from {record['gain_requested']:g} by {by}")return notesif "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}"+ for region, entry in zip(record["regions"], fold["regions"]):+ name = "--region " + ",".join(f"{v:g}" for v in region)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")@@ -881,17 +1166,28 @@ def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]: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]+ asked = {"gain": kwargs.get("gain"), "freq": kwargs.get("freq"), "zeta": kwargs.get("zeta"), "board": kwargs.get("board"),+ "on_fold": str(kwargs.get("on_fold") or "refuse"), "read_on": kwargs.get("read_on"),+ "stretch_floor": kwargs.get("stretch_floor"), "breathe": kwargs.get("breathe"), "lag": kwargs.get("lag"),+ "gain_across": kwargs.get("gain_across")}+ if kwargs.get("frames") is not None:+ if kwargs.get("out") is None:+ raise SystemExit(f"{verb}: --frames needs --out, a new folder for the swayed frames")+ result = sway_frames(Path(str(kwargs["frames"])), Path(str(kwargs["out"])), list(kwargs["region"]), # type: ignore[arg-type]+ fps=kwargs.get("fps"), verb=verb, **asked) # type: ignore[arg-type]+ else:+ for flag in ("out", "fps"):+ if kwargs.get(flag) is not None:+ raise SystemExit(f"{verb}: --{flag} goes with --frames; a loop directory is swayed where it is")+ result = sway_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), verb=verb, **asked) # type: ignore[arg-type]fold = result["fold"]own = "held" in fold["regions"][0] # the regions took gains of their ownfor 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")}+ where = "out" if "out" in result else "strip"+ print(json.dumps({k: result[k] for k in (where, "regions", "gain", "gain_requested", "on_fold", "body_bob_px", "reach_px")}| ({"region_gains": [entry["gain"] for entry in fold["regions"]]} if own else {})+ | ({"drive": result["drive"]["kind"]} if "drive" in result 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))diff --git a/sprite_gen/video/sway_inspect.py b/sprite_gen/video/sway_inspect.pyindex fc1c247..bda3bd0 100644--- a/sprite_gen/video/sway_inspect.py+++ b/sprite_gen/video/sway_inspect.py@@ -57,6 +57,7 @@ from typing import Anyfrom PIL import Imagefrom sprite_gen._deps import np+from sprite_gen.effects import breathe as breathe_modfrom sprite_gen.spec.runio import atomic_write_setfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import sway@@ -107,10 +108,11 @@ def _engine_version() -> str: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,+def policy(ask: sway.Ask) -> dict[str, Any]:+ """The way the motion is read and a region moved: its name (by the drive: the body's motion or the breath) 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": ask.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}@@ -119,15 +121,17 @@ 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+def _weight_and_gradient(x: np.ndarray, y: np.ndarray, ellipse: tuple[float, ...]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:+ """A region's weight at points (x, y) — cos² of the ellipse's own radius, 1 over its flat share where it has one,+ 0 at its rim and outside (`sway.region_weight`) — and the weight's gradient there, across and down."""+ cx, cy, rx, ry = ellipse[:4]+ flat = sway.flat_of(ellipse)u, v = (x - cx) / rx, (y - cy) / ryr = 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)+ weight = breathe_mod.flat_cos2(r, flat)+ falling = r if flat == 0 else np.clip((r - flat) / (1 - flat), 0.0, None) # the way left, from the flat share to the rim+ slope = np.where(inside & (falling > 0), -(math.pi / 2) * np.sin(math.pi * falling) / (1 - flat) / np.where(r > 0, r, 1.0), 0.0)return weight, slope * u / rx, slope * v / ry@@ -255,14 +259,17 @@ def _png(board: np.ndarray) -> bytes: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,+def inspect_loop(loop_dir: Path, regions: list[tuple[float, ...]], out_dir: Path, *,+ gain: float | None = None, freq: float | None = None, zeta: float | None = None,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]:+ read_on: str | None = None, stretch_floor: float | None = None, breathe: Path | None = None,+ lag: float | None = None, gain_across: 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)+ read_on=read_on, stretch_floor=stretch_floor, breathe=breathe, lag=lag,+ gain_across=gain_across)+ ask = request.askout_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")@@ -284,16 +291,16 @@ def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]solid = before[..., 3] >= sway.ALPHA_SOLIDfield = 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]+ masks = [sway.region_weight(xx, yy, region, carry) > 0 for region in ask.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)):+ for i, (region, radius, g, hold, mask) in enumerate(zip(ask.regions, answer.radii, answer.gains, answer.held, masks)):+ cx, cy, rx, ry, *flat = regiondx, 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: Gentries.append({- "index": i, "ellipse": [round(cx + float(carry[0]), 6), round(cy + float(carry[1]), 6), rx, ry],+ "index": i, "ellipse": [round(cx + float(carry[0]), 6), round(cy + float(carry[1]), 6), rx, ry, *flat],"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,@@ -329,10 +336,12 @@ def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]"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(),+ "regions": [list(region) for region in ask.regions],+ "settings": {"gain": ask.gain, "on_fold": ask.on_fold, "freq_hz": ask.freq, "zeta": ask.zeta,+ "read_on": ask.read_on, "stretch_floor": ask.stretch_floor}+ | ({} if ask.gain_across is None else {"gain_across": ask.gain_across})+ | ({} if ask.breath is None else {"breathe_sha256": ask.breath.sha256, "lag": ask.breath.lag}),+ "policy": policy(ask),"engine": {"name": "sprite-gen", "version": _engine_version()},}input_id = _sha256(_canonical({@@ -359,7 +368,7 @@ def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]"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))],+ } for i, (region, radius, g, hold) in enumerate(zip(ask.regions, answer.radii, answer.gains, answer.held))],"seams": [pairs[key] for key in sorted(pairs)],"cells": cells,"boards": {@@ -389,10 +398,12 @@ 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]+ gain=kwargs.get("gain"), freq=kwargs.get("freq"), zeta=kwargs.get("zeta"), # type: ignore[arg-type]+ on_fold=str(kwargs.get("on_fold") or "refuse"),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]+ read_on=kwargs.get("read_on"), stretch_floor=kwargs.get("stretch_floor"), # type: ignore[arg-type]+ breathe=kwargs.get("breathe"), lag=kwargs.get("lag"), gain_across=kwargs.get("gain_across"), # type: ignore[arg-type]+ verb=verb)for note in sway.fold_notes(record["follow"], verb):print(note, file=sys.stderr)out_dir = out_dir.expanduser().resolve()