Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video-loop): cells are scaled with coverage and colour apart, so an edge gets no light rim or green tint
Soohong Kim7efd2bdec405
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7df38f7..019e71f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,10 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased - A loop's cells are scaled without a light rim or a green tint at the edge++- **`video-loop` scales its cells with coverage and colour taken apart** (`resize_cell`, used by `build_strip`, so the strip, the GIF, the WebP and `video-cycle-align`'s rebuild all get it). The strip used LANCZOS over premultiplied RGBA, whose negative lobes weigh the colours across an edge against each other and then divide by the edge's low coverage; on a keyed frame, whose edge holds a light rim outside a dark outline and ink with a little of the key's green, a scaled cell drew a lighter rim and greener ink than the frame had. Coverage now keeps LANCZOS's edge, held between the least and the most coverage of the source pixels the colour mixes from (no halo outside the silhouette, no hole inside it); colour is a Hamming mix of premultiplied colour, which has no negative lobe, so every pixel's colour is a mix of the colours under it. On a synthetic outlined figure (`tests/video/test_strip_resample.py`), LANCZOS left 1,462 pixels at 0.97x and 1,750 at 1.03x with a colour none of the source pixels under them had, and none are left now; the strands, 0.5-1.4 px wide, keep LANCZOS's coverage. Colour is no longer sharpened, so a 1 px line inside the body is a little softer when a cell is enlarged. A cell at its own size is copied as it is, as before. [docs/video-pipeline.md](docs/video-pipeline.md).+## v2.18.0 - A walk's jumping frames are remade by RIFE, its jolt is measured, and a direction set shares one cycle- **Jump frames are repaired** (`video-loop --repair auto`, the default for walk and run): a step whose coverage change is 1.4x the loop's median, over the whole body or the hair behind it (`--facing left` mirrors that box), is a jump, and the frame that broke it is replaced by the RIFE frame half way between its two neighbours — at most three, worst first, never next to a frame already made; every other frame stays the video's own. A single stray frame, which breaks the step into it and out of it, is the one remade. The report's `jump_repair` names the frames, the scores before and after and the interpolator; with a frame replaced the seam gate reads the rendered cells. `--repair off` cuts as filmed. On the 2026-10-03 eight-direction set it replaces the frames the experiment did in 8 of 10 views (the other two differ by one frame).diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex d70656a..b94bcaa 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -499,6 +499,20 @@ Outputs:which (`body_ref`: `first-frame` or `tallest-grounded`) and records `body_src_h` and `scale`. `delay_ms = cycle_seconds / frames`, so a24 fps clip yields 41.67 ms cells; render at 24 fps to keep one cell per frame(a 30 fps render of 24 fps cells is a 5:4 pulldown and judders).+- **Cells** are scaled with their coverage and their colour taken apart (`resize_cell`; a cell+ at its own size is copied as it is). Coverage keeps LANCZOS's edge, held between the least and+ the most coverage of the source pixels the colour mixes from, so nothing spills outside the+ silhouette and nothing opens inside it. Colour is a Hamming mix of premultiplied colour, a+ filter with no negative lobe, so every pixel's colour is a mix of the colours under it. The+ strip used LANCZOS over premultiplied RGBA before, which weighs the colours across an edge+ against each other and divides by the edge's low coverage: on a keyed frame, whose edge holds+ a light rim and ink with a little of the key's green, it drew a lighter rim and greener ink+ than the frame had. On the synthetic outlined figure in `tests/video/test_strip_resample.py`+ (a light rim, green-tinted ink, strands 0.5-1.4 px wide), LANCZOS left 1,462 pixels at 0.97x+ and 1,750 at 1.03x with a colour none of the source pixels under them had; the split leaves+ none, and the strands keep LANCZOS's coverage. Colour is no longer sharpened, so a 1 px line+ inside the body comes out a little softer than LANCZOS drew it when a cell is enlarged. The+ GIF and WebP are cut from these cells.- `<name>.gif` — `n_out` frames evenly across the cycle, 1-bit alpha, disposal 2, `loop=0`.`n_out` is a **playback density, not a fixed count**: `round(cycle_seconds × --gif-fps)`(default 24 fps = the source rate, so every cycle frame is kept; floor 4, never more thandiff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex a69a28e..7e3aaa1 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -607,6 +607,61 @@ def first_frame_height(path: Path) -> int:return box[3] - box[1]+def _support_bounds(n_src: int, n_out: int, support: float) -> tuple[np.ndarray, np.ndarray]:+ """First and last source index Pillow's resample reads for each output index, for a filter+ of `support` source pixels (`precompute_coeffs` in Pillow's Resample.c: the support widens+ by the scale when shrinking)."""+ scale = n_src / n_out+ reach = support * max(1.0, scale)+ centre = (np.arange(n_out) + 0.5) * scale+ lo = np.clip(np.floor(centre - reach + 0.5).astype(int), 0, n_src - 1)+ hi = np.clip(np.floor(centre + reach + 0.5).astype(int) - 1, 0, n_src - 1)+ return lo, np.maximum(lo, hi)+++def _window_extrema(a: np.ndarray, rows: tuple[np.ndarray, np.ndarray], cols: tuple[np.ndarray, np.ndarray]) -> tuple[np.ndarray, np.ndarray]:+ """Min and max of `a` over each output pixel's source window (separable, rows then columns)."""+ def along(v: np.ndarray, lo: np.ndarray, hi: np.ndarray, axis: int) -> tuple[np.ndarray, np.ndarray]:+ low = high = np.take(v, lo, axis=axis)+ for d in range(1, int((hi - lo).max()) + 1):+ step = np.take(v, np.minimum(lo + d, hi), axis=axis)+ low, high = np.minimum(low, step), np.maximum(high, step)+ return low, high++ lo_c, hi_c = along(a, *cols, axis=1)+ return along(lo_c, *rows, axis=0)[0], along(hi_c, *rows, axis=0)[1]+++def resize_cell(image: Image.Image, size: tuple[int, int]) -> Image.Image:+ """Scale one RGBA cell with its coverage and its colour taken apart.++ LANCZOS over premultiplied RGBA (Pillow's RGBa) rings: its negative lobes weigh the colours+ across an edge against each other, and dividing by the low coverage at the edge throws the+ result past every colour the source had there — a light rim around a dark outline, a key+ tint where the ink was only a little green. So the two are resampled apart. Coverage keeps+ LANCZOS's crisp edge, held to the range of the source coverage the colour mixes from (no+ halo outside the silhouette, no hole inside it). Colour is a Hamming mix of premultiplied+ colour, a filter with no negative lobe: every pixel's colour is a weighted mix of the+ colours under it and never one they did not have. docs/video-pipeline.md "Cells"."""+ if image.size == tuple(size):+ return image.copy()+ w, h = size+ src = np.asarray(image.convert("RGBA"), dtype=np.float32)+ alpha = src[..., 3]++ def scaled(channel: np.ndarray, resample: Image.Resampling) -> np.ndarray:+ return np.asarray(Image.fromarray(np.ascontiguousarray(channel)).resize(size, resample), dtype=np.float32)++ mix_alpha = scaled(alpha, Image.Resampling.HAMMING)+ mix = np.stack([scaled(src[..., c] * alpha, Image.Resampling.HAMMING) for c in range(3)], axis=-1)+ low, high = _window_extrema(alpha, _support_bounds(image.height, h, 1.0), _support_bounds(image.width, w, 1.0))+ cover = np.clip(scaled(alpha, Image.Resampling.LANCZOS), low, high)+ cover = np.where(mix_alpha > 1e-3, np.round(cover), 0)+ colour = np.where((cover > 0)[..., None], np.round(mix / np.maximum(mix_alpha, 1e-3)[..., None]), 0)+ out = np.dstack([np.clip(colour, 0, 255), np.clip(cover, 0, 255)]).astype(np.uint8)+ return Image.fromarray(out, "RGBA")++def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS, max_height: int = STRIP_MAX_HEIGHT, max_width: int = STRIP_MAX_WIDTH, cycle_seconds: float, body_height: int | None = None, anchor: str = "none", kind: str = "periodic", standing_src: int | None = None) -> tuple[Image.Image, dict[str, Any]]:"""Union-crop (no bottom pad so feet meet the floor), scale, bottom-align, tile horizontally.@@ -666,9 +721,9 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,im = frames[i]cell = Image.new("RGBA", (round(cell_src_w), bottom - top), (0, 0, 0, 0))cell.alpha_composite(im.crop((0, top, im.width, bottom)), (round(lead - feet[i]), 0))- cells.append(cell.resize((w, h), Image.LANCZOS))+ cells.append(resize_cell(cell, (w, h)))else:- cells = [im.crop((left, top, right, bottom)).resize((w, h), Image.LANCZOS) for im in chosen]+ cells = [resize_cell(im.crop((left, top, right, bottom)), (w, h)) for im in chosen]strip = Image.new("RGBA", (w * len(cells), h), (0, 0, 0, 0))for k, im in enumerate(cells):strip.alpha_composite(im, (k * w, 0))diff --git a/tests/video/test_strip_resample.py b/tests/video/test_strip_resample.pynew file mode 100644index 0000000..9b68cde--- /dev/null+++ b/tests/video/test_strip_resample.py@@ -0,0 +1,198 @@+"""`video-loop` cells are scaled without a ring at the edge.++A keyed frame's edge holds what the keyer left there: a light rim outside a dark outline,+ink carrying a little of the key's green, half-covered strands. LANCZOS over premultiplied+RGBA weighs the colours across that edge against each other and divides by the edge's low+coverage, so a scaled cell carried colour that no source pixel near it had: a lighter rim,+greener ink. `resize_cell` scales coverage and colour apart: coverage keeps LANCZOS's edge,+held to the range of the coverage under it; colour is a Hamming mix of premultiplied colour.++The figure is synthetic and area-sampled: a dark-outlined body (a skin half and a white+half), a light rim outside part of the outline, green-tinted ink along another part, a+1 px line across the body, a hair cap with strands 0.5-1.4 px wide.+"""+from __future__ import annotations++import math++import numpy as np+import pytest+from PIL import Image++from sprite_gen.video import loop++SS = 4 # supersamples per pixel side+OUTLINE = (28, 18, 16)+INK_GREEN = (21, 27, 2)+SKIN = (238, 206, 178)+SHIRT = (245, 245, 240)+HAIR = (170, 52, 36)+RIM = (235, 228, 196)+BODY = (80.0, 120.0, 46.0, 2.2) # centre x, centre y, radius, outline width+CAP = (80.0, 58.0, 30.0, 1.6)+STRANDS = [(-150, 0.5, 18), (-125, 0.7, 20), (-100, 1.0, 18), (-60, 1.4, 16), (-35, 0.8, 18)] # degrees, width, length+SCALES = (0.5, 0.9662, 1.0256, 1.5)+++def _strand(deg: float) -> tuple[float, float, float, float]:+ t = math.radians(deg)+ return CAP[0] + (CAP[2] - 1) * math.cos(t), CAP[1] + (CAP[2] - 1) * math.sin(t), math.cos(t), math.sin(t)+++def _figure(shift: float = 0.0, width: int = 160, height: int = 180) -> Image.Image:+ ys, xs = np.mgrid[0 : height * SS, 0 : width * SS]+ X = (xs + 0.5) / SS - shift+ Y = (ys + 0.5) / SS - shift+ rgb = np.zeros(X.shape + (3,))+ a = np.zeros(X.shape)++ def paint(mask: np.ndarray, colour: tuple[int, int, int]) -> None:+ rgb[mask] = colour+ a[mask] = 1.0++ cx, cy, r, t = BODY+ rb = np.hypot(X - cx, Y - cy)+ ang = np.degrees(np.arctan2(Y - cy, X - cx))+ paint((rb < r + t + 0.6) & (ang > -40) & (ang < 50), RIM)+ paint(rb < r + t, OUTLINE)+ paint((rb < r + t) & (ang > 100) & (ang < 170), INK_GREEN)+ paint((rb < r) & (Y < cy), SKIN)+ paint((rb < r) & (Y >= cy), SHIRT)+ paint((rb < r) & (np.abs(Y - (cy + 18.3)) < 0.5), OUTLINE)+ qx, qy, qr, qt = CAP+ rc = np.hypot(X - qx, Y - qy)+ paint((rc < qr + qt) & (Y < qy + 2), OUTLINE)+ paint((rc < qr) & (Y < qy), HAIR)+ for deg, thick, length in STRANDS:+ x0, y0, dx, dy = _strand(deg)+ along = np.clip((X - x0) * dx + (Y - y0) * dy, 0, length)+ paint(np.hypot(X - (x0 + along * dx), Y - (y0 + along * dy)) < thick / 2, HAIR)+ A = a.reshape(height, SS, width, SS).mean(axis=(1, 3))+ P = (rgb * a[..., None]).reshape(height, SS, width, SS, 3).mean(axis=(1, 3))+ C = np.where(A[..., None] > 0, P / np.maximum(A[..., None], 1e-9), 0)+ return Image.fromarray(np.dstack([C.round(), (A * 255).round()]).astype(np.uint8), "RGBA")+++def _size(image: Image.Image, scale: float) -> tuple[int, int]:+ return round(image.width * scale), round(image.height * scale)+++def _windows(n_src: int, n_out: int) -> list[range]:+ """Source pixels whose centre lies within the Hamming filter's reach of each output pixel's centre."""+ ratio = n_src / n_out+ reach = max(1.0, ratio)+ out = []+ for k in range(n_out):+ c = (k + 0.5) * ratio+ out.append(range(max(0, math.ceil(c - reach - 0.5)), min(n_src - 1, math.floor(c + reach - 0.5)) + 1))+ return out+++def _neighbour_ranges(src: Image.Image, size: tuple[int, int]):+ s = np.asarray(src).astype(int)+ rows, cols = _windows(src.height, size[1]), _windows(src.width, size[0])+ lo = np.full((size[1], size[0], 3), 256)+ hi = np.full((size[1], size[0], 3), -1)+ amin = np.full((size[1], size[0]), 255)+ amax = np.zeros((size[1], size[0]), int)+ for v, ry in enumerate(rows):+ for u, rx in enumerate(cols):+ block = s[ry.start : ry.stop, rx.start : rx.stop].reshape(-1, 4)+ amin[v, u], amax[v, u] = block[:, 3].min(), block[:, 3].max()+ seen = block[block[:, 3] > 0, :3]+ if len(seen):+ lo[v, u], hi[v, u] = seen.min(axis=0), seen.max(axis=0)+ return lo, hi, amin, amax+++def _colour_outside(src: Image.Image, out: Image.Image) -> int:+ """Visible output pixels (alpha >= 38) whose colour is more than one level outside the range of+ the visible source pixels under them."""+ lo, hi, _, _ = _neighbour_ranges(src, out.size)+ o = np.asarray(out).astype(int)+ seen = o[..., 3] >= 38+ outside = ((o[..., :3] < lo - 1) | (o[..., :3] > hi + 1)).any(axis=-1)+ return int(np.count_nonzero(seen & outside))++[email protected]("scale", SCALES)+def test_cell_colour_is_always_a_mix_of_the_colours_under_it(scale: float) -> None:+ src = _figure()+ size = _size(src, scale)+ assert _colour_outside(src, loop.resize_cell(src, size)) == 0+ # the filter it replaces put colour there that nothing under it had+ assert _colour_outside(src, src.resize(size, Image.Resampling.LANCZOS)) > 100++[email protected]("scale", SCALES)+def test_cell_coverage_has_no_halo_and_no_hole(scale: float) -> None:+ src = _figure(shift=0.37)+ size = _size(src, scale)+ _, _, amin, amax = _neighbour_ranges(src, size)+ a = np.asarray(loop.resize_cell(src, size))[..., 3].astype(int)+ assert ((a >= amin) & (a <= amax)).all()+ # LANCZOS dips inside the silhouette and spills past it+ lz = np.asarray(src.resize(size, Image.Resampling.LANCZOS))[..., 3].astype(int)+ assert np.count_nonzero((lz < amin) | (lz > amax)) > 20+++def _strand_peaks(image: Image.Image, scale_xy: tuple[float, float], shift: float) -> list[float]:+ a = np.asarray(image)[..., 3] / 255.0+ h, w = a.shape+ peaks = []+ for deg, _, length in STRANDS:+ x0, y0, dx, dy = _strand(deg)+ found = []+ for t in np.arange(0.3 * length, 0.9 * length, 0.5):+ px, py = (x0 + t * dx + shift) * scale_xy[0], (y0 + t * dy + shift) * scale_xy[1]+ near = [a[v, u] for v in range(int(py) - 2, int(py) + 3) for u in range(int(px) - 2, int(px) + 3)+ if 0 <= u < w and 0 <= v < h and math.hypot(u + 0.5 - px, v + 0.5 - py) <= 1.0]+ found.append(max(near))+ peaks.append(float(np.mean(found)))+ return peaks++[email protected]("scale", SCALES)+def test_strands_keep_the_coverage_lanczos_gave_them(scale: float) -> None:+ for shift in (0.0, 0.25, 0.5, 0.75):+ src = _figure(shift=shift)+ size = _size(src, scale)+ sxy = (size[0] / src.width, size[1] / src.height)+ new = _strand_peaks(loop.resize_cell(src, size), sxy, shift)+ old = _strand_peaks(src.resize(size, Image.Resampling.LANCZOS), sxy, shift)+ assert min(n - o for n, o in zip(new, old)) >= -0.03, (shift, new, old)+++def test_a_cell_at_its_own_size_is_untouched() -> None:+ src = _figure()+ out = loop.resize_cell(src, src.size)+ assert out is not src and out.tobytes() == src.tobytes()++[email protected]("scale", (0.37, 0.5, 0.9662, 1.0256, 1.5, 2.3))+def test_coverage_clamp_reads_every_pixel_the_colour_filter_mixes(scale: float) -> None:+ n_src = 41+ n_out = round(n_src * scale)+ lo, hi = loop._support_bounds(n_src, n_out, 1.0)+ for x in range(n_src):+ impulse = np.zeros((1, n_src), np.float32)+ impulse[0, x] = 1.0+ response = np.asarray(Image.fromarray(impulse).resize((n_out, 1), Image.Resampling.HAMMING))[0]+ for u in np.nonzero(response > 1e-6)[0]:+ assert lo[u] <= x <= hi[u], (scale, x, u, lo[u], hi[u])++[email protected]("anchor", ("none", "feet"))+def test_build_strip_scales_every_cell_this_way(monkeypatch, anchor: str) -> None:+ frames = [_figure(shift=k * 0.5) for k in range(4)]+ calls: list[tuple[int, int]] = []+ resize_cell = loop.resize_cell++ def spy(image: Image.Image, size: tuple[int, int]) -> Image.Image:+ calls.append(tuple(size))+ return resize_cell(image, size)++ monkeypatch.setattr(loop, "resize_cell", spy)+ _, meta = loop.build_strip(frames, cycle_seconds=0.5, body_height=150, anchor=anchor)+ assert meta["scale"] != 1.0+ assert calls == [(meta["w"], meta["h"])] * meta["frames"]