Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(scene): a strip's cells are read at its exact rate (its `fps`, or a `delay_ms` within 0.01 ms of a whole rate read as that rate), so a frame on a cell boundary of a 24, 60 or 15 fps strip shows the cell that starts there; a layer cut from a filmed clip that would show a cell again is given at the scene's times with RIFE's frames between, held on purpose stays held, and each layer's repeats are reported
Soohong Kim11c486aa688c
diff --git a/docs/scene.md b/docs/scene.mdindex 20993ea..414ec3b 100644--- a/docs/scene.md+++ b/docs/scene.md@@ -32,6 +32,25 @@ sprite-gen scene-inspect --spec scene.json --out scene-check.jsonFor animations, replace the PNG reference with an [external frame descriptor, loop strip or runtime atlas](asset-tools.md#shared-asset-input). Add `"state": "walk"` to an atlas reference when it has several states. Paths resolve relative to the scene spec; frame/image paths within asset descriptors resolve relative to those descriptors. Asset timing and anchors stay in the asset metadata.+A loop strip's cells play at the strip's own rate: its `fps` (`video-loop` writes it, unrounded to six places), or, on a strip written before it, its `delay_ms`. A `delay_ms` with a fraction of a millisecond that lies within 0.01 ms of 1000 over a whole number is that rate (41.67 ms is 24 fps, 16.67 ms is 60 fps); a whole number of milliseconds, and any other value, is read as it is. The same reading applies to a direction sheet's rows and a grid sheet's `delay_ms`. Read as 41.67 ms, a 24 fps strip drifted a scene a cell late: in a 24 fps scene its first cell showed twice and every cell after it one frame late; in a 20 fps scene every fifth frame showed the cell before the one its time falls on. A stride report measured on the rounded time still names the same cells.++## Cells at the scene's times++A layer whose asset is a cut of a filmed clip — a `video-loop` or `video-stop` strip, whose sidecar names its `source_cut` — is read for which of its cells each scene frame shows. Where a scene frame would show the cell the frame before it shows (the scene's frames come faster than the cells, as a 24 fps cut in a 60 fps scene does, or a `playback_rate` under 1 plays it slower), and nothing holds that cell on purpose, the layer is given at the scene's times: every frame of it is the cell its time falls on, or the frame RIFE makes between the two cells either side at its own time. Each frame made is judged as `video-loop` judges a frame it makes for a held cell ([loop-repair.md](loop-repair.md) section 7): one that drags a planted part, cross-fades two poses, opens a hole, draws a double outline or shows a pose beside it again is made again at another fraction within half a scene frame of its time, and one with no fraction left shows the nearer cell again, named. A layer that shows no cell again keeps its cells as its timing picks them, byte for byte; so does every layer with `--fill-held off`.++Held on purpose, and never made between:++| Held | Where |+|---|---|+| Not a video cut | A still, an atlas row, a pixel drawing, a frame descriptor, a strip that names no `source_cut`: its cells are drawings, each held as drawn |+| Before its start | A layer with `loop: false` and a negative `offset` holds its first cell until its time reaches it |+| A one-shot's end | A layer with `loop: false` holds its last cell from that cell's time on (`hold_last` on a `once` cut) |+| A hold its strip lists | The runs of cells the strip's `holds` names (`from` to `to`, both counted): within one, its cells as they stand; from its last cell to the next pose, frames made |++A frame that shows the cell a frame held on purpose shows (the first cell, on at its start) goes on holding it. RIFE is located the first time a frame is to be made, so a render that makes none needs no binary, and each frame between two cells at one fraction is made once a render. With no RIFE installed the layer keeps its cells, a `scene-render: warning:` line names the layer, the scene frames that show a cell again and the install command, and the report records it; it is never a failure. Any other RIFE failure stops the render, naming `--fill-held off`.++Each layer's row of `repeats`, in the inspection (`scene-inspect`, and `inspection.repeats` in `scene.report.json`), lists by which cell each scene frame shows, exactly, the scene frames that show the cell the frame before shows: as runs (`from`, `to`, both counted, the `cell` — or `{"between": [a, b], "t": t}` for a frame made — `intended` and `why`), with `repeated_frames` and `unintended_frames`. A video cut's row carries `fill_held`: the `mode`, whether the scene's times were `applied`, how many frames were `made`, the frames `shown_again`, the `interpolator`, and `why` with `unmade` (`frames`, `rife`, `install`) where nothing was made. A layer with frames not held on purpose adds a line to the inspection's `warnings`, and its `status` is `needs-review`.+## Spec ownership and units| Field | Contract |@@ -80,6 +99,8 @@ Stride magnitude is converted from source pixels/second to the rendered horizontThe output directory is dedicated to one render and must be empty. Rendering and encoding stage before publication, protected by the shared run-directory writer lock. Invalid specs, changed sources, encoder errors or publication failures stop with a nonzero result. Sources and pre-existing outputs are preserved; the CLI does not regenerate assets or retry a failed encoder automatically.+`--fill-held auto` (the default) gives a layer cut from a filmed clip at the scene's times where it would show a cell again ([Cells at the scene's times](#cells-at-the-scenes-times)); `--fill-held off` gives every layer's cells as its timing picks them. `scene-inspect` takes the same flag and measures what that render would show. What was not made — no RIFE, a frame refused, `--fill-held off` — is printed as `scene-render: warning:` lines once the render is published.+GIF defaults preserve the scene frame rate, use 256 colours without dithering (for flat pixel-art colours), and cap width at 640 pixels. `--gif-width`, `--gif-fps`, `--gif-colors` and `--gif-dither` make those choices explicit; `sierra2_4a` can preserve gradual tones in painted scenery. GIF fps cannot exceed scene fps; more samples require rendering the scene itself at a higher rate. `--gif-max-bytes` defaults to 8,000,000: an oversized result fails and asks for an explicit budget or quality change. The encoder never silently lowers frame rate, resolution or colours.```bash@@ -92,7 +113,7 @@ sprite-gen scene-render --spec scene.json --out-dir gif-render/ --formats gif \| `frames/frame-NNNNN.png` | All rendered frames when `png` is selected || `scene.mp4`, `scene.gif` | Selected encoded formats || `check-NNNNN.png` | Representative rendered frames for visual review |-| `scene.report.json` | Source fingerprints, output list, encoding details and scene inspection |+| `scene.report.json` | Source fingerprints, output list, `fill_held`, encoding details and scene inspection (with each layer's `repeats`) || `placement.json` | Resolved placement and source references, camera, light, fps and duration || `layers/<id>.png` | Optional canvas-sized plates at time zero, with `--export-layers` |@@ -100,8 +121,8 @@ Layer plates are static; animated layers remain references in `placement.json`.## Inspection-`scene-inspect` reports viewport clipping, including completely offscreen layers, repeat joins, timing and loop measurements. It compares the actual last rendered output frame with the first as well as ordinary adjacent transitions; phase closure is separate from visual seam quality. A clean numerical result still needs visual review, especially for locomotion and repeating architecture.+`scene-inspect` reports viewport clipping, including completely offscreen layers, repeat joins, timing and loop measurements, and each layer's scene frames that show a cell again (`repeats`). It compares the actual last rendered output frame with the first as well as ordinary adjacent transitions; phase closure is separate from visual seam quality. A clean numerical result still needs visual review, especially for locomotion and repeating architecture.`--require-loop` makes a failed loop check return nonzero. Without `--out`, the JSON is printed. An output report cannot overwrite a source, a source alias or the reserved writer lock. Inspection does not fix, reverse, flip or resample source frames.-Python APIs: `load_scene(path)` in `sprite_gen.scene.model`, `render_scene(spec, out_dir, **options)` in `sprite_gen.scene.render`, and `inspect_scene(scene, **options)` in `sprite_gen.scene.inspect_scene`. Each command also supports `python -m` with its module name.+Python APIs: `load_scene(path)` in `sprite_gen.scene.model`, `render_scene(spec, out_dir, **options)` and `Renderer(scene, fill_held=, interpolate=)` in `sprite_gen.scene.render`, and `inspect_scene(scene, **options)` in `sprite_gen.scene.inspect_scene`; `interpolate` stands in for RIFE. Each command also supports `python -m` with its module name.diff --git a/sprite_gen/scene/inspect_scene.py b/sprite_gen/scene/inspect_scene.pyindex 04c69c8..93de366 100644--- a/sprite_gen/scene/inspect_scene.py+++ b/sprite_gen/scene/inspect_scene.py@@ -25,10 +25,10 @@ def _mae(a, b) -> float:return float(np.abs(a - b).mean())-def inspect_scene(scene: Scene, *, renderer=None, frame_dir=None):+def inspect_scene(scene: Scene, *, renderer=None, frame_dir=None, fill_held="auto", interpolate=None):from sprite_gen.frames.cutout import GREEN, MAGENTAfrom sprite_gen.scene.render import Renderer- renderer = renderer or Renderer(scene)+ renderer = renderer or Renderer(scene, fill_held=fill_held, interpolate=interpolate)first = previous = Nonegreen, magenta = 0, 0clipped = {layer.id: {"top_frames": 0, "bottom_frames": 0, "side_frames": 0, "offscreen_frames": 0,@@ -100,10 +100,14 @@ def inspect_scene(scene: Scene, *, renderer=None, frame_dir=None):offscreen = [name for name, s in clipped.items() if s["offscreen_frames"]]if offscreen:warnings.append(f"layers entirely outside the viewport in some frames: {', '.join(offscreen)}")+ # Each layer's scene frames that show the cell the frame before shows, by which cell each shows (`Renderer.repeats`):+ # what was not made, or not held on purpose, is a line to look at.+ warnings += renderer.warningsreturn {"kind": "sprite-gen-scene-inspection", "version": 1, "frames": scene.frame_count,"source_fingerprints": scene.source_fingerprints, "status": "needs-review" if warnings else "measured","loop": loop, "key_like_pixels": {GREEN: green, MAGENTA: magenta}, "clipping": clipped,- "sources": sources, "tile_joins": tiles, "warnings": warnings, "visual_review_required": True}+ "sources": sources, "tile_joins": tiles, "repeats": renderer.repeats, "warnings": warnings,+ "visual_review_required": True}def output_path(out, scene: Scene) -> Path:@@ -126,14 +130,17 @@ def add_arguments(parser):parser.add_argument("--spec", type=Path, required=True)parser.add_argument("--out", type=Path)parser.add_argument("--require-loop", action="store_true")+ parser.add_argument("--fill-held", choices=("auto", "off"), default="auto",+ help="as scene-render reads it: auto (default) measures a layer cut from a filmed clip at the scene's "+ "times where it would show a cell again; off measures its cells as cut")-def run(spec, out=None, require_loop=False):+def run(spec, out=None, require_loop=False, fill_held="auto"):try:scene = load_scene(spec)if out is not None:output_path(out, scene)- report = inspect_scene(scene)+ report = inspect_scene(scene, fill_held=fill_held)payload = json.dumps(report, indent=2) + "\n"if out is not None:target = output_path(out, scene)diff --git a/sprite_gen/scene/render.py b/sprite_gen/scene/render.pyindex e7506a5..842c989 100644--- a/sprite_gen/scene/render.py+++ b/sprite_gen/scene/render.py@@ -16,6 +16,7 @@ import jsonfrom pathlib import Pathimport shutilimport subprocess+import sysimport tempfilefrom PIL import Image@@ -52,26 +53,227 @@ def composite(target, source, x, y):target.alpha_composite(source.crop((left-x, top-y, right-x, bottom-y)), (left, top))+# `--fill-held`: auto gives a layer cut from a filmed clip at the scene's own times (`Renderer`), off gives its cells as+# the asset's timing picks them — the word `video-loop --fill-held` uses.+FILL_HELD_MODES = ("auto", "off")+DOC = 'docs/scene.md "Cells at the scene\'s times"'+++def _frames_said(frames, most=12):+ """Scene frame numbers, as a person is told them: the first `most`, then how many more."""+ shown = ", ".join(map(str, frames[:most]))+ return shown + (f" and {len(frames) - most} more" if len(frames) > most else "")+++class _Between:+ """The frames made between two cells of a layer for one render, each kept by the two cells and its fraction (the+ asset's cells and the time): RIFE is located the first time a frame is asked for, so a render that makes none+ needs no binary. With `cache` (`rife.Cache`, `--between-cache`), a frame is also kept across renders under the bytes+ of its two cells, the time and the RIFE that made it, and taken from there when asked for again."""++ def __init__(self, interpolate=None, cache=None):+ self.interpolate = interpolate+ self.made_by = None if interpolate is None else {"kind": "injected"}+ self.cache = cache+ self.kept = {}++ def __call__(self, a, b, t):+ key = (id(a), id(b), float(t).hex())+ if key not in self.kept:+ if self.interpolate is None:+ from sprite_gen.video import rife as rife_mod+ found = rife_mod.Rife()+ self.made_by = found.describe()+ self.interpolate = found+ if self.cache is not None:+ self.kept[key] = self.cache.frame(self.interpolate, a.convert("RGBA"), b.convert("RGBA"), t)+ else:+ self.kept[key] = self.interpolate(a, b, t)+ return self.kept[key]++class Renderer:- def __init__(self, scene: Scene):+ """Each layer's frames placed at a scene time (`frame`).++ A layer cut from a filmed clip (a `video-loop` or `video-stop` strip: its sidecar names `source_cut`) is read for+ the cells it shows at the scene's frames, by which cell each frame shows. Where a scene frame shows the cell the+ frame before it shows, and nothing holds that cell on purpose — before the layer's start or after a one-shot's end+ (where it holds its first or last cell), within a run of cells its strip lists as held (`holds`) — the layer is+ given at the scene's times (`fill_held` auto): every frame of it the cell its time falls on, or the frame RIFE makes+ between the two cells either side at its own time, judged as `video-loop` judges a frame made for a held cell+ (`held_fill.at_times`); one refused shows the nearer cell again, named. A layer that shows no cell again keeps its+ cells as picked, byte for byte. Any other layer (a still, an atlas row, a pixel drawing) holds its cells as drawn.+ No RIFE installed: the layer keeps its cells and `warnings` says so. `repeats` is each layer's table of scene frames+ showing the cell the frame before shows, each run held on purpose (`intended`, and why) or not. `between_cache` is a+ directory the frames made are kept in and taken from (`rife.Cache`: under the bytes of the two cells, the time and+ the RIFE), counted in `between_cache_record()`; nothing is kept without it."""++ def __init__(self, scene: Scene, *, fill_held="auto", interpolate=None, between_cache=None):+ if fill_held not in FILL_HELD_MODES:+ raise ValueError(f"fill_held must be one of {', '.join(FILL_HELD_MODES)}, not {fill_held!r}")+ cache = None+ if between_cache is not None:+ from sprite_gen.video import rife as rife_mod+ if interpolate is not None and not callable(getattr(interpolate, "identity", None)):+ raise ValueError("--between-cache keeps frames under the RIFE that made them: the interpolator given names "+ "no identity")+ try:+ cache = rife_mod.Cache(Path(between_cache))+ except OSError as exc:+ raise ValueError(f"--between-cache {between_cache}: {exc}") from exc+ self.cache = cacheself.scene = scene+ self.fill_held = fill_heldself.prepared = {}+ self.planned = {}+ self.repeats = []+ self.warnings = []# Import only when scene/shadow is used; ordinary sprite commands need no scene setup.from sprite_gen.effects.shadow import project_shadow+ self._project_shadow = project_shadowfor layer in scene.layers:- seq = layer.sequence- size = tuple(layer.raster_size)- anchor = tuple(a*new/old for a, new, old in zip(seq.anchor, size, seq.size))- frames = {}- for source in seq.frames:- image = resize_cell(source, size)- if layer.repeat_x:- image = image.crop((0, 0, round(layer.period*layer.scale), size[1]))- if layer.opacity != 1:- image.putalpha(image.getchannel("A").point(lambda a: round(a*layer.opacity)))- shadow = project_shadow(image, anchor, **scene.light) if layer.shadow else None- frames[id(source)] = (image, anchor, shadow, image.getchannel("A").getbbox())- self.prepared[layer.id] = frames+ self.prepared[layer.id] = {id(source): self._prepare(layer, source) for source in layer.sequence.frames}+ between = _Between(interpolate, cache)+ for layer in scene.layers:+ self._plan(layer, between)++ def between_cache_record(self):+ """The `--between-cache` directory and its counts (`rife.Cache.record`), or None without one."""+ return self.cache.record() if self.cache is not None else None++ def _prepare(self, layer, source):+ seq = layer.sequence+ size = tuple(layer.raster_size)+ anchor = tuple(a*new/old for a, new, old in zip(seq.anchor, size, seq.size))+ image = resize_cell(source, size)+ if layer.repeat_x:+ image = image.crop((0, 0, round(layer.period*layer.scale), size[1]))+ if layer.opacity != 1:+ image.putalpha(image.getchannel("A").point(lambda a: round(a*layer.opacity)))+ shadow = self._project_shadow(image, anchor, **self.scene.light) if layer.shadow else None+ return (image, anchor, shadow, image.getchannel("A").getbbox())++ def _plan(self, layer, between):+ """Read which cell `layer` shows at each scene frame (and at the scene's end, which the loop check reads), give+ it at the scene's times where it shows a cell again and nothing holds it (see the class), and write its row of+ `repeats`."""+ scene, seq = self.scene, layer.sequence+ n, count = len(seq.frames), scene.frame_count+ asset = [i / scene.fps * layer.playback_rate + layer.offset for i in range(count + 1)]+ cells = [seq.index_at(a, loop=layer.loop) for a in asset]+ video = bool(seq.metadata.get("video_cut"))+ even = len(set(seq.durations)) == 1+ holds = seq.metadata.get("holds") or []+ hold_last = bool(seq.metadata.get("hold_last"))++ def held(i):+ """Why the cell frame `i` shows is held on purpose, or None."""+ if not video:+ return "not a video cut: its cells are drawings, each held as drawn"+ if n < 2:+ return "a single cell"+ if not even:+ return "its cells are not one length each: held as its timing says"+ if not layer.loop and asset[i] < 0:+ return "before its start: its first cell held"+ if not layer.loop and cells[i] == n - 1:+ return "the one-shot's end: its last cell held" + (" (hold_last)" if hold_last else "")+ for h in holds:+ if h["from"] <= cells[i] < h["to"]:+ return f"a hold its strip lists (cells {h['from']}-{h['to']}{', ' + h['kind'] if h.get('kind') else ''})"+ return None++ why_held = [held(i) for i in range(count + 1)]+ # A frame that shows the cell a frame held on purpose shows (the first cell, on at its start) goes on holding it.+ kept = [None] + [why_held[i] or why_held[i - 1] for i in range(1, count + 1)]+ again = [i for i in range(1, count) if cells[i] == cells[i - 1] and kept[i] is None]+ identity = [("cell", c) for c in cells]+ unintended = {}+ record = {"mode": self.fill_held, "applied": False, "made": 0, "shown_again": []} if video else None+ if again:+ cell_fps = 1 / seq.durations[0]+ cause = (f"the scene's frames come faster than the cells ({cell_fps:g} cells a second at playback "+ f"{layer.playback_rate:g} in a {scene.fps:g} fps scene)")+ if self.fill_held == "off":+ unintended.update({i: f"{cause}: --fill-held off, given as cut" for i in again})+ record["why"] = "--fill-held off"+ self.warnings.append(f"layer {layer.id}: {len(again)} scene frame{'s' if len(again) > 1 else ''} show the cell "+ f"before them again ({_frames_said(again)}) — --fill-held off, given as cut ({DOC})")+ else:+ self._fill(layer, between, asset, cells, why_held, kept, identity, unintended, record, again, cause)+ repeated = [i for i in range(1, count) if identity[i] == identity[i - 1]]+ runs = []+ for i in repeated:+ why = unintended.get(i) or kept[i] or "shown again"+ intended = i not in unintended and kept[i] is not None+ shown = identity[i][1] if identity[i][0] == "cell" else {"between": list(identity[i][1]), "t": identity[i][2]}+ last = runs[-1] if runs else None+ if last and last["to"] == i - 1 and last["why"] == why and last["cell"] == shown:+ last["to"] = i+ else:+ runs.append({"from": i - 1, "to": i, "cell": shown, "intended": intended, "why": why})+ row = {"layer": layer.id, "asset": layer.asset, "video_cut": video, "cells": n, "frames": count,+ "repeated_frames": len(repeated), "unintended_frames": sum(1 for i in repeated if i in unintended or kept[i] is None),+ "runs": runs}+ if record is not None:+ row["fill_held"] = record+ self.repeats.append(row)++ def _fill(self, layer, between, asset, cells, why_held, kept, identity, unintended, record, again, cause):+ """The layer at the scene's times (`held_fill.at_times`): each frame not held on purpose, the cell its time+ falls on or the frame made between the cells either side; what became of it in `record`."""+ from sprite_gen.video import held_fill as held_fill_mod+ from sprite_gen.video import rife as rife_mod+ seq = layer.sequence+ n, d = len(seq.frames), seq.durations[0]+ playing = [i for i in range(len(asset)) if why_held[i] is None]+ at = [((a % seq.duration) if layer.loop else a) / d for a in (asset[i] for i in playing)]+ spacing = min(1.0, layer.playback_rate / (self.scene.fps * d))+ try:+ out, made = held_fill_mod.at_times(list(seq.frames), between, at, ring=layer.loop, spacing=spacing)+ except rife_mod.RifeNotInstalled as exc:+ unintended.update({i: f"{cause}: RIFE is not installed, given as cut" for i in again})+ record.update(why="RIFE is not installed", unmade={"frames": again, "rife": str(exc), "install": rife_mod.install_command()})+ self.warnings.append(f"layer {layer.id}: {len(again)} scene frame{'s' if len(again) > 1 else ''} show the cell before "+ f"them again ({_frames_said(again)}) — RIFE is not installed, so no frame between was made; "+ f"run `{rife_mod.install_command()}` and render again ({DOC})")+ return+ except (ValueError, rife_mod.RifeUnavailable) as exc:+ raise ValueError(f"layer {layer.id}: {exc}; the layer shows a cell again and the frames between are to be made — "+ f"fix RIFE, or pass --fill-held off to give its cells as cut ({DOC})") from exc+ plan = {}+ hows = {how["cell"]: how for how in made["frames"]}+ refused = {playing[k]: how["between"] for k, how in hows.items() if "taken" in how}+ for k, (i, frame, source) in enumerate(zip(playing, out, made["source_frames"])):+ if source is None:+ how = hows[k]+ identity[i] = ("made", tuple(how["between"]), how["t"])+ plan[i] = self._prepare(layer, frame)+ else:+ identity[i] = ("cell", source)+ if source != cells[i]:+ plan[i] = self.prepared[layer.id][id(seq.frames[source])]+ for i in range(1, len(asset) - 1):+ if identity[i] == identity[i - 1] and kept[i] is None:+ a = identity[i][1]+ pair = refused.get(i) or refused.get(i - 1)+ unintended[i] = (f"no frame between cells {pair[0]} and {pair[1]} was made without a fault: the nearer cell "+ "shown again" if pair else+ f"cells {a} and {(a + 1) % n} show one picture and its strip lists no hold there")+ self.planned[layer.id] = plan+ shown_again = sorted(i for i in refused if i < len(asset) - 1) # scene frames: the scene's end is the loop check's+ record.update(applied=True, made=made["made"], shown_again=shown_again,+ interpolator=between.made_by if made["made"] or shown_again else None)+ if shown_again:+ self.warnings.append(f"layer {layer.id}: {len(shown_again)} scene frame{'s' if len(shown_again) > 1 else ''} "+ f"({_frames_said(shown_again)}) show the cell beside them again: no frame between was made "+ f"there without a fault ({DOC})")++ def cell_at(self, time):+ """The scene frame `time` falls on, where the plan reads it (a frame of the scene, or its end), else None."""+ index = time * self.scene.fps+ i = round(index)+ return i if abs(index - i) < 1e-6 else Nonedef frame(self, time: float, *, only=None, geometry=False):"""Composite the scene at ``time``; with ``geometry`` also return every placement.@@ -87,8 +289,13 @@ class Renderer:for layer in scene.layers:if only and layer.id != only:continue- source = layer.sequence.frame_at(time*layer.playback_rate+layer.offset, loop=layer.loop)- image, anchor, shadow, bbox = self.prepared[layer.id][id(source)]+ planned = self.planned.get(layer.id)+ at = self.cell_at(time) if planned else None+ if at is not None and at in planned:+ image, anchor, shadow, bbox = planned[at]+ else:+ source = layer.sequence.frame_at(time*layer.playback_rate+layer.offset, loop=layer.loop)+ image, anchor, shadow, bbox = self.prepared[layer.id][id(source)]point = [layer.at[i] + layer.velocity[i]*time - (scene.camera_at[i]+scene.camera_velocity[i]*time)*layer.parallax for i in range(2)]left, top = point[0]-anchor[0], point[1]-anchor[1]offsets = [0]@@ -219,10 +426,16 @@ def _validate_output(output: Path, scene: Scene):def render_scene(spec, out_dir, *, formats="mp4,gif", gif_max_bytes=GIF_MAX_BYTES_DEFAULT, gif_width=None, gif_fps=None,- gif_colors=GIF_COLORS_DEFAULT, gif_dither=GIF_DITHER_DEFAULT, export_layers=False):+ gif_colors=GIF_COLORS_DEFAULT, gif_dither=GIF_DITHER_DEFAULT, export_layers=False, fill_held="auto",+ interpolate=None, between_cache=None):+ """Render `spec` into the new or empty `out_dir`. `fill_held` (`Renderer`): auto gives a layer cut from a filmed clip+ at the scene's times where it would show a cell again; off gives its cells as cut. `interpolate` stands in for RIFE;+ `between_cache` keeps the frames made between cells across renders (`Renderer`).+ What was not made (no RIFE, a frame refused, off) is printed as `scene-render: warning:` lines once the render is+ published, and recorded in the report's `inspection.repeats`."""scene = load_scene(spec)formats = parse_formats(formats)- renderer = Renderer(scene)+ renderer = Renderer(scene, fill_held=fill_held, interpolate=interpolate, between_cache=between_cache)settings = encoding_settings(scene, formats, gif_width=gif_width, gif_fps=gif_fps, gif_colors=gif_colors,gif_dither=gif_dither, gif_max_bytes=gif_max_bytes)output = Path(out_dir).expanduser().resolve()@@ -233,7 +446,10 @@ def render_scene(spec, out_dir, *, formats="mp4,gif", gif_max_bytes=GIF_MAX_BYTEacquire_run_dir_lock(output, "scene-render")if any(p.name != LOCK_FILENAME for p in output.iterdir()):raise ValueError("scene output directory became nonempty before the writer lock")- return _render_locked(scene, renderer, output, formats, settings, export_layers)+ report = _render_locked(scene, renderer, output, formats, settings, export_layers)+ for line in renderer.warnings:+ print(f"scene-render: warning: {line}", file=sys.stderr)+ return reportexcept BaseException:release_run_dir_lock(output)if created:@@ -275,10 +491,12 @@ def _render_locked(scene, renderer, output, formats, settings, export_layers):"layer_plate_time": 0 if export_layers else None, "portable": False,"note": "Placement metadata references source files; copy referenced assets when moving this output."}report = {"kind": "sprite-gen-scene-render", "version": 1, "source_spec": str(scene.path),- "source_fingerprints": scene.source_fingerprints, "frames": scene.frame_count,+ "source_fingerprints": scene.source_fingerprints, "frames": scene.frame_count, "fill_held": renderer.fill_held,# Report paths are manifest entries, so they use "/" on every OS."files": [relative_posix(p, output) for p in payloads] + ["placement.json", "scene.report.json"],"encoding": encoding, "inspection": check}+ if renderer.cache is not None:+ report["between_cache"] = renderer.between_cache_record()payloads[output / "placement.json"] = json.dumps(placement, indent=2)+"\n"payloads[output / "scene.report.json"] = json.dumps(report, indent=2)+"\n"# The fingerprints are the bytes that were decoded; an input replaced since@@ -315,6 +533,17 @@ def add_arguments(parser):parser.add_argument("--gif-dither", choices=GIF_DITHER_CHOICES, default=GIF_DITHER_DEFAULT,help="paletteuse dithering; default none keeps flat pixel-art colours exact")parser.add_argument("--export-layers", action="store_true")+ parser.add_argument("--fill-held", choices=FILL_HELD_MODES, default="auto",+ help="auto (default): a layer cut from a filmed clip (a video-loop or video-stop strip) that would show "+ "a cell again at the scene's frames — the scene faster than its cells, a playback_rate under 1 — "+ "is given at the scene's times, each frame its cell or RIFE's frame between the cells either side, "+ "judged as video-loop judges one; held on purpose stays held (before its start, a one-shot's end, "+ "a hold its strip lists, any layer that is not a video cut). No RIFE: its cells as cut, with a "+ "warning line. off: every layer's cells as its timing picks them")+ parser.add_argument("--between-cache", type=Path,+ help="a directory the frames made between cells are kept in and taken from on the next render, "+ "under the bytes of the two cells, the time and the RIFE that made them (the report's "+ "between_cache counts them); nothing is kept without it")def run(**kwargs):diff --git a/sprite_gen/spec/assets.py b/sprite_gen/spec/assets.pyindex b3cadb2..15143a0 100644--- a/sprite_gen/spec/assets.py+++ b/sprite_gen/spec/assets.py@@ -77,10 +77,14 @@ def same_identity(reported, sequence) -> bool:for key in ("source", "state", "frame_count", "size"):if reported[key] != expected[key]:return False- for key in ("anchor_px", "durations_seconds"):- a, b = reported[key], expected[key]- if not isinstance(a, list) or len(a) != len(b) or not all(_close(x, y) for x, y in zip(a, b)):- return False+ a, b = reported["anchor_px"], expected["anchor_px"]+ if not isinstance(a, list) or len(a) != len(b) or not all(_close(x, y) for x, y in zip(a, b)):+ return False+ # A report measured when a strip's cells were read off `delay_ms` rounded to hundredths (0.04167 s for 24 fps)+ # names the same cells read at their exact rate (`frame_seconds`).+ a, b = reported["durations_seconds"], expected["durations_seconds"]+ if not isinstance(a, list) or len(a) != len(b) or not all(_close(x, y) or _close(_snapped_seconds(x), y) for x, y in zip(a, b)):+ return Falsereturn True@@ -91,6 +95,30 @@ def _close(a, b) -> bool:return False+# A cell's time written in milliseconds rounded to hundredths (`video-loop`'s `delay_ms`, 41.67 for 24 fps) that lies+# within SNAP_MS of a whole number of cells a second is that rate's: the rounding drifts a scene a frame late.+SNAP_MS = 0.01+++def frame_seconds(delay_ms) -> float:+ """One cell's time, seconds, of a sidecar's `delay_ms`: a value with a fraction of a millisecond within SNAP_MS of+ 1000 over a whole number is that rate's exact time (41.67 is 1/24 s); a whole number of milliseconds, and any+ other value, is read as it is."""+ ms = finite(delay_ms, "delay_ms", positive=True)+ if ms != int(ms):+ rate = round(1000 / ms)+ if rate >= 1 and abs(ms - 1000 / rate) <= SNAP_MS:+ return 1 / rate+ return ms / 1000+++def _snapped_seconds(value) -> float:+ try:+ return frame_seconds(round(float(value) * 1000, 2))+ except (TypeError, ValueError, OverflowError):+ return float("nan")++@dataclass(frozen=True)class FrameSequence:"""An in-memory frame sequence: ``frames, durations, anchor, source_files, metadata``.@@ -132,18 +160,23 @@ class FrameSequence:return sum(self.durations)def frame_at(self, t: float, loop=True):+ return self.frames[self.index_at(t, loop=loop)]++ def index_at(self, t: float, loop=True) -> int:+ """Which frame plays at `t` seconds: looped over the sequence, or held on the last frame after its end (and+ on the first before its start) where `loop` is false."""t = finite(t, "frame time")if loop:t %= self.durationelif t >= self.duration:- return self.frames[-1]+ return len(self.frames) - 1t = max(0, t)end = 0.0- for frame, duration in zip(self.frames, self.durations):+ for k, duration in enumerate(self.durations):end += durationif t < end - 1e-10:- return frame- return self.frames[-1]+ return k+ return len(self.frames) - 1def fingerprints(self):"""SHA-256 of the exact bytes this sequence was decoded from, keyed by resolved path.@@ -214,6 +247,23 @@ def _choose(rows, state):return state+def _holds(value, n: int) -> list[dict]:+ """A strip's `holds`, the runs of cells it shows one picture in on purpose (`from` to `to`, both counted, with+ their `kind` and `reason`), checked against its `n` cells; absent, none."""+ if value is None:+ return []+ if not isinstance(value, list):+ raise ValueError("strip holds must be a list")+ out = []+ for entry in value:+ if not isinstance(entry, dict) or any(type(entry.get(k)) is not int for k in ("from", "to")):+ raise ValueError("each strip hold needs integer from and to")+ if not 0 <= entry["from"] < entry["to"] < n:+ raise ValueError(f"strip hold {entry['from']}-{entry['to']} is not a run of its {n} cells")+ out.append({"from": entry["from"], "to": entry["to"], "kind": entry.get("kind"), "reason": entry.get("reason")})+ return out++def _integer(value, name):number = finite(value, name, positive=True)if number != int(number):@@ -301,7 +351,7 @@ def _load_asset(source, snapshot, *, state=None, fps=None, anchor=None):sheet = snapshot.image((source.parent / data["sheet"]).resolve())frames = _grid_frames(sheet, data["columns"], len(rows), data["cell_w"], data["cell_h"],selected["frames"], row=selected["row"])- durations = [finite(selected["delay_ms"], "delay_ms", positive=True)/1000] * len(frames)+ durations = [frame_seconds(selected["delay_ms"])] * len(frames)meta.update({key: selected[key] for key in PLAYBACK_FIELDS if key in selected})meta.update(state=state, direction=state)declared_anchor = selected.get("anchor", declared_anchor)@@ -320,7 +370,7 @@ def _load_asset(source, snapshot, *, state=None, fps=None, anchor=None):raise ValueError("grid sheet requires row-major order and no --state")sheet = snapshot.image(source.with_suffix(".png"))frames = _grid_frames(sheet, data["columns"], data["rows"], data["frame_width"], data["frame_height"], data["frames"])- durations = [finite(data["delay_ms"], "delay_ms", positive=True)/1000] * len(frames)+ durations = [frame_seconds(data["delay_ms"])] * len(frames)elif all(k in data for k in ("frames", "w", "h", "delay_ms")):if state is not None:raise ValueError("--state is only valid for atlas input")@@ -329,7 +379,13 @@ def _load_asset(source, snapshot, *, state=None, fps=None, anchor=None):if sheet.size != (n * w, h):raise ValueError("loop strip size disagrees with its sidecar")frames = [sheet.crop((i*w, 0, (i+1)*w, h)) for i in range(n)]- durations = [finite(data["delay_ms"], "delay_ms", positive=True)/1000] * n+ # The cells' own rate where the strip says it (`fps`), else its `delay_ms` (`frame_seconds`).+ durations = ([1 / finite(data["fps"], "fps", positive=True)] if "fps" in data else [frame_seconds(data["delay_ms"])]) * n+ if "source_cut" in data:+ # A cut of a filmed clip (`video-loop`, `video-stop`): a scene gives it at its own times+ # (sprite_gen.scene.render), holding only the cells its strip lists as held on purpose (`holds`).+ meta["video_cut"] = True+ meta["holds"] = _holds(data.get("holds"), n)# `video-loop` writes `loop: false` for a one-shot cut (rest -> action -> rest);# an older sidecar without the key is a loop, as every strip was before.meta["loop"] = data.get("loop", True)diff --git a/tests/scene/test_scene_fill_held.py b/tests/scene/test_scene_fill_held.pynew file mode 100644index 0000000..b26bc44--- /dev/null+++ b/tests/scene/test_scene_fill_held.py@@ -0,0 +1,401 @@+# SPDX-License-Identifier: Apache-2.0+"""A layer cut from a filmed clip is given at the scene's times (sprite_gen/scene/render.py `Renderer`, docs/scene.md+"Cells at the scene's times").++A loop strip's cells are read at their own rate (`fps`, or a `delay_ms` rounded to hundredths read as the whole rate it+rounds: 41.67 is 24 fps), so a 24 fps strip in a 24 fps scene shows each cell once. A layer whose strip names its+`source_cut` (a `video-loop` or `video-stop` cut) and would show a cell again at the scene's frames — a 24 fps cut in a+60 fps scene, a playback_rate under 1 — has every frame at its own time: the cell it falls on, or the frame made between+the cells either side, judged as `video-loop` judges a frame made for a held cell. What is held on purpose stays held+(before its start and after a one-shot's end, a run of cells its strip lists, any layer that is not a video cut); a+scene that shows no cell again renders byte for byte as before. With no RIFE the cells are given as cut and a warning+line and the report say so. Each layer's scene frames that show the cell the frame before shows are a table+(`repeats`), each run held on purpose or not.++The interpolator is the stand-in of the held-cell tests (`Between`): the synthetic walker drawn again at the time asked+for, so no binary runs."""++from __future__ import annotations++import hashlib+import json+import math+import os+from pathlib import Path++import pytest+from PIL import Image++from sprite_gen.scene.model import load_scene+from sprite_gen.scene.render import Renderer+from tests.video.held_fill_inputs import N, Between, walk_at++CANVAS = 160+++def strip(root: Path, name: str, cells: list[Image.Image], *, fps: float | None = 24.0, delay_ms: float | None = None,+ cut: bool = True, loop: bool = True, holds: list | None = None, hold_last: bool | None = None) -> str:+ """A loop strip and its sidecar as `video-loop` writes them: the cells side by side, `delay_ms` rounded to+ hundredths, `fps` where given, `source_cut` where `cut`."""+ w, h = cells[0].size+ sheet = Image.new("RGBA", (w * len(cells), h))+ for k, cell in enumerate(cells):+ sheet.paste(cell, (k * w, 0))+ rate = fps if fps is not None else 1000 / delay_ms+ meta = {"frames": len(cells), "w": w, "h": h, "delay_ms": delay_ms if delay_ms is not None else round(1000 / rate, 2),+ "loop": loop, "kind": "periodic" if loop else "once"}+ if fps is not None:+ meta["fps"] = fps+ if cut:+ meta["source_cut"] = {"source": "synthetic", "start": 0, "length": len(cells)}+ if holds is not None:+ meta["holds"] = holds+ if hold_last is not None:+ meta["hold_last"] = hold_last+ sheet.save(root / f"{name}.strip.png")+ (root / f"{name}.strip.json").write_text(json.dumps(meta))+ return f"{name}.strip.json"+++def scene(root: Path, source: str, *, fps: float, duration: float, **layer) -> Path:+ spec = {"kind": "sprite-gen-scene", "version": 1, "canvas": {"width": CANVAS, "height": CANVAS, "background": [16, 16, 16]},+ "fps": fps, "duration": duration, "assets": {"hero": source},+ "layers": [{"id": "hero", "asset": "hero", "at": [CANVAS // 2, 150], **layer}]}+ path = root / "scene.json"+ path.write_text(json.dumps(spec))+ return path+++def cycle() -> list[Image.Image]:+ return [walk_at(k) for k in range(N)]+++def frames_digest(renderer: Renderer, count: int, fps: float) -> str:+ """The pictures of a scene's frames, as decoded: each frame's size and RGBA bytes."""+ digest = hashlib.sha256(f"{count}".encode())+ for i in range(count):+ image = renderer.frame(i / fps)+ digest.update(f"{image.size}".encode())+ digest.update(image.tobytes())+ return digest.hexdigest()+++def row(renderer: Renderer, layer: str = "hero") -> dict:+ return next(r for r in renderer.repeats if r["layer"] == layer)+++def shown(renderer: Renderer, fps: float, count: int) -> list[bytes]:+ return [renderer.frame(i / fps, only="hero").tobytes() for i in range(count)]+++def plate(image: Image.Image) -> bytes:+ """`image` placed as the layer places a 120 x 140 cell at (80, 150), on a clear canvas."""+ canvas = Image.new("RGBA", (CANVAS, CANVAS), (0, 0, 0, 0))+ canvas.alpha_composite(image, (CANVAS // 2 - 60, 150 - 140))+ return canvas.tobytes()+++class Refusing:+ """An interpolator that must not be called."""++ def __call__(self, a, b, t):+ raise AssertionError(f"no frame between is to be made here (t {t})")+++def _no_rife(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)+ path = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not (Path(d) / "rife-ncnn-vulkan").exists()]+ monkeypatch.setenv("PATH", os.pathsep.join(path))+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))+++# --- The cells' own rate -----------------------------------------------------------------------------------------------++def test_a_24_fps_strip_in_a_24_fps_scene_shows_each_cell_once(tmp_path):+ # The checkpoint's probe: `build_strip` writes delay_ms 41.67 for 24 fps, which drifted the scene a cell late from+ # its second frame (pixels 40, 40, 80, 120). Read at the strip's own rate it shows cells 0, 1, 2, 3.+ from sprite_gen.video.loop import build_strip+ frames = [Image.new("RGBA", (16, 16), (40 * (i + 1), 20, 30, 255)) for i in range(4)]+ sheet, meta = build_strip(frames, cycle_seconds=4 / 24)+ sheet.save(tmp_path / "probe.strip.png")+ for name, sidecar in (("with-fps", meta), ("old", {k: v for k, v in meta.items() if k != "fps"})):+ (tmp_path / "probe.strip.json").write_text(json.dumps(sidecar))+ spec = {"kind": "sprite-gen-scene", "version": 1, "canvas": {"width": 64, "height": 32, "background": [0, 0, 0]},+ "fps": 24, "duration": 4 / 24, "assets": {"probe": "probe.strip.json"},+ "layers": [{"id": "probe", "asset": "probe", "at": [32, 32]}]}+ (tmp_path / "scene.json").write_text(json.dumps(spec))+ renderer = Renderer(load_scene(tmp_path / "scene.json"))+ assert meta["delay_ms"] == 41.67+ assert [renderer.frame(i / 24).getpixel((32, 28))[0] for i in range(4)] == [40, 80, 120, 160], name++[email protected]("rate", [24, 60, 15])+def test_a_frame_on_a_cell_boundary_shows_the_cell_that_starts_there(rate, tmp_path):+ # A strip at `rate` in a 20 fps scene: scene frame i falls in cell i * rate / 20, exactly. Where that is whole the+ # frame is on the boundary (0.25 s of a 24 fps strip is cell 6, not 5): the strip's rounded delay (41.67, 16.67,+ # 66.67 ms) read as it was drifted those frames a cell late.+ cells = [Image.new("RGBA", (16, 16), (4 * k + 10, 20, 30, 255)) for k in range(rate)]+ source = strip(tmp_path, "cells", cells, fps=None, delay_ms=round(1000 / rate, 2), cut=False)+ spec = {"kind": "sprite-gen-scene", "version": 1, "canvas": {"width": 64, "height": 32, "background": [0, 0, 0]},+ "fps": 20, "duration": 1.0, "assets": {"cells": source},+ "layers": [{"id": "cells", "asset": "cells", "at": [32, 32]}]}+ (tmp_path / "scene.json").write_text(json.dumps(spec))+ renderer = Renderer(load_scene(tmp_path / "scene.json"), interpolate=Refusing())+ got = [(renderer.frame(i / 20).getpixel((32, 28))[0] - 10) // 4 for i in range(20)]+ assert got == [i * rate // 20 for i in range(20)]+ boundary = [i for i in range(20) if i * rate % 20 == 0]+ assert len(boundary) >= 4 and all(got[i] == i * rate // 20 for i in boundary)+ if rate == 24:+ assert got[5] == 6 # 0.25 s x 24+++def test_a_delay_rounded_to_hundredths_is_read_as_the_whole_rate_it_rounds_and_nothing_else_moves():+ from sprite_gen.spec.assets import frame_seconds+ assert frame_seconds(41.67) == 1 / 24 and frame_seconds(16.67) == 1 / 60 and frame_seconds(33.33) == 1 / 30+ assert frame_seconds(66.67) == 1 / 15 and frame_seconds(83.33) == 1 / 12+ # A whole number of milliseconds is what its writer meant (a pixel drawing's 100 ms, an atlas's 42 ms), and a rate+ # that is not whole (23.976 fps: 41.71 ms) is not taken for one.+ assert frame_seconds(100) == 0.1 and frame_seconds(42) == 0.042 and frame_seconds(7) == 0.007+ assert frame_seconds(41.71) == 41.71 / 1000 and frame_seconds(16.68) == 16.68 / 1000+++def test_a_stride_report_measured_on_the_rounded_delay_names_the_cells_read_at_their_exact_rate(tmp_path):+ from sprite_gen.spec.assets import load_asset, same_identity, sequence_identity+ source = strip(tmp_path, "walk", cycle(), fps=None, delay_ms=41.67)+ seq = load_asset(tmp_path / source)+ old = {**sequence_identity(seq), "durations_seconds": [0.04167] * N}+ assert seq.durations == (1 / 24,) * N+ assert same_identity(old, seq)+ assert not same_identity({**old, "durations_seconds": [0.0417] * N}, seq)+++def test_a_24_fps_cut_in_a_20_fps_scene_shows_each_cell_at_its_own_time(tmp_path):+ # No cell is shown twice either way; read off 41.67 ms, every fifth frame (a time on a cell's start) showed the+ # cell before it: cells 4, 5, 7 where they are 4, 6, 7. The exact rate changes those frames' pictures.+ source = strip(tmp_path, "walk", cycle())+ renderer = Renderer(load_scene(scene(tmp_path, source, fps=20, duration=1.0)), interpolate=Refusing())+ picked = [renderer.scene.layers[0].sequence.index_at(i / 20) for i in range(20)]+ assert picked == [math.floor(i * 1.2 + 1e-9) for i in range(20)] and picked[4:7] == [4, 6, 7]+ assert row(renderer)["repeated_frames"] == 0 and row(renderer)["fill_held"] == {+ "mode": "auto", "applied": False, "made": 0, "shown_again": []}+++# --- A scene that shows no cell again is as before ---------------------------------------------------------------------++# Pinned on the engine before the cells were given at the scene's times (the frames as decoded, `frames_digest`).+UNREPEATED = {+ "25-in-25": (dict(fps=25.0), dict(fps=25, duration=24 / 25),+ "1bf5022e2d337b3b07d23a6ef0ef0edcab8928f8dde7177ab328fb50941a5868"),+ "20-in-20-old-sidecar": (dict(fps=None, delay_ms=50.0), dict(fps=20, duration=24 / 20),+ "1bf5022e2d337b3b07d23a6ef0ef0edcab8928f8dde7177ab328fb50941a5868"),+ "25-in-20": (dict(fps=25.0), dict(fps=20, duration=1.0),+ "33bc07fc36d8e80a537b3d80f2aea54dd0a838964820922aa0b5b1d31056ca79"),+ # Rates whose rounded delay is under the exact one: read as it was, no frame drifted.+ "30-in-30": (dict(fps=30.0), dict(fps=30, duration=24 / 30),+ "1bf5022e2d337b3b07d23a6ef0ef0edcab8928f8dde7177ab328fb50941a5868"),+ "12-in-12": (dict(fps=12.0), dict(fps=12, duration=24 / 12),+ "1bf5022e2d337b3b07d23a6ef0ef0edcab8928f8dde7177ab328fb50941a5868"),+ "48-in-48": (dict(fps=48.0), dict(fps=48, duration=24 / 48),+ "1bf5022e2d337b3b07d23a6ef0ef0edcab8928f8dde7177ab328fb50941a5868"),+}++[email protected]("case", sorted(UNREPEATED))+def test_a_scene_that_shows_no_cell_again_renders_byte_for_byte_as_before(case, tmp_path):+ asset, timing, pinned = UNREPEATED[case]+ source = strip(tmp_path, "walk", cycle(), **asset)+ renderer = Renderer(load_scene(scene(tmp_path, source, **timing)), interpolate=Refusing())+ count = round(timing["fps"] * timing["duration"])+ assert row(renderer)["repeated_frames"] == 0 and renderer.planned == {}+ assert frames_digest(renderer, count, timing["fps"]) == pinned+++# --- Cells at the scene's times ----------------------------------------------------------------------------------------++def test_a_24_fps_cut_in_a_60_fps_scene_shows_no_cell_twice(tmp_path):+ source = strip(tmp_path, "walk", cycle())+ spec = scene(tmp_path, source, fps=60, duration=1.0)+ # As cut (`--fill-held off`, the engine before it): 36 of the 60 frames show the cell the frame before shows.+ off = Renderer(load_scene(spec), fill_held="off")+ assert row(off)["unintended_frames"] == 36 and row(off)["fill_held"]["why"] == "--fill-held off"+ assert all(r["intended"] is False for r in row(off)["runs"])+ assert any("--fill-held off" in line for line in off.warnings)+ between = Between(walk_at, range(N), period=N)+ on = Renderer(load_scene(spec), interpolate=between)+ record = row(on)+ assert record["repeated_frames"] == 0 and record["unintended_frames"] == 0 and record["runs"] == []+ # 12 of the 60 times fall on a cell (every fifth: 0, 2, 4, ... cells); the 48 others are made at their own time.+ assert record["fill_held"]["made"] == 48 and record["fill_held"]["shown_again"] == []+ assert on.warnings == []+ pictures = shown(on, 60, 60)+ assert all(a != b for a, b in zip(pictures, pictures[1:]))+ for i in (0, 1, 2, 7, 59):+ assert pictures[i] == plate(walk_at(i * 0.4)), i+ # Each fraction is made once and kept: a loop's times come round again (the asset and the time).+ assert len(between.calls) == len({c for c in between.calls})+++class Named:+ """An interpolator with an identity, as RIFE has one: what a frame kept by `--between-cache` is kept under."""++ def __init__(self, inner, name="stand-in"):+ self.inner, self.name, self.calls = inner, name, 0++ def identity(self):+ return self.name++ def __call__(self, a, b, t):+ self.calls += 1+ return self.inner(a, b, t)+++def test_a_between_cache_keeps_the_frames_made_for_the_next_render(tmp_path):+ source = strip(tmp_path, "walk", cycle())+ spec = scene(tmp_path, source, fps=60, duration=1.0)+ cache = tmp_path / "between"+ first = Named(Between(walk_at, range(N), period=N))+ made = Renderer(load_scene(spec), interpolate=first, between_cache=cache)+ assert made.between_cache_record() == {"dir": str(cache.resolve()), "hits": 0, "misses": 48, "unreadable": 0, "not_kept": 0}+ # The next render takes every frame from the cache (the two cells' bytes, the time, the RIFE): none is made.+ taken = Renderer(load_scene(spec), interpolate=Named(Refusing()), between_cache=cache)+ assert taken.between_cache_record()["hits"] == 48 and taken.between_cache_record()["misses"] == 0+ assert shown(taken, 60, 60) == shown(made, 60, 60)+ # Another RIFE is another key; an interpolator naming none is refused, as nothing could say what made a frame.+ other = Named(Between(walk_at, range(N), period=N), name="another")+ assert Renderer(load_scene(spec), interpolate=other, between_cache=cache).between_cache_record()["misses"] == 48+ with pytest.raises(ValueError, match="names no identity"):+ Renderer(load_scene(spec), interpolate=Between(walk_at, range(N), period=N), between_cache=cache)+ # Without it, nothing is kept and the report says nothing of it.+ assert Renderer(load_scene(spec), interpolate=Between(walk_at, range(N), period=N)).between_cache_record() is None+++def test_a_scene_at_60_fps_closes_on_its_first_frame_as_the_loop_check_reads_it(tmp_path):+ from sprite_gen.scene.inspect_scene import inspect_scene+ source = strip(tmp_path, "walk", cycle())+ loaded = load_scene(scene(tmp_path, source, fps=60, duration=1.0, offset=0.01))+ report = inspect_scene(loaded, renderer=Renderer(loaded, interpolate=Between(walk_at, range(N), period=N)))+ assert report["loop"]["phase_closure_pass"] and report["loop"]["phase_closure_mae"] == 0+ assert report["repeats"][0]["unintended_frames"] == 0+++def test_a_playback_rate_under_1_gives_the_cut_its_frames_between(tmp_path):+ source = strip(tmp_path, "walk", cycle())+ spec = scene(tmp_path, source, fps=24, duration=1.0, playback_rate=0.5)+ assert row(Renderer(load_scene(spec), fill_held="off"))["unintended_frames"] == 12+ on = Renderer(load_scene(spec), interpolate=Between(walk_at, range(N), period=N))+ assert row(on)["repeated_frames"] == 0 and row(on)["fill_held"]["made"] == 12+ assert shown(on, 24, 24)[1] == plate(walk_at(0.5))+++def test_a_once_cut_holds_its_first_cell_before_it_starts_and_its_last_after_it_ends(tmp_path):+ cells = [walk_at(k) for k in range(8)]+ source = strip(tmp_path, "act", cells, loop=False, hold_last=True)+ # Starts 0.1 s in, plays 8 cells at 24 fps over 0.33 s, holds: 0.6 s at 60 fps.+ spec = scene(tmp_path, source, fps=60, duration=0.6, offset=-0.1)+ between = Between(walk_at, range(8))+ on = Renderer(load_scene(spec), interpolate=between)+ record = row(on)+ assert record["unintended_frames"] == 0+ whys = {r["why"] for r in record["runs"]}+ assert whys == {"before its start: its first cell held", "the one-shot's end: its last cell held (hold_last)"}+ assert all(r["intended"] for r in record["runs"])+ first, last = record["runs"][0], record["runs"][-1]+ assert (first["from"], first["cell"]) == (0, 0) and (last["to"], last["cell"]) == (35, 7)+ # Between its start and its last cell, each frame at its own time: no frame is made from the last cell onward.+ assert all(ta < 7 and tb <= 7 for ta, tb, _ in between.calls)+ assert record["fill_held"]["made"] > 0+++def test_a_run_of_cells_its_strip_lists_as_held_stays_held(tmp_path):+ # Cells 6 to 9 show cell 6's picture: a hold the motion means (four cells), listed by the strip.+ cells = [walk_at(k) for k in range(N)]+ cells[7:10] = [cells[6]] * 3+ holds = [{"from": 6, "to": 9, "kind": "motion-hold", "reason": "held 4 cells, longer than a drawing on threes"}]+ source = strip(tmp_path, "walk", cells, holds=holds)+ between = Between(walk_at, range(N), period=N)+ on = Renderer(load_scene(scene(tmp_path, source, fps=60, duration=1.0)), interpolate=between)+ record = row(on)+ assert record["unintended_frames"] == 0+ listed = [r for r in record["runs"] if r["intended"]]+ assert listed and all(r["why"] == "a hold its strip lists (cells 6-9, motion-hold)" for r in listed)+ # Inside the hold nothing is made; from its last cell (cell 9, cell 6's picture) to the next pose the frames are.+ assert {(ta, tb) for ta, tb, _ in between.calls if 6 <= ta < 10} == {(6.0, 10.0)}+++def test_a_strip_that_names_no_cut_is_drawings_held_as_drawn(tmp_path):+ source = strip(tmp_path, "walk", cycle(), cut=False)+ spec = scene(tmp_path, source, fps=60, duration=1.0)+ on = Renderer(load_scene(spec), interpolate=Refusing())+ record = row(on)+ assert record["video_cut"] is False and "fill_held" not in record and record["unintended_frames"] == 0+ assert {r["why"] for r in record["runs"]} == {"not a video cut: its cells are drawings, each held as drawn"}+ assert shown(on, 60, 60) == shown(Renderer(load_scene(spec), fill_held="off"), 60, 60)+++def test_a_still_is_one_cell_held_as_drawn(tmp_path):+ walk_at(0).save(tmp_path / "still.png")+ renderer = Renderer(load_scene(scene(tmp_path, "still.png", fps=10, duration=1.0)), interpolate=Refusing())+ assert row(renderer)["runs"] == [{"from": 0, "to": 9, "cell": 0, "intended": True,+ "why": "not a video cut: its cells are drawings, each held as drawn"}]+++# --- What was not made is said -----------------------------------------------------------------------------------------++def test_no_rife_gives_the_cells_as_cut_and_says_which_frames_and_how_to_install(tmp_path, monkeypatch, capsys):+ from sprite_gen.scene.render import render_scene+ from sprite_gen.video import rife as rife_mod+ _no_rife(monkeypatch, tmp_path)+ source = strip(tmp_path, "walk", cycle())+ spec = scene(tmp_path, source, fps=60, duration=1.0)+ report = render_scene(spec, tmp_path / "out", formats="png")+ record = report["inspection"]["repeats"][0]+ assert record["unintended_frames"] == 36+ assert record["fill_held"]["why"] == "RIFE is not installed"+ assert record["fill_held"]["unmade"]["install"] == rife_mod.install_command()+ assert all(r["why"].endswith("RIFE is not installed, given as cut") for r in record["runs"])+ err = capsys.readouterr().err+ assert "scene-render: warning: layer hero: 36 scene frames show the cell before them again (1, 2, 4," in err+ assert f"RIFE is not installed, so no frame between was made; run `{rife_mod.install_command()}`" in err+ assert report["inspection"]["status"] == "needs-review"+ # The frames are the cells as cut.+ off = Renderer(load_scene(spec), fill_held="off")+ written = [Image.open(p).tobytes() for p in sorted((tmp_path / "out" / "frames").glob("frame-*.png"))]+ assert written == [off.frame(i / 60).tobytes() for i in range(60)]+++def test_a_frame_between_refused_shows_the_nearer_cell_again_named(tmp_path):+ source = strip(tmp_path, "walk", cycle())+ # An interpolator that gives the cell before back: each frame between shows a pose beside it (`held`), refused.+ on = Renderer(load_scene(scene(tmp_path, source, fps=60, duration=0.2)), interpolate=lambda a, b, t: a.copy())+ record = row(on)+ assert record["fill_held"]["made"] == 0 and record["fill_held"]["shown_again"]+ assert record["unintended_frames"] > 0+ assert all(r["intended"] is False and r["why"].startswith("no frame between cells") for r in record["runs"])+ assert any("show the cell beside them again: no frame between was made there without a fault" in line+ for line in on.warnings)+++def test_a_rife_that_fails_stops_the_render_naming_the_way_to_give_the_cells_as_cut(tmp_path):+ from sprite_gen.scene import render+ from sprite_gen.video import rife as rife_mod++ def broken(a, b, t):+ raise rife_mod.RifeUnavailable("rife-ncnn-vulkan exited 1")++ source = strip(tmp_path, "walk", cycle())+ spec = scene(tmp_path, source, fps=60, duration=0.2)+ with pytest.raises(ValueError, match="layer hero: rife-ncnn-vulkan exited 1; .*pass --fill-held off"):+ render.render_scene(spec, tmp_path / "out", formats="png", interpolate=broken)+ assert not (tmp_path / "out").exists()+ with pytest.raises(SystemExit, match="scene-render: layer hero"):+ render.run(spec=spec, out_dir=tmp_path / "out", formats="png", interpolate=broken)+++def test_scene_inspect_reports_each_layer_s_repeats_and_takes_the_same_flag(tmp_path, capsys):+ from sprite_gen.scene import inspect_scene+ source = strip(tmp_path, "walk", cycle())+ spec = scene(tmp_path, source, fps=60, duration=1.0)+ assert inspect_scene.run(spec, fill_held="off") == 0+ report = json.loads(capsys.readouterr().out)+ assert report["repeats"][0]["unintended_frames"] == 36 and report["status"] == "needs-review"+ assert any(line.startswith("layer hero: 36 scene frames show the cell before them again") for line in report["warnings"])