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.pyindex 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 rilayer'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 itsown; 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 annotationsimport argparse+import dataclassesimport hashlibimport ioimport 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 counteddef 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[floafor 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, fbyte — 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, freturn 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 alonegain_across: float | None = None # the gain across asked; None: --gain, across as downbreath: 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@propertydef 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, freraise 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: floaif 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 centredef 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), weightsdef 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, *, vreturn 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, *, vgains, 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, *, vif all(held):k = radii.index(max(radii)) # the largest folds at the largest gain: if it is held, every region isevery = 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 = Noneif 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 notesdef _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.metastrip_path = request.strip_pathsource = request.source_path@@ -1083,7 +1603,9 @@ def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fpgain: 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 theirown 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, ...]], *, fpregions are read on it and not on the first frame: each frame's body is read from it and the regions carriedfrom 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 0diff --git a/sprite_gen/video/sway_inspect.py b/sprite_gen/video/sway_inspect.pyindex 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 toodef _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.pyindex 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) == ownassert {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.pynew file mode 100644index 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)]