Skip to content

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

refactor(video): a frame's mass centre, a named contact's spans, a body on the floor and a cell at a given time, each one function the engine already ran inline

Soohong Kimb6eabeb855b7
diff --git a/sprite_gen/qa/motion.py b/sprite_gen/qa/motion.py
index f38e615..4c8f412 100644
--- a/sprite_gen/qa/motion.py
+++ b/sprite_gen/qa/motion.py
@@ -52,7 +52,10 @@ def _number(value, name):
return value
-def _contact_spans(contacts, count):
+def contact_spans(contacts, count):
+ """Zero-based inclusive spans of frames, ordered and apart: `0:4,8:12`, consecutive indices, or (start, end) pairs
+ (`analyze_motion`); a single play's contacts a clip does not show are named in the same form (video-loop --contact,
+ sprite_gen/video/root_motion.py)."""
if contacts is None:
return []
if isinstance(contacts, str):
@@ -114,6 +117,13 @@ def _foot_roi(foot_box, size):
return x, y, width, height
+def centroid(mask):
+ """The mean of a silhouette's pixels, at their centres: [x, y], or None where it is empty. A frame's `centroid_px`,
+ and the root of a single play's cell (sprite_gen/video/root_motion.py)."""
+ ys, xs = np.nonzero(mask)
+ return [float(xs.mean() + 0.5), float(ys.mean() + 0.5)] if len(xs) else None
+
+
def _bbox(mask):
ys, xs = np.nonzero(mask)
if not len(xs):
@@ -266,7 +276,7 @@ def analyze_motion(sequence: FrameSequence, *, contacts=None, foot_box=None, fac
anchor = [_number(v, "anchor") for v in sequence.anchor]
if facing not in (None, "left", "right"):
raise ValueError("facing must be left or right")
- spans = _contact_spans(contacts, len(frames))
+ spans = contact_spans(contacts, len(frames))
box = _foot_roi(foot_box, (width, height))
starts = []
elapsed = 0.0
@@ -320,12 +330,11 @@ def analyze_motion(sequence: FrameSequence, *, contacts=None, foot_box=None, fac
if touches:
sides[side].append(index)
edge_sides.append(side)
- ys, xs = np.nonzero(mask)
rows.append({
"frame": index, "time_seconds": starts[index], "duration_seconds": durations[index],
"bbox": bbox, "anchor_px": anchor.copy(),
"bbox_from_anchor": [v - anchor[i % 2] for i, v in enumerate(bbox)] if bbox else None,
- "centroid_px": [float(xs.mean() + 0.5), float(ys.mean() + 0.5)] if bbox else None,
+ "centroid_px": centroid(mask),
"opaque_pixels": int(mask.sum()), "edge_sides": edge_sides,
})
bboxes = [row["bbox"] for row in rows if row["bbox"] is not None]
diff --git a/sprite_gen/video/held_fill.py b/sprite_gen/video/held_fill.py
index b81e66f..5880d7e 100644
--- a/sprite_gen/video/held_fill.py
+++ b/sprite_gen/video/held_fill.py
@@ -35,7 +35,9 @@ made again at another fraction of RETIME_T within half a cell of its own time, e
why. A run is made whole or kept whole: half made it would step back.
`upsample` gives a cut at a rate above its own (`--out-fps`) its frames between, at their own times, never a frame
-shown again; a cell where both frames beside its time show one picture (a hold kept) is that picture."""
+shown again; a cell where both frames beside its time show one picture (a hold kept) is that picture. `at_times` makes
+a cut's cells at any times so: `upsample`'s, and the air a single play's air retime gives a new length
+(`root_motion.retime`, docs/video-pipeline.md "Root motion")."""
from __future__ import annotations
@@ -281,17 +283,16 @@ def times(n: int, fps: float, out_fps: float, *, ring: bool) -> list[float]:
return [k * (n - 1) / (count - 1) for k in range(count)]
-def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ring: bool, fps: float, out_fps: float,
- reads: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
- """`frames` given at `out_fps` (`times`): a cell on a frame's time is that frame, one between two frames showing
- one picture is that picture, any other is made between the two at its own time (`_made`, within half a cell of
- it), and one no frame made is taken for is the nearer frame and named (`shown_again`)."""
+def at_times(frames: list[Image.Image], interpolate: rife_mod.Interpolate, at: Sequence[float], *, ring: bool,
+ spacing: float | Sequence[float], reads: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`frames` at the times `at`, in frames of the cut: a cell on a frame's time is that frame, one between two frames
+ showing one picture is that picture, any other is made between the two at its own time (`_made`, within half its
+ `spacing` of it: frames a cell, one for all or one each), and one no frame made is taken for is the nearer frame and
+ named (`shown_again`). The record: how many were made, the cells shown again, and how each was (`frames`)."""
n = len(frames)
- at = times(n, fps, out_fps, ring=ring)
same = same_steps(frames + ([frames[0]] if ring else []))
if reads is None:
reads = bool(ghost_screen(frames)["reads"])
- spacing = fps / out_fps
out: list[Image.Image] = []
made: list[dict[str, Any]] = []
shown_again: list[int] = []
@@ -305,7 +306,8 @@ def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ri
out.append(frames[a])
continue
t = tau - a
- frame, how = _made(interpolate, frames[a], frames[(a + 1) % n], t, (t - spacing / 2, t + spacing / 2), reads=reads)
+ half = (spacing if isinstance(spacing, (int, float)) else spacing[k]) / 2
+ frame, how = _made(interpolate, frames[a], frames[(a + 1) % n], t, (t - half, t + half), reads=reads)
if frame is None:
out.append(frames[near % n])
shown_again.append(k)
@@ -313,8 +315,15 @@ def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ri
continue
out.append(frame)
made.append({"cell": k, "between": [a, (a + 1) % n], **how})
- return out, {"asked": out_fps, "fps": fps, "applied": True, "cells": len(out), "times": [round(x, 4) for x in at],
- "made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made}
+ return out, {"made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made}
+
+
+def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ring: bool, fps: float, out_fps: float,
+ reads: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`frames` given at `out_fps` (`times`), each cell at its own time (`at_times`, within half a cell of it)."""
+ at = times(len(frames), fps, out_fps, ring=ring)
+ out, made = at_times(frames, interpolate, at, ring=ring, spacing=fps / out_fps, reads=reads)
+ return out, {"asked": out_fps, "fps": fps, "applied": True, "cells": len(out), "times": [round(x, 4) for x in at], **made}
def public(record: dict[str, Any]) -> dict[str, Any]:
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 5f6191a..e5b42cc 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -762,7 +762,7 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,
# over the whole cycle undercounts a jump (crouch + airborne frames dominate) and then
# over-scales it — the 2026-09-09 hero read 22 % taller than the walk beside it.
floor = max(b[3] for b in boxes)
- grounded = [b[3] - b[1] for b in boxes if b[3] >= floor - 4] or [b[3] - b[1] for b in boxes]
+ grounded = [b[3] - b[1] for b in boxes if nonloop.on_floor(b, floor)] or [b[3] - b[1] for b in boxes]
# `standing_src` is the caller's own measurement of the standing pose (run_loop: the clip's
# first frame, or the cut's first — clip frame `standing_frame` — where the cut is filmed at
# another size than it). The tallest grounded frame counts whatever is raised overhead — an attack's
diff --git a/sprite_gen/video/nonloop.py b/sprite_gen/video/nonloop.py
index 49f4cf4..b1a0567 100644
--- a/sprite_gen/video/nonloop.py
+++ b/sprite_gen/video/nonloop.py
@@ -45,6 +45,7 @@ POSE_SHAPE_TOLERANCE = 0.05
POSE_FLOOR_TOLERANCE = 0.02
GROUND_HEIGHT_MAX = 0.8
GROUND_STATES = frozenset({"death", "fall"})
+GROUND_PX = 4 # a body whose lowest row is this close to the floor row stands on it (`on_floor`)
Box = tuple[int, int, int, int]
@@ -192,6 +193,13 @@ def metadata(cycle: dict[str, Any], indices: list[int]) -> dict[str, Any]:
"name": "motion_peak"}]}
+def on_floor(box: Box, floor: int) -> bool:
+ """Whether a body box (`body_box`) stands on the floor: its lowest row within GROUND_PX of the floor's, the lowest
+ row a body reaches. The strip's standing height is read on the frames that do (`loop.build_strip`), and a single
+ play's contacts with the ground are (sprite_gen/video/root_motion.py)."""
+ return box[3] >= floor - GROUND_PX
+
+
def body_box(frame: Any) -> Box | None:
return frame.getchannel("A").point(lambda a: 255 if a >= 8 else 0).getbbox()