Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video): video-follow replaces the loop's files only once all of them are written
Soohong Kim0caea29ce1cc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7108eaa..87a2737 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,9 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased+- **Fix: `video-follow` replaces the loop's files only once all of them are written.** The strip, the GIF and the WebP were written over the loop's before the record was, so a run that failed on the record — `follow.follow_loop` given numpy numbers, an int64 of which has no JSON form (`TypeError`) — or on an animation's check left a moved strip beside a record that did not say so. Now the strip, GIF, WebP and record are written and checked in a scratch directory beside the loop (`.follow.*`), each under its own name, and moved over the loop's files after the record is written; a run that fails on the way leaves all four as they were (the strip as cut is still kept as `follow.source.png`, as on a refusal). `follow_loop` reads its regions, `gain`, `freq` and `zeta` as the floats the command line gives, so numpy numbers, or plain ints, write the strip and record that the same numbers as floats write, byte for byte (a caller that passed plain ints finds them recorded as floats, `80.0` where it was `80`). `loop.verify_animation` closes the file it checks. The command's output, its strip, GIF, WebP and record, and `--help` are as before, byte for byte. [docs/video-pipeline.md](docs/video-pipeline.md#6-follow-through--video-follow).+- **`tests/video/test_follow.py`** moves a chest and a smaller head region given as int64, int32, float32, float64 and plain int coordinates, as the rows of an int64 array, and with a float32 `gain`: each writes the strip, GIF, WebP and record the float coordinates write, byte for byte (before this the int64 run failed on the record with the strip already moved). A run made to fail on its record or on its WebP's check, on a loop as cut and on one already followed, leaves the strip, GIF, WebP and record as they were, and nothing beside them but `follow.source.png`.+- **Output change: `video-follow --on-fold lower` gives each region a gain of its own.** One gain for the strip, set by the region with the smallest radius, let the smallest ellipse decide for every part: a small one (an ear) lowered a large one (a chest) to its own gain, and where that gain went under 1 refused the whole strip, so the chest did not move either. Now a region that folds at `--gain` takes the largest gain that does not fold it (in steps of 0.01), a region that does not fold keeps `--gain`, and one that would have to go under 1, the mass as measured, is **held**: it does not move, and stderr names it by its `--region` (`video-follow: --region <cx,cy,rx,ry> folds at --gain <g>, under 1 (the mass as measured): it is held, and does not move`); a region lowered while another keeps its gain is named the same way (`video-follow: --gain 2.5 folds --region <cx,cy,rx,ry> (a move of <px> px); lowered to --gain <g> for it`). The strip is refused only when every region is held, and that message names the largest region (`… folds a region of radius <r> px over itself (the largest of <n> regions: every one folds), and --on-fold lower would have to go under --gain 1 …`); with one region it reads as before. Where regions of different gains overlap, the larger move wins (`follow.move_regions` takes groups of regions, each with its own offset), and the move there is nowhere steeper than either region's own. In the record each `fold.regions` entry gains `gain` (0 when held) and `held`, the strip's `gain` is the largest any region moved by (`dx_px`, `dy_px` and `reach_px` are that gain's), `fold.ratio` is the nearest any region came to folding and `fold.lowered` says whether any region was lowered or held; the printed summary gains `region_gains`. A strip whose regions all take one gain — one region, regions that fold alike, or none that folds — is written as before, strip, GIF, WebP and record byte for byte. `--on-fold refuse`, the default, is unchanged. [docs/video-pipeline.md](docs/video-pipeline.md#6-follow-through--video-follow).- **`tests/video/test_follow.py`** moves a chest with a region on the head too small to move at gain 1: before this the strip was refused, now the head region is held and the strip is the chest's alone, byte for byte (and at `--gain 0.9` the chest still moves at 0.9). A head region that folds at 1.75 beside a chest that does not fold takes 1.75 while the chest keeps 2.5, each region's pixels those of the region moved alone at its gain; a small region inside a larger one folds nowhere; a strip whose every region is held is refused untouched; two regions that fold alike are written with the one-gain record and the strip their gain asked for gives; the command names the region it lowered and the one it held.diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex b9cafe2..a8c7ee1 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -1056,6 +1056,9 @@ sprite-gen video-follow --loop-dir set/front-walk/loop --region 136,164,60,50 [-the nearest any region came to folding. A lowered gain is also named on stderr — per region,with the `--region` it was given, where they differ — and so is a held region; the printedsummary then carries `region_gains`.+ All four are written and checked beside the loop first and moved over its files only once the+ record is written too, so a run that fails on the way — an animation that fails its check, a+ record that does not serialise — leaves the strip, GIF, WebP and record as they were.`cycle/` is left as cut. The strip as it was is kept as `follow.source.png`; running`video-follow` again reads from it, so a second run never moves a moved strip. `--board` writes the cells before and after where the partsits lowest and highest, on white.diff --git a/sprite_gen/video/follow.py b/sprite_gen/video/follow.pyindex 1bb86e5..2345a85 100644--- a/sprite_gen/video/follow.py+++ b/sprite_gen/video/follow.py@@ -35,8 +35,10 @@ from __future__ import annotationsimport argparseimport jsonimport math+import osimport shutilimport sys+import tempfilefrom pathlib import Pathfrom typing import Any@@ -175,6 +177,11 @@ def follow_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]]freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, board: Path | None = None,on_fold: str = "refuse") -> dict[str, Any]:loop_dir = loop_dir.expanduser().resolve()+ # 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.+ regions = [tuple(float(v) for v in region) for region in regions]+ gain, freq, zeta = float(gain), float(freq), float(zeta)metas = sorted(loop_dir.glob("*.strip.json"))if len(metas) != 1:raise SystemExit(f"video-follow: {loop_dir}: expected one <name>.strip.json from video-loop, found {len(metas)}")@@ -228,7 +235,7 @@ def follow_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]]gains = [lowered_gain(requested, reach_per_gain, radius) if fold else requested for radius, fold in zip(radii, folds)]# One that would have to go under the mass as measured does not move at all; the strip is# refused only when that is every region.- held = [bool(fold and g < GAIN_MEASURED) for fold, g in zip(folds, gains)] # numpy radii compare to numpy bools+ held = [fold and g < GAIN_MEASURED for fold, g in zip(folds, gains)]if all(held):k = radii.index(max(radii)) # the largest folds at the largest gain: if it is held, every region isevery = f" (the largest of {len(regions)} regions: every one folds)" if len(regions) > 1 else ""@@ -251,33 +258,43 @@ def follow_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]]joined = Image.new("RGBA", (w * n, h), (0, 0, 0, 0))for k, c in enumerate(out):joined.alpha_composite(c, (k * w, 0))- joined.save(strip_path)delay_ms = max(20, round(float(meta["delay_ms"])))gif_path, webp_path = loop_dir / f"{name}.gif", loop_dir / f"{name}.webp"- save_clean_gif(out, gif_path, duration_ms=delay_ms, loop=0, alpha_threshold=128)- loop_mod.write_webp(out, webp_path, delay_ms=delay_ms, workdir=loop_dir / ".webp-frames")- shutil.rmtree(loop_dir / ".webp-frames", ignore_errors=True)- record = {- "regions": [list(r) for r in regions], "gain": gain, "freq_hz": freq, "zeta": zeta, "harmonics": HARMONICS,- "source": SOURCE, "body_px": height0,- "body_bob_px": [round(float(np.ptp(cols)), 2), round(float(np.ptp(rows)), 2)],- "dx_px": np.round(dx, 2).tolist(), "dy_px": np.round(dy, 2).tolist(),- "reach_px": round(reach, 2),- "gain_requested": requested, "on_fold": on_fold,- "fold": {- "lowered": any(g != requested for g in gains), "ratio": round(max(ratios), 3),- "reach_requested_px": round(reach_requested, 2), "reach_per_gain_px": round(reach_per_gain, 3),- # Where the regions took gains of their own, each says the gain it moved by and whether it- # was held still (gain 0); where they all took one, the strip's `gain` is every region's.- "regions": [{"radius_px": radius, "ratio": round(ratio, 3),- "gain_limit": None if (limit := gain_limit(reach_per_gain, radius)) is None else round(limit, 3)}- | ({} if len(set(gains)) == 1 else {"gain": g, "held": hold})- for radius, ratio, g, hold in zip(radii, ratios, gains, held)],- },- "gif": loop_mod.verify_animation(gif_path, expect_frames=n, check_stale=False),- "webp": loop_mod.verify_animation(webp_path, expect_frames=n, check_stale=True),- }- atomic_write_text(meta_path, json.dumps({**meta, "follow": record}, indent=2) + "\n")+ # Written and checked beside the loop first, each under its own name, and moved over the loop's files+ # only once the record is written too: a run that fails on the way (an animation that fails its check, a+ # record that does not serialise) leaves the strip, its animations and its record as they were. Staged as+ # files, not as payloads in memory (runio.atomic_write_set): img2webp writes a file, and the check reads one.+ stage = Path(tempfile.mkdtemp(prefix=".follow.", dir=loop_dir))+ try:+ staged = {path: stage / path.name for path in (strip_path, gif_path, webp_path, meta_path)}+ joined.save(staged[strip_path])+ save_clean_gif(out, staged[gif_path], duration_ms=delay_ms, loop=0, alpha_threshold=128)+ loop_mod.write_webp(out, staged[webp_path], delay_ms=delay_ms, workdir=stage / ".webp-frames")+ record = {+ "regions": [list(r) for r in regions], "gain": gain, "freq_hz": freq, "zeta": zeta, "harmonics": HARMONICS,+ "source": SOURCE, "body_px": height0,+ "body_bob_px": [round(float(np.ptp(cols)), 2), round(float(np.ptp(rows)), 2)],+ "dx_px": np.round(dx, 2).tolist(), "dy_px": np.round(dy, 2).tolist(),+ "reach_px": round(reach, 2),+ "gain_requested": requested, "on_fold": on_fold,+ "fold": {+ "lowered": any(g != requested for g in gains), "ratio": round(max(ratios), 3),+ "reach_requested_px": round(reach_requested, 2), "reach_per_gain_px": round(reach_per_gain, 3),+ # Where the regions took gains of their own, each says the gain it moved by and whether it+ # was held still (gain 0); where they all took one, the strip's `gain` is every region's.+ "regions": [{"radius_px": radius, "ratio": round(ratio, 3),+ "gain_limit": None if (limit := gain_limit(reach_per_gain, radius)) is None else round(limit, 3)}+ | ({} if len(set(gains)) == 1 else {"gain": g, "held": hold})+ for radius, ratio, g, hold in zip(radii, ratios, gains, held)],+ },+ "gif": loop_mod.verify_animation(staged[gif_path], expect_frames=n, check_stale=False),+ "webp": loop_mod.verify_animation(staged[webp_path], expect_frames=n, check_stale=True),+ }+ atomic_write_text(staged[meta_path], json.dumps({**meta, "follow": record}, indent=2) + "\n")+ for path, written in staged.items(): # the record last, as it was written last+ os.replace(written, path)+ finally:+ shutil.rmtree(stage, ignore_errors=True)if board is not None:_board(cells, out, dy, board)record["board"] = str(board)diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 6545ed9..e9fb15e 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -833,19 +833,20 @@ def write_webp(frames: list[Image.Image], out: Path, *, delay_ms: int, workdir:def verify_animation(path: Path, *, expect_frames: int, check_stale: bool) -> dict[str, Any]:- im = Image.open(path)- n = getattr(im, "n_frames", 1)- loop = im.info.get("loop")- corners_ok = True- stale = 0- for k in range(n):- im.seek(k)- f = im.convert("RGBA")- w, h = f.size- corners_ok &= all(f.getpixel(c)[3] == 0 for c in ((0, 0), (w - 1, 0), (0, h - 1), (w - 1, h - 1)))- if check_stale:- stale += sum(1 for p in f.get_flattened_data() if p[3] == 0 and (p[0] or p[1] or p[2]))- report = {"file": path.name, "format": im.format, "n_frames": n, "loop": loop, "size": list(im.size), "corners_transparent": corners_ok, "stale_rgb_under_alpha0": stale, "bytes": path.stat().st_size}+ # Closed on the way out: `video-follow` checks its animations before it moves them over the loop's.+ with Image.open(path) as im:+ n = getattr(im, "n_frames", 1)+ loop = im.info.get("loop")+ corners_ok = True+ stale = 0+ for k in range(n):+ im.seek(k)+ f = im.convert("RGBA")+ w, h = f.size+ corners_ok &= all(f.getpixel(c)[3] == 0 for c in ((0, 0), (w - 1, 0), (0, h - 1), (w - 1, h - 1)))+ if check_stale:+ stale += sum(1 for p in f.get_flattened_data() if p[3] == 0 and (p[0] or p[1] or p[2]))+ report = {"file": path.name, "format": im.format, "n_frames": n, "loop": loop, "size": list(im.size), "corners_transparent": corners_ok, "stale_rgb_under_alpha0": stale, "bytes": path.stat().st_size}problems = []if n != expect_frames:problems.append(f"{n} frames, expected {expect_frames}")diff --git a/tests/video/test_follow.py b/tests/video/test_follow.pyindex 63918ff..520966b 100644--- a/tests/video/test_follow.py+++ b/tests/video/test_follow.py@@ -358,6 +358,56 @@ def test_the_command_names_the_regions_it_lowered_and_held(loop_dir, capsys):assert held.startswith(f'video-follow: {names[2]} folds at --gain 0.') and held.endswith('under 1 (the mass as measured): it is held, and does not move')+def outputs(loop_dir):+ """What a follow-through writes over the loop, by name."""+ return {name: (loop_dir/name).read_bytes() for name in ('walk.strip.png', 'walk.gif', 'walk.webp', 'walk.strip.json')}+++def test_numpy_numbers_write_what_the_command_line_writes(loop_dir):+ # The command line gives floats. Numpy numbers from a caller wrote the strip, the GIF and the WebP and then+ # failed on the record (an int64 has no JSON form): a moved strip beside a record that does not say so.+ chest = tuple(float(round(v)) for v in chest_region(loop_dir))+ head = tuple(float(round(v)) for v in head_region(loop_dir, 0.7)) # folds at the default gain; the chest does not+ given = follow.follow_loop(loop_dir, [chest, head], on_fold='lower')+ assert 'held' in given['fold']['regions'][0] # the regions took gains of their own+ written = outputs(loop_dir)+ for kind in (np.int64, np.int32, np.float32, np.float64, int):+ result = follow.follow_loop(loop_dir, [tuple(kind(v) for v in r) for r in (chest, head)], on_fold='lower')+ assert outputs(loop_dir) == written, kind+ assert json.dumps(result) == json.dumps(given), kind+ # The regions as the rows of an array, and the settings as numpy numbers.+ result = follow.follow_loop(loop_dir, np.asarray([chest, head], dtype=np.int64), gain=np.float32(follow.GAIN_DEFAULT),+ freq=np.float64(follow.FREQ_DEFAULT), zeta=np.float64(follow.ZETA_DEFAULT), on_fold='lower')+ assert outputs(loop_dir) == written and json.dumps(result) == json.dumps(given)++[email protected]('failure', ['record', 'animation'])[email protected]('followed', [False, True])+def test_a_run_that_fails_leaves_the_loop_as_it_was(loop_dir, monkeypatch, failure, followed):+ # The strip and its animations were written over the loop's before the record was: a record that did not+ # serialise, or an animation that failed its check, left them moved beside a record that does not say so.+ region = chest_region(loop_dir)+ if followed:+ follow.follow_loop(loop_dir, [region])+ before, names = outputs(loop_dir), sorted(p.name for p in loop_dir.iterdir())+ as_cut = (loop_dir/follow.SOURCE).read_bytes() if followed else before['walk.strip.png']+ check = loop.verify_animation++ def failing(path, **kw):+ report = check(path, **kw)+ if failure == 'animation' and path.suffix == '.webp':+ raise SystemExit(f'video-loop: {path.name} failed verification: forced')+ return report | ({'forced': object()} if failure == 'record' else {})++ monkeypatch.setattr(loop, 'verify_animation', failing)+ with pytest.raises(TypeError if failure == 'record' else SystemExit):+ follow.follow_loop(loop_dir, [region], gain=1.5)+ assert outputs(loop_dir) == before+ # Nothing is left beside the loop but the strip as cut, kept as on any refusal.+ assert sorted(p.name for p in loop_dir.iterdir()) == sorted({*names, follow.SOURCE})+ assert (loop_dir/follow.SOURCE).read_bytes() == as_cut++def test_bad_regions_are_refused(loop_dir):with pytest.raises(SystemExit, match='outside'):follow.follow_loop(loop_dir, [(9999, 10, 5, 5)])