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): --hold-mask keeps pixels as they are while a band moves its regions round them — the mask carried by its own pixels and grown, its soft edge and air kept, every read headed into them stopped short and sloped, never read backwards; off, the band is f236b58's byte for byte

Soohong Kimb86cdf9a7e33
diff --git a/sprite_gen/video/sway.py b/sprite_gen/video/sway.py
index 3cd2a65..9264ba3 100644
--- a/sprite_gen/video/sway.py
+++ b/sprite_gen/video/sway.py
@@ -109,6 +109,21 @@ the cell it was read on are looked for in each cell within CARRY_SEARCH px of wh
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.
+
+`--hold-mask` (with `--band`; off by default, and off nothing of it is read or written) holds pixels the band moves
+round: an arm that hangs over the part, a dress below it. The mask is a PNG drawn on the cell the regions were read on,
+each of its 8-connected pieces carried into every cell by its own solid pixels as a band carries a region (`carry_mask`;
+by the lay where that is uncertain, named) and grown by HOLD_GROW px for what that carry may be off by; or a folder of
+one mask per cell, held as given. The move is not changed. In every cell the mask, the pixels not opaque within the
+move's reach and HOLD_EDGE px of it (its soft edge, the half-clear rim of a gap beside it) and the clear pixels as near
+(the air) keep their bytes. Every other pixel is read as without the mask, but a read headed into what is kept stops
+short of it (`free_back`): it goes back f = min(s, h) px of its move s, h HOLD_SLOPE of how far it could go, lowered
+until it rises by at most HOLD_SLOPE a px every way, and the gap the part leaves is drawn from the part stretched in
+order, never read backwards: a read takes at least the move's own least area or 1 − HOLD_SLOPE of the source's,
+whichever is less (`read_share`; read between neighbours, 1 − HOLD_SLOPE·√2). A read that still takes a kept pixel is
+read from the others, or walked back further. The record holds the mask, the carry of each piece in every cell and a
+ledger per cell (`hold_ledger`): what was kept, what was read short, and the pixels whose read takes the source
+backwards, read off the move each read took.
"""
from __future__ import annotations
@@ -181,6 +196,15 @@ 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
+# A hold mask (`--hold-mask`) under a band: the pixels it holds, carried by their own pixels, keep their bytes with their
+# soft edge and the air beside them; a read headed into them takes a share of its move that rises no faster than HOLD_SLOPE.
+HOLD_POLICY = "own-pixels-grown/kept-edge-air/read-short-sloped/1"
+HOLD_GROW = 3 # px (4-neighbour steps) a mask carried from the cell it was drawn on is grown by: what its carry may be off by
+HOLD_EDGE = 2 # px past the move's reach (4-neighbour steps) round the held pixels: what is not opaque there is held, what is clear kept
+HOLD_MARGIN = 1 # px (8-neighbour steps): a read stops short of the kept pixels by as much, unless it is already that near
+HOLD_SLOPE = 0.5 # of a px: how much more of its move a read takes a px further any way (across, down or both), at most
+HOLD_ROUND = 1 # px each way the share of a read is taken at its least over, then averaged over (0: as found)
+HOLD_STEPS = 16 # a read whose four pixels still take a kept one walks back a 1/HOLD_STEPS of its move at a time
def parse_region(text: str) -> tuple[float, ...]:
@@ -760,39 +784,51 @@ def carry_own(base: Image.Image, cells: list[Image.Image], regions: list[tuple[f
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):
+ entries = carry_mask(whole, cells, cell_wholes, mask, base_shift, lays, base_index,
+ "no solid pixel of the cell it was read on is under it")
+ for k in range(len(cells)):
out[k].append(entries[k])
return out
+def carry_mask(whole: np.ndarray, cells: list[Image.Image], cell_wholes: dict[int, np.ndarray], mask: np.ndarray,
+ base_shift: tuple[float, float], lays: list[tuple[float, float]], base_index: int | None,
+ empty: str) -> dict[int, dict[str, Any]]:
+ """Per cell, where the pixels of `whole` (`_whole_premultiplied` of the cell they were read on, carried there by
+ `base_shift`) under `mask` are (`carry_match`), as `carry_own` carries a region: in the loop's order from `base_index`,
+ each cell around where the cell before had them, or around its lay; by the lay where that is uncertain, or where the
+ mask holds no pixel (`empty` says why). `cell_wholes` keeps each cell's `_whole_premultiplied` once read."""
+ n = len(cells)
+ order = list(range(n)) if base_index is None else [(base_index + i) % n for i in range(1, n)]
+ 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": empty}
+ 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)
+ return entries
+
+
@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
@@ -943,6 +979,7 @@ class Ask:
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
+ hold: Hold | None = None # pixels a band moves round and leaves as they are (`--hold-mask`); None: none
@property
def across(self) -> float:
@@ -958,10 +995,11 @@ def read_ask(regions: list[tuple[float, ...]], *, gain: float | None = None, fre
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, band: float | str | None = None, band_margin: float | str | None = None,
- band_up: tuple[float, float | str] | str | None = None, verb: str = VERB) -> Ask:
+ band_up: tuple[float, float | str] | str | None = None, hold_mask: Path | 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. `band` (px or AUTO; None: off) moves each region as one
- mass, `band_margin` and `band_up` shaping it."""
+ mass, `band_margin` and `band_up` shaping it, and `hold_mask` (a PNG or a folder of them; None: off) holds pixels
+ the band moves round."""
# 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.
@@ -997,8 +1035,11 @@ def read_ask(regions: list[tuple[float, ...]], *, gain: float | None = None, fre
if not 0 <= stretch_floor < 1: # a NaN is neither
raise SystemExit(f"{verb}: --stretch-floor is the least area a moved pixel keeps, at least 0 and under 1; got {stretch_floor:g}")
breath = None if breathe is None else read_breath(breathe, lag, verb=verb)
+ shaped = _read_band(regions, band, band_margin, band_up, stretch_floor, verb)
+ if hold_mask is not None and shaped is None:
+ raise SystemExit(f"{verb}: --hold-mask keeps pixels as they are while a band moves its regions round them; it needs --band")
return Ask(regions, gain, freq, zeta, on_fold, None if read_on is None else str(read_on), stretch_floor, gain_across,
- breath, _read_band(regions, band, band_margin, band_up, stretch_floor, verb))
+ breath, shaped, None if hold_mask is None else read_hold(hold_mask, verb))
def _read_band(regions: list[tuple[float, ...]], band: float | str | None, margin: float | str | None,
@@ -1047,7 +1088,8 @@ def read_request(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: floa
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, band: float | str | None = None,
- band_margin: float | str | None = None, band_up: tuple[float, float | str] | str | None = None) -> Request:
+ band_margin: float | str | None = None, band_up: tuple[float, float | str] | str | None = None,
+ hold_mask: Path | None = None) -> Request:
loop_dir = loop_dir.expanduser().resolve()
metas = sorted(loop_dir.glob("*.strip.json"))
if len(metas) != 1:
@@ -1060,7 +1102,7 @@ def read_request(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: floa
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, band=band, band_margin=band_margin, band_up=band_up,
- verb=verb)
+ hold_mask=hold_mask, verb=verb)
return Request(loop_dir, name, meta_path, meta_bytes, meta, ask)
@@ -1095,6 +1137,7 @@ class Answer:
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
+ hold: Held | None = None # what the hold mask comes to (`--hold-mask`); None: none
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
@@ -1113,8 +1156,29 @@ class Answer:
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()
+ if self.hold is not None:
+ return (self.hold.drawn[k] if k in self.hold.drawn else self.held_cell(k)[0]).copy()
return _draw(self.cells[k], lambda xx, yy: self.band_field(k, xx, yy)[0])
+ def held_cell(self, k: int) -> tuple[Image.Image, dict[str, np.ndarray]]:
+ """Under a hold mask, cell k drawn round it (`draw_held`), what it keeps there — the mask's pixels (`mask`), the
+ held pixels and the air (`hold_sets`) — and how each pixel was read. Kept in `Held.drawn`."""
+ assert self.hold is not None
+ cell = self.cells[k]
+ w, h = cell.size
+ yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+ mask = self.hold.mask_in(k)
+ held, air = hold_sets(mask, cell, self.hold.edge)
+ field = self.band_field(k, xx, yy)[0]
+ if field is None or all(dx == 0 and dy == 0 for _, (dx, dy) in self.moves_in(k)):
+ still = np.zeros((h, w))
+ drawn, read = cell.copy(), {"share": np.ones((h, w)), "readers": still > 0, "renormalised": still > 0,
+ "walked": still > 0, "read_x": still, "read_y": still}
+ else:
+ drawn, read = draw_held(cell, field, held, air)
+ self.hold.drawn.setdefault(k, drawn)
+ return drawn, {"mask": mask, "held": held, "air": air, **read}
+
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`)."""
@@ -1158,7 +1222,8 @@ class Answer:
| ({} 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()})
+ | ({} if self.band is None else {"band": self.band_record()}) \
+ | ({} if self.hold is None else {"hold": self.hold_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,
@@ -1166,16 +1231,7 @@ class Answer:
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
-
+ carried = _carried_record
return {
"policy": BAND_POLICY, "asked": band.asked.asked(), "reach_px": round(band.reach, 4),
"band_px": band.band, "margin_px": band.margin,
@@ -1188,6 +1244,34 @@ class Answer:
"ledger": band.ledger,
}
+ def hold_record(self) -> dict[str, Any]:
+ """The hold mask as the record holds it (`--hold-mask`): what was asked, how its pieces are grown, kept round and
+ read round, each piece's size and box on the cell it was drawn on, where each is carried in every cell and from
+ what (None where a mask is given for each cell), the cells carried by the lay and why, and the ledger."""
+ assert self.hold is not None
+ hold, per_cell = self.hold, self.hold.asked.per_cell
+ return {
+ "policy": HOLD_POLICY, "asked": hold.asked.asked(), "grow_px": None if per_cell else HOLD_GROW, "edge_px": hold.edge,
+ "margin_px": HOLD_MARGIN, "slope": HOLD_SLOPE, "round_px": HOLD_ROUND, "steps": HOLD_STEPS,
+ "pieces": [{"px": int(piece.sum()), "box": _box(piece)} for piece in hold.pieces],
+ "carry": None if per_cell else {"search_px": CARRY_SEARCH,
+ "cells": [[_carried_record(entry) for entry in cell] for cell in hold.carried]},
+ "lay": [{"cell": k, "piece": i, "why": entry["why"]} for k, cell in enumerate(hold.carried)
+ for i, entry in enumerate(cell) if entry["from"] == "lay"],
+ "ledger": hold.ledger,
+ }
+
+
+def _carried_record(entry: dict[str, Any]) -> dict[str, Any]:
+ """A carry (`carry_mask`'s entry) as the record holds it."""
+ 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
+
def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str = VERB,
strip_sha256: str | None = None) -> Answer:
@@ -1353,20 +1437,28 @@ def solve_cells(ask: Ask, cells: list[Image.Image], frame_ms: float | None, *, v
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)
+ banded = _banded(answer, shaped, reach_requested, carried, steepest, verb)
+ return banded if ask.hold is None else _held(banded, None if reference is None else reference[0], 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
+ base, base_shift, base_index, lays = _band_base(answer, reference)
+ return carry_own(base, answer.cells, answer.ask.regions, base_shift, lays, base_index=base_index)
+
+
+def _band_base(answer: Answer, reference: Image.Image | None) -> tuple[Image.Image, tuple[float, float], int | None, list[tuple[float, float]]]:
+ """The cell the regions were read on, as a band carries from it (`_carry_band`): the picture, how it lies from cell 0,
+ which of the cells it is (None: the reference frame, none of them), and every cell's lay."""
+ cells = answer.cells
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)
+ return reference, (0.0, 0.0), None, lays
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)
+ return cells[base], lays[base], base, lays
def band_steepest(regions: list[tuple[float, ...]], shapes: list[Any], carried: list[list[dict[str, Any]]],
@@ -1514,6 +1606,412 @@ def band_notes(record: dict[str, Any], verb: str = VERB, at: str = f"{loop_mod.S
return notes
+@dataclass(frozen=True, eq=False)
+class Hold:
+ """A hold mask asked (`--hold-mask`): one PNG drawn on the cell the regions were read on, or a folder of PNGs, one per
+ cell in name order; a pixel is held where the PNG's alpha is ALPHA_SOLID or more — where it has no alpha, where it is
+ that light. The sha256 of each file's bytes."""
+
+ masks: list[np.ndarray]
+ sha256: list[str]
+ per_cell: bool
+
+ def asked(self) -> dict[str, Any]:
+ return {"per_cell": self.per_cell, "sha256": self.sha256 if self.per_cell else self.sha256[0]}
+
+
+def _mask_of(image: Image.Image) -> np.ndarray:
+ """The pixels a hold mask's PNG holds: alpha ALPHA_SOLID or more, or, where the PNG has no alpha, that light."""
+ if image.mode in ("RGBA", "LA", "PA") or "transparency" in image.info:
+ return np.asarray(image.convert("RGBA").getchannel("A")) >= ALPHA_SOLID
+ return np.asarray(image.convert("L")) >= ALPHA_SOLID
+
+
+def read_hold(path: Path, verb: str = VERB) -> Hold:
+ """A hold mask (`--hold-mask`) read: a PNG, or a folder of PNGs, one per cell, in name order. A single mask that holds
+ no pixel is refused; a cell of a folder may hold none."""
+ path = Path(path).expanduser()
+ files = sorted(path.glob("*.png")) if path.is_dir() else [path]
+ if not files:
+ raise SystemExit(f"{verb}: --hold-mask {path}: a folder of masks with no PNG in it")
+ masks, digests = [], []
+ for file in files:
+ try:
+ data = file.read_bytes()
+ with Image.open(io.BytesIO(data)) as image:
+ masks.append(_mask_of(image))
+ except (OSError, ValueError) as exc:
+ raise SystemExit(f"{verb}: --hold-mask {file}: not read ({exc})") from exc
+ digests.append(hashlib.sha256(data).hexdigest())
+ if not any(mask.any() for mask in masks):
+ raise SystemExit(f"{verb}: --hold-mask {path}: holds no pixel (alpha {ALPHA_SOLID} or more, or that light where it has "
+ "no alpha)")
+ return Hold(masks, digests, path.is_dir())
+
+
+def _grow4(mask: np.ndarray, steps: int) -> np.ndarray:
+ """`mask` grown by `steps` 4-neighbour steps (a diamond), nothing carried round the cell's edge."""
+ out = mask.copy()
+ for _ in range(steps):
+ p = np.pad(out, 1)
+ out = p[1:-1, 1:-1] | p[:-2, 1:-1] | p[2:, 1:-1] | p[1:-1, :-2] | p[1:-1, 2:]
+ return out
+
+
+def _grow8(mask: np.ndarray, steps: int = 1) -> np.ndarray:
+ """`mask` grown by `steps` 8-neighbour steps (a square), nothing carried round the cell's edge."""
+ h, w = mask.shape
+ for _ in range(steps):
+ p, out = np.pad(mask, 1), mask.copy()
+ for dy in range(3):
+ for dx in range(3):
+ out |= p[dy:dy + h, dx:dx + w]
+ mask = out
+ return mask
+
+
+def _pieces(mask: np.ndarray) -> list[np.ndarray]:
+ """`mask`'s 8-connected pieces, in the order of their first pixel row by row."""
+ left, pieces = mask.copy(), []
+ while left.any():
+ y, x = divmod(int(np.argmax(left)), mask.shape[1])
+ piece = np.zeros_like(mask)
+ piece[y, x] = True
+ while True:
+ grown = _grow8(piece) & left
+ if not (grown & ~piece).any():
+ break
+ piece = grown
+ pieces.append(piece)
+ left &= ~piece
+ return pieces
+
+
+def _shifted(mask: np.ndarray, shift: tuple[float, float]) -> np.ndarray:
+ """`mask` moved by `shift` (across, down): every pixel the moved mask covers some of, the whole-pixel moves on either
+ side of it joined, nothing carried round the cell's edge."""
+ h, w = mask.shape
+ out = np.zeros_like(mask)
+ for sx in {math.floor(shift[0]), math.ceil(shift[0])}:
+ for sy in {math.floor(shift[1]), math.ceil(shift[1])}:
+ if abs(sx) >= w or abs(sy) >= h:
+ continue
+ src = mask[max(0, -sy):h - max(0, sy), max(0, -sx):w - max(0, sx)]
+ out[max(0, sy):max(0, sy) + src.shape[0], max(0, sx):max(0, sx) + src.shape[1]] |= src
+ return out
+
+
+@dataclass(frozen=True, eq=False)
+class Held:
+ """What a hold mask comes to on the cells (`--hold-mask`): the mask in its 8-connected pieces on the cell it was drawn
+ on, which lies `base_shift` from cell 0, each piece carried into every cell by its own pixels (`carried`, per cell and
+ piece, as `carry_mask` carries it; none where a mask is given for each cell), how far round the held pixels their soft
+ edge and the air beside them reach (`edge`, 4-neighbour steps), and the ledger (`hold_ledger`). Each cell is drawn once
+ (`drawn`)."""
+
+ asked: Hold
+ pieces: list[np.ndarray]
+ base_shift: tuple[float, float]
+ carried: list[list[dict[str, Any]]]
+ edge: int
+ ledger: dict[str, Any] | None = None
+ drawn: dict[int, Image.Image] = dataclasses.field(default_factory=dict)
+
+ def mask_in(self, k: int) -> np.ndarray:
+ """The mask's pixels in cell k: the mask given for it, or each piece carried there and the whole grown by HOLD_GROW
+ px (4-neighbour steps), what a piece's carry may be off by where the part it holds changes its shape."""
+ if self.asked.per_cell:
+ return self.asked.masks[k]
+ carried = np.zeros_like(self.asked.masks[0])
+ for piece, entry in zip(self.pieces, self.carried[k]):
+ carried |= _shifted(piece, (entry["px"][0] - self.base_shift[0], entry["px"][1] - self.base_shift[1]))
+ return _grow4(carried, HOLD_GROW)
+
+
+def hold_sets(mask: np.ndarray, cell: Image.Image, edge: int) -> tuple[np.ndarray, np.ndarray]:
+ """What a hold keeps in a cell: the held pixels — the mask and every pixel not opaque (alpha over 0, under 255) within
+ `edge` 4-neighbour steps of it, its soft edge and the half-clear rim of a gap beside it — and the air, the clear pixels
+ within as far. Both keep their bytes; no pixel solid in the cell reads either, no clear one the held."""
+ alpha = np.asarray(cell.getchannel("A"))
+ near = _grow4(mask, edge) & ~mask
+ return mask | (near & (alpha > 0) & (alpha < 255)), near & (alpha == 0)
+
+
+def _bilinear(a: np.ndarray, sx: np.ndarray, sy: np.ndarray) -> np.ndarray:
+ """`a` (one value a pixel) read at (sx, sy) as `_sample` reads a cell."""
+ h, w = a.shape
+ x0 = np.clip(np.floor(sx).astype(int), 0, w - 2)
+ y0 = np.clip(np.floor(sy).astype(int), 0, h - 2)
+ fx, fy = np.clip(sx - x0, 0, 1), np.clip(sy - y0, 0, 1)
+ return (a[y0, x0] * (1 - fx) + a[y0, x0 + 1] * fx) * (1 - fy) + (a[y0 + 1, x0] * (1 - fx) + a[y0 + 1, x0 + 1] * fx) * fy
+
+
+def _mean_along(a: np.ndarray, r: int, axis: int) -> np.ndarray:
+ """The mean over 2·r + 1 along `axis`, the edge value carried past the cell's edge."""
+ pad = [(0, 0), (0, 0)]
+ pad[axis] = (r + 1, r)
+ c = np.cumsum(np.pad(a, pad, mode="edge"), axis=axis)
+ if axis == 0:
+ return (c[2 * r + 1:] - c[:-(2 * r + 1)]) / (2 * r + 1)
+ return (c[:, 2 * r + 1:] - c[:, :-(2 * r + 1)]) / (2 * r + 1)
+
+
+def _least_round(a: np.ndarray, r: int) -> np.ndarray:
+ """The least of `a` over each pixel's square of side 2·r + 1 (the edge value past the cell's edge)."""
+ out = a
+ for axis in (0, 1):
+ p = np.pad(out, [(r, r) if i == axis else (0, 0) for i in range(2)], mode="edge")
+ n = out.shape[axis]
+ out = np.min([np.take(p, range(i, i + n), axis=axis) for i in range(2 * r + 1)], axis=0)
+ return out
+
+
+def free_back(kept: np.ndarray, way: tuple[float, float], far: float) -> np.ndarray:
+ """Per pixel, how far (px) a read can go back against `way` (the unit vector the cell's part moves along) before the
+ four pixels it reads (`_sample`'s) take a `kept` pixel, or one within HOLD_MARGIN px of them (8-neighbour steps) where
+ the pixel is not itself that near: followed an eighth of a pixel at a time, `far` where it does not come to one within
+ `far`. Along a line the way the part moves, it rises by at most a px a px and falls past each kept pixel."""
+ h, w = kept.shape
+ near = _grow8(kept, HOLD_MARGIN)
+ free = np.full((h, w), float(far))
+ # Only a pixel `far` or less along `way` from the margin can come to it; between two whole steps a read's four pixels
+ # may pair the one step's column with the other's row, a pixel off either.
+ swept = near.copy()
+ for i in range(1, math.ceil(far) + 1):
+ swept |= _shifted(near, (i * way[0], i * way[1]))
+ ys, xs = np.nonzero(_grow8(swept) & ~kept)
+ if not len(ys):
+ return free
+ hard, soft = kept.astype(np.float64), near.astype(np.float64)
+ own = soft[ys, xs] # 1 where the pixel is itself within the margin: then only the kept pixels stop it
+ found = np.full(len(ys), float(far))
+ left = np.arange(len(ys))
+ for i in range(1, math.ceil(8 * far) + 1):
+ tau = min(i / 8, far)
+ sx, sy = xs[left] - tau * way[0], ys[left] - tau * way[1]
+ stops = (_bilinear(hard, sx, sy) > 0) | (_bilinear(soft, sx, sy) > own[left] + 1e-9)
+ found[left[stops]] = (i - 1) / 8
+ left = left[~stops]
+ if not len(left):
+ break
+ free[ys, xs] = found
+ return free
+
+
+def _sloped(a: np.ndarray, slope: float) -> np.ndarray:
+ """`a` lowered until no pixel is more than `slope` over any of its 8 neighbours: per pixel the least of a(q) + slope
+ times q's distance in whole steps across or down, whichever is more (the edge value carried past the cell's edge)."""
+ for _ in range(sum(a.shape)):
+ p = np.pad(a, 1, mode="edge")
+ rows = np.minimum(np.minimum(p[:-2], p[1:-1]), p[2:])
+ lowered = np.minimum(a, np.minimum(np.minimum(rows[:, :-2], rows[:, 1:-1]), rows[:, 2:]) + slope)
+ if np.array_equal(lowered, a):
+ break
+ a = lowered
+ return a
+
+
+def read_share(free: np.ndarray, size: np.ndarray) -> np.ndarray:
+ """Per pixel, the share of its move (`size` px long) a read takes round a hold: the read goes back f = min(size, h) px,
+ h HOLD_SLOPE of `free` (`free_back`), taken at its least within HOLD_ROUND px each way and then averaged over as far,
+ and lowered until it is nowhere more than HOLD_SLOPE over a neighbour (`_sloped`); 1 where f is the whole move, so
+ those pixels read as without the hold."""
+ # Within a cell every move is s·ô, one way ô (the groups' offsets are one motion times their gains), so the read
+ # p − f·ô takes 1 − ∂ô f of the source's area, and 1 − (ôx·Dx f + ôy·Dy f) read between neighbours as `jacobian` reads
+ # it: h rises by at most κ (HOLD_SLOPE) a px every way, so where f = h a read takes at least 1 − κ (between
+ # neighbours 1 − κ(|ôx| + |ôy|) ≥ 1 − κ√2), and where f = s the move's own least area — over 0 wherever the move does
+ # not fold; where f turns from the one to the other the two mix between neighbours, and the ledger reads those
+ # (`read_turn_folded_px`, `read_turn_least`).
+ reach = HOLD_SLOPE * free
+ if HOLD_ROUND:
+ r = HOLD_ROUND
+ reach = _mean_along(_mean_along(_least_round(reach, r), r, 0), r, 1)
+ reach = _sloped(reach, HOLD_SLOPE)
+ return np.where(reach >= size, 1.0, reach / np.maximum(size, 1e-12))
+
+
+def draw_held(cell: Image.Image, field: tuple[np.ndarray, np.ndarray, np.ndarray], held: np.ndarray,
+ air: np.ndarray) -> tuple[Image.Image, dict[str, np.ndarray]]:
+ """`cell` moved by `field` (`_draw`'s: covered, across, down) round what a hold keeps (`hold_sets`: the held pixels and
+ the air beside them). The field is as it is; the held pixels and the air keep their bytes; every other pixel is read
+ as `_draw` reads it, but only as far back along its move as `read_share` lets it, which stops short of every kept
+ pixel. A read whose four pixels still take one it may not (a solid pixel a kept one, a clear pixel a held one) is read
+ from the others where they are half its weight or more (`renormalised`), else walked back a 1/HOLD_STEPS of its move
+ at a time until they are (`walked`). Where every read takes its whole move and no kept pixel the cell is `_draw`'s,
+ byte for byte. Also returns, per pixel, the share of its move each read took (`share`), the pixels read (`readers`)
+ and the move each read took (`read_x`, `read_y`; 0 on what is kept and on what does not move)."""
+ 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)
+ inside, move_x, move_y = field
+ size = np.hypot(move_x, move_y)
+ pm = src.copy()
+ pm[..., :3] *= pm[..., 3:4] / 255
+ kept = held | air
+ solid = src[..., 3] >= ALPHA_SOLID
+ readers = inside & ~kept & (size > 0)
+ share = np.ones((h, w))
+ if readers.any():
+ y, x = divmod(int(np.argmax(np.where(readers, size, -1))), w)
+ way = (float(move_x[y, x] / size[y, x]), float(move_y[y, x] / size[y, x]))
+ share = np.where(readers, read_share(free_back(kept, way, float(size[y, x]) / HOLD_SLOPE + 1), size), 1.0)
+ sx, sy = xx - share * move_x, yy - share * move_y
+ moved = _sample(pm, sx, sy)
+ x0 = np.clip(np.floor(sx).astype(int), 0, w - 2)
+ y0 = np.clip(np.floor(sy).astype(int), 0, h - 2)
+ fx, fy = np.clip(sx - x0, 0, 1), np.clip(sy - y0, 0, 1)
+ off = np.zeros((h, w), bool)
+ for oy, ox, weight in ((0, 0, (1 - fx) * (1 - fy)), (0, 1, fx * (1 - fy)), (1, 0, (1 - fx) * fy), (1, 1, fx * fy)):
+ off |= (weight > 0) & np.where(solid, kept[y0 + oy, x0 + ox], held[y0 + oy, x0 + ox])
+ off &= readers
+ renormalised, walked = np.zeros((h, w), bool), np.zeros((h, w), bool)
+ if off.any():
+ ys, xs = np.nonzero(off)
+ of_solid = solid[ys, xs]
+ t = share[ys, xs].copy()
+ left, first = np.arange(len(ys)), True
+ while len(left):
+ ly, lx = ys[left], xs[left]
+ px, py = lx - t[left] * move_x[ly, lx], ly - t[left] * move_y[ly, lx]
+ ax0 = np.clip(np.floor(px).astype(int), 0, w - 2)
+ ay0 = np.clip(np.floor(py).astype(int), 0, h - 2)
+ ax, ay = np.clip(px - ax0, 0, 1), np.clip(py - ay0, 0, 1)
+ total, taken = np.zeros((len(left), 4)), np.zeros(len(left))
+ for oy, ox, weight in ((0, 0, (1 - ax) * (1 - ay)), (0, 1, ax * (1 - ay)), (1, 0, (1 - ax) * ay), (1, 1, ax * ay)):
+ tap_y, tap_x = ay0 + oy, ax0 + ox
+ ok = np.where(of_solid[left], ~kept[tap_y, tap_x], ~held[tap_y, tap_x]) * weight
+ total += pm[tap_y, tap_x] * ok[:, None]
+ taken += ok
+ done = taken >= 0.5
+ moved[ly[done], lx[done]] = total[done] / taken[done][:, None]
+ (renormalised if first else walked)[ly[done], lx[done]] = True
+ share[ly[done], lx[done]] = t[left[done]]
+ left, first = left[~done], False
+ t[left] = np.maximum(t[left] - 1 / HOLD_STEPS, 0.0) # at 0 a pixel reads itself, which it may
+ alpha = np.clip(np.round(moved[..., 3:4]), 0, 255)
+ moved[..., :3] = np.where(alpha > 0, moved[..., :3] * 255 / np.maximum(moved[..., 3:4], 1e-3), 0)
+ moved[..., 3:4] = alpha
+ out = np.where((inside & ~kept)[..., None], np.clip(np.round(moved), 0, 255), src).astype(np.uint8)
+ taken_x, taken_y = np.where(readers, share * move_x, 0.0), np.where(readers, share * move_y, 0.0)
+ return Image.fromarray(out, "RGBA"), {"share": share, "readers": readers, "renormalised": renormalised, "walked": walked,
+ "read_x": taken_x, "read_y": taken_y}
+
+
+def _held(answer: Answer, reference: Image.Image | None, verb: str) -> Answer:
+ """`answer` round its hold mask (`--hold-mask`): one mask, drawn on the cell the regions were read on (`_band_base`),
+ in its pieces, each carried into every cell by its own solid pixels there as a band carries a region (`carry_mask`),
+ or a mask for each cell as given; and the ledger of every cell (`hold_ledger`)."""
+ hold, cells = answer.ask.hold, answer.cells
+ assert hold is not None
+ w, h = cells[0].size
+ for mask in hold.masks:
+ if mask.shape != (h, w):
+ raise SystemExit(f"{verb}: --hold-mask is {mask.shape[1]}x{mask.shape[0]}, the cells are {w}x{h}: a mask is drawn on "
+ "a cell, pixel for pixel")
+ if hold.per_cell and len(hold.masks) != len(cells):
+ raise SystemExit(f"{verb}: --hold-mask holds {len(hold.masks)} masks and there are {len(cells)} cells: a folder gives "
+ "one mask per cell, in name order")
+ edge = math.ceil(answer.reach) + HOLD_EDGE
+ if hold.per_cell:
+ held = Held(hold, [], (0.0, 0.0), [], edge)
+ else:
+ base, base_shift, base_index, lays = _band_base(answer, reference)
+ solid = np.asarray(base.getchannel("A")) >= ALPHA_SOLID
+ whole, cell_wholes = _whole_premultiplied(base), {}
+ pieces = _pieces(hold.masks[0])
+ carried: list[list[dict[str, Any]]] = [[] for _ in cells]
+ for piece in pieces:
+ entries = carry_mask(whole, cells, cell_wholes, piece & solid, base_shift, lays, base_index,
+ "no solid pixel of the cell it was drawn on is under it")
+ for k in range(len(cells)):
+ carried[k].append(entries[k])
+ held = Held(hold, pieces, (float(base_shift[0]), float(base_shift[1])), carried, edge)
+ answer = dataclasses.replace(answer, hold=held)
+ return dataclasses.replace(answer, hold=dataclasses.replace(held, ledger=hold_ledger(answer)))
+
+
+def hold_ledger(answer: Answer) -> dict[str, Any]:
+ """Per cell, what a hold kept and how the reads round it went (`--hold-mask`), each count a list over the cells with its
+ largest beside it:
+ - `held_px`, `soft_px`, `air_px`: the mask's pixels, the pixels not opaque held round it, the clear ones kept round it;
+ - `short_px`: pixels read short of their move; `renormalised_px`, `walked_px`: those whose four pixels still took a kept
+ one, read from the others or walked back further (`draw_held`);
+ - `read_folded_px`: opaque pixels of the drawn cell, not kept nor beside a kept one (4-neighbours), whose read takes 0
+ or less of the source's area (`jacobian` of the move each read took: the source read backwards), and
+ `read_folded_edge_px` those beside a kept one, where the part moves under it and the read is meant to jump;
+ - `read_least`: the least area a read of the first kind takes, and where (area, x, y; None where none moves);
+ - `read_turn_folded_px` and `read_turn_least`: the same for those of the first kind where the read turns from the
+ whole move to the share round the hold (`read_share`): some of the pixel and its 4-neighbours read the whole move
+ and some less, the two mixed between neighbours, where the bound on the read's area does not hold."""
+ keys = ("held_px", "soft_px", "air_px", "short_px", "renormalised_px", "walked_px", "read_folded_px", "read_folded_edge_px",
+ "read_least", "read_turn_folded_px", "read_turn_least")
+ ledger: dict[str, list[Any]] = {key: [] for key in keys}
+ for k in range(len(answer.cells)):
+ drawn, read = answer.held_cell(k)
+ mask, held, air = read["mask"], read["held"], read["air"]
+ kept = held | air
+ h, w = mask.shape
+ area = np.ones((h, w))
+ area[1:-1, 1:-1] = jacobian(read["read_x"], read["read_y"])
+ counted = np.zeros((h, w), bool)
+ counted[1:-1, 1:-1] = True
+ counted &= (np.asarray(drawn.getchannel("A")) >= ALPHA_SOLID) & ~kept
+ beside = _grow4(kept, 1)
+ folded = counted & (area <= 0)
+ ledger["held_px"].append(int(mask.sum()))
+ ledger["soft_px"].append(int((held & ~mask).sum()))
+ ledger["air_px"].append(int(air.sum()))
+ ledger["short_px"].append(int((read["readers"] & (read["share"] < 1)).sum()))
+ ledger["renormalised_px"].append(int(read["renormalised"].sum()))
+ ledger["walked_px"].append(int(read["walked"].sum()))
+ ledger["read_folded_px"].append(int((folded & ~beside).sum()))
+ ledger["read_folded_edge_px"].append(int((folded & beside).sum()))
+ live = counted & ~beside & read["readers"]
+ sp = np.pad(read["share"], 1, mode="edge")
+ around = [read["share"], sp[:-2, 1:-1], sp[2:, 1:-1], sp[1:-1, :-2], sp[1:-1, 2:]]
+ turn = live & (np.minimum.reduce(around) < 1) & (np.maximum.reduce(around) >= 1)
+ ledger["read_turn_folded_px"].append(int((folded & turn).sum()))
+ for key, where in (("read_least", live), ("read_turn_least", turn)):
+ if where.any():
+ y, x = divmod(int(np.argmin(np.where(where, area, np.inf))), w)
+ ledger[key].append([round(float(area[y, x]), 4), x, y])
+ else:
+ ledger[key].append(None)
+ 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 hold_notes(record: dict[str, Any], verb: str = VERB, at: str = f"{loop_mod.SWAY_RECORD}.hold") -> list[str]:
+ """What to say of a hold's record (`--hold-mask`), a line each, as warnings: the cells a piece of the mask was carried
+ by the lay in and why, and the reads round it that took a kept pixel or turned back — in how many cells, up to how many
+ pixels and in which cell, and where in the record (`at`)."""
+ hold, notes = record["hold"], []
+ by_piece: dict[int, list[dict[str, Any]]] = {}
+ for entry in hold["lay"]:
+ by_piece.setdefault(entry["piece"], []).append(entry)
+ for i, entries in sorted(by_piece.items()):
+ whys = "; ".join(f"cell {e['cell']}: {e['why']}" for e in entries)
+ notes.append(f"{verb}: warning: --hold-mask carries its piece {i} by the body's lay in {len(entries)} cells, its own "
+ f"pixels not found surely ({whys}) — {at}.lay")
+ ledger, n = hold["ledger"], len(hold["ledger"]["held_px"])
+ said = {"renormalised_px": "reads took a kept pixel and were read from the others",
+ "walked_px": "reads took a kept pixel and were walked back further",
+ "read_folded_px": "reads take the source backwards (0 or less of its area)"}
+ 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])
+ notes.append(f"{verb}: warning: --hold-mask: {what} in {len(cells)} of {n} cells, up to {ledger[key + '_max']} px (cell "
+ f"{top}) — {at}.ledger.{key}")
+ return notes
+
+
def _keep_floor(ask: Ask, radii: list[float], gains: list[float], held: list[bool],
move: tuple[np.ndarray, np.ndarray], verb: str) -> tuple[list[float], list[bool], dict[str, Any]]:
"""The fold rule's gains (`gains`, 0 where `held`) lowered where a region's move would leave a pixel less than
@@ -1549,10 +2047,11 @@ def sway_loop(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: float |
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,
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]:
+ band_up: tuple[float, float | str] | str | None = None, hold_mask: Path | 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, band=band,
- band_margin=band_margin, band_up=band_up, verb=verb)
+ band_margin=band_margin, band_up=band_up, hold_mask=hold_mask, 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
@@ -1605,7 +2104,7 @@ def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fp
stretch_floor: float | None = None, breathe: Path | None = None, lag: float | None = None,
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]:
+ hold_mask: Path | 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
@@ -1618,7 +2117,7 @@ def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fp
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, band=band, band_margin=band_margin, band_up=band_up,
- verb=verb)
+ hold_mask=hold_mask, 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:
@@ -1733,6 +2232,13 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
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("--hold-mask", type=Path, default=None, metavar="MASK.png|DIR",
+ help="with --band: pixels the band moves round and leaves as they are (an arm hanging over the part, a dress "
+ "below it), a PNG drawn on the cell the regions were read on (alpha, or light where it has none, "
+ f"{ALPHA_SOLID} or more holds), each piece carried into every cell by its own pixels and grown by "
+ f"{HOLD_GROW} px; or a folder of one PNG per cell in name order, held as given. The pixels not opaque round "
+ "it and the air beside it are kept too, and a read headed into them stops short, its share of the move "
+ f"rising by {HOLD_SLOPE:g} a px from them. Off by default")
parser.add_argument("--board", type=Path, help="write a before/after picture at the frames where the part sits lowest and highest")
@@ -1772,7 +2278,7 @@ def run(**kwargs: object) -> int:
"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"), "band": kwargs.get("band"), "band_margin": kwargs.get("band_margin"),
- "band_up": kwargs.get("band_up")}
+ "band_up": kwargs.get("band_up"), "hold_mask": kwargs.get("hold_mask")}
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")
@@ -1791,6 +2297,9 @@ def run(**kwargs: object) -> int:
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)
+ if "hold" in result:
+ for note in hold_notes(result, verb, f"{FRAMES_RECORD} hold" if where == "out" else f"{loop_mod.SWAY_RECORD}.hold"):
+ 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 {})
@@ -1798,6 +2307,9 @@ def run(**kwargs: object) -> int:
| ({"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 {})
+ | ({"hold": {"pieces": len(result["hold"]["pieces"]),
+ "lay_cells": sorted({entry["cell"] for entry in result["hold"]["lay"]}),
+ "read_folded_px_max": result["hold"]["ledger"]["read_folded_px_max"]}} if "hold" in result else {})
| ({"board": result["board"]} if "board" in result else {}), ensure_ascii=False, indent=2))
return 0
diff --git a/tests/video/test_follow_inspect.py b/tests/video/test_follow_inspect.py
index 72c274e..5fa2ae5 100644
--- a/tests/video/test_follow_inspect.py
+++ b/tests/video/test_follow_inspect.py
@@ -453,9 +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)]))
- # 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'}
+ # video-sway's own: its board, the frames path beside the loop directory, the band (`--band`), whose carry by the
+ # region's own pixels the inspection does not read, and the pixels a band leaves as they are (`--hold-mask`)
+ own = {'board', 'frames', 'out', 'fps', 'reference', 'band', 'band_margin', 'band_up', 'hold_mask'}
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_hold.py b/tests/video/test_sway_hold.py
new file mode 100644
index 0000000..ead3483
--- /dev/null
+++ b/tests/video/test_sway_hold.py
@@ -0,0 +1,353 @@
+"""`video-sway --band --hold-mask`: pixels a band moves round and leaves as they are.
+
+A mask drawn on the cell the regions were read on is carried into each cell by its own pixels, and there it, the pixels
+not opaque round it and the clear pixels beside it keep their bytes, whatever part of the figure it holds: an arm that
+hangs over the moving part, a belt below it. Every other pixel is read as the band reads it, but a read headed into what
+is kept stops short, its share of the move rising by HOLD_SLOPE a pixel, so the gap the part leaves is drawn from the part
+in order and no read takes the source backwards — even where the band's own move leaves a pixel almost none of its area.
+Synthetic figures only: the inspection's body with a striped arm over its left side, a half-clear edge beside the arm, a
+clear notch at the waist under it, a belt across its hips and a patch of the torso's own cloth; and the read-on test's
+runner, cut and turned, a mask on its chest's rim.
+
+Each case first reads what a sway writes with and without the mask (its cells, whether it refuses, what it says), so on
+a release without the mask the same input fails on what comes out; the hold's own record and ledger are 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, N, TORSO, W, H, figure, strip_dir, sway as body_sway
+from tests.video.test_follow_read_on import aligned, cells_of as cut_cells, chest as cut_chest, meta_of, origin, origin_once # noqa: F401 (fixtures)
+
+POLICY = 'own-pixels-grown/kept-edge-air/read-short-sloped/1'
+ARM = [(150, 60, 40), (120, 40, 25), (180, 90, 60)] # an arm's fur in stripes 2 px high, redder to the right
+ARM_BOX = (28, 50, 40, 92) # x0, y0, x1, y1 in cell 0, the last pixel's included: over the torso's left side and past it
+SOFT = (150, 60, 40, 160) # a half-clear column beside the arm, over the torso
+NOTCH = (35, 93, 37, 98) # the waist's notch under the arm: clear, its right column half clear
+BELT_BOX = (35, 100, 85, 108) # a belt across the hips, a colour of its own each column
+PATCH_BOX = (74, 94, 80, 97) # a patch of the torso's own cloth: nothing tells one place of it from the next
+FILES = [f'frame-{k:03d}.png' for k in range(N)]
+
+
+def text(region):
+ return ','.join(f'{v:g}' for v in region)
+
+
+def arm_colour(x, y):
+ base = ARM[(y // 2) % 3]
+ return base[0] + 3*(x - ARM_BOX[0]), base[1], base[2]
+
+
+def belt_colour(x, y):
+ return 90 + (x - BELT_BOX[0]), 30 + 10*((y - BELT_BOX[1]) % 3), 140
+
+
+def held_figure(k, n=N):
+ """The inspection's body with an arm, its half-clear edge, the waist's notch and a belt, all carried with the body."""
+ sx, sy = body_sway(k, n)
+ im = figure(k, n)
+ d = ImageDraw.Draw(im)
+ x0, y0, x1, y1 = ARM_BOX
+ for y in range(y0, y1+1):
+ for x in range(x0, x1+1):
+ d.point((x+sx, y+sy), fill=(*arm_colour(x, y), 255))
+ d.line((x1+1+sx, y0+sy, x1+1+sx, y1+sy), fill=SOFT)
+ nx0, ny0, nx1, ny1 = NOTCH
+ d.rectangle((nx0+sx, ny0+sy, nx1-1+sx, ny1+sy), fill=(0, 0, 0, 0))
+ d.line((nx1+sx, ny0+sy, nx1+sx, ny1+sy), fill=(*TORSO[:3], 190))
+ bx0, by0, bx1, by1 = BELT_BOX
+ for y in range(by0, by1+1):
+ for x in range(bx0, bx1+1):
+ d.point((x+sx, y+sy), fill=(*belt_colour(x, y), 255))
+ return im
+
+
+def boxed(box, shift=(0, 0)):
+ """A cell's pixels in a box (x0, y0, x1, y1, the last pixel's included), moved by `shift`."""
+ m = np.zeros((H, W), bool)
+ x0, y0, x1, y1 = box
+ m[y0+shift[1]:y1+1+shift[1], x0+shift[0]:x1+1+shift[0]] = True
+ return m
+
+
+def mask_png(path, *boxes):
+ """A hold mask drawn on cell 0: opaque white over the boxes, clear elsewhere."""
+ m = np.zeros((H, W), bool)
+ for box in boxes:
+ m |= boxed(box)
+ Image.fromarray(np.where(m[..., None], 255, 0).astype(np.uint8).repeat(4, axis=2), 'RGBA').save(path)
+ return path
+
+
+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 cells_of(loop_dir):
+ strip = np.asarray(Image.open(loop_dir/'walk.strip.png').convert('RGBA'))
+ return [np.ascontiguousarray(strip[:, k*W:(k+1)*W]) for k in range(strip.shape[1]//W)]
+
+
+def grow(mask, px):
+ """`mask` grown by `px` px every way (8-neighbour steps)."""
+ for _ in range(px):
+ p = np.pad(mask, 1)
+ mask = np.logical_or.reduce([p[dy:dy+H, dx:dx+W] for dy in range(3) for dx in range(3)])
+ return mask
+
+
+def arm_like(rgb):
+ """Pixels whose colour is within 25 of the arm's fur."""
+ fur = np.array([arm_colour(x, y) for y in range(6) for x in range(ARM_BOX[0], ARM_BOX[2]+1)], np.float64)
+ d = np.min(np.linalg.norm(rgb[..., None, :3].astype(np.float64) - fur, axis=-1), axis=-1)
+ return d < 25
+
+
+def folded_reads(answer, k):
+ """Cell k's opaque pixels, neither kept nor beside a kept one, whose read takes the source backwards: the area each
+ takes, read off the move each read took (`held_cell`), at 0 or under."""
+ drawn, read = answer.held_cell(k)
+ kept = read['held'] | read['air']
+ p = np.pad(kept, 1)
+ beside = kept | p[:-2, 1:-1] | p[2:, 1:-1] | p[1:-1, :-2] | p[1:-1, 2:]
+ rx, ry = read['read_x'], read['read_y']
+ area = (1 - (rx[1:-1, 2:] - rx[1:-1, :-2])/2) * (1 - (ry[2:, 1:-1] - ry[:-2, 1:-1])/2) \
+ - (rx[2:, 1:-1] - rx[:-2, 1:-1])/2 * (ry[1:-1, 2:] - ry[1:-1, :-2])/2
+ counted = (np.asarray(drawn)[..., 3] >= 128) & ~beside
+ return int((counted[1:-1, 1:-1] & (area <= 0)).sum()), float(area[counted[1:-1, 1:-1]].min()) if counted[1:-1, 1:-1].any() else 1.0
+
+
+# ---------------------------------------------------------------- off, nothing of it
+
+def test_without_a_hold_mask_the_band_is_as_ever(tmp_path):
+ plain, asked = strip_dir(tmp_path/'plain', held_figure), strip_dir(tmp_path/'asked', held_figure)
+ assert cli.main(['video-sway', '--loop-dir', str(plain), '--region', text(CHEST), '--band', 'auto']) == 0
+ sway.sway_loop(asked, [CHEST], band='auto', hold_mask=None)
+ assert (plain/'walk.strip.png').read_bytes() == (asked/'walk.strip.png').read_bytes()
+ assert 'hold' not in json.loads((plain/'walk.strip.json').read_text())['follow']
+
+
+# ---------------------------------------------------------------- what is held
+
+def test_what_the_mask_holds_its_soft_edge_and_the_air_keep_their_bytes_in_every_cell(tmp_path):
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX, BELT_BOX)
+ plain_dir, held_dir = strip_dir(tmp_path/'plain', held_figure), strip_dir(tmp_path/'held', held_figure)
+ sway.sway_loop(plain_dir, [CHEST], band='auto')
+ record = sway.sway_loop(held_dir, [CHEST], band='auto', hold_mask=mask)
+ source, plain, held = cells_of(strip_dir(tmp_path/'source', held_figure)), cells_of(plain_dir), cells_of(held_dir)
+ arm_moved = arm_new_plain = 0
+ for k in range(N):
+ shift = body_sway(k)
+ arm, belt = boxed(ARM_BOX, shift), boxed(BELT_BOX, shift)
+ edge, rim = boxed((ARM_BOX[2]+1, ARM_BOX[1], ARM_BOX[2]+1, ARM_BOX[3]), shift), boxed((NOTCH[2], NOTCH[1], NOTCH[2], NOTCH[3]), shift)
+ soft, notch = edge | rim, boxed((NOTCH[0], NOTCH[1], NOTCH[2]-1, NOTCH[3]), shift)
+ assert (source[k][..., 3][edge] == SOFT[3]).all() and (source[k][..., 3][rim] == 190).all(), k
+ assert (source[k][..., 3][notch] == 0).all(), k
+ for what, where in (('arm', arm), ('belt', belt), ('soft edge', soft), ('air in the notch', notch)):
+ assert np.array_equal(held[k][where], source[k][where]), (k, what)
+ arm_moved += not np.array_equal(plain[k][arm], source[k][arm])
+ # No fur is drawn off the arm, and no pixel solid by the arm (2 px round it, off it and what it keeps) is left clear.
+ off = ~arm & ~soft
+ new = lambda cell: arm_like(cell) & (cell[..., 3] >= 128) & ~arm_like(source[k]) & off
+ arm_new_plain += int(new(plain[k]).sum())
+ assert not new(held[k]).any(), k
+ near = grow(arm, 2) & ~arm & ~soft & ~notch & (source[k][..., 3] >= 128)
+ assert (held[k][..., 3][near] >= 128).all(), k
+ assert arm_moved > N//2 and arm_new_plain > 0 # without the mask the band moves the arm and draws its fur on the chest
+ hold = record['hold']
+ assert (hold['policy'], hold['asked'], hold['grow_px']) == (POLICY, {'per_cell': False, 'sha256': hashlib.sha256(mask.read_bytes()).hexdigest()}, 3)
+ assert hold['edge_px'] == math.ceil(answer_of(strip_dir(tmp_path/'again', held_figure), [CHEST], band='auto').reach) + 2
+ assert [piece['px'] for piece in hold['pieces']] == [int(boxed(ARM_BOX).sum()), int(boxed(BELT_BOX).sum())]
+ assert [piece['box'] for piece in hold['pieces']] == [list(ARM_BOX), list(BELT_BOX)]
+ carry = hold['carry']['cells']
+ assert carry[0] == [{'px': [0.0, 0.0], 'from': 'base'}]*2
+ for k in range(1, N): # the arm and the belt are each found by their own pixels, where the body carries them
+ assert [entry['from'] for entry in carry[k]] == ['pixels', 'pixels'], k
+ for entry in carry[k]:
+ assert np.allclose(entry['px'], body_sway(k), atol=0.5), k
+ assert hold['lay'] == [] and max(hold['ledger']['short_px']) > 0
+
+
+def test_pixels_no_read_round_the_mask_comes_near_are_the_bands_byte_for_byte(tmp_path):
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX)
+ plain_dir, held_dir = strip_dir(tmp_path/'plain', held_figure), strip_dir(tmp_path/'held', held_figure)
+ sway.sway_loop(plain_dir, [CHEST], band='auto')
+ sway.sway_loop(held_dir, [CHEST], band='auto', hold_mask=mask)
+ plain, held = cells_of(plain_dir), cells_of(held_dir)
+ assert sum(not np.array_equal(held[k], plain[k]) for k in range(N)) > N//2 # the mask holds what the band moved
+ answer = answer_of(strip_dir(tmp_path/'again', held_figure), [CHEST], band='auto', hold_mask=mask)
+ # A read is shortened only within reach / HOLD_SLOPE (and a pixel and the margin) of what is kept, every way (its
+ # share, lowered to rise by HOLD_SLOPE a px at most, is never over HOLD_SLOPE times that far), and its share is rounded
+ # over HOLD_ROUND px each way: past that, the cell is the band's.
+ far = math.ceil(answer.reach/sway.HOLD_SLOPE) + 1 + sway.HOLD_MARGIN + 2*sway.HOLD_ROUND + 1
+ beyond = 0
+ for k in range(N):
+ _, read = answer.held_cell(k)
+ away = ~grow(read['held'] | read['air'], far)
+ assert np.array_equal(held[k][away], plain[k][away]), k
+ beyond += int((away & np.any(plain[k] != np.asarray(answer.cells[k]), axis=-1)).sum())
+ assert beyond > 0 # the band moves pixels out there, and they are moved as without the mask
+
+
+def test_a_steep_band_beside_the_mask_is_read_in_order(tmp_path):
+ # A band the move at gain 1.3 does not fold and the move at 2.5 does, past a margin of 2, at the gain the fold rule
+ # lowers it to: the band's own move leaves a pixel little of its area, and the arm's right side lies in it. Where the
+ # part leaves the arm the gap is drawn from the part, its read never taking the source backwards.
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX)
+ per_gain = answer_of(strip_dir(tmp_path/'unit', held_figure), [CHEST], gain=1.0).reach_per_gain
+ kw = dict(band=math.ceil(1.3*per_gain*math.pi/2), band_margin=2, on_fold='lower')
+ held_dir = strip_dir(tmp_path/'held', held_figure)
+ record = sway.sway_loop(held_dir, [CHEST], hold_mask=mask, **kw)
+ source, held = cells_of(strip_dir(tmp_path/'source', held_figure)), cells_of(held_dir)
+ for k in range(N):
+ arm = boxed(ARM_BOX, body_sway(k))
+ assert np.array_equal(held[k][arm], source[k][arm]), k
+ assert record['fold']['lowered'] and min(record['band']['ledger']['jacobian_min']) < 0.2
+ answer = answer_of(strip_dir(tmp_path/'again', held_figure), [CHEST], hold_mask=mask, **kw)
+ short = 0
+ for k in range(N):
+ folded, least = folded_reads(answer, k)
+ assert folded == 0 and least > 0, (k, least)
+ short += int((answer.held_cell(k)[1]['share'] < 1).sum())
+ assert short > 0
+ ledger = record['hold']['ledger']
+ assert ledger['read_folded_px'] == [0]*N and ledger['read_folded_px_max'] == 0
+ assert all(least is None or least[0] > 0 for least in ledger['read_least'])
+ # Where a read turns from the whole move to its share round the mask the bound does not hold; the ledger reads it.
+ assert ledger['read_turn_folded_px'] == [0]*N and any(least is not None for least in ledger['read_turn_least'])
+ assert all(least is None or least[0] > 0 for least in ledger['read_turn_least'])
+
+
+# ---------------------------------------------------------------- the same hold on every path
+
+def test_a_folder_of_the_masks_carried_holds_as_the_one_mask(tmp_path):
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX, BELT_BOX)
+ one_dir, folder_dir = strip_dir(tmp_path/'one', held_figure), strip_dir(tmp_path/'folder', held_figure)
+ one = sway.sway_loop(one_dir, [CHEST], band='auto', hold_mask=mask)
+ source, held = cells_of(strip_dir(tmp_path/'source', held_figure)), cells_of(one_dir)
+ for k in range(N):
+ arm = boxed(ARM_BOX, body_sway(k))
+ assert np.array_equal(held[k][arm], source[k][arm]), k
+ answer = answer_of(strip_dir(tmp_path/'again', held_figure), [CHEST], band='auto', hold_mask=mask)
+ masks = tmp_path/'masks'
+ masks.mkdir()
+ for k in range(N):
+ held = answer.hold.mask_in(k)
+ Image.fromarray(np.where(held, 255, 0).astype(np.uint8), 'L').save(masks/f'cell-{k:03d}.png')
+ given = sway.sway_loop(folder_dir, [CHEST], band='auto', hold_mask=masks)
+ assert (one_dir/'walk.strip.png').read_bytes() == (folder_dir/'walk.strip.png').read_bytes()
+ assert given['hold']['asked']['per_cell'] and len(given['hold']['asked']['sha256']) == N
+ assert given['hold']['carry'] is None and given['hold']['grow_px'] is None and given['hold']['pieces'] == []
+ assert given['hold']['ledger'] == one['hold']['ledger']
+
+
+def test_the_frames_are_held_as_the_strip(tmp_path):
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX, BELT_BOX)
+ frames = tmp_path/'frames'
+ frames.mkdir()
+ for k, name in enumerate(FILES):
+ held_figure(k).save(frames/name)
+ loop_dir = strip_dir(tmp_path/'loop', held_figure, delay_ms=41.67) # a frame at --fps 24, as a strip's meta writes it
+ assert cli.main(['video-sway', '--frames', str(frames), '--out', str(tmp_path/'out'), '--fps', '24', '--region', text(CHEST),
+ '--band', 'auto', '--hold-mask', str(mask)]) == 0
+ strip_record = sway.sway_loop(loop_dir, [CHEST], band='auto', hold_mask=mask)
+ strip = cells_of(loop_dir)
+ for k, name in enumerate(FILES):
+ out, arm = np.asarray(Image.open(tmp_path/'out'/name).convert('RGBA')), boxed(ARM_BOX, body_sway(k))
+ assert np.array_equal(out[arm], np.asarray(held_figure(k))[arm]), k
+ assert np.array_equal(out, strip[k]), k
+ assert json.loads((tmp_path/'out'/'sway.json').read_text())['hold'] == strip_record['hold']
+
+
+def test_a_turned_loop_held_on_the_cuts_reading_is_the_cuts_held_sway_cell_for_cell(origin, tmp_path):
+ # The mask is drawn on the cut's first cell, where the regions were read; the turned loop carries it from there.
+ o, read_on, _ = origin
+ cx, cy, rx, _ = cut_chest(o)
+ rim = np.zeros(cut_cells(o)[0].shape[:2], bool)
+ rim[round(cy) - 4:round(cy) + 5, round(cx - rx) - 2:round(cx - rx) + 7] = True # the chest's left rim and just past it
+ mask = tmp_path/'mask.png'
+ Image.fromarray(np.where(rim, 255, 0).astype(np.uint8), 'L').save(mask)
+ sway.sway_loop(shutil.copytree(o, tmp_path/'banded'), [cut_chest(o)], on_fold='lower', band='auto')
+ held = sway.sway_loop(shutil.copytree(o, tmp_path/'held'), [cut_chest(o)], on_fold='lower', band='auto', hold_mask=mask)
+ loop_dir = aligned(o, tmp_path/'turned')
+ turned = meta_of(loop_dir)['cycle_align']['turned_by']
+ result = sway.sway_loop(loop_dir, [cut_chest(o)], on_fold='lower', read_on=read_on, band='auto', hold_mask=mask)
+ moved, reference, banded = cut_cells(loop_dir), cut_cells(tmp_path/'held'), cut_cells(tmp_path/'banded')
+ n = len(reference)
+ assert sum(not np.array_equal(reference[k], banded[k]) for k in range(n)) > n//2 # the mask holds what the band moves
+ assert all(np.array_equal(moved[k], reference[(k+turned) % n]) for k in range(n))
+ assert result['read_on']['relation'] == 'transported'
+ cut_carry, turned_carry = held['hold']['carry']['cells'], result['hold']['carry']['cells']
+ assert [[entry['px'] for entry in turned_carry[k]] for k in range(n)] == [[entry['px'] for entry in cut_carry[(k+turned) % n]] for k in range(n)]
+
+
+# ---------------------------------------------------------------- refused, and said
+
+def test_what_a_mask_is_refused_for_leaves_the_loop_as_it_was(tmp_path):
+ loop_dir = strip_dir(tmp_path/'loop', held_figure)
+ as_cut = (loop_dir/'walk.strip.png').read_bytes()
+ small = tmp_path/'small.png'
+ Image.new('RGBA', (W-1, H), (255, 255, 255, 255)).save(small)
+ empty = tmp_path/'empty.png'
+ Image.new('RGBA', (W, H)).save(empty)
+ broken = tmp_path/'broken.png'
+ broken.write_bytes(b'not a png')
+ few = tmp_path/'few'
+ few.mkdir()
+ for k in range(3):
+ Image.new('L', (W, H), 255).save(few/f'{k}.png')
+ nothing = tmp_path/'nothing'
+ nothing.mkdir()
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX)
+ for args, said in (
+ (['--hold-mask', str(mask)], r'--hold-mask keeps pixels as they are while a band moves its regions round them; it needs --band$'),
+ (['--band', 'auto', '--hold-mask', str(small)], rf'--hold-mask is {W-1}x{H}, the cells are {W}x{H}: a mask is drawn on a cell'),
+ (['--band', 'auto', '--hold-mask', str(empty)], r'holds no pixel \(alpha 128 or more'),
+ (['--band', 'auto', '--hold-mask', str(broken)], r'broken.png: not read'),
+ (['--band', 'auto', '--hold-mask', str(few)], rf'--hold-mask holds 3 masks and there are {N} cells: a folder gives one mask per cell'),
+ (['--band', 'auto', '--hold-mask', str(nothing)], r'a folder of masks with no PNG in it$')):
+ with pytest.raises(SystemExit, match=said) as refused:
+ cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), *args])
+ assert refused.value.code not in (0, None), args
+ 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_piece_on_cloth_with_no_pattern_is_carried_by_the_lay_and_the_record_and_the_warnings_say_so(tmp_path, capsys):
+ mask = mask_png(tmp_path/'mask.png', ARM_BOX, PATCH_BOX)
+ loop_dir = strip_dir(tmp_path/'loop', held_figure)
+ source = cells_of(strip_dir(tmp_path/'source', held_figure))
+ assert cli.main(['video-sway', '--loop-dir', str(loop_dir), '--region', text(CHEST), '--band', 'auto', '--hold-mask', str(mask)]) == 0
+ out = capsys.readouterr()
+ held = cells_of(loop_dir)
+ for k in range(N): # carried by the lay, which is where the body carries it here: held all the same
+ patch = boxed(PATCH_BOX, body_sway(k))
+ assert np.array_equal(held[k][patch], source[k][patch]), k
+ hold = json.loads((loop_dir/'walk.strip.json').read_text())['follow']['hold']
+ lay = hold['lay']
+ assert lay and {entry['piece'] for entry in lay} == {1}
+ whys = '; '.join(f"cell {e['cell']}: {e['why']}" for e in lay)
+ assert (f"--hold-mask carries its piece 1 by the body's lay in {len(lay)} cells, its own pixels not found surely ({whys}) "
+ "— follow.hold.lay") in out.err
+ summary = json.loads(out.out)
+ assert summary['hold'] == {'pieces': 2, 'lay_cells': sorted({e['cell'] for e in lay}), 'read_folded_px_max': 0}
+ ledger = hold['ledger']
+ for key in ('held_px', 'soft_px', 'air_px', 'short_px', 'renormalised_px', 'walked_px', 'read_folded_px', 'read_folded_edge_px',
+ 'read_turn_folded_px'):
+ assert len(ledger[key]) == N and ledger[f'{key}_max'] == max(ledger[key]), key
+ assert len(ledger['read_least']) == len(ledger['read_turn_least']) == N
+ assert min(ledger['held_px']) > int(boxed(ARM_BOX).sum()) and min(ledger['soft_px']) > 0 and min(ledger['air_px']) > 0
+ for key in ('renormalised_px', 'walked_px', 'read_folded_px'):
+ assert (f'follow.hold.ledger.{key}' in out.err) == (ledger[f'{key}_max'] > 0), key