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(video-sway): --band moves a region as one mass — the weight flat over its ellipse grown by the move's reach and falling over a band read off it, the region carried by its own pixels; off, the strip and record are 3.5.0's

Soohong Kim5fe36ea94dc3
diff --git a/sprite_gen/video/sway.py b/sprite_gen/video/sway.py
index cc7e85a..3cd2a65 100644
--- a/sprite_gen/video/sway.py
+++ b/sprite_gen/video/sway.py
@@ -91,11 +91,30 @@ A region's fifth number, flat, is the share of the way from its centre to its ri
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.
+
+`--band PX|auto` moves a region as one mass instead (`BAND_POLICY`; off by default, and off nothing of it is read or
+written). The weight is 1 over the region's ellipse grown by `--band-margin` every way and falls to 0 (cos², along the
+ray from the centre) over the band past it: the whole part moves, and only what is round it gives. A pixel of the part
+lands where the weight is still 1 only if the flat part reaches as far as the part goes, so the margin left auto is the
+move's reach and a pixel (ceil(reach) + 1), and the band left auto is the narrowest the move does not fold
+(ceil(reach × π / 2) + 1): the reach is read off the move first, at the gain asked, and the band and margin from it.
+The fold rule reads a region by its narrowest band, `--on-fold lower` as ever, and then the steepest its weight falls
+along the move (`band_steepest`): where the flat ellipse and the outer one differ in shape the band is narrower across
+its ring than its px. `--band-up FLAT[,PX|auto]` gives the
+part above the centre its own: the flat part stops FLAT of the region's height over the centre and the weight falls
+over PX from there — left auto, the band or as far as HANG_PAST px over the region's top, whichever is further — so the
+upper part gives and the rest moves whole. A region's flat share is the other way of moving it whole and is refused
+with it. A band carries each region by its own pixels, not by the body's lay: the solid pixels under its ellipse in
+the cell it was read on are looked for in each cell within CARRY_SEARCH px of where the cell before had them, or of the
+lay (`carry_match`, `carry_own`), and a cell where that is uncertain is carried by the lay, the record saying which and
+why. Outside every region's band no pixel changes. The record holds the band, the carry of each region in every cell
+and a ledger of what the move did in each cell, and what is in the ledger is said in a warning line.
"""
from __future__ import annotations
import argparse
+import dataclasses
import hashlib
import io
import json
@@ -152,6 +171,16 @@ 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
+# A region moved as one mass (`--band`): flat over its ellipse grown by a margin, cos² to 0 over a band past it,
+# carried by its own pixels. The record names it, as POLICY names the way without it.
+BAND_POLICY = "own-pixels/margin-band-cos2/1"
+AUTO = "auto" # a band, margin or band above read off the move
+HANG_PAST = 3.0 # px over a region's top the band above runs at least, left auto: all of the ellipse moves some, nothing over it
+# Under a band, a region is carried by its own pixels; a cell where they are not found surely is carried by the lay.
+CARRY_BASIS_BAND = {"reading": "outline-lay", "region": "own-pixels"}
+CARRY_SEARCH = 9 # px either way a region's pixels are looked for in a cell (whole pixels), around where the cell before had them
+PRESSED, STRETCHED = 0.85, 1.15 # of a pixel's area: the ledger counts a moved pixel left with less, or more
+MOVED_PX = 0.5 # px: a pixel outside every region moved this far or more is counted
def parse_region(text: str) -> tuple[float, ...]:
@@ -200,6 +229,41 @@ def parse_read_on(text: str) -> str:
return text
+def _px_or_auto(flag: str, text: str, *, least: float, above: bool) -> float | str:
+ """A px number (over `least` when `above`, else at least it), or AUTO."""
+ if text == AUTO:
+ return AUTO
+ try:
+ value = float(text)
+ except ValueError:
+ value = math.nan
+ if not (value > least if above else value >= least) or not math.isfinite(value): # a NaN is neither
+ raise argparse.ArgumentTypeError(f"{flag} wants px ({'over' if above else 'at least'} {least:g}) or {AUTO}, got {text!r}")
+ return value
+
+
+def parse_band(text: str) -> float | str:
+ return _px_or_auto("--band", text, least=0.0, above=True)
+
+
+def parse_band_margin(text: str) -> float | str:
+ return _px_or_auto("--band-margin", text, least=0.0, above=False)
+
+
+def parse_band_up(text: str) -> tuple[float, float | str]:
+ """`--band-up FLAT[,PX|auto]`: the share of the region's height over its centre that stays flat (over 0, at most 1),
+ and the band above it (AUTO when left out)."""
+ flat, _, band = text.partition(",")
+ try:
+ share = float(flat)
+ except ValueError:
+ share = math.nan
+ if not 0 < share <= 1: # a NaN is not
+ raise argparse.ArgumentTypeError(f"--band-up wants FLAT[,PX|auto], FLAT the share of the region's height over its "
+ f"centre that stays flat (over 0, at most 1), got {text!r}")
+ return share, _px_or_auto("--band-up", band or AUTO, least=0.0, above=True)
+
+
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)
@@ -549,15 +613,39 @@ def move_field(xx: np.ndarray, yy: np.ndarray, moves: list[tuple[list[tuple[floa
for region in regions:
weight = np.maximum(weight, region_weight(xx, yy, region, shift))
weights.append(weight)
+ return _largest_move(weights, [offset for _, offset in moves])
+
+
+def _largest_move(weights: list[np.ndarray], offsets: list[tuple[float, float]]) -> tuple[np.ndarray, np.ndarray, np.ndarray] | None:
+ """Per pixel, whether a group's weight (one per offset) is over 0 there, and the largest of the groups' weighted
+ moves, across and down. None when no weight is over 0 anywhere."""
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]
+ largest = np.argmax(np.stack([math.hypot(*offset) * weight for offset, weight in zip(offsets, weights)]), axis=0)[None]
+ move_x = np.take_along_axis(np.stack([offset[0] * weight for offset, weight in zip(offsets, weights)]), largest, 0)[0]
+ move_y = np.take_along_axis(np.stack([offset[1] * weight for offset, weight in zip(offsets, weights)]), largest, 0)[0]
return inside, move_x, move_y
+def band_weight(xx: np.ndarray, yy: np.ndarray, centre: tuple[float, float], flat: tuple[float, float, float],
+ band: tuple[float, float, float]) -> np.ndarray:
+ """Per pixel, how much of a banded region's move it takes (`--band`): 1 inside the flat ellipse about `centre` — its
+ radii across, above and below (`flat`) — 0 on and past the outer one, whose radii are those and `band`'s (across,
+ above, below), and between them cos² of the share of the way across, along the ray from the centre. The pixels the
+ region covers are those where this is over 0."""
+ (cx, cy), (ax, up, down), (bx, band_up, band_down) = centre, flat, band
+ dx, dy = np.asarray(xx, np.float64) - cx, np.asarray(yy, np.float64) - cy
+ above = dy < 0
+ ay, by = np.where(above, up, down), np.where(above, band_up, band_down)
+ inner = np.hypot(dx / ax, dy / ay)
+ outer = np.hypot(dx / (ax + bx), dy / (ay + by))
+ with np.errstate(divide="ignore", invalid="ignore"):
+ # Along the ray, inner/outer is the outer radius over the flat one: the share across is linear in the distance.
+ share = np.clip((inner - 1) * outer / (inner - outer), 0.0, 1.0)
+ return np.where(inner <= 1, 1.0, np.where(outer < 1, np.cos(0.5 * math.pi * share) ** 2, 0.0))
+
+
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`.
@@ -568,10 +656,16 @@ def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, f
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()
+ return _draw(cell, lambda xx, yy: move_field(xx, yy, moves, shift))
+
+
+def _draw(cell: Image.Image, field_of: Any) -> Image.Image:
+ """`cell` moved by the field `field_of(xx, yy)` gives (whether a pixel is covered, its move across and down; None:
+ nothing is), sampled as premultiplied bilinear colour; a pixel no region covers keeps its bytes."""
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)
+ field = field_of(xx, yy)
if field is None:
return cell.copy()
inside, move_x, move_y = field
@@ -587,6 +681,165 @@ def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, f
return Image.fromarray(out, "RGBA")
+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 _whole_premultiplied(cell: Image.Image) -> np.ndarray:
+ """A cell's premultiplied RGBA as whole numbers, 255 times it (each colour times the alpha, and the alpha times 255):
+ a squared difference of two of them, summed, is a whole number, the same on every machine."""
+ rgba = np.asarray(cell.convert("RGBA"), np.int64)
+ return np.concatenate([rgba[..., :3] * rgba[..., 3:4], rgba[..., 3:4] * 255], axis=-1)
+
+
+@dataclass(frozen=True)
+class Carried:
+ """Where a region's own pixels are in a cell (`carry_match`): their shift from the cell they were read on, or None
+ and why that is uncertain; the least of the masked squared difference, and its second difference across and down
+ there, each per pixel of the mask in premultiplied colour (0 to 255) squared."""
+
+ shift: tuple[float, float] | None
+ why: str | None
+ least: float
+ curvature: tuple[float, float] | None = None
+
+
+def carry_match(base: np.ndarray, cell: np.ndarray, mask: np.ndarray, guess: tuple[float, float],
+ search: int = CARRY_SEARCH, around: str = "the lay") -> Carried:
+ """Where the pixels of `base` under `mask` are in `cell` (both `_whole_premultiplied`): the whole-pixel move, within
+ `search` px of `guess` each way (`around` says what it is: the body's lay, or where the cell before had them), with
+ the least squared difference over the mask — past the cell's edge is clear — and a parabola through it and its
+ neighbours each way for the part of a pixel. Uncertain where the least is on the search's edge (the pixels may be
+ further), where it is tied with a place more than a pixel away, or where the difference does not curve up across or
+ down (nothing there tells one place from the next)."""
+ ys, xs = np.nonzero(mask)
+ gx, gy = int(round(guess[0])), int(round(guess[1]))
+ pad = search + math.ceil(max(abs(guess[0]), abs(guess[1]))) + 2
+ padded = np.pad(cell, ((pad, pad), (pad, pad), (0, 0)))
+ steps = np.arange(-search, search + 1)
+ rows = ys[None, None, :] + (gy + steps)[:, None, None] + pad
+ cols = xs[None, None, :] + (gx + steps)[None, :, None] + pad
+ grid = ((padded[rows, cols] - base[ys, xs]) ** 2).sum(axis=(2, 3)) # [down, across], whole numbers
+ unit = len(ys) * 255 ** 2
+ iy, ix = np.unravel_index(int(np.argmin(grid)), grid.shape)
+ least = int(grid[iy, ix])
+ edge = 2 * search
+ if iy in (0, edge) or ix in (0, edge):
+ return Carried(None, f"the least is on the search's edge, {search} px from {around}", least / unit)
+ if (np.abs(np.argwhere(grid == least) - [iy, ix]).max(axis=1) > 1).any():
+ return Carried(None, "the least is tied with a place more than a pixel away", least / unit)
+ across = int(grid[iy, ix - 1]) - 2 * least + int(grid[iy, ix + 1])
+ down = int(grid[iy - 1, ix]) - 2 * least + int(grid[iy + 1, ix])
+ curvature = (across / unit, down / unit)
+ if across <= 0 or down <= 0:
+ way = "across" if across <= 0 else "down"
+ return Carried(None, f"the difference does not curve up {way}", least / unit, curvature)
+ fx = float(np.clip(0.5 * (int(grid[iy, ix - 1]) - int(grid[iy, ix + 1])) / across, -0.5, 0.5))
+ fy = float(np.clip(0.5 * (int(grid[iy - 1, ix]) - int(grid[iy + 1, ix])) / down, -0.5, 0.5))
+ return Carried((gx - search + int(ix) + fx, gy - search + int(iy) + fy), None, least / unit, curvature)
+
+
+def carry_own(base: Image.Image, cells: list[Image.Image], regions: list[tuple[float, ...]], base_shift: tuple[float, float],
+ lays: list[tuple[float, float]], base_index: int | None) -> list[list[dict[str, Any]]]:
+ """Per cell and region, where a band carries the region (`--band`): by its own pixels — the solid pixels under its
+ ellipse in `base`, the cell it was read on or carried to by `base_shift`, found in the cell (`carry_match`) — or by
+ the lay where that is uncertain, saying why. The cell `base_index` is `base` itself. The cells are looked at in the
+ loop's order from it (from cell 0 where `base` is none of them), each around where the cell before had the pixels:
+ a part moves little from one cell to the next, and the outline's lay can jump where the outline changes (an arm
+ swung out from the body); around the cell's own lay where the cell before had them by its lay, or is `base`."""
+ w, h = base.size
+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+ solid = np.asarray(base.getchannel("A")) >= ALPHA_SOLID
+ whole = _whole_premultiplied(base)
+ cell_wholes: dict[int, np.ndarray] = {}
+ n = len(cells)
+ order = list(range(n)) if base_index is None else [(base_index + i) % n for i in range(1, n)]
+ out: list[list[dict[str, Any]]] = [[] for _ in cells]
+ for region in regions:
+ mask = (region_weight(xx, yy, region, base_shift) > 0) & solid
+ entries: dict[int, dict[str, Any]] = {}
+ if base_index is not None:
+ entries[base_index] = {"px": [float(base_shift[0]), float(base_shift[1])], "from": "base"}
+ before: tuple[int, tuple[float, float]] | None = None # the cell before and where its own pixels were found
+ for k in order:
+ lay = (float(lays[k][0]), float(lays[k][1]))
+ if not mask.any():
+ entries[k] = {"px": list(lay), "from": "lay", "why": "no solid pixel of the cell it was read on is under it"}
+ continue
+ if k not in cell_wholes:
+ cell_wholes[k] = _whole_premultiplied(cells[k])
+ if before is None:
+ guess, around = (lay[0] - base_shift[0], lay[1] - base_shift[1]), "the lay"
+ else:
+ guess, around = before[1], f"where cell {before[0]} had it"
+ found = carry_match(whole, cell_wholes[k], mask, guess, around=around)
+ entry: dict[str, Any] = {"least": found.least, "curvature": None if found.curvature is None else list(found.curvature)}
+ if found.shift is None:
+ entries[k] = {"px": list(lay), "from": "lay", "why": found.why} | entry
+ before = None
+ else:
+ entries[k] = {"px": [base_shift[0] + found.shift[0], base_shift[1] + found.shift[1]], "from": "pixels"} | entry
+ before = (k, found.shift)
+ for k in range(n):
+ out[k].append(entries[k])
+ return out
+
+
+@dataclass(frozen=True)
+class Band:
+ """A band asked (`--band`): its px, the margin's (`--band-margin`) and, above the centre, the share of the region's
+ height that stays flat and the band from there (`--band-up`; None: above as below). Each px is a number or AUTO, read
+ off the move (`band_shapes`)."""
+
+ band: float | str
+ margin: float | str = AUTO
+ up: tuple[float, float | str] | None = None
+
+ def asked(self) -> dict[str, Any]:
+ return {"band": self.band, "margin": self.margin, "up": None if self.up is None else {"flat": self.up[0], "band": self.up[1]}}
+
+
+def band_shapes(band: Band, regions: list[tuple[float, ...]], reach: float) -> tuple[float, float, list[tuple[tuple[float, float, float], tuple[float, float, float]]]]:
+ """The band's px and the margin's, AUTO read off the move's reach at the gain asked — the margin the reach and a
+ pixel, ceil(reach) + 1, so the part is still on the flat where it goes, and the band the narrowest the move does
+ not fold, ceil(reach × π / 2) + 1 — and per region its flat radii and its bands, each across, above and below."""
+ band_px = float(math.ceil(reach * math.pi / 2) + 1) if band.band == AUTO else float(band.band)
+ margin_px = float(math.ceil(reach) + 1) if band.margin == AUTO else float(band.margin)
+ shapes = []
+ for _, _, rx, ry in regions:
+ flat, bands = [rx + margin_px, ry + margin_px, ry + margin_px], [band_px, band_px, band_px]
+ if band.up is not None:
+ share, up = band.up
+ flat[1] = share * ry
+ bands[1] = max(band_px, (1 - share) * ry + HANG_PAST) if up == AUTO else float(up)
+ shapes.append((tuple(flat), tuple(bands)))
+ return band_px, margin_px, shapes
+
+
+@dataclass(frozen=True, eq=False)
+class Banded:
+ """What a band comes to on the cells: its px and the margin's, read off `reach` (the move's at the gain asked), each
+ region's flat radii and bands, where each region is carried in every cell (`carry_own`), the steepest its weight falls
+ along the move (`band_steepest`), and the ledger of what the move does in each cell (`band_ledger`)."""
+
+ asked: Band
+ reach: float
+ band: float
+ margin: float
+ shapes: list[tuple[tuple[float, float, float], tuple[float, float, float]]]
+ carried: list[list[dict[str, Any]]] # per cell, per region
+ steepest: list[tuple[float, int]] # per region, u·∇w at its steepest per unit of gain, and the cell (`band_steepest`)
+ ledger: dict[str, Any] | None = None
+
+
@dataclass(frozen=True, eq=False)
class Breath:
"""The breath a sway follows (`--breathe`): the Breathe layer's record of it — `sprite-gen breathe` writes
@@ -689,6 +942,7 @@ class Ask:
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
+ band: Band | None = None # each region moved as one mass over a band (`--band`); None: the weight falls from the centre
@property
def across(self) -> float:
@@ -703,9 +957,11 @@ class Ask:
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:
+ gain_across: float | None = None, band: float | str | None = None, band_margin: float | str | None = None,
+ band_up: tuple[float, float | str] | str | 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."""
+ or, on the breath (`breathe`), the breath's gain and lag. `band` (px or AUTO; None: off) moves each region as one
+ mass, `band_margin` and `band_up` shaping it."""
# 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.
@@ -742,7 +998,29 @@ def read_ask(regions: list[tuple[float, ...]], *, gain: float | None = None, fre
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)
+ breath, _read_band(regions, band, band_margin, band_up, stretch_floor, verb))
+
+
+def _read_band(regions: list[tuple[float, ...]], band: float | str | None, margin: float | str | None,
+ up: tuple[float, float | str] | str | None, stretch_floor: float | None, verb: str) -> Band | None:
+ """The band asked (`--band`, `--band-margin`, `--band-up`), checked as the command line checks it; None when off."""
+ if band is None:
+ if margin is not None or up is not None:
+ raise SystemExit(f"{verb}: --band-margin and --band-up shape a band; they need --band")
+ return None
+ flat = [region for region in regions if len(region) > 4]
+ if flat:
+ raise SystemExit(f"{verb}: --band moves a region whole over its ellipse grown by the margin, and a region's fifth number "
+ f"(flat, {flat[0][4]:g} on --region {','.join(f'{v:g}' for v in flat[0])}) is the other way of moving it "
+ "whole: give the region as cx,cy,rx,ry with --band")
+ if stretch_floor is not None:
+ raise SystemExit(f"{verb}: --stretch-floor reads the weight that falls from a region's centre; with --band the fold "
+ "rule reads the band")
+ try:
+ return Band(parse_band(str(band)), AUTO if margin is None else parse_band_margin(str(margin)),
+ None if up is None else parse_band_up(up if isinstance(up, str) else ",".join(str(v) for v in up)))
+ except argparse.ArgumentTypeError as exc:
+ raise SystemExit(f"{verb}: {exc}") from exc
@dataclass(frozen=True, eq=False)
@@ -768,7 +1046,8 @@ class 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:
+ lag: float | None = None, gain_across: float | None = None, band: float | str | None = None,
+ band_margin: float | str | None = None, band_up: tuple[float, float | str] | str | None = None) -> Request:
loop_dir = loop_dir.expanduser().resolve()
metas = sorted(loop_dir.glob("*.strip.json"))
if len(metas) != 1:
@@ -780,7 +1059,8 @@ def read_request(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: floa
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")
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)
+ breathe=breathe, lag=lag, gain_across=gain_across, band=band, band_margin=band_margin, band_up=band_up,
+ verb=verb)
return Request(loop_dir, name, meta_path, meta_bytes, meta, ask)
@@ -814,6 +1094,7 @@ class Answer:
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`)
reference: dict[str, Any] | None = None # the frame the regions were read on, when not cell 0 (`--reference`)
+ band: Banded | None = None # what the band comes to (`--band`); None: the weight falls from the centre
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
@@ -828,7 +1109,23 @@ class Answer:
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))
+ if self.band is None:
+ return move_regions(self.cells[k], self.moves_in(k), self.carry(k))
+ if all(dx == 0 and dy == 0 for _, (dx, dy) in self.moves_in(k)):
+ return self.cells[k].copy()
+ return _draw(self.cells[k], lambda xx, yy: self.band_field(k, xx, yy)[0])
+
+ def band_field(self, k: int, xx: np.ndarray, yy: np.ndarray) -> tuple[tuple[np.ndarray, np.ndarray, np.ndarray] | None, list[np.ndarray]]:
+ """Under a band, cell k's move per pixel (`move_field`'s: covered, across, down; None where no region covers a
+ pixel) and each region's weight, every region carried by its own carry in the cell (`Banded.carried`)."""
+ assert self.band is not None
+ weights = [band_weight(xx, yy, (region[0] + carried["px"][0], region[1] + carried["px"][1]), *shape)
+ for region, shape, carried in zip(self.ask.regions, self.band.shapes, self.band.carried[k])]
+ # The groups as `solve_cells` makes them: one per gain a region moves by, in the order of `moves`.
+ groups = [[i for i, (rg, hold) in enumerate(zip(self.gains, self.held)) if rg == g and not hold] for g in self.moves]
+ group_weights = [np.max([weights[i] for i in members], axis=0) if members else np.zeros(np.shape(xx)) for members in groups]
+ offsets = [(mx[k], my[k]) for mx, my in self.moves.values()]
+ return _largest_move(group_weights, offsets), weights
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
@@ -858,8 +1155,38 @@ class Answer:
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)}) \
- | ({} if self.reference is None else {"reference": self.reference})
+ | ({} if self.read_on is None and self.stretch is None and self.band is None else
+ {"carry_basis": dict(CARRY_BASIS if self.band is None else CARRY_BASIS_BAND)}) \
+ | ({} if self.reference is None else {"reference": self.reference}) \
+ | ({} if self.band is None else {"band": self.band_record()})
+
+ def band_record(self) -> dict[str, Any]:
+ """The band as the record holds it (`--band`): what was asked, the reach it was read off, its px and the margin's,
+ each region's flat radii and bands (across, above, below), where each region is carried in every cell and from
+ what, the cells carried by the lay and why, and the ledger."""
+ assert self.band is not None
+ band = self.band
+
+ def carried(entry: dict[str, Any]) -> dict[str, Any]:
+ out = {"px": [round(v, 4) + 0.0 for v in entry["px"]], "from": entry["from"]}
+ if "why" in entry:
+ out["why"] = entry["why"]
+ if "least" in entry:
+ out["least"] = round(entry["least"], 4)
+ out["curvature"] = None if entry["curvature"] is None else [round(v, 4) for v in entry["curvature"]]
+ return out
+
+ return {
+ "policy": BAND_POLICY, "asked": band.asked.asked(), "reach_px": round(band.reach, 4),
+ "band_px": band.band, "margin_px": band.margin,
+ "regions": [{"flat_px": [round(v, 4) for v in flat], "band_px": [round(v, 4) for v in bands],
+ "steepest": {"per_gain": round(per_gain, 4), "cell": k, "ratio": round(g * per_gain, 3)}}
+ for (flat, bands), (per_gain, k), g in zip(band.shapes, band.steepest, self.gains)],
+ "carry": {"search_px": CARRY_SEARCH, "cells": [[carried(entry) for entry in cell] for cell in band.carried]},
+ "lay": [{"cell": k, "region": i, "why": entry["why"]} for k, cell in enumerate(band.carried)
+ for i, entry in enumerate(cell) if entry["from"] == "lay"],
+ "ledger": band.ledger,
+ }
def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str = VERB,
@@ -953,7 +1280,14 @@ def solve_cells(ask: Ask, cells: list[Image.Image], frame_ms: float | None, *, v
return float(np.max(np.hypot(g * whole_across, g * whole_down)))
reach = reach_at(gain)
- radii = [region_radius(region) for region in regions]
+ shaped = None
+ if ask.band is None:
+ radii, sized, larger = [region_radius(region) for region in regions], "a region of radius", "give the region larger radii"
+ else:
+ # The reach first, at the gain asked: the band and the margin are read off it, and the fold rule reads each
+ # region by its narrowest band.
+ shaped = band_shapes(ask.band, regions, reach)
+ radii, sized, larger = [min(bands) for _, bands in shaped[2]], "a region's band of", "give a wider --band"
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.
@@ -961,8 +1295,8 @@ def solve_cells(ask: Ask, cells: list[Image.Image], frame_ms: float | None, *, v
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")
+ raise SystemExit(f"{verb}: a move of {reach:.1f} px folds {sized} {smallest:g} px over itself; "
+ f"lower --gain or {larger}")
# 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.
@@ -974,26 +1308,210 @@ def solve_cells(ask: Ask, cells: list[Image.Image], frame_ms: float | None, *, v
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 "
+ raise SystemExit(f"{verb}: a move of {reach:.1f} px folds {sized} {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")
+ f"{reach_per_gain:.1f} px; the largest gain that does not fold is {gains[k]:g}); {larger}")
gains = [0.0 if hold else g for g, hold in zip(gains, held)]
stretch = None
if ask.stretch_floor is not None:
gains, held, stretch = _keep_floor(ask, radii, gains, held, (whole_across, whole_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 (the reach,
- # like the fold, over the whole move the fold rule reads).
- moves = {g: move(g) for g, hold in zip(gains, held) if not hold}
- reaches = {g: reach_at(g) for g in moves}
- 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], 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,
- None if reference is None else reference[1])
+
+ def answer_at(gains: list[float], held: list[bool]) -> Answer:
+ # 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 (the reach,
+ # like the fold, over the whole move the fold rule reads).
+ moves = {g: move(g) for g, hold in zip(gains, held) if not hold}
+ reaches = {g: reach_at(g) for g in moves}
+ gain = max(moves)
+ dx, dy = moves[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], 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, reaches[gain], groups, read_on, stretch,
+ None if reference is None else reference[1])
+
+ answer = answer_at(gains, held)
+ if shaped is None:
+ return answer
+ # Under a band the regions are carried by their own pixels, whatever the gain; and where the flat ellipse and the
+ # outer one differ in shape (above the centre under --band-up) the band is narrower across its ring than its px,
+ # so the weight falls steeper than the fold rule reads. A pixel moved by the gain times u (the move at gain 1)
+ # keeps 1 − gain · u·∇w of its area: each region's steepest u·∇w over the cells may lower its gain further.
+ carried = _carry_band(answer, None if reference is None else reference[0])
+ steepest = band_steepest(regions, shaped[2], carried, move(1.0), (w, h))
+ over = [not hold and g * per_gain >= 1 for g, hold, (per_gain, _) in zip(gains, held, steepest)]
+ if any(over):
+ i = over.index(True)
+ per_gain, k = steepest[i]
+ why = (f"--band's weight falls steeper than its {shaped[0]:g} px where the band is narrower across its ring (cell {k}: "
+ f"at --gain {gains[i]:g} a pixel keeps {1 - gains[i] * per_gain:.3f} of its area)")
+ if on_fold == "refuse":
+ raise SystemExit(f"{verb}: {why}; lower --gain or give a wider --band" + (" or --band-up" if ask.band.up else ""))
+ lowered = [steepest_gain(g, per_gain) if fold else g for g, fold, (per_gain, _) in zip(gains, over, steepest)]
+ held = [hold or (fold and g < GAIN_MEASURED) for g, hold, fold in zip(lowered, held, over)]
+ if all(held):
+ raise SystemExit(f"{verb}: {why}, and --on-fold lower would have to go under --gain {GAIN_MEASURED:g}; give a wider "
+ "--band" + (" or --band-up" if ask.band.up else ""))
+ answer = answer_at([0.0 if hold else g for g, hold in zip(lowered, held)], held)
+ return _banded(answer, shaped, reach_requested, carried, steepest, verb)
+
+
+def _carry_band(answer: Answer, reference: Image.Image | None) -> list[list[dict[str, Any]]]:
+ """Each region carried by its own pixels (`carry_own`) from the cell it was read on: the reference frame; on a loop
+ carried from its cut (`--read-on`, transported), the cut's cell 0 where the loop holds it, so the loop is carried as
+ the cut is, cell for cell; else cell 0, where the lay or the cut's reading carried the regions."""
+ cells, regions = answer.cells, answer.ask.regions
+ lays = [answer.carry(k) for k in range(len(cells))]
+ if reference is not None:
+ return carry_own(reference, cells, regions, (0.0, 0.0), lays, base_index=None)
+ cut_cells = (answer.read_on or {}).get("cut_cells") or []
+ base = cut_cells.index(0) if 0 in cut_cells else 0
+ return carry_own(cells[base], cells, regions, lays[base], lays, base_index=base)
+
+
+def band_steepest(regions: list[tuple[float, ...]], shapes: list[Any], carried: list[list[dict[str, Any]]],
+ unit: tuple[np.ndarray, np.ndarray], size: tuple[int, int]) -> list[tuple[float, int]]:
+ """Per region, the steepest its band's weight falls along the move at gain 1 (`unit`, per cell), u·∇w over every
+ pixel of every cell (∇ read between each pixel's neighbours, as `jacobian` reads it), and that cell: a pixel moved
+ by gain g keeps 1 − g · u·∇w of its area, so the region folds at g · this ≥ 1."""
+ w, h = size
+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+ out = []
+ for i, (region, shape) in enumerate(zip(regions, shapes)):
+ per_cell = []
+ for k, cell in enumerate(carried):
+ px = cell[i]["px"]
+ weight = band_weight(xx, yy, (region[0] + px[0], region[1] + px[1]), *shape)
+ across = (weight[1:-1, 2:] - weight[1:-1, :-2]) / 2
+ down = (weight[2:, 1:-1] - weight[:-2, 1:-1]) / 2
+ per_cell.append(float(np.max(unit[0][k] * across + unit[1][k] * down)))
+ k = int(np.argmax(per_cell))
+ out.append((per_cell[k], k))
+ return out
+
+
+def steepest_gain(gain: float, per_gain: float) -> float:
+ """The largest gain, in steps of GAIN_STEP and no more than `gain`, at which a slope of `per_gain` per unit of gain
+ (`band_steepest`) stays under 1."""
+ if per_gain <= 0:
+ return gain
+ steps = math.ceil(1 / per_gain / GAIN_STEP) - 1 # under the limit, never on it
+ while steps > 0 and round(steps * GAIN_STEP, 2) * per_gain >= 1:
+ steps -= 1
+ return min(gain, round(steps * GAIN_STEP, 2))
+
+
+def _banded(answer: Answer, shaped: tuple[float, float, list[Any]], reach: float, carried: list[list[dict[str, Any]]],
+ steepest: list[tuple[float, int]], verb: str) -> Answer:
+ """`answer` under its band, each region carried as `_carry_band` carried it, the steepest its weight falls
+ (`band_steepest`), and the ledger of every cell (`band_ledger`). Refused where the move folds the picture all the
+ same."""
+ band_px, margin_px, shapes = shaped
+ ask = answer.ask
+ assert ask.band is not None
+ banded = dataclasses.replace(answer, band=Banded(ask.band, reach, band_px, margin_px, shapes, carried, steepest))
+ ledger = band_ledger(banded)
+ if min(ledger["jacobian_min"]) <= 0:
+ k = int(np.argmin(ledger["jacobian_min"]))
+ raise SystemExit(f"{verb}: --band {band_px:g} px passes the fold rule (a move of {reach:.1f} px), and cell {k}'s move "
+ f"folds the picture all the same (a pixel takes {ledger['jacobian_min'][k]:g} of its area); this is "
+ "the engine's fault — nothing was written")
+ return dataclasses.replace(banded, band=dataclasses.replace(banded.band, ledger=ledger))
+
+
+def _box(mask: np.ndarray) -> list[int] | None:
+ """The box (x0, y0, x1, y1, the last pixel's included) of a mask's pixels; None when it has none."""
+ ys, xs = np.nonzero(mask)
+ return None if not len(ys) else [int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())]
+
+
+def band_ledger(answer: Answer) -> dict[str, Any]:
+ """Per cell, what a band's move does (`--band`), each count a list over the cells with its largest beside it:
+ - `band_on_regions_px`: solid pixels under a region's ellipse, carried, that the weight takes less than 1 of — the
+ band lies over the part;
+ - `pressed_px`, `stretched_px`: pixels of the moved cell, solid and moved, left with under PRESSED or over STRETCHED
+ of their area (the area of the source a pixel takes, `jacobian`, is 1 over it), the box they lie in, and the least
+ and the most area with where it is (`area_least`, `area_most`: area, x, y);
+ - `outside_moved_px`: solid pixels under no region's ellipse that the move takes MOVED_PX or more;
+ - `jacobian_min`: the least area of the source any pixel of the moved cell takes (0 or under: the picture folds)."""
+ assert answer.band is not None
+ w, h = answer.cells[0].size
+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+ keys = ("band_on_regions_px", "pressed_px", "pressed_box", "area_least", "stretched_px", "stretched_box", "area_most",
+ "outside_moved_px", "jacobian_min")
+ ledger: dict[str, list[Any]] = {key: [] for key in keys}
+ for k, cell in enumerate(answer.cells):
+ alpha = np.asarray(cell.getchannel("A"), np.float32)
+ solid = alpha >= ALPHA_SOLID
+ field, weights = answer.band_field(k, xx, yy)
+ regions = np.logical_or.reduce([region_weight(xx, yy, region, entry["px"]) > 0
+ for region, entry in zip(answer.ask.regions, answer.band.carried[k])])
+ ledger["band_on_regions_px"].append(int((solid & regions & (np.max(weights, axis=0) < 1)).sum()))
+ moving = field is not None and any(dx != 0 or dy != 0 for _, (dx, dy) in answer.moves_in(k))
+ if not moving:
+ for key, empty in (("pressed_px", 0), ("pressed_box", None), ("area_least", None), ("stretched_px", 0),
+ ("stretched_box", None), ("area_most", None), ("outside_moved_px", 0), ("jacobian_min", 1.0)):
+ ledger[key].append(empty)
+ continue
+ inside, move_x, move_y = field
+ # The moved cell's alpha as `_draw` draws it: the alpha channel read alone, bilinear, is the premultiplied mix's.
+ drawn = np.where(inside, np.clip(np.round(_sample(alpha[..., None], xx - move_x, yy - move_y)[..., 0]), 0, 255), alpha)
+ area_of = jacobian(move_x, move_y)
+ counted = np.zeros((h, w), bool)
+ counted[1:-1, 1:-1] = (inside & (drawn >= ALPHA_SOLID))[1:-1, 1:-1] & (area_of > 0)
+ area = np.ones((h, w))
+ area[1:-1, 1:-1] = 1 / np.where(area_of > 0, area_of, 1.0) # each pixel's area: 1 over the source's it takes
+ pressed, stretched = counted & (area < PRESSED), counted & (area > STRETCHED)
+ for key, mask in (("pressed", pressed), ("stretched", stretched)):
+ ledger[f"{key}_px"].append(int(mask.sum()))
+ ledger[f"{key}_box"].append(_box(mask))
+ for key, pick, empty in (("area_least", np.argmin, np.inf), ("area_most", np.argmax, -np.inf)):
+ if counted.any():
+ y, x = divmod(int(pick(np.where(counted, area, empty))), w)
+ ledger[key].append([round(float(area[y, x]), 4), x, y])
+ else:
+ ledger[key].append(None)
+ ledger["outside_moved_px"].append(int((solid & ~regions & (np.hypot(move_x, move_y) >= MOVED_PX)).sum()))
+ ledger["jacobian_min"].append(round(float(area_of.min()), 4))
+ out: dict[str, Any] = {}
+ for key in keys:
+ out[key] = ledger[key]
+ if key.endswith("_px"):
+ out[f"{key}_max"] = max(ledger[key], default=0)
+ return out
+
+
+def band_notes(record: dict[str, Any], verb: str = VERB, at: str = f"{loop_mod.SWAY_RECORD}.band") -> list[str]:
+ """What to say of a band's record (`--band`), a line each, as warnings: the cells a region was carried by the lay
+ in and why, and every count of the ledger that is not 0 in some cell — in how many cells, up to how many pixels and
+ in which cell, and where in the record (`at`: the band's key in the strip's meta, or in a frames folder's record)."""
+ band, notes = record["band"], []
+ by_region: dict[int, list[dict[str, Any]]] = {}
+ for entry in band["lay"]:
+ by_region.setdefault(entry["region"], []).append(entry)
+ for i, entries in sorted(by_region.items()):
+ name = "--region " + ",".join(f"{v:g}" for v in record["regions"][i])
+ whys = "; ".join(f"cell {e['cell']}: {e['why']}" for e in entries)
+ notes.append(f"{verb}: warning: --band carries {name} by the body's lay in {len(entries)} cells, its own pixels not "
+ f"found surely ({whys}) — {at}.lay")
+ ledger, n = band["ledger"], len(band["ledger"]["jacobian_min"])
+ said = {"band_on_regions_px": "the band lies over solid pixels of the regions",
+ "pressed_px": f"moved pixels are left under {PRESSED:g} of their area",
+ "stretched_px": f"moved pixels are left over {STRETCHED:g} of their area",
+ "outside_moved_px": f"solid pixels outside every region move {MOVED_PX:g} px or more"}
+ for key, what in said.items():
+ counts = ledger[key]
+ cells = [k for k, count in enumerate(counts) if count]
+ if not cells:
+ continue
+ top = max(range(n), key=lambda k: counts[k])
+ extra = ""
+ if key in ("pressed_px", "stretched_px"):
+ spot = ledger["area_least" if key == "pressed_px" else "area_most"][top]
+ extra = f", {'least' if key == 'pressed_px' else 'most'} {spot[0]:g} at {spot[1]},{spot[2]}"
+ notes.append(f"{verb}: warning: --band: {what} in {len(cells)} of {n} cells, up to {ledger[key + '_max']} px (cell "
+ f"{top}{extra}) — {at}.ledger.{key}")
+ return notes
def _keep_floor(ask: Ask, radii: list[float], gains: list[float], held: list[bool],
@@ -1030,9 +1548,11 @@ def sway_loop(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: float |
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]:
+ band: float | str | None = None, band_margin: float | str | None = None,
+ band_up: tuple[float, float | str] | str | 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, breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)
+ stretch_floor=stretch_floor, breathe=breathe, lag=lag, gain_across=gain_across, band=band,
+ band_margin=band_margin, band_up=band_up, 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
@@ -1083,7 +1603,9 @@ def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fp
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, reference: Path | None = None, verb: str = VERB) -> dict[str, Any]:
+ gain_across: float | None = None, reference: Path | None = None, band: float | str | None = None,
+ band_margin: float | str | None = None, band_up: tuple[float, float | str] | str | 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
@@ -1095,7 +1617,8 @@ def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fp
regions are read on it and not on the first frame: each frame's body is read from it and the regions carried
from there, as they are on the loop's own cells."""
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)
+ breathe=breathe, lag=lag, gain_across=gain_across, band=band, band_margin=band_margin, band_up=band_up,
+ 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:
@@ -1197,6 +1720,19 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
"first cell, for a way in or out of the loop (sprite-gen breathe --loop-cells --start-cell): each "
"frame's body is read from it and the regions carried from there (one size with the frames)")
add_request_arguments(parser, loop_dir=False)
+ parser.add_argument("--band", type=parse_band, default=None, metavar=f"PX|{AUTO}",
+ help="move each region as one mass: 1 over its ellipse grown by --band-margin, falling to 0 (cos²) over PX px "
+ f"past it ({AUTO}: ceil(reach x π/2) + 1, the narrowest the move does not fold), carried into each cell by "
+ "its own pixels (the body's lay where they are not found surely, named in the record and a warning); "
+ "the fold rule reads the band. Off by default: the weight falls from the centre. Not with a region's "
+ "flat share, nor --stretch-floor")
+ parser.add_argument("--band-margin", type=parse_band_margin, default=None, metavar=f"PX|{AUTO}",
+ help=f"with --band: how far past the ellipse the weight stays 1, every way (default {AUTO}: the move's reach "
+ "and a pixel, ceil(reach) + 1, so the part is still on the flat where it goes)")
+ parser.add_argument("--band-up", type=parse_band_up, default=None, metavar=f"FLAT[,PX|{AUTO}]",
+ help="with --band: above the centre the flat part stops FLAT (over 0, at most 1) of the region's height over "
+ f"it and the weight falls over PX from there ({AUTO}, the default: the band, or to {HANG_PAST:g} px over the "
+ "region's top where that is further): the upper part gives, the rest moves whole. Default: above as below")
parser.add_argument("--board", type=Path, help="write a before/after picture at the frames where the part sits lowest and highest")
@@ -1235,7 +1771,8 @@ def run(**kwargs: object) -> int:
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")}
+ "gain_across": kwargs.get("gain_across"), "band": kwargs.get("band"), "band_margin": kwargs.get("band_margin"),
+ "band_up": kwargs.get("band_up")}
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")
@@ -1251,11 +1788,16 @@ def run(**kwargs: object) -> int:
for note in fold_notes(result, verb):
print(note, file=sys.stderr)
where = "out" if "out" in result else "strip"
+ if "band" in result:
+ for note in band_notes(result, verb, f"{FRAMES_RECORD} band" if where == "out" else f"{loop_mod.SWAY_RECORD}.band"):
+ print(note, file=sys.stderr)
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 {})
+ | ({"band": {"band_px": result["band"]["band_px"], "margin_px": result["band"]["margin_px"],
+ "lay_cells": sorted({entry["cell"] for entry in result["band"]["lay"]})}} if "band" in result else {})
| ({"board": result["board"]} if "board" in result else {}), ensure_ascii=False, indent=2))
return 0
diff --git a/sprite_gen/video/sway_inspect.py b/sprite_gen/video/sway_inspect.py
index e029b31..275eccc 100644
--- a/sprite_gen/video/sway_inspect.py
+++ b/sprite_gen/video/sway_inspect.py
@@ -188,16 +188,7 @@ def seam(a: tuple[float, ...], b: tuple[float, ...], move_a: tuple[float, float]
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
+jacobian = sway.jacobian # the area of the source a moved pixel takes; the band's ledger reads it too
def _least(area: np.ndarray | None, mask: np.ndarray) -> tuple[float, list[int] | None]:
diff --git a/tests/video/test_follow_inspect.py b/tests/video/test_follow_inspect.py
index 119d6f7..72c274e 100644
--- a/tests/video/test_follow_inspect.py
+++ b/tests/video/test_follow_inspect.py
@@ -453,7 +453,9 @@ def test_the_command_takes_what_video_follow_takes(tmp_path, capsys):
cli.COMMANDS[cli.VERB_ALIASES['video-follow'][0]][1](parsers[0])
add_arguments(parsers[1])
followed, inspected = vars(parsers[0].parse_args(asked)), vars(parsers[1].parse_args([*asked, '--out-dir', str(out)]))
- own = {'board', 'frames', 'out', 'fps', 'reference'} # video-sway's own: its board, and the frames path beside the loop directory
+ # video-sway's own: its board, the frames path beside the loop directory, and the band (`--band`), whose carry by the
+ # region's own pixels the inspection does not read
+ own = {'board', 'frames', 'out', 'fps', 'reference', 'band', 'band_margin', 'band_up'}
assert set(inspected)-set(followed) == {'out_dir', 'scale', 'columns'} and set(followed)-set(inspected) == own
assert {key: inspected[key] for key in followed if key not in own} == {key: value for key, value in followed.items() if key not in own}
capsys.readouterr()
diff --git a/tests/video/test_sway_band.py b/tests/video/test_sway_band.py
new file mode 100644
index 0000000..8b69d65
--- /dev/null
+++ b/tests/video/test_sway_band.py
@@ -0,0 +1,436 @@
+"""`video-sway --band`: a region moved as one mass.
+
+Without it a region's weight falls from its centre, so a large part moves its middle and presses the rest in. With it the
+weight is 1 over the region's ellipse grown by a margin and falls to 0 over a band past it, each "auto" read off the
+move's reach; the fold rule reads the band, and the steepest the weight falls where the band is narrower across its ring
+than its px, and `--band-up` gives the part above the centre its own flat share and band.
+Each region is carried into a cell by its own pixels, and by the body's lay where they are not found surely, the record
+saying which. Past every band no byte changes, and a ledger says, cell by cell, what the move did. Synthetic figures only:
+the inspection's body (a soft part on a torso that sways once and bobs twice a cycle), the frames test's noise-textured
+body, the read-on test's runner, cloth with no pattern and cloth dotted every 4 px.
+
+Each case first reads what a sway writes with or without the band (its cells, its fold, whether it refuses, what it
+says), so on a release without the band the same input fails on what comes out; the band's own record is read after.
+"""
+import hashlib
+import io
+import json
+import math
+import shutil
+
+import numpy as np
+import pytest
+from PIL import Image, ImageDraw
+from sprite_gen import cli
+from sprite_gen.video import sway
+
+from tests.video.test_follow_inspect import CHEST, HEAD, LEG, N, PART, W, H, cells, sway as body_sway, strip_dir
+from tests.video.test_follow_inspect import TORSO as TORSO_COLOUR
+from tests.video.test_follow_read_on import aligned, cells_of, chest, meta_of, origin, origin_once # noqa: F401 (fixtures)
+from tests.video.test_sway_frames import TORSO, as_strip_cell, cut, frame, frames_dir, rgba
+
+FILES = [f'frame-{k:03d}.png' for k in range(N)]
+POLICY = 'own-pixels/margin-band-cos2/1'
+OWN_PIXELS = {'reading': 'outline-lay', 'region': 'own-pixels'}
+SEARCH = 9 # px either way of the lay a region's pixels are looked for
+EDGE = f"the least is on the search's edge, {SEARCH} px from the lay"
+TIE = 'the least is tied with a place more than a pixel away'
+
+
+def text(region):
+ return ','.join(f'{v:g}' for v in region)
+
+
+def answer_of(loop_dir, regions, **kw):
+ """What `video-sway` asked the same way comes to on the loop (`sway.solve`), with nothing written."""
+ request = sway.read_request(loop_dir, regions, **kw)
+ strip = request.source_path if request.source_path.exists() else request.strip_path
+ data = strip.read_bytes()
+ return sway.solve(request, Image.open(io.BytesIO(data)).convert('RGBA'), strip_name=strip.name,
+ strip_sha256=hashlib.sha256(data).hexdigest())
+
+
+def auto(reach):
+ """The margin and band `auto` reads off a move's reach: the reach and a pixel, and the narrowest band it does not fold."""
+ return math.ceil(reach)+1, math.ceil(reach*math.pi/2)+1
+
+
+def shapes(record):
+ """Each region's flat radii and bands as the band's record holds them."""
+ return [{key: region[key] for key in ('flat_px', 'band_px')} for region in record['band']['regions']]
+
+
+def whole_move(cell, dx, dy):
+ """`cell` moved by (dx, dy) everywhere, as the engine draws a move (one region flat over far more than the cell)."""
+ w, h = cell.size
+ return np.asarray(sway.move_regions(cell, [([(w/2, h/2, 1e4, 1e4, 0.9)], (dx, dy))], (0.0, 0.0)))
+
+
+def rings(shape, centre, flat, band):
+ """Per pixel, how far out it is, in the flat ellipse's radii and in the outer one's (1 on each rim): the flat
+ ellipse about `centre` with radii across, above and below, the outer one those and the band's."""
+ yy, xx = np.mgrid[0:shape[0], 0:shape[1]].astype(np.float64)
+ dx, dy = xx-centre[0], yy-centre[1]
+ above = dy < 0
+ ay, by = np.where(above, flat[1], flat[2]), np.where(above, band[1], band[2])
+ return np.hypot(dx/flat[0], dy/ay), np.hypot(dx/(flat[0]+band[0]), dy/(ay+by))
+
+
+def sliding(slide, part=PART, dots=False):
+ """The inspection's figure, its soft part drawn a further `slide(k)` whole pixels from where the torso carries it:
+ the part slides on the body, and the body's outline does not show it. `part` the part's colour (the torso's: cloth
+ with no pattern); `dots`: the torso dotted every 4 px each way, the dots carried with it, and no part."""
+ def draw(k):
+ sx, sy = body_sway(k)
+ ex, ey = slide(k)
+ im = Image.new('RGBA', (W, H))
+ d = ImageDraw.Draw(im)
+ d.rectangle((45+sx, 20+sy, 75+sx, 45+sy), fill=HEAD)
+ d.rectangle((35+sx, 46+sy, 85+sx, 110+sy), fill=TORSO_COLOUR)
+ if dots:
+ for y in range(48, 109, 4):
+ for x in range(37, 84, 4):
+ d.point((x+sx, y+sy), fill=PART)
+ else:
+ d.ellipse((46+sx+ex, 60+sy+ey, 74+sx+ex, 84+sy+ey), fill=part)
+ d.rectangle((44+sx, 111+sy, 50+sx, 150), fill=LEG)
+ d.rectangle((70+sx, 111+sy, 76+sx, 150), fill=LEG)
+ return im
+ return draw
+
+
+def slide(k):
+ return round(2*math.sin(4*math.pi*k/N)), round(2*math.cos(2*math.pi*k/N))-2
+
+
+def ramp(k):
+ """3 px further down each cell, to 12 px from where the torso carries it, held there, and back by the loop's end."""
+ return 0, 3*min(k, N-k, 4)
+
+
+def lay_warning(region, entries):
+ whys = '; '.join(f'cell {k}: {why}' for k, why in entries)
+ return (f"--band carries --region {text(region)} by the body's lay in {len(entries)} cells, its own pixels not found "
+ f"surely ({whys}) — follow.band.lay")
+
+
+# ---------------------------------------------------------------- the band's shape, read off the move
+
+def test_without_a_band_the_record_and_the_strip_are_as_ever(tmp_path):
+ plain = strip_dir(tmp_path/'plain')
+ asked = strip_dir(tmp_path/'asked')
+ assert cli.main(['video-sway', '--loop-dir', str(plain), '--region', text(CHEST)]) == 0
+ sway.sway_loop(asked, [CHEST], band=None, band_margin=None, band_up=None)
+ assert (plain/'walk.strip.png').read_bytes() == (asked/'walk.strip.png').read_bytes()
+ record = json.loads((plain/'walk.strip.json').read_text())['follow']
+ assert 'band' not in record and 'carry_basis' not in record
+
+
+def test_auto_reads_the_margin_and_the_band_off_the_moves_reach(tmp_path):
+ loop_dir = strip_dir(tmp_path/'loop')
+ reach = answer_of(loop_dir, [CHEST]).reach_requested # the move at the gain asked, before any band
+ margin, band = auto(reach)
+ record = sway.sway_loop(loop_dir, [CHEST], band='auto')
+ # The fold rule reads the band: auto is the narrowest the move at the gain asked does not fold.
+ assert [r['radius_px'] for r in record['fold']['regions']] == [band] and not record['fold']['lowered']
+ assert record['fold']['ratio'] == round(reach*math.pi/(2*band), 3) < 1
+ assert record.get('carry_basis') == OWN_PIXELS
+ banded = record['band']
+ assert (banded['policy'], banded['asked'], banded['reach_px'], banded['band_px'], banded['margin_px']) == \
+ (POLICY, {'band': 'auto', 'margin': 'auto', 'up': None}, round(reach, 4), band, margin)
+ assert shapes(record) == [{'flat_px': [CHEST[2]+margin, CHEST[3]+margin, CHEST[3]+margin], 'band_px': [band]*3}]
+ assert min(banded['ledger']['jacobian_min']) > 0
+ given = sway.sway_loop(strip_dir(tmp_path/'given'), [CHEST], band=40, band_margin=0)
+ assert [r['radius_px'] for r in given['fold']['regions']] == [40]
+ assert shapes(given) == [{'flat_px': [CHEST[2], CHEST[3], CHEST[3]], 'band_px': [40, 40, 40]}]
+
+
+def test_the_fold_rule_reads_a_narrow_band_and_lowers_or_refuses_as_ever(tmp_path):
+ per_gain = answer_of(strip_dir(tmp_path/'unit'), [CHEST], gain=1.0).reach_per_gain
+ band = math.ceil(1.3*per_gain*math.pi/2) # the move at gain 1.3 does not fold it, the move at 2.5 does
+ assert 2.5*per_gain*math.pi/(2*band) >= 1
+ with pytest.raises(SystemExit, match=rf"folds a region's band of {band} px over itself; lower --gain or give a wider --band$"):
+ sway.sway_loop(strip_dir(tmp_path/'refused'), [CHEST], band=band)
+ lowered = sway.sway_loop(strip_dir(tmp_path/'lowered'), [CHEST], band=band, on_fold='lower')
+ assert lowered['fold']['lowered'] and 1 <= lowered['gain'] < 2.5
+ assert lowered['reach_px']*math.pi/(2*band) < 1 and lowered['fold']['regions'][0]['radius_px'] == band
+
+
+def test_a_band_narrower_across_its_ring_than_its_px_lowers_or_refuses_by_its_steepest_slope(tmp_path):
+ # Flat to a tenth of the radius above the centre, the band above runs out from a flat ellipse of another shape than
+ # the outer one: across its ring it is narrower than its px, and the move at the gain asked, which the band's px
+ # does not fold, folds the picture there.
+ _, band = auto(answer_of(strip_dir(tmp_path/'unit'), [CHEST]).reach_requested)
+ with pytest.raises(SystemExit, match=rf"--band's weight falls steeper than its {band} px where the band is narrower across its "
+ r"ring \(cell \d+: at --gain 2.5 a pixel keeps -[\d.]+ of its area\); lower --gain or give a "
+ r"wider --band or --band-up$"):
+ sway.sway_loop(strip_dir(tmp_path/'refused'), [CHEST], band='auto', band_up='0.1')
+ lowered = sway.sway_loop(strip_dir(tmp_path/'lowered'), [CHEST], band='auto', band_up='0.1', on_fold='lower')
+ assert lowered['fold']['lowered'] and 1 <= lowered['gain'] < 2.5
+ assert lowered['fold']['regions'][0]['radius_px'] == band and lowered['fold']['ratio'] < 1 # the band's px passes
+ steepest = lowered['band']['regions'][0]['steepest']
+ # The largest gain in steps of 0.01 whose steepest slope leaves every pixel some of its area.
+ assert steepest['ratio'] == round(lowered['gain']*steepest['per_gain'], 3) < 1 <= round((lowered['gain']+0.01)*steepest['per_gain'], 2)
+ assert min(lowered['band']['ledger']['jacobian_min']) > 0
+ whole = sway.sway_loop(strip_dir(tmp_path/'whole'), [CHEST], band='auto')
+ assert whole['gain'] == 2.5 and whole['band']['regions'][0]['steepest']['ratio'] < 1
+
+
+def test_band_up_stops_the_flat_part_over_the_centre_and_runs_its_band_past_the_top(tmp_path):
+ whole_dir, up_dir = strip_dir(tmp_path/'whole'), strip_dir(tmp_path/'up')
+ whole = sway.sway_loop(whole_dir, [CHEST], band='auto')
+ up = sway.sway_loop(up_dir, [CHEST], band='auto', band_up=(0.4, 'auto'))
+ moved_whole, moved_up = cells(whole_dir/'walk.strip.png'), cells(up_dir/'walk.strip.png')
+ # Below the centre the two are one move; above it the upper part gives.
+ upper_gives = 0
+ for k in range(N):
+ centre = math.ceil(CHEST[1]+body_sway(k)[1]+1)
+ assert np.array_equal(moved_whole[k][centre:], moved_up[k][centre:]), k
+ upper_gives += not np.array_equal(moved_whole[k][:centre], moved_up[k][:centre])
+ assert upper_gives > N//2
+ margin, band = whole['band']['margin_px'], whole['band']['band_px']
+ assert shapes(up) == [{'flat_px': [CHEST[2]+margin, round(0.4*CHEST[3], 4), CHEST[3]+margin],
+ 'band_px': [band, round(max(band, 0.6*CHEST[3]+3), 4), band]}]
+ assert up['band']['asked']['up'] == {'flat': 0.4, 'band': 'auto'}
+ # The band lies over the part only where it is asked to.
+ assert up['band']['ledger']['band_on_regions_px_max'] > 0 and whole['band']['ledger']['band_on_regions_px_max'] == 0
+ given = sway.sway_loop(strip_dir(tmp_path/'given'), [CHEST], band=40, band_up='0.4,20')
+ assert given['band']['regions'][0]['band_px'] == [40, 20, 40]
+ assert given['fold']['regions'][0]['radius_px'] == 20 # the fold rule reads the narrowest
+
+
+# ---------------------------------------------------------------- refused
+
[email protected]('args, said', [
+ (['--region', f'{text(CHEST)},0.5', '--band', 'auto'], r'a region\'s fifth number \(flat, 0.5 on --region 60,72,18,16,0.5\) is '
+ r'the other way of moving it whole'),
+ (['--region', text(CHEST), '--band', 'auto', '--stretch-floor', '0.5'], r'--stretch-floor reads the weight that falls'),
+ (['--region', text(CHEST), '--band-margin', '3'], r'--band-margin and --band-up shape a band; they need --band$'),
+ (['--region', text(CHEST), '--band-up', '0.4'], r'--band-margin and --band-up shape a band; they need --band$'),
+])
+def test_what_a_band_cannot_be_asked_with_is_refused_and_says_why(tmp_path, args, said):
+ loop_dir = strip_dir(tmp_path/'loop')
+ as_cut = (loop_dir/'walk.strip.png').read_bytes()
+ with pytest.raises(SystemExit, match=said) as refused:
+ cli.main(['video-sway', '--loop-dir', str(loop_dir), *args])
+ assert refused.value.code not in (0, None)
+ assert (loop_dir/'walk.strip.png').read_bytes() == as_cut and 'follow' not in json.loads((loop_dir/'walk.strip.json').read_text())
+
+
+def test_a_flat_share_of_0_is_four_numbers_and_takes_a_band(tmp_path):
+ four, five = strip_dir(tmp_path/'four'), strip_dir(tmp_path/'five')
+ assert cli.main(['video-sway', '--loop-dir', str(four), '--region', text(CHEST), '--band', 'auto']) == 0
+ assert cli.main(['video-sway', '--loop-dir', str(five), '--region', f'{text(CHEST)},0', '--band', 'auto']) == 0
+ assert (four/'walk.strip.png').read_bytes() == (five/'walk.strip.png').read_bytes()
+
+
[email protected]('flag, value, said', [
+ ('--band', '0', "--band wants px (over 0) or auto, got '0'"), ('--band', '-3', "--band wants px (over 0) or auto"),
+ ('--band', 'wide', "--band wants px (over 0) or auto, got 'wide'"), ('--band', 'nan', "--band wants px (over 0) or auto"),
+ ('--band-margin', '-1', "--band-margin wants px (at least 0) or auto, got '-1'"),
+ ('--band-up', '0', "--band-up wants FLAT[,PX|auto]"), ('--band-up', '1.5', "--band-up wants FLAT[,PX|auto]"),
+ ('--band-up', '0.4,0', "--band-up wants px (over 0) or auto, got '0'"), ('--band-up', 'top', "--band-up wants FLAT[,PX|auto]")])
+def test_a_band_out_of_range_is_refused_by_the_command_line(tmp_path, capsys, flag, value, said):
+ loop_dir = strip_dir(tmp_path/'loop')
+ with pytest.raises(SystemExit) as refused:
+ cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto', flag, value])
+ assert refused.value.code == 2
+ assert f'argument {flag}: {said}' in capsys.readouterr().err
+
+
+# ---------------------------------------------------------------- what moves and what does not
+
+def test_the_flat_part_moves_whole_and_past_the_band_no_byte_changes(tmp_path):
+ loop_dir, meta = cut(tmp_path, [frame(k) for k in range(N)])
+ left, top = meta['source_rect'][:2]
+ region = (TORSO[0]-left, TORSO[1]-top, 16.0, 20.0)
+ answer = answer_of(loop_dir, [region], band='auto', band_margin=2, on_fold='lower')
+ record = sway.sway_loop(loop_dir, [region], band='auto', band_margin=2, on_fold='lower')
+ strip, w = rgba(loop_dir/'walk.strip.png'), meta['w']
+ _, band = auto(answer.reach_requested)
+ flat, bands = (region[2]+2, region[3]+2, region[3]+2), (band, band, band)
+ moved = 0
+ for k in range(N):
+ src, out = np.asarray(answer.cells[k]), strip[:, k*w:(k+1)*w]
+ dx, dy = answer.dx[k], answer.dy[k]
+ lay = answer.carry(k)
+ inner, outer = rings(src.shape[:2], (region[0]+lay[0], region[1]+lay[1]), flat, bands)
+ # Well inside the flat part, the region grown by the margin, the cell moves by its offset itself; past the band
+ # (and a tenth of it, for the carry) every byte is as it was, the colour under clear pixels too.
+ core, far = inner <= 0.9, outer >= 1.1
+ assert np.array_equal(out[core], whole_move(answer.cells[k], dx, dy)[core]), k
+ assert np.array_equal(out[far], src[far]), k
+ moved += math.hypot(dx, dy) > 0
+ assert moved > N//2
+ banded = record['band']
+ assert shapes(record) == [{'flat_px': list(flat), 'band_px': list(bands)}] and banded['margin_px'] == 2
+ yy, xx = np.mgrid[0:meta['h'], 0:w].astype(np.float32)
+ just_outside = just_inside_changed = 0
+ for k in range(N):
+ src, out = np.asarray(answer.cells[k]), strip[:, k*w:(k+1)*w]
+ shift = banded['carry']['cells'][k][0]['px']
+ inner, outer = rings(src.shape[:2], (region[0]+shift[0], region[1]+shift[1]), flat, bands)
+ # Past the band's own rim, where the region is carried, no byte changes; inside it the weight is over 0.
+ assert np.array_equal(src[outer >= 1], out[outer >= 1]), k
+ just_outside += int(((outer >= 1) & (outer < 1.1)).sum())
+ just_inside_changed += int(((outer < 1) & (outer > 0.85) & (src != out).any(axis=-1)).sum())
+ (inside, move_x, move_y), _ = answer.band_field(k, xx, yy)
+ assert not inside[outer >= 1].any() and inside[outer < 0.999].all()
+ # The flat part moves by the offset itself, and just past it less.
+ dx, dy = answer.dx[k], answer.dy[k]
+ assert np.all(move_x[inner <= 1] == dx) and np.all(move_y[inner <= 1] == dy), k
+ if math.hypot(dx, dy) > 0:
+ assert np.all(np.hypot(move_x, move_y)[(inner > 1.02) & (outer < 1)] < math.hypot(dx, dy)), k
+ assert just_outside > 0 and just_inside_changed > 0
+ assert banded['ledger']['outside_moved_px_max'] > 0
+
+
+def test_a_region_is_carried_by_its_own_pixels_where_the_part_slides_on_the_body(tmp_path):
+ loop_dir = strip_dir(tmp_path/'loop', sliding(slide))
+ answer = answer_of(loop_dir, [CHEST], band='auto')
+ assert np.allclose(answer.carry(5), body_sway(5), atol=0.5) # the body's lay does not see the part slide
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto']) == 0
+ moved = cells(loop_dir/'walk.strip.png')
+ for k in range(N):
+ # The part moves whole where it is: every pixel of it is the cell moved by the cell's offset.
+ sx, sy = body_sway(k)
+ ex, ey = slide(k)
+ inner, _ = rings((H, W), (CHEST[0]+sx+ex, CHEST[1]+sy+ey), (14.0, 12.0, 12.0), (1, 1, 1))
+ assert np.array_equal(moved[k][inner <= 1], whole_move(answer.cells[k], answer.dx[k], answer.dy[k])[inner <= 1]), k
+ band = json.loads((loop_dir/'walk.strip.json').read_text())['follow']['band']
+ assert band['lay'] == [] and band['carry']['search_px'] == SEARCH
+ ex0, ey0 = slide(0)
+ for k, (entry,) in enumerate(band['carry']['cells']):
+ if k == 0:
+ assert entry == {'px': [0.0, 0.0], 'from': 'base'}
+ continue
+ sx, sy = body_sway(k)
+ ex, ey = slide(k)
+ assert entry['from'] == 'pixels' and entry['curvature'][0] > 0 and entry['curvature'][1] > 0, k
+ assert abs(entry['px'][0]-(sx+ex-ex0)) < 0.1 and abs(entry['px'][1]-(sy+ey-ey0)) < 0.1, (k, entry)
+
+
+def test_cloth_with_no_pattern_is_carried_by_the_lay_and_a_warning_names_each_cell(tmp_path, capsys):
+ loop_dir = strip_dir(tmp_path/'loop', sliding(lambda k: (0, 0), part=TORSO_COLOUR))
+ lays = [[round(float(v), 4)+0.0 for v in answer_of(loop_dir, [CHEST]).carry(k)] for k in range(N)]
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto']) == 0
+ assert lay_warning(CHEST, [(k, EDGE) for k in range(1, N)]) in capsys.readouterr().err
+ band = json.loads((loop_dir/'walk.strip.json').read_text())['follow']['band']
+ assert band['lay'] == [{'cell': k, 'region': 0, 'why': EDGE} for k in range(1, N)]
+ for k in range(1, N):
+ entry = band['carry']['cells'][k][0]
+ assert entry['from'] == 'lay' and entry['px'] == lays[k] and entry['curvature'] is None
+
+
+def test_a_part_that_slides_further_from_the_lay_than_the_search_is_found_where_the_cell_before_had_it(tmp_path):
+ loop_dir = strip_dir(tmp_path/'loop', sliding(ramp))
+ answer = answer_of(loop_dir, [CHEST], band='auto')
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto']) == 0
+ moved = cells(loop_dir/'walk.strip.png')
+ for k in range(N):
+ # 12 px from the lay and moved whole all the same: each cell is looked at around where the cell before had it.
+ sx, sy = body_sway(k)
+ ex, ey = ramp(k)
+ inner, _ = rings((H, W), (CHEST[0]+sx+ex, CHEST[1]+sy+ey), (14.0, 12.0, 12.0), (1, 1, 1))
+ assert np.array_equal(moved[k][inner <= 1], whole_move(answer.cells[k], answer.dx[k], answer.dy[k])[inner <= 1]), k
+ band = json.loads((loop_dir/'walk.strip.json').read_text())['follow']['band']
+ assert band['lay'] == []
+ for k, (entry,) in enumerate(band['carry']['cells'][1:], 1):
+ sx, sy = body_sway(k)
+ ex, ey = ramp(k)
+ assert entry['from'] == 'pixels' and abs(entry['px'][0]-(sx+ex)) < 0.1 and abs(entry['px'][1]-(sy+ey)) < 0.1, (k, entry)
+
+
+def test_a_part_further_than_the_search_from_the_cell_before_is_carried_by_the_lay(tmp_path, capsys):
+ loop_dir = strip_dir(tmp_path/'loop', sliding(lambda k: (0, 12) if k == 5 else (0, 0)))
+ lay5 = [round(float(v), 4)+0.0 for v in answer_of(loop_dir, [CHEST]).carry(5)]
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto']) == 0
+ edge = f"the least is on the search's edge, {SEARCH} px from where cell 4 had it"
+ assert lay_warning(CHEST, [(5, edge)]) in capsys.readouterr().err
+ band = json.loads((loop_dir/'walk.strip.json').read_text())['follow']['band']
+ assert band['lay'] == [{'cell': 5, 'region': 0, 'why': edge}] and band['carry']['cells'][5][0]['px'] == lay5
+ # The cell after is looked at around its own lay again, and found.
+ assert all(cell[0]['from'] == 'pixels' for k, cell in enumerate(band['carry']['cells']) if k not in (0, 5))
+
+
+def test_cloth_dotted_every_4_px_is_a_tie_and_carried_by_the_lay(tmp_path, capsys):
+ # One place of the dots looks as another 4 px away does, and none of those is on the search's edge.
+ loop_dir = strip_dir(tmp_path/'loop', sliding(lambda k: (0, 0), dots=True))
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto']) == 0
+ assert lay_warning(CHEST, [(k, TIE) for k in range(1, N)]) in capsys.readouterr().err
+ band = json.loads((loop_dir/'walk.strip.json').read_text())['follow']['band']
+ assert band['lay'] == [{'cell': k, 'region': 0, 'why': TIE} for k in range(1, N)]
+ assert all(cell[0]['least'] == 0 for cell in band['carry']['cells'][1:]) # the dots are found, in more than one place
+
+
+# ---------------------------------------------------------------- the ledger
+
+def test_the_ledger_counts_each_cell_and_a_warning_says_what_is_in_it(tmp_path, capsys):
+ loop_dir = strip_dir(tmp_path/'loop')
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto',
+ '--band-up', '0.4']) == 0
+ err = capsys.readouterr().err
+ assert '— follow.band.ledger.band_on_regions_px' in err and '— follow.band.ledger.outside_moved_px' in err
+ record = json.loads((loop_dir/'walk.strip.json').read_text())['follow']
+ ledger = record['band']['ledger']
+ for key in ('band_on_regions_px', 'pressed_px', 'stretched_px', 'outside_moved_px'):
+ assert len(ledger[key]) == N and ledger[f'{key}_max'] == max(ledger[key])
+ if ledger[f'{key}_max']:
+ top = ledger[key].index(ledger[f'{key}_max'])
+ cells_in = sum(1 for count in ledger[key] if count)
+ assert f'in {cells_in} of {N} cells, up to {ledger[key + "_max"]} px (cell {top}' in err and f'follow.band.ledger.{key}' in err
+ else:
+ assert f'follow.band.ledger.{key}' not in err
+ assert ledger['band_on_regions_px_max'] > 0 and ledger['outside_moved_px_max'] > 0
+ for k in range(N):
+ for key, area, beyond in (('pressed', 'area_least', lambda a: a < 0.85), ('stretched', 'area_most', lambda a: a > 1.15)):
+ assert (ledger[f'{key}_px'][k] > 0) == (ledger[f'{key}_box'][k] is not None), k
+ if ledger[f'{key}_px'][k]:
+ x0, y0, x1, y1 = ledger[f'{key}_box'][k]
+ a, x, y = ledger[area][k]
+ assert beyond(a) and x0 <= x <= x1 and y0 <= y <= y1, k
+ still = [k for k in range(N) if record['dx_px'][k] == 0 and record['dy_px'][k] == 0]
+ for k in still:
+ assert ledger['jacobian_min'][k] == 1.0 and ledger['pressed_px'][k] == ledger['outside_moved_px'][k] == 0
+
+
+# ---------------------------------------------------------------- the same band on every path
+
+def test_the_frames_are_banded_as_the_strip_cut_from_them(tmp_path):
+ src = frames_dir(tmp_path/'cycle-frames')
+ frames = [frame(k) for k in range(N)]
+ loop_dir, meta = cut(tmp_path, frames)
+ left, top = meta['source_rect'][:2]
+ region = (TORSO[0]-left, TORSO[1]-top, 16.0, 20.0)
+ args = ['video-sway', '--frames', str(src), '--region', text((TORSO[0], TORSO[1], 16.0, 20.0)), '--fps', '24', '--on-fold', 'lower']
+ assert cli.main([*args, '--out', str(tmp_path/'plain')]) == 0
+ assert cli.main([*args, '--out', str(tmp_path/'swayed'), '--band', 'auto', '--band-up', '0.4']) == 0
+ out = tmp_path/'swayed'
+ assert sum(rgba(out/name).tobytes() != rgba(tmp_path/'plain'/name).tobytes() for name in FILES) > N//2
+ strip_record = sway.sway_loop(loop_dir, [region], on_fold='lower', band='auto', band_up=(0.4, 'auto'))
+ strip, w = rgba(loop_dir/'walk.strip.png'), meta['w']
+ for k, name in enumerate(FILES):
+ with Image.open(out/name) as im:
+ cell = as_strip_cell(im.convert('RGBA'), meta['source_rect'])
+ assert np.array_equal(cell, strip[:, k*w:(k+1)*w]), f'cell {k} differs from the strip path'
+ record = json.loads((out/'sway.json').read_text())
+ for key in ('gain', 'dx_px', 'dy_px', 'reach_px', 'fold', 'carry_basis'):
+ assert record[key] == strip_record[key], key
+ # One answer, but for the ledger's places, which are each one's own pixels (a frame's, a cell's of the strip).
+ assert {k: v for k, v in record['band'].items() if k != 'ledger'} == {k: v for k, v in strip_record['band'].items() if k != 'ledger'}
+
+
+def test_a_turned_loop_banded_on_the_cuts_reading_is_the_cuts_banded_sway_cell_for_cell(origin, tmp_path):
+ o, read_on, followed = origin
+ banded = sway.sway_loop(shutil.copytree(o, tmp_path/'banded'), [chest(o)], on_fold='lower', band='auto')
+ loop_dir = aligned(o, tmp_path/'turned')
+ turned = meta_of(loop_dir)['cycle_align']['turned_by']
+ result = sway.sway_loop(loop_dir, [chest(o)], on_fold='lower', read_on=read_on, band='auto')
+ moved, reference, plain = cells_of(loop_dir), cells_of(tmp_path/'banded'), cells_of(followed)
+ n = len(reference)
+ assert sum(not np.array_equal(reference[k], plain[k]) for k in range(n)) > n//2 # the band moves the part otherwise
+ assert all(np.array_equal(moved[k], reference[(k+turned) % n]) for k in range(n))
+ assert result['read_on']['relation'] == 'transported' and result['carry_basis'] == OWN_PIXELS
+ assert (result['band']['band_px'], result['band']['margin_px']) == (banded['band']['band_px'], banded['band']['margin_px'])
+ cut_carry, turned_carry = banded['band']['carry']['cells'], result['band']['carry']['cells']
+ assert [turned_carry[k][0]['px'] for k in range(n)] == [cut_carry[(k+turned) % n][0]['px'] for k in range(n)]