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(held-fill): a loop's last cells and its wrap are filled as any held run, the cut is read again once its repairs have run, and what is kept as the motion means it is listed in the strip (`holds`) with its exact rate (`fps`); the loop report records the cut's arguments (`cut_args`) so `loop.cut_again` can cut it again, and an effect's lifetime names its held runs in a warning

Soohong Kimfcd0b7d2c55f
diff --git a/sprite_gen/video/held_fill.py b/sprite_gen/video/held_fill.py
index f9ea096..3aafb22 100644
--- a/sprite_gen/video/held_fill.py
+++ b/sprite_gen/video/held_fill.py
@@ -20,10 +20,14 @@ settled end) does not part them: the arm's pixel reads under it. A small part's
the same picture, as a hold plays.
`fill` makes each run's cells again, between the run's first cell and the next pose, at their own times — the cells of a
-run of three a third and two thirds of the way — so the cut keeps its length, its beat, its first and last cells and
-its wrap: a made cell stands where a held cell stood. A run is kept as filmed where filling it would change what the
-cut means: longer than HOLD_MAX cells (a drawing held on threes is three: longer is a hold the motion means), the opening
-or the closing pose of a cut played once, the last cells of a loop (their next pose is across its wrap). A cut drawn on
+run of three a third and two thirds of the way — so the cut keeps its length, its beat and its first cell: a made cell
+stands where a held cell stood. A loop is a ring (`wrap`): the run that closes it is made between its last pose and the
+loop's first cell, and last cells that show the first cell's picture again (`wrap_same`, a cut a cell too long) are
+made between the cell before them and the first, which stays. A run is kept as filmed where filling it would change
+what the cut means (`KEEPS`, each kept run's `keep`, listed by `intended` as the strip's `holds`): longer than HOLD_MAX
+cells, joined across a loop's wrap (a drawing held on threes is three: longer is a hold the motion means), the opening
+or the closing pose of a cut played once. `again` reads the cut once more after its repairs and fills what they left
+shown again, the same way. A cut drawn on
twos or threes keeps every run (`drawn`): limited animation, each drawing shown as long as the next. It is drawn so where
its held-drawings reading (`held.measure_cycle`, which `video-cycle-align` reads) gives a hold of 2 or 3 and every run is
that long, but a run cut short at the cut's first or last cell: a clip carried to a higher rate by repeating frames
@@ -76,7 +80,7 @@ def _thumbs(frames: Sequence[Image.Image]) -> np.ndarray:
return np.stack([_small_features(f).reshape(-1, 4) for f in frames])
-def _premultiplied(frame: Image.Image) -> np.ndarray:
+def premultiplied(frame: Image.Image) -> np.ndarray:
a = np.asarray(frame.convert("RGBA"), dtype=np.float32) / 255.0
return np.concatenate([a[..., :3] * a[..., 3:], a[..., 3:]], axis=-1)
@@ -93,7 +97,7 @@ def same_steps(frames: Sequence[Image.Image]) -> list[bool]:
"""For each step of `frames` (cell k to k + 1), whether the two show the same picture: on the thumbnail and on the
frames as cut (see the module)."""
t = _thumbs(frames)
- return [_same(t[k], t[k + 1]) and _same(_premultiplied(frames[k]), _premultiplied(frames[k + 1]))
+ return [_same(t[k], t[k + 1]) and _same(premultiplied(frames[k]), premultiplied(frames[k + 1]))
for k in range(len(frames) - 1)]
@@ -116,11 +120,20 @@ def runs(same: Sequence[bool]) -> list[dict[str, int]]:
return found
-def reading(same: Sequence[bool]) -> dict[str, Any]:
- """The cells, the poses and the held runs of a cut whose steps are `same`."""
+def reading(same: Sequence[bool], *, wrap: bool = False) -> dict[str, Any]:
+ """The cells, the poses and the held runs of a cut whose steps are `same`. `wrap`: a loop whose last cell shows its
+ first cell's picture again, one pose less, said `wrap_held` (the runs are not read across the wrap)."""
held = runs(same)
cells = len(same) + 1
- return {"cells": cells, "poses": cells - sum(r["length"] - 1 for r in held), "held_runs": held}
+ poses = cells - sum(r["length"] - 1 for r in held)
+ return {"cells": cells, "poses": poses - 1 if wrap and poses > 1 else poses, "held_runs": held,
+ **({"wrap_held": True} if wrap and poses > 1 else {})}
+
+
+def wrap_same(frames: Sequence[Image.Image]) -> bool:
+ """Whether a loop's last cell shows its first cell's picture again: the step across its wrap, read as `same_steps`
+ reads a step."""
+ return len(frames) > 1 and same_steps([frames[-1], frames[0]])[0]
def said(record: dict[str, Any]) -> str:
@@ -217,89 +230,190 @@ def drawn(found: Sequence[dict[str, int]], n: int, hold: int | None) -> int | No
return hold if all(r["length"] == hold or (r["length"] < hold and edge(r)) for r in found) else None
-def _fillable(run: dict[str, int], n: int, *, ring: bool, on: int | None = None) -> str | None:
- """Why a held run is kept as filmed, or None where it is made again. `on` is the hold of a cut drawn on twos or
- threes (`drawn`)."""
+def _drawn_why(on: int) -> str:
+ return (f"the cut is drawn on {'twos' if on == 2 else 'threes'} (its held-drawings reading holds {on}, and so does "
+ "every run): limited animation, kept as filmed")
+
+
+KEEPS = ("motion-hold", "drawn", "opening", "closing") # why a run is kept as the motion means it (`intended`)
+
+
+def _fillable(run: dict[str, int], n: int, *, ring: bool, on: int | None = None,
+ length: int | None = None) -> tuple[str, str] | None:
+ """Why a held run is kept as filmed and what kind of hold it is (one of KEEPS), or None where it is made again. `on`
+ is the hold of a cut drawn on twos or threes (`drawn`); `length` the cells showing its picture where a loop's wrap
+ joins it to the run across it. A loop's last cells are made again too, between their first and the loop's first
+ cell across the wrap: a loop has no closing pose."""
if on is not None:
- return (f"the cut is drawn on {'twos' if on == 2 else 'threes'} (its held-drawings reading holds {on}, and so does "
- "every run): limited animation, kept as filmed")
- if run["length"] > HOLD_MAX:
- return (f"held {run['length']} cells, longer than a drawing on threes ({HOLD_MAX}): a hold the motion means, "
- "kept as filmed")
- if run["start"] + run["length"] == n:
- return ("the loop's last cells: their next pose is across its wrap, and the wrap stays as cut" if ring else
- "the cut's closing pose, kept as filmed")
+ return _drawn_why(on), "drawn"
+ held = run["length"] if length is None else length
+ if held > HOLD_MAX:
+ across = "" if length is None else " across the loop's wrap"
+ return (f"held {held} cells{across}, longer than a drawing on threes ({HOLD_MAX}): a hold the motion means, "
+ "kept as filmed"), "motion-hold"
+ if run["start"] + run["length"] == n and not ring:
+ return "the cut's closing pose, kept as filmed", "closing"
if run["start"] == 0 and not ring:
- return "the cut's opening pose, kept as filmed"
+ return "the cut's opening pose, kept as filmed", "opening"
return None
+def _make_run(frames: Sequence[Image.Image], interpolate: rife_mod.Interpolate, a: int, b: int, cells: Sequence[int], *,
+ reads: bool) -> tuple[list[tuple[int, Image.Image]], list[dict[str, Any]]]:
+ """Each of `cells` made between frame `a` and frame `b` (a loop's `b` n is its first cell across the wrap) at its own
+ time, within half a cell of it (`_made`), the cell delivered before each the one made before it: the frames taken,
+ up to the first refused, and how each was tried."""
+ n = len(frames)
+ taken: list[tuple[int, Image.Image]] = []
+ tried: list[dict[str, Any]] = []
+ for c in cells:
+ t = (c - a) / (b - a)
+ half = 0.5 / (b - a)
+ frame, how = _made(interpolate, frames[a], frames[b % n], t, (t - half, t + half), reads=reads,
+ before=taken[-1][1] if taken else None)
+ tried.append({"cell": c, "between": [a, b % n], **how})
+ if frame is None:
+ break
+ taken.append((c, frame))
+ return taken, tried
+
+
def fill(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool,
same: Sequence[bool] | None = None, mode: str = "auto", reads: bool | None = None,
- hold: int | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ hold: int | None = None, wrap: bool | None = None, drawn_on: int | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
"""`frames` with each held run's cells made again between the run's first cell and the next pose (see the module),
- and the record: the reading before (`before`, each run `filled` or why not), the cells made (`made`, and how each
- was, `frames`), the cells left for want of an interpolator (`unmade`, `interpolate` None), the hold of a cut drawn
- on twos or threes (`drawn`), and the reading of the frames returned (`cells`, `poses`, `held_runs`). `same` is the
- steps' reading as filmed (`same_steps` of `frames` where None); `reads` whether the ghost screen reads the cut (read
- on `frames` where None); `hold` the cut's held-drawings reading (`held.measure_cycle`)."""
+ and the record: the reading before (`before`, each run `filled` or why not, and a loop's wrap, `wrap`), the cells
+ made (`made`, and how each was, `frames`), the cells left for want of an interpolator (`unmade`, `interpolate`
+ None), the hold of a cut drawn on twos or threes (`drawn`), and the reading of the frames returned (`cells`,
+ `poses`, `held_runs`, `wrap_held`). `same` is the steps' reading as filmed (`same_steps` of `frames` where None);
+ `wrap`, for a loop, whether its last cell shows its first cell's picture as filmed (`wrap_same` of `frames` where
+ None); `reads` whether the ghost screen reads the cut (read on `frames` where None); `hold` the cut's held-drawings
+ reading (`held.measure_cycle`); `drawn_on` the hold of a cut known drawn on twos or threes where its own runs do
+ not read so (a loop resampled to another length from one drawn so, every run of it kept).
+
+ A loop whose last cells show its first cell's picture again (`wrap`) keeps its first cell: the cells before the wrap
+ that show it are made again between the pose before them and the first cell, as one run with the cells after it that
+ show it too (a run starting the loop, made as any other) — kept whole where that run is longer than HOLD_MAX."""
if mode not in MODES:
raise ValueError(f"fill mode {mode!r}: one of {', '.join(MODES)}")
same = list(same_steps(frames) if same is None else same)
n = len(frames)
- on = drawn(runs(same), n, hold)
+ found = runs(same)
+ on = drawn(found, n, hold) if drawn_on is None else drawn_on
+ whole = len(found) == 1 and found[0]["length"] == n # one picture throughout: no pose to make anything between
+ wrapped = ring and not whole and (wrap_same(frames) if wrap is None else bool(wrap))
out = list(frames)
before = []
made: list[int] = []
unmade: list[int] = []
rows: list[dict[str, Any]] = []
- for run in runs(same):
- row: dict[str, Any] = dict(run)
- cells = list(range(run["start"] + 1, run["start"] + run["length"]))
- why = "--fill-held off" if mode == "off" else _fillable(run, n, ring=ring, on=on)
- if why is None and interpolate is None:
+ tail: dict[str, Any] | None = None
+ joined_keep: tuple[str, str] | None = None
+ if wrapped:
+ last = found[-1] if found and found[-1]["start"] + found[-1]["length"] == n else None
+ first = found[0] if found and found[0]["start"] == 0 else None
+ s = last["start"] if last is not None else n - 1
+ joined = (n - s) + (first["length"] if first is not None else 1)
+ tail = {"start": s, "length": n - s, "joined": joined}
+ joined_keep = None if mode == "off" else _fillable(tail, n, ring=True, on=on, length=joined)
+
+ def attempt(row: dict[str, Any], a: int, b: int, cells: list[int], keep: tuple[str, str] | None) -> dict[str, Any]:
+ nonlocal reads, unmade, made, rows
+ if mode == "off":
+ return {**row, "filled": False, "why": "--fill-held off"}
+ if keep is not None:
+ return {**row, "filled": False, "why": keep[0], "keep": keep[1]}
+ if interpolate is None:
unmade += cells
- why = "no interpolator"
- if why is not None:
- before.append({**row, "filled": False, "why": why})
- continue
+ return {**row, "filled": False, "why": "no interpolator"}
if reads is None:
reads = bool(ghost_screen(frames)["reads"])
- a, b = run["start"], run["start"] + run["length"]
- taken, tried = [], []
- for c in cells:
- t = (c - a) / (b - a)
- half = 0.5 / (b - a)
- frame, how = _made(interpolate, frames[a], frames[b % n], t, (t - half, t + half), reads=reads,
- before=taken[-1][1] if taken else None)
- tried.append({"cell": c, "between": [a, b % n], **how})
- if frame is None:
- break
- taken.append((c, frame))
+ taken, tried = _make_run(frames, interpolate, a, b, cells, reads=reads)
if len(taken) < len(cells):
refused = sorted({f for row_ in tried for t_ in row_["tries"] for f in t_["faults"]})
- before.append({**row, "filled": False, "faults": refused, "tries": tried,
- "why": f"a frame between was refused ({', '.join(refused) or 'ghost band over the retime bar'}): kept as filmed"})
- continue
+ return {**row, "filled": False, "faults": refused, "tries": tried,
+ "why": f"a frame between was refused ({', '.join(refused) or 'ghost band over the retime bar'}): kept as filmed"}
for c, frame in taken:
out[c] = frame
made += cells
rows += tried
- before.append({**row, "filled": True, "made": cells})
+ return {**row, "filled": True, "made": cells}
+
+ wrap_row: dict[str, Any] | None = None
+ if tail is not None:
+ # The cells before the wrap showing the first cell's picture, made between the pose before them and the first cell.
+ s = tail["start"]
+ wrap_row = attempt(dict(tail), s - 1, n, list(range(s, n)), joined_keep)
+ for run in found:
+ row: dict[str, Any] = dict(run)
+ if tail is not None and run["start"] + run["length"] == n:
+ before.append({**row, "wrap": True, **{k: v for k, v in wrap_row.items() if k not in ("start", "length", "joined")}})
+ continue
+ cells = list(range(run["start"] + 1, run["start"] + run["length"]))
+ if tail is not None and run["start"] == 0 and joined_keep is not None and joined_keep[1] == "motion-hold":
+ # one hold with the cells before the wrap, longer than a drawing on threes: kept whole with them
+ before.append(attempt(row, 0, run["length"], cells, joined_keep))
+ continue
+ before.append(attempt(row, run["start"], run["start"] + run["length"], cells, _fillable(run, n, ring=ring, on=on)))
record: dict[str, Any] = {
"mode": mode, "pixel_same": PIXEL_SAME, "changed_max": CHANGED_MAX, "hold_max": HOLD_MAX,
- "before": {**reading(same), "held_runs": before},
- "made": made, "frames": rows,
- "contact": [{"cell": r["cell"], **r["contact"]} for r in rows if r["contact"]["reads"]],
+ "before": {**reading(same, wrap=wrapped), "held_runs": before, **({"wrap": wrap_row} if wrap_row is not None else {})},
+ "made": sorted(made), "frames": sorted(rows, key=lambda r: r["cell"]),
}
+ record["contact"] = [{"cell": r["cell"], **r["contact"]} for r in record["frames"] if r["contact"]["reads"]]
if on is not None:
record["drawn"] = on
if unmade:
- record["unmade"] = {"cells": unmade}
- record.update(reading(same_steps(out)) if made else reading(same))
+ record["unmade"] = {"cells": sorted(unmade)}
+ record.update(reading(same_steps(out), wrap=ring and wrap_same(out)) if made else reading(same, wrap=wrapped))
return out, record
+def intended(record: dict[str, Any]) -> list[dict[str, Any]]:
+ """The runs the fill kept as the motion means them (KEEPS: longer than HOLD_MAX, drawn on twos or threes, the opening
+ or closing pose of a cut played once), each as its cells, both ends in (`from`, `to`), its `kind` and `reason`: the
+ holds a reader of the cut should not take for a picture shown again by mistake."""
+ before = record["before"]
+ rows = [r for r in before["held_runs"] if r.get("keep")]
+ found = [{"from": r["start"], "to": r["start"] + r["length"] - 1, "kind": r["keep"], "reason": r["why"]} for r in rows
+ if not r.get("wrap")]
+ wrap = before.get("wrap")
+ if wrap and wrap.get("keep"):
+ found.append({"from": wrap["start"], "to": wrap["start"] + wrap["length"] - 1, "kind": wrap["keep"], "reason": wrap["why"]})
+ return sorted(found, key=lambda h: h["from"])
+
+
+def again(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, record: dict[str, Any], *, ring: bool,
+ mode: str = "auto", skip: Sequence[int] = ()) -> tuple[list[Image.Image], dict[str, Any] | None]:
+ """The cut read again once everything after the fill has run, each run of cells showing one picture that the fill
+ did not leave (no kept run of `record` holds a cell of it, and no cell of it is in `skip`: cells a repair already gave
+ way to the frame beside it, its frame between refused) made again as the fill makes a run (`fill`, with the same
+ rules): the frames, and the record of it, None where no such run was read. A cut drawn on twos or threes, or cut
+ with the fill off, is not read again."""
+ if mode == "off" or "drawn" in record:
+ return frames, None
+ before = record["before"]
+ kept: set[int] = set()
+ for r in [*before["held_runs"], *([before["wrap"]] if before.get("wrap") else [])]:
+ if not r["filled"]:
+ kept.update(range(r["start"], r["start"] + r["length"]))
+ if before.get("wrap") and not before["wrap"]["filled"]:
+ kept.add(0)
+ same = same_steps(frames)
+ n = len(frames)
+ left = set(skip) | kept
+ new = [r for r in runs(same) if not left & set(range(r["start"], r["start"] + r["length"]))]
+ wrap = ring and "wrap" not in before and 0 not in left and (n - 1) not in left and wrap_same(frames)
+ if not new and not wrap:
+ return frames, None
+ masked = [False] * len(same)
+ for r in new:
+ for k in range(r["start"], r["start"] + r["length"] - 1):
+ masked[k] = True
+ out, made = fill(frames, interpolate, ring=ring, same=masked, mode=mode, wrap=wrap)
+ return out, made
+
+
def times(n: int, fps: float, out_fps: float, *, ring: bool) -> list[float]:
"""The times, in frames of the cut, of the cells of a cut of `n` frames at `fps` given at `out_fps`: a loop's
round(n·out_fps/fps) cells over its cycle, a cut played once from its first frame to its last."""
@@ -367,10 +481,28 @@ def public(record: dict[str, Any]) -> dict[str, Any]:
out: dict[str, Any] = {k: record[k] for k in ("mode", "why", "drawn", "cells", "poses", "held_runs", "made") if k in record}
before = record["before"]
out["before"] = {"cells": before["cells"], "poses": before["poses"],
- "held_runs": [{k: v for k, v in r.items() if k != "tries"} for r in before["held_runs"]]}
+ "held_runs": [{k: v for k, v in r.items() if k != "tries"} for r in before["held_runs"]],
+ **({"wrap_held": True} if before.get("wrap_held") else {}),
+ **({"wrap": {k: v for k, v in before["wrap"].items() if k != "tries"}} if "wrap" in before else {})}
+ if record.get("wrap_held"):
+ out["wrap_held"] = True
if "unmade" in record:
out["unmade"] = {k: record["unmade"][k] for k in ("cells", "why", "install") if k in record["unmade"]}
if "out_fps" in record:
out["out_fps"] = {k: record["out_fps"][k] for k in ("asked", "fps", "applied", "cells", "made", "shown_again", "why", "install")
if k in record["out_fps"]}
+ if "again" in record:
+ out["again"] = public(record["again"])
+ return out
+
+
+def strip_holds(holds: Sequence[dict[str, Any]], samples: Sequence[int], times: Sequence[float] | None = None) -> list[dict[str, Any]]:
+ """`holds` (cells of the cut, both ends in, as `intended` gives them) as cells of the strip that holds `samples` of
+ the frames delivered: a frame delivered at a rate of its own (`times`, in cells of the cut) is in a hold where its
+ time is. A hold left on fewer than two of the strip's cells is not one there."""
+ out = []
+ for h in holds:
+ cells = [j for j, k in enumerate(samples) if h["from"] <= (k if times is None else times[k]) <= h["to"]]
+ if len(cells) >= 2:
+ out.append({"from": cells[0], "to": cells[-1], "kind": h["kind"], "reason": h["reason"]})
return out
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 8e08e02..1c58877 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -862,6 +862,9 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,
"body_ref": ("cut-first-frame" if standing_frame else "first-frame") if standing_src is not None else "tallest-grounded",
"scale": round(scale, 4),
"delay_ms": round(1000 * cycle_seconds / len(cells), 2),
+ # The cells' own rate, unrounded to six places: `delay_ms` rounded to hundredths of a millisecond (41.67 for
+ # 24 fps) drifts a scene a frame late on every cell (the asset loader reads `fps` first).
+ "fps": round(len(cells) / cycle_seconds, 6),
"cycle_frames": L,
"cycle_seconds": round(cycle_seconds, 4),
"subsampled": L > cap,
@@ -1413,14 +1416,14 @@ def _located(interpolate: rife_mod.Interpolate | None, made_by: list[dict[str, s
return lazy
-def _fill_held(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, same: list[bool],
- mode: str, hold: int | None) -> tuple[list[Image.Image], dict[str, Any]]:
+def fill_cut(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, same: list[bool] | None,
+ mode: str, hold: int | None, wrap: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
"""`held_fill.fill` on the cut, with RIFE located only once a frame is to be made: a cut with no held cell, or only
runs kept as filmed, needs no binary. The record names the interpolator that made the frames. A frame to make and no
RIFE installed: the held cells are delivered as filmed, and the record says which and how to install it (`unmade`)."""
made_by: list[dict[str, str]] = []
lazy = _located(interpolate, made_by)
- asked = partial(held_fill_mod.fill, ring=ring, same=same, mode=mode, hold=hold)
+ asked = partial(held_fill_mod.fill, ring=ring, same=same, mode=mode, hold=hold, wrap=wrap)
try:
frames, record = asked(frames, lazy)
except rife_mod.RifeNotInstalled as exc:
@@ -1433,6 +1436,24 @@ def _fill_held(frames: list[Image.Image], interpolate: rife_mod.Interpolate | No
return frames, record
+def _fill_again(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, record: dict[str, Any], *, ring: bool,
+ mode: str, skip: list[int]) -> tuple[list[Image.Image], dict[str, Any] | None]:
+ """`held_fill.again` on the cut, with RIFE located only once a frame is to be made, as `fill_cut` does."""
+ made_by: list[dict[str, str]] = []
+ lazy = _located(interpolate, made_by)
+ asked = partial(held_fill_mod.again, record=record, ring=ring, mode=mode, skip=skip)
+ try:
+ frames, again = asked(frames, lazy)
+ except rife_mod.RifeNotInstalled as exc:
+ frames, again = asked(frames, None)
+ if again is not None and "unmade" in again:
+ again["unmade"].update(why="RIFE is not installed", rife=str(exc), install=rife_mod.install_command())
+ return frames, again
+ if again is not None and again["made"]:
+ again["interpolator"] = {**made_by[0], **lazy.counts()} if made_by else {"kind": "injected"}
+ return frames, again
+
+
def _upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, fps: float,
out_fps: float) -> tuple[list[Image.Image], dict[str, Any]]:
"""`held_fill.upsample` on the cut, with RIFE located only once a frame is to be made. No RIFE installed: the cut is
@@ -1483,7 +1504,7 @@ def _air_lines(name: str, record: dict[str, Any]) -> list[str]:
"motion\")"] if again else []
-def _fill_lines(record: dict[str, Any]) -> list[str]:
+def fill_lines(record: dict[str, Any]) -> list[str]:
"""What became of the cut's held cells, in words (`video-loop: warning:` lines): the cells left for want of RIFE, the
runs a frame between was refused for, the frames made to look at. A run kept as the motion's own says nothing."""
lines = []
@@ -1497,6 +1518,10 @@ def _fill_lines(record: dict[str, Any]) -> list[str]:
last = run["start"] + run["length"] - 1
lines.append(f"held cells {run['start']}-{last} kept as filmed: {run['why']} — look at them in the loop, or film "
"it again (docs/loop-repair.md section 7)")
+ wrap = record["before"].get("wrap")
+ if wrap and wrap.get("faults") is not None and not any(r.get("wrap") for r in record["before"]["held_runs"]):
+ lines.append(f"cell {wrap['start']}, the loop's last, shows its first cell again across the wrap and was kept as filmed: "
+ f"{wrap['why']} — look at the wrap in the loop, or cut it a cell shorter (docs/loop-repair.md section 7)")
for made in record.get("frames", []):
if made["look"]:
a, b = made["between"]
@@ -1505,7 +1530,13 @@ def _fill_lines(record: dict[str, Any]) -> list[str]:
return lines
-def _out_fps_lines(record: dict[str, Any]) -> list[str]:
+def _lifetime_lines(record: dict[str, Any]) -> list[str]:
+ """The held runs of an effect's lifetime, played as filmed (no frame between is made for one), in words."""
+ return [f"cells {r['start']}-{r['start'] + r['length'] - 1} of the effect's lifetime show one picture — played as filmed, "
+ "an effect's lifetime is not filled (docs/loop-repair.md section 7)" for r in record["held_runs"]]
+
+
+def out_fps_lines(record: dict[str, Any]) -> list[str]:
"""What became of a rate asked above the clip's (`--out-fps`), in words: not met for want of RIFE, or cells where no
frame between was made and the frame beside them is shown again."""
if not record["applied"]:
@@ -2375,6 +2406,23 @@ def _cell_record(strip_bytes: bytes, cells: list[Image.Image], *, start: int, le
for k, cell in ((frame(c), cell) for c, cell in zip(samples, cells))]}
+def cut_again(report: dict[str, Any], out_dir: Path, *, report_path: Path, **asked: Any) -> dict[str, Any]:
+ """The cut `report` records made again from its frames into `out_dir`, as it was asked (`cut_args`), but for what
+ `asked` changes (`fill_held="off"`: the cut as filmed for an alignment's frames). ValueError where it cannot be: a
+ report from before `cut_args` was recorded, or frames no longer where it read them."""
+ args = report.get("cut_args")
+ if not isinstance(args, dict):
+ raise ValueError("its report records no cut_args (cut before sprite-gen recorded what a cut was asked with)")
+ frames_dir = Path(str(report.get("frames_dir", "")))
+ if not frames_dir.is_dir():
+ raise ValueError(f"its frames are no longer at {frames_dir}")
+ kw = {**args, **asked}
+ regions = kw.pop("anchor_regions", None)
+ contacts = kw.pop("contacts", None)
+ return run_loop(frames_dir, out_dir, report_path=report_path, anchor_regions=[tuple(r) for r in regions] if regions else None,
+ contacts=list(contacts) if contacts else None, **kw)
+
+
def run_loop(frames_dir: Path, out_dir: Path, **options: Any) -> dict[str, Any]:
"""Cut the loop (`_cut_loop`, which takes the options). The frames a size hold or the gait fallback scales back
are written in folders of the run's own (`_Scratch`), removed however the run ends."""
@@ -2550,6 +2598,17 @@ def _cut_loop(
# (sprite_gen/video/held.py) — over the whole clip as keyed, before any cut. A record for
# `video-cycle-align`, which says when a held clip stretched to the set's length must be filmed again.
"drawings": held_mod.measure(clip_steps, fps=fps),
+ # What the cut was asked with, the frames read from `frames_dir`: `video-cycle-align` cuts a loop whose held cells
+ # were made again once more with the fill off, for the frames it aligns (CUT_ARGS, `cut_again`).
+ "cut_args": {"fps": fps, "state": state, "min_len": min_len, "max_len": max_len, "n_out": n_out, "seam_max": seam_max,
+ "name": name, "cycle_mode": cycle_mode, "gif_fps": gif_fps, "start": start, "length": length,
+ "strip_height": strip_height, "body_height": body_height, "anchor": anchor,
+ "anchor_regions": [list(r) for r in anchor_regions] if anchor_regions is not None else None,
+ "repair": repair, "facing": facing, "jolt_max": jolt_max, "head_step_max": head_step_max,
+ "size_hold": size_hold, "steps": steps, "overlap_wrap": overlap_wrap, "wrap_blend": wrap_blend,
+ "unfixed": unfixed, "seam_pop_max": seam_pop_max, "view": view, "body_turn": body_turn,
+ "fill_held": fill_held, "out_fps": out_fps, "air_retime": air_retime, "meters_per_px": meters_per_px,
+ "contacts": list(contacts) if contacts is not None else None},
}
if lead is not None:
# `search_from`: the first clip frame the search read (0: the whole clip, or a cut the caller named).
@@ -2792,9 +2851,10 @@ def _cut_loop(
im, d = drop_specks(im, alpha_over=16, diagonal=False, apart=0)
specks += d
frames.append(im)
- # Each step of the cut as filmed, read for a picture shown again (held_fill.same_steps): before an anchor moves each
- # frame of a pair apart.
+ # Each step of the cut as filmed, read for a picture shown again (held_fill.same_steps), and the step across a loop's
+ # wrap (its last cell showing its first again): before an anchor moves each frame of a pair apart.
same = held_fill_mod.same_steps(frames)
+ filmed_wrap = held_fill_mod.wrap_same(frames)
if prof.gait:
report_base["gait"] = evidence_mod.gait_observation(frames, cycle)
@@ -2834,6 +2894,8 @@ def _cut_loop(
if cycle["kind"] == "lifetime":
report_base["held_fill"] = {"mode": fill_held, "why": "an effect's lifetime is played as filmed", "made": [],
"before": held_fill_mod.reading(same), **held_fill_mod.reading(same)}
+ for line in _lifetime_lines(report_base["held_fill"]):
+ print(f"video-loop: warning: {name}: {line}", file=sys.stderr)
else:
# The cells that show the picture before them again, made between the poses beside them (docs/loop-repair.md
# section 7), on the cut as anchored, before anything reads its flow or its wrap. A cut drawn on twos or threes
@@ -2841,7 +2903,8 @@ def _cut_loop(
cut_drawings = report_base["cycle_drawings"]
hold = cut_drawings["hold"] if cut_drawings["hold"] is not None else report_base["drawings"]["hold"]
try:
- frames, report_base["held_fill"] = _fill_held(frames, interpolate, ring=ring, same=same, mode=fill_held, hold=hold)
+ frames, report_base["held_fill"] = fill_cut(frames, interpolate, ring=ring, same=same, mode=fill_held, hold=hold,
+ wrap=filmed_wrap)
except (ValueError, rife_mod.RifeUnavailable) as exc:
error = (f"video-loop: {exc}; the cut shows a picture again and the frames between are to be made — fix RIFE, "
"or pass --fill-held off to cut it as filmed (docs/loop-repair.md section 7)")
@@ -2849,7 +2912,7 @@ def _cut_loop(
raise SystemExit(error) from exc
if report_base["held_fill"]["made"]:
report_base["seam_measurement"] = "rendered-cells"
- for line in _fill_lines(report_base["held_fill"]):
+ for line in fill_lines(report_base["held_fill"]):
print(f"video-loop: warning: {name}: {line}", file=sys.stderr)
if prof.gait:
# The ghost screen of the cut as filmed (docs/loop-repair.md section 4), read before the jump repair: each
@@ -3030,6 +3093,24 @@ def _cut_loop(
if not report_base["ghost_screen"]["reads"]:
print(f"video-loop: warning: the ghost screen does not read this cut — {report_base['ghost_screen']['why']}; no frame "
"of it is named a ghost, here or in video-cycle-align, so look at cycle/ (docs/loop-repair.md)", file=sys.stderr)
+ if cycle["kind"] != "lifetime":
+ # The cut read again once the repairs have run (docs/loop-repair.md section 7): a run of cells showing one picture
+ # the fill did not read — one a repair left — is made as the fill makes one; a filmed ghost given way to the frame
+ # beside it, its frame between refused, is not tried again (its warning above says so).
+ given = [g["frame"] for g in report_base.get("ghost_given_way") or []]
+ try:
+ frames, read_again = _fill_again(frames, interpolate, report_base["held_fill"], ring=ring, mode=fill_held, skip=given)
+ except (ValueError, rife_mod.RifeUnavailable) as exc:
+ error = (f"video-loop: {exc}; the cut shows a picture again after its repair and the frames between are to be "
+ "made — fix RIFE, or pass --fill-held off to cut it as filmed (docs/loop-repair.md section 7)")
+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})
+ raise SystemExit(error) from exc
+ if read_again is not None:
+ report_base["held_fill"]["again"] = read_again
+ if read_again["made"]:
+ report_base["seam_measurement"] = "rendered-cells"
+ for line in fill_lines(read_again):
+ print(f"video-loop: warning: {name}: read again after the repair: {line}", file=sys.stderr)
held_record = report_base["held_fill"]
upsampled = None
# A cut played once carries its root motion (docs/video-pipeline.md, "Root motion"), read against the clip's floor.
@@ -3073,7 +3154,7 @@ def _cut_loop(
"without --out-fps (docs/loop-repair.md section 7)")
refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})
raise SystemExit(error) from exc
- for line in _out_fps_lines(held_record["out_fps"]):
+ for line in out_fps_lines(held_record["out_fps"]):
print(f"video-loop: warning: {name}: {line}", file=sys.stderr)
if held_record["out_fps"]["applied"]:
upsampled = held_record["out_fps"]["times"]
@@ -3082,8 +3163,8 @@ def _cut_loop(
if not ring:
cycle_seconds = len(frames) / out_fps # first to last frame as filmed, each cell 1/out_fps
n_out = min(n_asked, len(frames))
- # The cut as delivered, read again: its poses over its cells.
- held_record.update(held_fill_mod.reading(held_fill_mod.same_steps(frames)))
+ # The cut as delivered, read again: its poses over its cells (a loop's wrap read too).
+ held_record.update(held_fill_mod.reading(held_fill_mod.same_steps(frames), wrap=ring and held_fill_mod.wrap_same(frames)))
C = len(frames) # the cells delivered: the cut's frames, or more at --out-fps
cycle_dir.mkdir(parents=True, exist_ok=True)
for old in cycle_dir.glob("frame-*.png"):
@@ -3145,6 +3226,11 @@ def _cut_loop(
strip_meta["clip_feet"] = report_base["clip_feet"]
# The cut's held cells, what became of them, and its poses over its cells (docs/loop-repair.md section 7).
strip_meta["held_fill"] = held_fill_mod.public(held_record)
+ # The holds the motion means, as cells of the strip (held_fill.intended): what a reader of it — `inspect-holds`, a
+ # scene — does not take for a picture shown again by mistake.
+ strip_meta["holds"] = held_fill_mod.strip_holds(
+ held_fill_mod.intended(held_record) + (held_fill_mod.intended(held_record["again"]) if held_record.get("again") else []),
+ strip_meta["sample_indices"], upsampled)
if cycle["kind"] in root_motion_mod.KINDS:
# Where the body is in each cell, what each touches and the air (docs/video-pipeline.md, "Root motion"): read on
# the cells' frames as delivered, each at its time as it plays.
diff --git a/tests/video/test_held_fill.py b/tests/video/test_held_fill.py
index 5a31f9a..a2b72d1 100644
--- a/tests/video/test_held_fill.py
+++ b/tests/video/test_held_fill.py
@@ -425,15 +425,51 @@ def test_the_opening_and_the_closing_pose_of_a_cut_played_once_are_kept():
assert "opening" in whys[0] and "closing" in whys[1]
-def test_a_loop_s_held_cells_at_its_wrap_are_kept_and_at_its_start_made():
- frames = _planted([0, 0, 1, 2, 3, 4, 5, 5])
- between = Between(_reach, range(7), period=None)
- # The wrap closes on cell 0 again: a frame between the last pose and the first is the wrap's, not the hold's.
+def test_a_loop_s_held_cells_at_its_wrap_are_made_between_its_last_pose_and_its_first_cell():
+ # A loop has no closing pose: its last cells' next pose is its first cell, across the wrap. Before, the run at the
+ # end was kept as filmed and said nothing (`the loop's last cells`), a picture shown twice on every pass.
+ frames = [walk_at(t) for t in [0, 0, *range(1, N - 2), N - 3]]
+ between = Between(walk_at, range(N), period=N)
out, record = held_fill.fill(frames, between, ring=True)
runs = record["before"]["held_runs"]
- assert (runs[0]["start"], runs[0]["filled"]) == (0, True)
- assert (runs[1]["start"], runs[1]["filled"]) == (6, False) and "wrap" in runs[1]["why"]
- assert record["made"] == [1] and out[0].tobytes() == frames[0].tobytes() and out[7].tobytes() == frames[7].tobytes()
+ assert [(r["start"], r["filled"]) for r in runs] == [(0, True), (N - 2, True)]
+ assert record["made"] == [1, N - 1] and "wrap" not in record["before"]
+ # cell 1 half way from cell 0 to the pose after it; the last cell half way from the last pose to cell 0 a cycle on
+ assert out[1].tobytes() == walk_at(0.5).tobytes() and out[N - 1].tobytes() == walk_at(N - 1.5).tobytes()
+ assert out[0].tobytes() == frames[0].tobytes() and record["held_runs"] == [] and "wrap_held" not in record
+
+
+def test_a_loop_whose_last_cell_shows_its_first_again_keeps_its_first_cell_and_makes_the_last():
+ # The step across the wrap is read too: a last cell that shows the first cell's picture again (a cut one cell too
+ # long) is made between the pose before it and the first cell; the first cell stays the first cell.
+ frames = [walk_at(t) for t in [*range(N - 1), 0]]
+ between = Between(walk_at, range(N), period=N)
+ out, record = held_fill.fill(frames, between, ring=True)
+ assert record["before"]["held_runs"] == [] and record["before"]["wrap_held"] is True
+ assert record["before"]["poses"] == N - 1
+ wrap = record["before"]["wrap"]
+ assert (wrap["start"], wrap["length"], wrap["joined"], wrap["filled"]) == (N - 1, 1, 2, True)
+ assert record["made"] == [N - 1] and out[N - 1].tobytes() == walk_at(N - 1).tobytes()
+ assert out[0].tobytes() == frames[0].tobytes() and record["poses"] == N and "wrap_held" not in record
+ assert held_fill.public(record)["before"]["wrap"]["made"] == [N - 1]
+
+
+def test_a_hold_across_a_loop_s_wrap_longer_than_three_cells_is_kept_whole():
+ # Two cells before the wrap and two after it show one picture: one hold of four, the motion's own, kept whole.
+ frames = [walk_at(t) for t in [0, 0, *range(1, N - 3), 0, 0]]
+ calls: list = []
+ out, record = held_fill.fill(frames, lambda a, b, t: calls.append(t) or a, ring=True)
+ runs = record["before"]["held_runs"]
+ assert calls == [] and record["made"] == []
+ assert [(r["start"], r["filled"]) for r in runs] == [(0, False), (N - 2, False)]
+ assert all("across the loop's wrap" in r["why"] for r in runs) and runs[1]["wrap"] is True
+ assert record["before"]["wrap"]["joined"] == 4 and record["wrap_held"] is True
+
+
+def test_a_cut_played_once_does_not_read_a_wrap():
+ frames = [walk_at(t) for t in [*range(N - 1), 0]]
+ out, record = held_fill.fill(frames, lambda a, b, t: a, ring=False)
+ assert "wrap" not in record["before"] and "wrap_held" not in record and record["made"] == []
def test_codec_copies_read_as_the_same_picture_and_the_slowest_motion_does_not():
diff --git a/tests/video/test_motion_anchor.py b/tests/video/test_motion_anchor.py
index f63e52a..1cb9812 100644
--- a/tests/video/test_motion_anchor.py
+++ b/tests/video/test_motion_anchor.py
@@ -100,7 +100,9 @@ def test_cli_writes_corrected_cycle_and_gates_rendered_cells(tmp_path, corrected
out = tmp_path / "output"
args = ["--frames-dir", str(keyed), "--out-dir", str(out), "--state", "walk", "--repair", "off",
"--cycle", "fixed", "--start", "0", "--length", "24", "--anchor", "motion",
- "--anchor-region", "55,27,86,60", "--anchor-region", "48,61,94,110"]
+ "--anchor-region", "55,27,86,60", "--anchor-region", "48,61,94,110", "--fill-held", "off"]
+ # Anchored, cells 5 to 7 differ by one pixel: the default would make 6 and 7 again after the anchor
+ # (docs/loop-repair.md section 7). Off, the cells are the anchor's own.
assert loop.main(args) == 0
result = json.loads((out / "loop.loop.report.json").read_text())
assert result["status"] == "passed"
diff --git a/tests/video/test_root_motion.py b/tests/video/test_root_motion.py
index 99709a2..60c08eb 100644
--- a/tests/video/test_root_motion.py
+++ b/tests/video/test_root_motion.py
@@ -319,6 +319,12 @@ def test_without_the_handle_the_cut_is_the_same_pictures_as_before_and_its_sidec
assert len(cells["cells"]) == meta["frames"]
source = meta["source_cut"]["source"]
assert source.pop("sha256") == evidence.source_identity(sorted(keyed.glob("*.png")), 24.0)["sha256"]
+ # 4.0.0 adds the strip's exact rate and the cells it shows again on purpose; the rest is as the base wrote it.
+ assert meta.pop("fps") == pytest.approx(meta["frames"] / meta["cycle_seconds"], rel=1e-4)
+ holds = meta.pop("holds")
+ rows = ((meta.get("held_fill") or {}).get("before") or {}).get("held_runs", [])
+ kept = [row.pop("keep") for row in rows if "keep" in row]
+ assert [h["kind"] for h in holds] == kept and set(kept) <= set(held_fill.KEEPS)
assert hashlib.sha256(json.dumps(meta, sort_keys=True).encode()).hexdigest() == SIDECARS[case]
assert (grown is not None) == (meta["kind"] in rm.KINDS)
if grown is not None: