Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

refactor(video-loop): held_fill.out_fps.shows is source_frames (the frame of the cut each cell is, null where it was made), the name cell_record's source_frame is read from, so the held fill's judge can name the frames a made frame shows again as shows

Soohong Kimf669bd2f2bf2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1dbd132..1477d3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- **Changed: wearing the crease row in like every other edge of the mask and reaching down to the crease only when laying a region over the figure (`--region-crease`, `--region-over`).** Removed: the step that filled each crease column back down to the crease row after the mask was worn in (`crease_kept` is gone). Now `--region-crease` ends the mask on the crease before the wear and the wear (`--region-shrink`) wears the whole mask in, the crease row too, like every other edge. So the record's `mask.box` ends `--region-shrink` rows above the crease row (2 rows at the default), as it did before `crease_kept`. New, under `--region-over` only: in every cell the region reaches down to the crease again (`crease_reach`): the crease's rows (its columns and rows on the cell the mask was drawn on; a column between two crease columns takes the nearer one's row, the left one's on a tie) are carried into the cell by the mask's carry there (the column rounded to the nearest, half to even; the row rounded down), and in each crease column where the region holds a pixel, the cell's solid pixels from the region's lowest pixel down to the crease's row join the region. The crease is the picture's own edge, so the layer reaches it in every cell while the wear still wears the mask in everywhere else. Without `--region-over` nothing reaches back down: the worn mask is the region.
- **New: solid under-edges, round rims, figure membranes, and recut strip pairing (`--region-over-solid`, `--region-rim-round`, `--region-membrane`, `--read-on-cut`).** `--region-over-solid` frees only solid pixels (alpha 128 or more) under the lower edge into the band while keeping softer pixels as anchors, and carries the region's soft edge with it under the lower edge. `--region-rim-round` holds the rim round beside the region across the wider of its two widths (`max(Lx, Ly)`), preventing steep downward steps below corners where the lower edge runs lower. `--region-membrane N` moves the figure under the lower edge within N + 1 px as a membrane by solving 4-neighbour figure means in passes instead of conjugate gradients (from a cos² start, at most 1200 passes, leaving no piece out) so the figure stretches rather than slides, drawing membrane pixels by their move and reporting membrane-specific fold refusals. `--read-on-cut STRIP` pairs regions read on another cut of the same clip by matching source frame numbers and applying a whole-pixel shift across crops on unaligned and aligned loops alike. The shift is taken on the frame as filmed, less where each cut's body or motion anchor moved that frame. Each cut is now read by its record of its cells alone: `cell_record` in the strip's record (`<name>.strip.json`), which `video-loop` now writes, bound to the strip by `cell_record.strip_sha256` (the sha256 of the strip PNG), with one entry per cell: `source_frame`, `anchor_move_px` (where the anchor moved that frame before the crop, whole px across and down), `scale` (`size_hold` and `gait_fallback`: the factor each step that holds a clip's frames to one size scaled that frame by, 1 where it did not hold them) and `as_filmed` (true where the cell's pixels at the end of the cut are its pixels anchored before any repair, the receipt `source_projection.before_repair_pixels_sha256` in the cut's report, and no step held the clip's frames to one size). On a loop aligned from its cut it reads the cut's own record, which `video-cycle-align` now keeps beside the cut's frames as filmed (`cycle.source/<name>.strip.json`) and which must be bound to the strip the alignment's origin names (`cycle_align.origin.strip_sha256`). It refuses, no-match, saying which and naming the field: a cut with no `cell_record` (any cut made before this release), a record bound to another strip, a record that does not give its cells as `video-loop` writes them (a field missing or not of its kind, in any cell), a loop aligned from its cut with no kept record, a paired cell a hold scaled or not cut as filmed, and two paired cells that are not the same pixels where they overlap at the shift (a record changed to call a cell as filmed is held to the cell's pixels). The report beside a cut is no longer looked for or read. All four options are off by default and leave strips, frames, and records byte for byte what they were when not given. See [video-pipeline](docs/video-pipeline.md) section 6.
- **New: the membrane's own keys (`--region-membrane-unpin`, `--region-clear-alpha`, `--region-floor-beside`, `--region-own-outline`).** `--region-membrane-unpin` makes what the membrane moves no anchor of the rim either, so the region's move does not fall to none at its first rows under its lower edge. `--region-clear-alpha A` (a whole number from 1 to 127) reads a pixel under alpha A as clear by the sets the region moves and holds and by the membrane's figure while the cell's bytes stay its own, so a speck of dust beside the figure holds nothing. `--region-floor-beside N` sets the lower edge beside the region's columns to the lowest pixel of its columns within N px of that side, not that of its nearest column alone. `--region-own-outline G` grows the region G 4-neighbour steps over the cell's solid pixels within G 4-neighbour steps of a clear pixel before the sets (never under its lower edge's line and never over pixels `--hold-mask` leaves out), moving the outline its carried mask leaves out with the region. All four require `--region-mask`, shape nothing without `--region-membrane` (leaving the same bytes and record, naming none of them), are off by default, and leave strips, frames, and records byte for byte what they were when not given. See [video-pipeline](docs/video-pipeline.md) section 6.
-- **Output change: `cell_record` in strip records, `source_projection` for motion anchors, and kept cut strip records.** `video-loop` now writes `cell_record` into every strip record it writes (the fields above). The strip PNG, the GIF, the WebP and the frames of `cycle/` keep their bytes; the strip record gains this one key. A cut's report gains `source_projection` (`recipe`, `wrap_dx_px`, `before_repair_pixels_sha256`) at `--anchor motion` and `--anchor motion-auto` too, with `recipe` `motion-anchor-correction-v1` there; it was written only at `--anchor none` and `body` before (unchanged there). `cell_record` is written in the strip record only, not in the report's copy of it. `video-cycle-align`'s first alignment of a loop now also writes `cycle.source/<name>.strip.json`, the loop's strip record as cut, byte for byte, before it rewrites `<name>.strip.json`; later alignments leave it as it is, and a new cut with `video-loop` removes it with `cycle.source/`. The aligned strip's record does not carry `cell_record` (it is the record of another strip). The pair policy `RECUT_POLICY` is now `same-clip/source-frame/whole-px-shift/2`. At `--out-fps` (3.8.0: cells each made at a time of their own, more cells than the cut has frames), and at `--out-fps` with the air retimed, the report's `held_fill.out_fps` gains `shows` (per cell, the frame of the cut it is, or null where it was made), and `cell_record` now reads a retimed cut the same way as a cut at `--out-fps`: `source_frame` is the frame the cell is, and for a cell made between two frames the cut's frame at or before its time (the frame the seam reads it as), with that frame's `anchor_move_px` and `scale`. `as_filmed` is true only where the cell's pixels are that frame's pixels anchored before any repair, so a cell that repeats a frame unchanged is as filmed, and a cell made between two frames, a cell moved onto the parabola or along, and every cell of a cut the retime laid on a larger canvas are not as filmed, and `video-sway --read-on-cut` does not pair them. The cells before the take-off that the retime neither moved nor laid on a larger canvas stay as filmed.
+- **Output change: `cell_record` in strip records, `source_projection` for motion anchors, and kept cut strip records.** `video-loop` now writes `cell_record` into every strip record it writes (the fields above). The strip PNG, the GIF, the WebP and the frames of `cycle/` keep their bytes; the strip record gains this one key. A cut's report gains `source_projection` (`recipe`, `wrap_dx_px`, `before_repair_pixels_sha256`) at `--anchor motion` and `--anchor motion-auto` too, with `recipe` `motion-anchor-correction-v1` there; it was written only at `--anchor none` and `body` before (unchanged there). `cell_record` is written in the strip record only, not in the report's copy of it. `video-cycle-align`'s first alignment of a loop now also writes `cycle.source/<name>.strip.json`, the loop's strip record as cut, byte for byte, before it rewrites `<name>.strip.json`; later alignments leave it as it is, and a new cut with `video-loop` removes it with `cycle.source/`. The aligned strip's record does not carry `cell_record` (it is the record of another strip). The pair policy `RECUT_POLICY` is now `same-clip/source-frame/whole-px-shift/2`. At `--out-fps` (3.8.0: cells each made at a time of their own, more cells than the cut has frames), and at `--out-fps` with the air retimed, the report's `held_fill.out_fps` gains `source_frames` (per cell, the frame of the cut it is, or null where it was made), and `cell_record` now reads a retimed cut the same way as a cut at `--out-fps`: `source_frame` is the frame the cell is, and for a cell made between two frames the cut's frame at or before its time (the frame the seam reads it as), with that frame's `anchor_move_px` and `scale`. `as_filmed` is true only where the cell's pixels are that frame's pixels anchored before any repair, so a cell that repeats a frame unchanged is as filmed, and a cell made between two frames, a cell moved onto the parabola or along, and every cell of a cut the retime laid on a larger canvas are not as filmed, and `video-sway --read-on-cut` does not pair them. The cells before the take-off that the retime neither moved nor laid on a larger canvas stay as filmed.
- Python callers: `sway_loop`, `sway_frames`, `read_request` and `read_ask` accept `region_over` (bool; default False) and `region_shear` (float; None: off). New in `sprite_gen.video.sway`: `shear_floor`, `layer_sets`, `lay_over`, `cover_depth`, `still_strip`, `tip_shape` and `move_steps`; constants `OVER_POLICY`, `TIP_COLS`, `TIP_AIR`, `TIP_RING`, `TIP_OFF` and `TIP_SEARCH`; `RegionMask` gains `over`, `shear`, `hold` and `edges()`; `Masked` gains `sheared`, `left_out` and `left_out_in(k)`; `rim_bands` gains `floor` (None: as before).
- Python callers: `sway_loop`, `sway_frames`, `read_request` and `read_ask` accept `region_over_solid` (bool; default False), `region_rim_round` (bool; default False) and `region_membrane` (int; None: off); `sway_loop` and `read_request` accept `read_on_cut` (Path; None: off, refused by `sway_frames`). New in `sprite_gen.video.sway`: `membrane_sets`, `membrane_move(free, figure, own, outline, move, reach)`, `recut_pair`, `recut_ask` and `read_cut`; new in `sprite_gen.video.loop`: `ramp_offset`; new in `sprite_gen.video.motion_anchor`: `laid_at`; constants `OVER_SOLID_POLICY`, `MEMBRANE_POLICY`, `RECUT_POLICY`, `RECUT_DRIFT` and `RIM_ROUND_POLICY`; `RegionMask` gains `over_solid`, `membrane` and `rim_round`; `Request` gains `read_on_cut`; `layer_sets(..., solid_only=False)` gains `solid_only` and returns the new set `below`; `read_on_relation(..., cut=False)` gains `cut`; and `transported_motion(..., paired=None)` gains `paired`. New in `sprite_gen.video.sway`: `cell_record(record, strip_sha256)` (the record of a strip's cells, a ValueError naming what it does not give), `recut_same(pair, cut_cell, cell, read_on)` (refuses two paired cells that are not the same pixels at the shift) and `aligned_from(loop_dir, meta_path, meta)` (the cut's record an alignment kept, or None); `recut_pair(meta, cut, read_on, *, strip_sha256, kept=None)` takes this loop's strip sha256 and the kept record; `read_cut` returns the strip picture under `strip`; `Request` gains `aligned_from`; new in `sprite_gen.video.loop`: constants `CELL_RECORD`, `CELL_SCALE_STEPS` and `MOTION_RECIPE`.
- **Tests**: new file `tests/video/test_sway_region_over.py` covers these cases on synthetic figures (the region test's body and its striped part over the torso's right side and past it over the air, with a dark crease under it on the torso; an arm block beside the part's lower left; a dark outline row under the part where it hangs over the air). Each case first reads what a sway writes with the new options (its cells, its record), so on a release without them the same input fails on what comes out:
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index 9157a64..aff0d30 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -2806,9 +2806,9 @@ time of its own, made by RIFE between the frames beside it, judged as the fill's
again. A loop has round(L x F / fps) cells over its cycle's seconds, at times k x L / cells; a cut played once runs
from its first frame to its last, round((L - 1) x F / fps) + 1 cells, each 1/F. A cell on a frame's time is that
frame; one between two frames showing one picture (a hold kept) is that picture; one no frame made is taken for is
-the nearer frame, named (`out_fps.shown_again`). The record's `out_fps.shows` gives the frame each cell is (null
-where it was made), which the strip record's `cell_record` reads (`docs/video-pipeline.md` section 6). `cycle/` holds
-every cell; the strip holds them up to its cell and
+the nearer frame, named (`out_fps.shown_again`). The record's `out_fps.source_frames` gives the frame each cell is
+(null where it was made), which the strip record's `cell_record` reads for its `source_frame` (`docs/video-pipeline.md`
+section 6). `cycle/` holds every cell; the strip holds them up to its cell and
width caps, subsampled past them as any strip is (`subsampled`). The strip metadata says `out_fps` and `source_fps`,
and `source_cut.times` in place of `samples`. With no RIFE the cut is delivered at its own rate with a `warning:` line
and `out_fps.applied` false. `video-cycle-align` and `video-stop` refuse such a loop (each makes its own frames
diff --git a/sprite_gen/video/held_fill.py b/sprite_gen/video/held_fill.py
index 446b643..37e41b0 100644
--- a/sprite_gen/video/held_fill.py
+++ b/sprite_gen/video/held_fill.py
@@ -289,7 +289,7 @@ def at_times(frames: list[Image.Image], interpolate: rife_mod.Interpolate, at: S
showing one picture is that picture, any other is made between the two at its own time (`_made`, within half its
`spacing` of it: frames a cell, one for all or one each), and one no frame made is taken for is the nearer frame and
named (`shown_again`). The record: how many were made, the cells shown again, how each was (`frames`), and the
- frame each cell is, None where it was made (`shows`)."""
+ frame each cell is, None where it was made (`source_frames`)."""
n = len(frames)
same = same_steps(frames + ([frames[0]] if ring else []))
if reads is None:
@@ -297,32 +297,32 @@ def at_times(frames: list[Image.Image], interpolate: rife_mod.Interpolate, at: S
out: list[Image.Image] = []
made: list[dict[str, Any]] = []
shown_again: list[int] = []
- shows: list[int | None] = []
+ source_frames: list[int | None] = []
for k, tau in enumerate(at):
near = round(tau)
if abs(tau - near) <= SNAP:
out.append(frames[near % n])
- shows.append(near % n)
+ source_frames.append(near % n)
continue
a = math.floor(tau)
if same[a]:
out.append(frames[a])
- shows.append(a)
+ source_frames.append(a)
continue
t = tau - a
half = (spacing if isinstance(spacing, (int, float)) else spacing[k]) / 2
frame, how = _made(interpolate, frames[a], frames[(a + 1) % n], t, (t - half, t + half), reads=reads)
if frame is None:
out.append(frames[near % n])
- shows.append(near % n)
+ source_frames.append(near % n)
shown_again.append(k)
made.append({"cell": k, "between": [a, (a + 1) % n], "taken": near % n, **how})
continue
out.append(frame)
- shows.append(None)
+ source_frames.append(None)
made.append({"cell": k, "between": [a, (a + 1) % n], **how})
return out, {"made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made,
- "shows": shows}
+ "source_frames": source_frames}
def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ring: bool, fps: float, out_fps: float,
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index db390f1..1b0f01a 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -2238,7 +2238,7 @@ def _cell_record(strip_bytes: bytes, cells: list[Image.Image], *, start: int, le
def frame(c: int) -> int:
if upsampled is None:
return c
- shown = upsampled["shows"][c]
+ shown = upsampled["source_frames"][c]
return shown if shown is not None else min(length - 1, math.floor(upsampled["times"][c]))
return {"strip_sha256": evidence_mod.digest(strip_bytes), "cells": [
@@ -2927,7 +2927,7 @@ def _cut_loop(
record = report_base["air_retime"]
held_record["out_fps"] = {"asked": out_fps, "fps": fps, "applied": True, "cells": len(frames),
"times": [round(x, 4) for x in upsampled], "made": record["made"],
- "shown_again": record["shown_again"], "shows": retimed["shows"]}
+ "shown_again": record["shown_again"], "source_frames": retimed["source_frames"]}
if out_fps is not None and retimed is None:
# A rate above the clip's: every cell at its own time, made between the frames beside it (held_fill.upsample).
try:
diff --git a/sprite_gen/video/root_motion.py b/sprite_gen/video/root_motion.py
index b93e978..8194418 100644
--- a/sprite_gen/video/root_motion.py
+++ b/sprite_gen/video/root_motion.py
@@ -228,7 +228,7 @@ def retime(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, fps:
"""The cut with each air that has a take-off and a landing retimed (see the module), at `rate` cells a second.
`times` are the frames' times in frames of the clip (for the declared contacts). Returns the frames, the record, and
what the cut's reading needs where it was retimed (None where not): each cell's time in frames of the cut (`times`),
- the frame each cell is, None where it was made (`shows`, held_fill.at_times'), what each cell touches (`touch`), and
+ the frame each cell is, None where it was made (`source_frames`, held_fill.at_times'), what each cell touches (`touch`), and
the canvas the cells were moved on (`offset`, where the frames' (0, 0) is)."""
L = len(frames)
roots, touch = reading(frames, floor=floor, times=times, declared=declared)
@@ -332,7 +332,7 @@ def retime(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, fps:
record.update(applied=True, rate=rate, air=airs, made=made["made"], shown_again=made["shown_again"],
canvas_offset=list(offset), **held_fill_mod.reading(same))
record["frames"] = made["frames"]
- return out, record, {"times": at, "shows": made["shows"], "touch": cell_touch, "offset": offset}
+ return out, record, {"times": at, "source_frames": made["source_frames"], "touch": cell_touch, "offset": offset}
def public(record: dict[str, Any]) -> dict[str, Any]:
diff --git a/tests/video/test_held_fill.py b/tests/video/test_held_fill.py
index 1840887..67ef537 100644
--- a/tests/video/test_held_fill.py
+++ b/tests/video/test_held_fill.py
@@ -357,7 +357,7 @@ def test_a_walk_asked_for_at_60_fps_is_made_of_frames_between(tmp_path):
def test_a_cut_at_a_rate_of_its_own_records_each_cell_as_the_frame_it_is_and_a_cell_made_between_as_not_filmed(tmp_path):
# The strip's record of its cells (`cell_record`, video-sway --read-on-cut) of a walk that shows frame 9 twice, its
# held cells kept, at --out-fps 49: a cell that is a frame (on its time, a hair before it, or between the two frames
- # of one picture, that picture again; `out_fps.shows`) is that frame as filmed; one made between two frames reads
+ # of one picture, that picture again; `out_fps.source_frames`) is that frame as filmed; one made between two frames reads
# as the frame before its time, is not as filmed but where its pixels are that frame's, and --read-on-cut does not
# pair it.
clip, between = shown_again(walk(), {9: 2}), Between(walk_at, range(N + 6), period=N)
@@ -369,11 +369,11 @@ def test_a_cut_at_a_rate_of_its_own_records_each_cell_as_the_frame_it_is_and_a_c
cells = sway.cell_record(own, _sha(Path(rep["strip"]["path"])))
shown = _cycle(rep)
kinds = []
- for c, (cell, times, shows) in enumerate(zip(cells, record["times"], record["shows"])):
+ for c, (cell, times, source) in enumerate(zip(cells, record["times"], record["source_frames"])):
assert cell["anchor_move_px"] == [0, 0] and cell["scale"] == {"size_hold": 1.0, "gait_fallback": 1.0}
frame = clip[cell["source_frame"]].tobytes()
- if shows is not None:
- assert cell["source_frame"] == shows and cell["as_filmed"] is True and shown[c].tobytes() == frame
+ if source is not None:
+ assert cell["source_frame"] == source and cell["as_filmed"] is True and shown[c].tobytes() == frame
kinds.append("on" if abs(times - round(times)) <= held_fill.SNAP else "again")
else:
# the stand-in draws the walk again at the cell's time: now and then that is a frame's own picture
diff --git a/tests/video/test_root_motion.py b/tests/video/test_root_motion.py
index 206f90f..7a00f3e 100644
--- a/tests/video/test_root_motion.py
+++ b/tests/video/test_root_motion.py
@@ -217,7 +217,7 @@ def test_no_rife_leaves_the_air_as_filmed_and_says_which_motion(tmp_path, monkey
def test_a_retimed_cut_records_each_cell_as_the_frame_it_is_and_a_cell_made_or_moved_as_not_filmed(tmp_path):
"""The strip's record of its cells (`cell_record`, video-sway --read-on-cut) of the jump with its air half as long
- again, on the clip's own canvas: a cell held_fill.at_times takes as a frame (`shows`) is that frame, one made between
+ again, on the clip's own canvas: a cell held_fill.at_times takes as a frame (`source_frames`) is that frame, one made between
two frames reads as the frame before its time; the cells up to the take-off are their frames as filmed, and no air
cell (made, or moved onto the parabola) nor any from the landing on (moved along) is, so --read-on-cut does not
pair it."""