Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video): video-loop searches a walk after its lead-in, and reads the standing height there
Soohong Kim5fabda06dc14
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 60207a0..d31c7c5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,10 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased+- **Fix: `video-loop` leaves a walk's lead-in out of the search.** A video model may reframe a small subject in a clip's first frames — the body grows or shrinks by a third or more in under half a second, then walks at its new size. Searched with those frames, the motion analysis read the reframing as the clip's motion and lost the walk's repeat, and the gait fallback, scaling back by a line through the clip, read the step as steady growth and shrank the walk. A walk or run's sizes are now read one cycle on (`gait_fallback.cycle_drift`, the size hold's model) and the frames from the first on that are off it by 10 % or more (`LEAD_IN_MIN`) are its lead-in (`gait_fallback.lead_in`); `--cycle auto` and `periodic` — the size hold, the motion analysis, the cycle search and the gait fallback — read the clip after it as a clip of its own, window included. Every frame number the report gives is the clip's own: `cycle.start`, each candidate's `start` and `context_pair_range`, a refusal's windows too, so `--cycle fixed --start` taken from them cuts the frames they name. Every walk and run report gains `lead_in` (`frames`, `height_change`, `first_off`, `min`, `method`, `search_from`); a clip too short to read its size one cycle on has none (`why`). A cut the caller names (`fixed`, `pinned`) is the caller's frames. `cycle.coverage` counts the frames the search read. The gait fallback now scales back by the size read one cycle on, as the hold does, so a first pose settling into the walk no longer hides a body that grows from it (`gait_fallback.scale_drift` gains `method: one-cycle-on` in the report); a clip that reaches the fallback with 3 % or more of change is scaled by that model now, and its pixels and the drift its refusal quotes can differ in the last places. A walk or run with no lead-in that the first search cuts is cut as before, its strip, GIF, WebP, cycle frames and `strip.json` byte for byte. [docs/video-pipeline.md](docs/video-pipeline.md#4-loop--period-first-seam-second-then-the-gait-floor), [docs/loop-review.md](docs/loop-review.md#the-gait-fallback-a-slow-walk-or-a-walk-toward-the-camera).+- **Fix: after a lead-in, `--body-height` reads the standing height on the cut's first frame.** The clip's first frame is the still's pose as filmed, but a walk that opens on a lead-in films it at another scale: read there, the standing height scaled the walk up into the cell cap. Such a cut now reads it on its own first frame, and `strip.json` says so (`body_ref: cut-first-frame`, `body_ref_frame`, the clip frame); `video-cycle-align` rebuilds such a strip at the same height. A clip with no lead-in reads its first frame as before, and its `strip.json` is as before. [docs/video-pipeline.md](docs/video-pipeline.md#4-loop--period-first-seam-second-then-the-gait-floor).+- **`tests/video/test_edge_speck_lead_in.py`**: a walker filmed at 0.63 of its size and reframed over 9 frames: a lead-in of 5 frames, found no cycle before, now cuts its 24-frame walk after it, every frame number its own; too slow a walk after the same lead-in is refused with windows that all start after it; a fixed cut there reads its standing height on its own first frame, and `video-cycle-align` keeps it. A walker that settles from its first pose and grows 5 % reads 2.8 % on a line and was refused; read one cycle on it is scaled back and cut.+- **Fix: `video-frames` erases a speck far from the body before the edge check.** A fleck the model drew drifting across the background survives the matte as a few pale pixels; where it crossed an edge band in one frame, the edge check read it as the subject framed too tight and refused the clip, and `video-loop --anchor motion-auto`, which never cleans a frame, kept it in the loop and widened every cell to reach it. Now every keyed frame has its specks erased before anything reads it (`frames.drop_specks`): a piece of the frame — its opaque pixels, corners joining them — under 1 % of the body (`SPECK_MIN_FRACTION`, at least 8 px) and more than a tenth of the body's height from it (`SPECK_APART`). Small pieces near the body are the subject's own and stay: the outline's loose pixels, a shadow drawn under a shoe, a part of a shoe the matte cut loose. Each report row gains `specks`, how many its frame lost, and the report `specks` (`dropped`, `frames` and the rule's numbers); a frame with no speck is not written again, so its bytes are as before. `video-loop`'s own pass on a cut that is not motion-reviewed (`--anchor none|feet|body`) erases every island of solid pixels under the same 1 % as before, pixel for pixel, through the same function (a run-based labelling, about twenty times faster than the pixel-by-pixel search it replaces). [docs/video-pipeline.md](docs/video-pipeline.md#3-frames--extract-key-check-the-edges).- **`tests/video/test_edge_speck_lead_in.py`** keys a body on magenta with five pale pixels in its right edge band in one frame: before this the frames were refused as framed too tight, now the fleck is erased (`specks: 1`) and no frame touches the edge; a shadow under the feet, a loose pixel by the outline and a far block too large to be a speck are kept; `video-loop`'s own reading still erases the loose pieces. A walker on magenta with a fleck drifting far from it, keyed and cut `--anchor motion-auto`, is cut 49 px wide, the walker alone (147 px before).diff --git a/docs/loop-review.md b/docs/loop-review.mdindex 1c8cb0c..434e85d 100644--- a/docs/loop-review.md+++ b/docs/loop-review.md@@ -127,15 +127,17 @@ When the local search finds no cycle, `motion-auto` looks once more, for two thifront or back gait does that the first search cannot see past. (Since 2.24.0 a clip that changessize by 1 % or more, read one cycle on, is held at its first frame's size before the firstsearch — [video-pipeline.md](video-pipeline.md) section 4, `size_hold` — so the fallback below-seldom finds anything left to scale back unless `--size-hold off` was passed. It still reads the-line through the clip, so a clip the hold left as filmed, whose line reads 3 % or more, is scaled-back here if the first search found no cycle.)+seldom finds anything left to scale back unless `--size-hold off` was passed. It reads the size+the way the hold does, one cycle on, so the two never disagree about a clip. A clip's lead-in —+its first frames, where the video model reframed a small subject — is left out of both searches,+[video-pipeline.md](video-pipeline.md) section 4, "A lead-in".)- **It walked toward the camera, or away from it.** Asked to walk in place, a front walksometimes comes closer, and the body grows through the clip, so the same pose never matches- itself in size. A straight-line fit of the subject's opaque height measures it (the exact line,- `sprite_gen.util.lsq`, as for the size hold); at 3 % or- more over the clip (`SCALE_DRIFT_MIN`) every frame is scaled back to the first frame's fitted+ itself in size. The change read one cycle on measures it (`gait_fallback.cycle_drift`, as for+ the size hold; it was a straight line through the clip before, which a first pose settling into+ the walk pulls flat over a body that does grow); at 3 % or+ more over the clip (`SCALE_DRIFT_MIN`) every frame is scaled back to the first frame'sheight about its fitted foot point, with its coverage and its colour mapped apart(`transform_cell`, [video-pipeline.md](video-pipeline.md) "Cells") so the soft edge keeps itscolour and gets no lighter rim or key tint from the resample. Thediff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex d73f318..a811fe0 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -829,6 +829,26 @@ the frames as filmed, as before 2.24.0. When the hold came in (2.24.0, read offmeasured on one front catwalk filmed from its first frame (+2.0 % over 3 s): the engine's seamratio of the cut went from 1.44 to 1.19.+**A lead-in is left out of the search** (walk and run, `--cycle auto` or `periodic`). A video+model may reframe a small subject in a clip's first frames: the body grows (or shrinks) by a third+or more in under half a second, then walks at its new size. Searched with those frames, the+motion analysis reads the reframing as the clip's motion and the walk's repeat is lost; the gait+fallback, which then scaled by a line through the clip, read the step as a steady growth and+shrank the walk. So the clip's sizes are read one cycle on (`gait_fallback.cycle_drift`, the+hold's model, a median over the whole clip), and the frames from the first on that are off that+model by 10 % or more (`LEAD_IN_MIN`; a walk's own frames stray from it by a head bob, a few+percent) are the lead-in (`gait_fallback.lead_in`). The search — the size hold, the motion+analysis, the cycle search and the gait fallback — reads the clip after it as a clip of its own,+its window included. What it finds, and what it refuses, is said in the clip's own frame numbers:+every `start` and `context_pair_range` in the report's `cycle`, refused candidates too, so a cut+taken again from them (`--cycle fixed --start`) is the frames they name. The report records it on+every walk and run (`lead_in`: `frames`, 0 for none; `height_change`, the walk's height where the+lead-in ends over the first frame's, less 1; `first_off`; `search_from`, the first frame the search+read). A cut the caller names (`fixed`, `pinned`) is the caller's frames, lead-in or not. A clip+too short to read its size one cycle on has no lead-in (`why`). On a synthetic walker filmed at+0.63 of its size and reframed over 9 frames, the search as filmed found no cycle, nor did the+fallback; after its 5-frame lead-in it cuts the 24-frame walk (`tests/video/test_edge_speck_lead_in.py`).+**Nothing is cut when a frame is scaled up.** A clip that shrinks is scaled up about its feet,and when the feet also rose in the frame (a back walk going away toward the horizon) the crownlands above the frame. Every frame is first widened by the room the furthest one reaches past@@ -938,8 +958,12 @@ Outputs:character size (`--strip-height` stays the cap). With a target, the standing height ismeasured on the **clip's first frame** instead — the base still's pose, which every clipstarts from — because the tallest grounded frame of an attack is its windup with the weapon- overhead, and scaling that to N shrank the character against its walk. The sidecar says- which (`body_ref`: `first-frame` or `tallest-grounded`) and records `body_src_h` and `scale`. `delay_ms = cycle_seconds / frames`, so a+ overhead, and scaling that to N shrank the character against its walk. A walk or run that opens+ on a lead-in (section 4) films that pose at another scale than the walk, so there the standing+ height is read on the cut's own first frame (`body_ref: cut-first-frame`, and `body_ref_frame`,+ the clip frame it was read on); read on the first frame, filmed small, it scaled the walk up into+ the cell cap. The sidecar says which (`body_ref`: `first-frame`, `cut-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 celldiff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex 71c3f2f..3630eb1 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -584,10 +584,11 @@ def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: listfor k, im in enumerate(frames):im.save(cycle_dir / f"frame-{k:03d}.png")cycle_seconds = len(frames) / fps- standing = meta.get("body_src_h") if meta.get("body_ref") == "first-frame" else None+ standing = meta.get("body_src_h") if meta.get("body_ref") in ("first-frame", "cut-first-frame") else Nonestrip, strip_meta = loop_mod.build_strip(frames, max_height=int(meta["cell_height_cap"]), cycle_seconds=cycle_seconds, body_height=meta.get("body_height_target"),- anchor="feet" if meta.get("foot_anchor") == "feet" else "none", kind=str(meta["kind"]), standing_src=standing)+ anchor="feet" if meta.get("foot_anchor") == "feet" else "none", kind=str(meta["kind"]), standing_src=standing,+ standing_frame=int(meta.get("body_ref_frame") or 0))# what build_strip does not own (how the cut was anchored) is carried over as it was; a# follow-through moved the old cycle's cells, so it is cleared and the record says soif "follow" in meta or (loop_dir / loop_mod.FOLLOW_SOURCE).exists():diff --git a/sprite_gen/video/gait_fallback.py b/sprite_gen/video/gait_fallback.pyindex 93e16cd..2fdaf95 100644--- a/sprite_gen/video/gait_fallback.py+++ b/sprite_gen/video/gait_fallback.py@@ -24,7 +24,15 @@ clip: a clip that starts from a standing pose and settles into the walk over itsreads that one change of pose as a body that shrinks all the way. The same pose a cycle lateris the same size unless the body really grows or shrinks, so the hold compares each frame'sheight with the frames whole pose-matched lags later and takes the middle of those changes; the-few frames of the first pose do not move a median of the rest.+few frames of the first pose do not move a median of the rest. The second search scales back by+the same reading, so both hold one size model.++A clip can also open on a **lead-in**: the video model reframes a small subject in its first+frames, so the body grows (or shrinks) by a third or more in under half a second and then walks+at its new size. The one-cycle-on model, a median over the whole clip, holds the walk's size;+the frames off it by `LEAD_IN_MIN` or more from the first one on are the lead-in (`lead_in`). A+walk's own frames stray from it by a head bob and hair, a few percent; a reframing starts tens+of percent off it."""from __future__ import annotations@@ -36,14 +44,17 @@ from sprite_gen._deps import npfrom sprite_gen.util import lsqfrom sprite_gen.util.resample import transform_cell-# Height change over the clip, from the fitted trend, at which the frames are scaled back.-# Nine in ten walk clips stay under it (median 0.5 %): their change is a head bob and hair.+# Height change over the clip, read one cycle on (`cycle_drift`), at which the second search scales+# the frames back. Nine in ten walk clips stay under it (median 0.5 %): their change is a head bob and hair.SCALE_DRIFT_MIN = 0.03# Height change over the clip at which a walk or run is held at its first frame's size before the# first cycle search (`video-loop --size-hold auto`). Below it the fitted trend is a head bob and# hair; above it a clip filmed from its first frame only grows or shrinks enough that the loop's# last frame is a different size from its first, and the loop pops at the wrap.SIZE_HOLD_MIN = 0.01+# A frame whose height is off the one-cycle-on model by this much is not yet walking at the clip's size:+# the first frames off it by this much are a lead-in (`lead_in`).+LEAD_IN_MIN = 0.1# The longest cycle the second search accepts, as a share of the clip and in seconds.LONG_CYCLE_FRACTION = 0.6LONG_CYCLE_SECONDS = 2.0@@ -164,6 +175,29 @@ def cycle_drift(frames: list[Image.Image], *, min_lag: int, max_lag: int) -> dic"height_last_px": round(float(height[-1]), 2), "height": height}+def lead_in(frames: list[Image.Image], *, min_lag: int, max_lag: int) -> dict:+ """The frames the clip opens on before its subject walks at the clip's size: from the first, every+ frame whose height (`coverage_heights`) is off the one-cycle-on model (`cycle_drift`) by+ LEAD_IN_MIN or more. `frames` is how many (0: none), `height_change` the model's height where the+ lead-in ends over the first frame's, less 1 (+0.5: the body grew by half), `first_off` how far the+ first frame is off the model. A frame with no subject ends it. A clip too short to show a cycle+ twice has no model to read it on: no lead-in, and `why` says so."""+ heights = coverage_heights(frames)+ measured = cycle_drift(frames, min_lag=min_lag, max_lag=max_lag)+ if measured["lag"] is None:+ return {"frames": 0, "height_change": 0.0, "first_off": None, "min": LEAD_IN_MIN, "method": "one-cycle-on",+ "why": "no lag in range: the clip is too short to read its size one cycle on"}+ model = measured["height"]+ off = heights / model - 1+ count = 0+ while count < len(frames) - 1 and np.isfinite(off[count]) and abs(off[count]) >= LEAD_IN_MIN:+ count += 1+ change = float(model[count] / heights[0] - 1) if count and heights[0] > 0 else 0.0+ return {"frames": count, "height_change": round(change, 4),+ "first_off": round(float(off[0]), 4) if np.isfinite(off[0]) else None,+ "min": LEAD_IN_MIN, "method": "one-cycle-on"}++def undo_padding(frames: list[Image.Image], measured: dict) -> tuple[int, int, int, int]:"""Left, top, right, bottom room every frame needs so `undo_scale` cuts nothing.diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex ef983af..ba8ace0 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -649,20 +649,22 @@ def ramp_frames(frames: list[Image.Image], wrap_dx: int) -> list[Image.Image]:return out-def first_frame_height(path: Path) -> int:- """The subject's height in the clip's first frame: the base still's pose as filmed.+def standing_height(path: Path, frame: int = 0) -> int:+ """The subject's height in clip frame `frame`: the clip's first frame, the base still's pose as filmed.Every clip starts from its still (image-to-video), so this is the same pose in everystate of one character — which is what one `--body-height` across states has to measure- to give that character one size.+ to give that character one size. A clip that opens on a lead-in is read on the cut's first+ frame instead (run_loop): its first frame is at another scale."""box = Image.open(path).convert("RGBA").getchannel("A").point(lambda v: 255 if v >= 8 else 0).getbbox()if box is None:- raise SystemExit(f"video-loop: {path.name}, the clip's first frame, has no subject to measure the standing height on (--body-height)")+ which = "the clip's first frame" if frame == 0 else f"frame {frame}, the cut's first"+ raise SystemExit(f"video-loop: {path.name}, {which}, has no subject to measure the standing height on (--body-height)")return box[3] - box[1]-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]]:+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, standing_frame: int = 0) -> tuple[Image.Image, dict[str, Any]]:"""Union-crop (no bottom pad so feet meet the floor), scale, bottom-align, tile horizontally.The cell count is capped by the strip's PIXEL width (`max_width`) as well as by@@ -686,7 +688,8 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,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]# `standing_src` is the caller's own measurement of the standing pose (run_loop: the clip's- # first frame). The tallest grounded frame counts whatever is raised overhead — an attack's+ # first frame, or the cut's first — clip frame `standing_frame` — where the clip opens on a+ # lead-in). The tallest grounded frame counts whatever is raised overhead — an attack's# windup lifts the weapon above the head — and would shrink that state against the others.body_src = standing_src if standing_src is not None else max(grounded)# max_height is a ceiling on the CELL; an explicit body_height is a target for the BODY.@@ -738,7 +741,7 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,"loop": kind != "one-shot","body_h": round(body_src * scale),"body_src_h": body_src, # the standing height as filmed; body_h / body_src_h > 1 means the cells were upscaled- "body_ref": "first-frame" if standing_src is not None else "tallest-grounded",+ "body_ref": ("cut-first-frame" if standing_frame else "first-frame") if standing_src is not None else "tallest-grounded","scale": round(scale, 4),"delay_ms": round(1000 * cycle_seconds / len(cells), 2),"cycle_frames": L,@@ -753,6 +756,8 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,"foot_sway_px": round(sway), # source px the planted foot moves within the gait, kept as is (0 when not measured)"foot_x": round(lead * scale) if feet else None, # x of the foot line inside every cell}+ if standing_src is not None and standing_frame:+ meta["body_ref_frame"] = standing_frame # the clip frame the standing height was read onif feet:# the spec asset loader reads a sidecar `anchor` as the [x, y] pivot (default:# bottom-centre); with feet alignment the true pivot is the foot line at the@@ -988,6 +993,19 @@ def _counted(cycle: dict[str, Any], steps: int, *, window: CutWindow, D: np.ndarreturn found+def _from_lead_in(record: Any, lead: int) -> Any:+ """A search's record (a cut, or the windows a refusal measured) in the clip's own frame numbers: the+ search read the clip after its first `lead` frames, so every `start` and `context_pair_range` it wrote+ moves on by `lead`. A caller cuts again from these (`--cycle fixed --start`) on the whole clip."""+ if isinstance(record, dict):+ return {key: (value + lead if key == "start" and isinstance(value, int)+ else [value[0] + lead, value[1] + lead] if key == "context_pair_range"+ else _from_lead_in(value, lead)) for key, value in record.items()}+ if isinstance(record, list):+ return [_from_lead_in(value, lead) for value in record]+ return record++def _one_shot(D: np.ndarray, window: CutWindow, hi: int, masses: np.ndarray) -> dict[str, Any]:"""`detect_one_shot` in its window: ONE_SHOT_MIN_LEN to `hi`, inside the caller's bounds. Where thecaller set one and no one-shot fits, the refusal says the window it searched."""@@ -1067,8 +1085,18 @@ def run_loop(raise SystemExit(f"video-loop: need at least 6 keyed frames in {frames_dir}, found {len(files)}")prof = profile_for(state)n = len(files)+ # A walk or run may open on a lead-in (gait_fallback.lead_in): the video model reframing a small+ # subject before it walks at the clip's size. An automatic search reads the clip after it as a clip+ # of its own, and what it finds is said in the clip's own frame numbers (`_from_lead_in`); a cut the+ # caller names (fixed, pinned) is the caller's frames, lead-in or not.+ gait_frames = [Image.open(f).convert("RGBA") for f in files] if prof.gait else None+ lead: dict[str, Any] | None = None+ if gait_frames is not None:+ whole = CutWindow.of(prof, n, fps, min_len, max_len)+ lead = gait_fallback.lead_in(gait_frames, min_lag=whole.lo, max_lag=whole.hi)+ skip = lead["frames"] if lead is not None and cycle_mode in ("auto", "periodic") else 0# Every search below reads its window off this one (`CutWindow`): none sets a bound of its own.- window = CutWindow.of(prof, n, fps, min_len, max_len)+ window = CutWindow.of(prof, n - skip, fps, min_len, max_len)lo, hi = window.lo, window.hiD = distance_matrix(files)# The clip's steps as keyed, before `--anchor motion-auto` reads its own distance or moves a frame:@@ -1089,10 +1117,16 @@ def run_loop(# `video-cycle-align`, which says when a held clip stretched to the set's length must be filmed again."drawings": held_mod.measure(clip_steps, fps=fps),}+ if lead is not None:+ # `search_from`: the first clip frame the search read (0: the whole clip, or a cut the caller named).+ report_base["lead_in"] = {**lead, "search_from": skip}cycle = None+ shifted = False+ clip_files, clip_D = files, D+ files, D = files[skip:], D[skip:, skip:]try:if anchor == "motion-auto":- source_frames = [Image.open(f).convert("RGBA") for f in files]+ source_frames = gait_frames[skip:]if size_hold == "auto":# A walk or run filmed from its first frame only grows or shrinks as it plays, so the# frame one cycle on is not the size of the first and the loop pops at the wrap. Hold@@ -1123,8 +1157,8 @@ def run_loop(except ValueError as first:# A front or back gait that walked toward the camera, or a slow one: one more# search, recorded (`gait_fallback`), and only after the first found nothing.- drift = gait_fallback.scale_drift(source_frames)- fallback = {"reason": str(first), "scale_drift": {k: drift[k] for k in ("height_first_px", "height_last_px", "drift")},+ drift = gait_fallback.cycle_drift(source_frames, min_lag=lo, max_lag=hi)+ fallback = {"reason": str(first), "scale_drift": {k: drift[k] for k in ("height_first_px", "height_last_px", "drift", "method")},"scale_drift_min": gait_fallback.SCALE_DRIFT_MIN, "scale_undone": False}if abs(drift["drift"]) >= gait_fallback.SCALE_DRIFT_MIN:fallback["padding_ltrb"] = list(gait_fallback.undo_padding(source_frames, drift))@@ -1134,7 +1168,7 @@ def run_loop(report_base["automatic_motion_analysis"] = analysisfallback["scale_undone"] = True# An explicit --max-len is the caller's ceiling and stays one.- hi_long = window.past(gait_fallback.long_window(lo, n, fps))+ hi_long = window.past(gait_fallback.long_window(lo, len(files), fps))fallback["window"] = [lo, hi_long]report_base["gait_fallback"] = fallbacktry:@@ -1163,9 +1197,9 @@ def run_loop(else:gait_floor = round(prof.min_seconds * fps) if prof.gait and prof.min_seconds > 0 else Nonecycle = detect_cycle(D, min_len=lo, max_len=hi, gait_floor=gait_floor,- signals=leg_signals([Image.open(f).convert("RGBA") for f in files]))+ signals=leg_signals(gait_frames[skip:] if gait_frames is not None else [Image.open(f).convert("RGBA") for f in files]))cycle["kind"] = "periodic"- floor = periodicity_floor(n, cycle["period_global"], partial_repeat=prof.action_seconds is not None)+ floor = periodicity_floor(len(files), cycle["period_global"], partial_repeat=prof.action_seconds is not None)cycle["periodicity_min"] = floorif prof.periodic and cycle["periodicity"] < floor:flat = (@@ -1182,20 +1216,25 @@ def run_loop(f"video-loop: no periodic cycle found — {flat}; the motion does not repeat, widen the window, ""regenerate the clip, or pass --cycle one-shot for a single performed action")+ if skip:+ cycle, shifted = _from_lead_in(cycle, skip), True# Whatever chose the cut — a search, a count, --cycle fixed or pinned — it is inside the caller's bounds.window.hold(cycle)except (SystemExit, ValueError) as exc:shutil.rmtree(out_dir.expanduser().resolve() / FALLBACK_FRAMES_DIR, ignore_errors=True)+ refused = getattr(exc, "diagnostics", cycle)write_loop_report(target, {**report_base, "status": "failed", "error": str(exc),- "cycle": getattr(exc, "diagnostics", cycle),+ "cycle": _from_lead_in(refused, skip) if skip and not shifted else refused,"periodic_attempt": periodic_attempt})if isinstance(exc, ValueError):raise SystemExit(f"video-loop: {exc}") from excraise+ # The cut is in the clip's own frame numbers; the frames it reads are the clip's, scaled where the search scaled them.+ files, D = clip_files[:skip] + files, clip_Di, L = cycle["start"], cycle["length"]if "steps" in cycle:- # A cut two steps long is one cycle: how much of a second the clip holds past it.- cycle["coverage"] = round((n - L) / L, 4)+ # A cut two steps long is one cycle: how much of a second the clip holds past it (after its lead-in).+ cycle["coverage"] = round((n - skip - L) / L, 4)# The same, over the cut alone: a clip held for part of its length is held where the cut is.report_base["cycle_drawings"] = held_mod.measure_cycle(clip_steps, start=i, length=L, fps=fps)# playback density, not a fixed count: a long cycle gets more frames so every state plays at@@ -1296,8 +1335,12 @@ def run_loop((out_dir / FOLLOW_SOURCE).unlink(missing_ok=True)for k, im in enumerate(frames):im.save(cycle_dir / f"frame-{k:03d}.png")+ # The standing height is the base still's pose as filmed, the clip's first frame — but a clip that opens+ # on a lead-in films that pose at another scale than the walk: there it is read on the cut's own first frame.+ standing_frame = i if lead is not None and lead["frames"] else 0strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),- standing_src=first_frame_height(files[0]) if body_height is not None else None)+ standing_src=standing_height(files[standing_frame], standing_frame) if body_height is not None else None,+ standing_frame=standing_frame)# The scaled-back frames are read for the last time above; the cycle cells keep them.shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)if state:diff --git a/tests/video/test_edge_speck_lead_in.py b/tests/video/test_edge_speck_lead_in.pyindex e375277..8eefbd0 100644--- a/tests/video/test_edge_speck_lead_in.py+++ b/tests/video/test_edge_speck_lead_in.py@@ -1,7 +1,12 @@# SPDX-License-Identifier: Apache-2.0-"""A fleck far from the body is not the subject touching the edge.+"""A fleck far from the body is not the subject touching the edge, and a clip's first frames that reframe a+small subject are not part of its walk.* `video-frames` erases a speck — a small piece far from the body — before the edge check reads the frame.+* `video-loop` reads a walk's lead-in (the first frames off the walk's size) and searches the clip after it;+ what it finds, and what it refuses, is said in the clip's own frame numbers. The gait fallback scales back+ by the size read one cycle on, as the hold does. A cut after a lead-in reads the standing height on its+ own first frame."""from __future__ import annotations@@ -107,3 +112,111 @@ def test_a_motion_auto_loop_of_a_clip_with_a_fleck_is_cut_without_it(tmp_path):repair="off")walker_width = walks.walker(0).getchannel("A").getbbox()assert out["strip"]["w"] <= walker_width[2] - walker_width[0] + 2 * 8 + 8 # the walker, its margins, a little sway+++# --- a walk's lead-in -----------------------------------------------------------------------------------------+++def zoomed(k: int, *, period: int = 24, frames: int = 9, start: float = 0.63) -> Image.Image:+ """The walker, filmed small and reframed over its first `frames` frames to its walking size: scaled from+ `start` about its feet, easing out (x1.59 over 0.4 s at the defaults)."""+ image = walks.walker(k, period=period)+ t = min(1.0, k / frames)+ s = start + (1 - start) * (1 - (1 - t) ** 2)+ if s >= 1:+ return image+ ax, ay = walks.FOOT+ return image.convert("RGBa").transform(image.size, Image.Transform.AFFINE, (1 / s, 0, ax * (1 - 1 / s), 0, 1 / s, ay * (1 - 1 / s)),+ resample=Image.Resampling.BICUBIC).convert("RGBA")+++def test_a_lead_in_is_the_first_frames_off_the_walks_size():+ lead = gait_fallback.lead_in([zoomed(k) for k in range(73)], min_lag=12, max_lag=36)+ assert 4 <= lead["frames"] <= 7 and lead["first_off"] < -0.3 and 0.45 < lead["height_change"] < 0.65+ shrinking = gait_fallback.lead_in([zoomed(k, start=1.5) for k in range(73)], min_lag=12, max_lag=36)+ assert shrinking["frames"] >= 3 and shrinking["first_off"] > 0.3 and shrinking["height_change"] < -0.25+ # A walk, a walk toward the camera, a first pose that settles into the walk: none has a lead-in.+ for clip in ([walks.walker(k) for k in range(73)], [walks.walker(k, grow=0.2) for k in range(73)],+ [walks.settling(k) for k in range(73)]):+ found = gait_fallback.lead_in(clip, min_lag=12, max_lag=36)+ assert found["frames"] == 0 and abs(found["first_off"]) < gait_fallback.LEAD_IN_MIN+ short = gait_fallback.lead_in([zoomed(k) for k in range(20)], min_lag=12, max_lag=36)+ assert short["frames"] == 0 and "too short" in short["why"]+++def test_the_search_reads_the_walk_after_its_lead_in(tmp_path):+ # Searched as filmed, the reframing hides the walk's repeat and the gait fallback fails too.+ code, report, _ = walks.run(tmp_path, [zoomed(k) for k in range(73)], "--size-hold", "off")+ assert code == 0+ lead = report["lead_in"]+ assert 4 <= lead["frames"] <= 7 and lead["search_from"] == lead["frames"]+ cycle = report["cycle"]+ assert abs(cycle["length"] - 24) <= 1 and "gait_fallback" not in report+ # Every frame number is the clip's own: a caller cuts again from them on the whole clip.+ assert cycle["start"] >= lead["frames"] and all(row["start"] >= lead["frames"] for row in cycle["candidates"])+ assert report["window"] == list(loop.profile_for("walk").window(73 - lead["frames"], 24.0))+++def test_a_refusal_after_a_lead_in_names_windows_in_the_clips_frames(tmp_path):+ # Too slow a walk to repeat: refused, with the windows measured — every one after the lead-in, numbered+ # as the clip is, which `--cycle fixed --start` cuts on.+ code, report, _ = walks.run(tmp_path, [zoomed(k, period=200) for k in range(73)], "--size-hold", "off")+ assert str(code).startswith("video-loop: no periodic cycle found")+ lead = report["lead_in"]["frames"]+ assert lead >= 4+ starts = [row["start"] for row in report["cycle"]["candidates"]]+ assert starts and min(starts) >= lead+++def test_the_gait_fallback_scales_back_by_the_size_read_one_cycle_on(tmp_path):+ # A walker that settles from its standing first pose and grows 5 %: a line through every frame reads+ # under 3 % and the frames were searched as filmed; one cycle on, the growth is read and scaled back.+ frames = [walks.settling(k, grow=0.05) for k in range(73)]+ assert gait_fallback.scale_drift(frames)["drift"] < gait_fallback.SCALE_DRIFT_MIN+ code, report, output = walks.run(tmp_path, frames, "--size-hold", "off")+ assert code == 0 and abs(report["cycle"]["length"] - 24) <= 1+ fallback = report["gait_fallback"]+ assert fallback["scale_undone"] is True and fallback["scale_drift"]["method"] == "one-cycle-on"+ assert fallback["scale_drift"]["drift"] > gait_fallback.SCALE_DRIFT_MIN+ cells = sorted((output / "cycle").glob("frame-*.png"))+ boxes = gait_fallback.subject_boxes([Image.open(p).convert("RGBA") for p in cells])+ assert np.ptp(boxes[:, 3] - boxes[:, 1]) <= 2+++def _height(path: Path) -> int:+ box = Image.open(path).convert("RGBA").getchannel("A").point(lambda v: 255 if v >= 8 else 0).getbbox()+ return box[3] - box[1]+++def _fixed(tmp_path: Path, clip: list[Image.Image], start: int) -> tuple[dict, dict, Path]:+ keyed = tmp_path / "keyed"+ keyed.mkdir()+ for k, image in enumerate(clip):+ image.save(keyed / f"{k:03}.png")+ out = loop.run_loop(keyed, tmp_path / "out", fps=24.0, state="walk", min_len=None, max_len=None, n_out=None,+ seam_max=1000.0, name="w", report_path=None, cycle_mode="fixed", start=start, length=24,+ body_height=120, anchor="body", repair="off")+ return out, json.loads((tmp_path / "out" / "w.strip.json").read_text()), keyed+++def test_a_cut_after_a_lead_in_reads_the_standing_height_on_its_own_first_frame(tmp_path):+ # Read on the first frame, filmed small, the standing height scaled the walk up by half again.+ out, meta, keyed = _fixed(tmp_path, [zoomed(k) for k in range(73)], 12)+ assert out["lead_in"]["frames"] >= 4 and out["lead_in"]["search_from"] == 0 # a named cut is the caller's frames+ assert meta["body_ref"] == "cut-first-frame" and meta["body_ref_frame"] == 12+ assert meta["body_src_h"] == _height(keyed / "012.png") > _height(keyed / "000.png") + 30+ assert meta["scale"] == round(120 / meta["body_src_h"], 4)+ # `video-cycle-align` rebuilds the strip at the same standing height.+ for name in ("a", "b"):+ shutil.copytree(tmp_path / "out", tmp_path / name)+ align.align_set([tmp_path / "a", tmp_path / "b"], between="nearest")+ aligned = json.loads((tmp_path / "a" / "w.strip.json").read_text())+ assert (aligned["body_ref"], aligned["body_ref_frame"], aligned["body_src_h"], aligned["scale"]) == \+ ("cut-first-frame", 12, meta["body_src_h"], meta["scale"])+++def test_a_cut_of_a_clip_with_no_lead_in_reads_its_first_frame_as_before(tmp_path):+ out, meta, keyed = _fixed(tmp_path, [walks.walker(k) for k in range(73)], 12)+ assert out["lead_in"]["frames"] == 0+ assert meta["body_ref"] == "first-frame" and "body_ref_frame" not in meta+ assert meta["body_src_h"] == _height(keyed / "000.png")