Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(size-hold): video-pipeline §4 and loop-review's gait fallback say a fixed walk or run cut is held before the cut is read, over the whole clip, its feet held on the first frame's row where they climb or sink 1 % of the height or more, which cuts are not held, size_hold.feet and size_hold.anchor_regions, what --size-hold off really leaves (motion-auto's gait fallback scales back 3 % or more, its feet as filmed) and that a held cut is not restored from its source frames; --size-hold help likewise; CHANGELOG Unreleased names the fixed-cut hold as a capability added, the feet held, the scan's numbers that change, video-loop-repair's refusal and the synthetic byte comparison
Soohong Kim09db984706fa
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7bc235f..a627aca 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,16 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased+**Upgrading from 3.0.0: Fixed walk or run cuts and clips whose feet climb or sink now hold size and feet before cutting, changing bytes when size changes by 1 % or more.** Application scan numbers change for held clips, and held fixed cuts are not restored by `video-loop-repair`. Loops cut with `--size-hold off`, clips changing size by under 1 %, held `motion-auto` cuts on one row, and non-walk cuts keep their bytes. The report records `size_hold` on fixed walk or run cuts, `size_hold.feet` when size is held, and `size_hold.anchor_regions` under `--anchor motion`; `producer` names the new version.++- **New: Fixed cuts hold size before the cut is read.** Walk or run cuts using `--cycle fixed` with any anchor (`none`, `body`, `feet`, `motion`) now hold size over the whole clip before reading the cut. Seams, foot crossings (`cycle.step_count`), the gate, and application scans are read on held frames. Under `--anchor motion`, target regions are read where held (`size_hold.anchor_regions`). Passing `--size-hold off` keeps filmed frames pixel for pixel, recording `size_hold: {"applied": false, "why": "--size-hold off"}`. Automatic searches with `--anchor body`, `feet`, or `none`, `--cycle pinned`, and idle cuts are not held.+- **Changed: The size hold moves climbing or sinking feet to the first frame's row.** Where size changes by 1 % or more and feet climb or sink by 1 % of first-frame height or more (`FOOT_HOLD_MIN`), frames shift so feet stay on the first frame's row. Foot drift is read one cycle on (`gait_fallback.foot_drift`), preventing settling poses from reading as climbing feet. This stops wrap jumps from shifting into position where motion search (`motion_anchor.SEARCH_RADIUS`, 28 rows) or body anchors cannot correct them. Level clips keep their bytes. `size_hold` records `feet` (`min`: 0.01, `method`: `one-cycle-on`, `change_px`, `held`).+- **Note: What --size-hold off leaves in place.** With `--size-hold off`, `motion-auto` keeps its gait fallback: if the first search finds no cycle, size changes of 3 % or more (`SCALE_DRIFT_MIN`) are scaled back one cycle on with feet where filmed (`gait_fallback.scale_undone`). Cuts with `off` keep their previous bytes.+- **Changed: Held fixed cuts are not restored from source frames.** `video-loop-repair` reads cuts through source projection, which treats `size_hold.applied` as `source-processing-unsupported`. Recuts or scans of held fixed clips are not restored from source frames.+- **Output changes** Fixed walk or run cuts, scans, and `motion-auto` cuts of clips with climbing or sinking feet change bytes when size changes by 1 % or more. Across ten synthetic walkers cut four ways with `auto` and `off`, 62 of 80 keep their bytes. Changed cases are the fixed body cut and scan of eight walks changing size by 1 % or more (shrinking 7 % and 2 %, growing 20 % and 2.5 %, slow walk shrinking 7 %, two walks away, settling walk growing 2.5 %), plus `motion-auto` of the two walks away. On a walk away (15 % smaller, feet 20 px higher), a fixed body cut refused at seam ratio 6.83 passes held at 1.25 (size alone failed at 10.03); shrinking 2 % moves from 3.80 to 1.46; a walk whose feet climb 96 px refused under `motion-auto` at 13.03 passes held at 1.08. Scan ratios drop on the 7 % shrinking walk from 1.16 to 0.52, and on the walk away from 1.66 to 0.42. Shrinking 7 % cut by hand drops from 7.97 to 2.04 (still refused), and a slow walk shrinking 7 % from 18.31 to 4.48. The walk away under `motion-auto` moves from 0.79 to 1.41 because feet are held on row before cutting rather than closed by motion ramps.+- **Python callers** `gait_fallback.foot_drift(frames, measured)` returns `min`, `method`, `change_px`, `held`, and `lift` (frame shifts in px, None when not held). `gait_fallback.FOOT_HOLD_MIN` (0.01) is added. `gait_fallback.undo_padding` and `undo_scale` take `lift=None`. `gait_fallback.held_box(box, k, measured, pad, lift=None)` maps filmed frame `k` boxes to held coordinates.+- **Tests** In `tests/video/test_gait_fallback.py`: fixed cuts of the walk away and 2 % shrinking walker pass held under 2.0 seam ratio, wrap changes matching internal steps (size-only hold fails on feet); `motion-auto` on the 96 px climbing walk passes held on row with motion anchor applied; `--size-hold off` gives filmed frames pixel for pixel and records why; stable walkers keep identical bytes under `auto` and `off` and record not held; idle fixed cuts omit `size_hold`; foot drift reads 21 px for the 20 px walk away, 0 for level walks, and 0 for settling poses (fitted lines read 2.7 px); held walks away need no top room and `held_box` aligns head boxes; `--anchor motion` regions match held positions; forward walks mark feet not held while walks away close at feet. In `tests/video/test_loop_silent_pass.py`: the walk away jitter test passes `--size-hold off` so feet climb crop rows as before.+**Upgrading from 3.0.0: Bakes retain the same bytes for figures whose anatomy is unchanged. The `pixel` refusal message now names the sides and pixel counts. A figure that had `face-absent` may now have a face, with a lower rigid boundary only when that face ends below the neck. `video-sway-inspect` records use schema 3, and a cell whose every offset is 0 is now copied as it was, including colour under clear pixels with `--gain 0`; the other changes add options, and without them the strip, records and inspection stay as before.** Smooth bakes that leave the in-breath share out keep their bytes. A smooth `breathe.json` config and a breath sway's `drive` record now carry `inhale`, Python callers of `smooth_wave` and `smooth_shoulder_wave` must pass the share, and `breathe.INHALE` is gone. A smooth `breathe.json` config and a breath sway's `drive` record now also carry `start_cell` (0 when left out) and `loop_cells` (null when left out), and a record without them reads as the loop itself from its first cell.The Breathe layer still supports `pixel` and `smooth`.diff --git a/docs/loop-review.md b/docs/loop-review.mdindex 126a236..57aba1c 100644--- a/docs/loop-review.md+++ b/docs/loop-review.md@@ -162,13 +162,7 @@ long, `--steps 2` keeps it and says so ([loop repair](loop-repair.md) section 3,### The gait fallback: a slow walk, or a walk toward the cameraWhen the local search finds no cycle, `motion-auto` looks once more, for two things a-front or back gait does that the first search cannot see past. (Since 2.24.0 a clip that changes-size by 1 % or more, read one cycle on, is held at its first frame's size before the first-search — [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 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".)+front or back gait does that the first search cannot see past. (A clip that changes size by 1 % or more, read one cycle on, is held at its first frame's size before the first search ([video-pipeline.md](video-pipeline.md) section 4, `size_hold`), and its feet are held on the first frame's row where they climb or sink by 1 % of the height or more over the clip, so the fallback below seldom finds anything left to scale back unless `--size-hold off` was passed. The fallback still scales the size alone with the feet left where they were filmed. That is what `--size-hold off` leaves in place: with `off`, a clip the first search does not cut is still scaled back at 3 % or more. Both read the size one cycle on, so the two never disagree about a clip. A clip's lead-in, 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 matchesdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 692031b..3d71d22 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -363,14 +363,11 @@ and a true cycle half a drawing late are **the same picture**. So`video-loop` cuts the period it always cut, and only **records** what a half or a third of it shows(`cycle.fundamental`, `sprite_gen/video/period.py`).-**The size is held before the search** (`--anchor motion-auto`, `--size-hold auto`, the default).-A walk or run filmed from its first frame only (no end frame) often grows or shrinks as it plays:-a front walk comes a little closer with every step, a back walk goes away. The loop is then cut on-frames that change size, so the frame one cycle after the first is not the first's size and the-loop pops at the wrap.--`--size-hold off` searches-the frames as filmed.+**The size is held before the search or cut** (`--size-hold auto`, the default). A walk or run clip filmed from its first frame only often grows or shrinks as it plays, so the frame one cycle after the first is not the first's size and the loop pops at the wrap. Under `--size-hold auto`, a walk or run cut automatically with `--anchor motion-auto` (before the cycle search) or cut by hand with `--cycle fixed` under any anchor (before the cut is read, over the whole clip) is held at its first frame's size. When a clip's height changes by 1 % or more over the clip, read one cycle on, frames are scaled back to the first frame's size about their feet. Where the size is held and the feet climb or sink by 1 % of the first frame's height or more over the clip, frames are also shifted so their feet stand on the first frame's row. This stops a receding walk's jump at the wrap from moving into place: the motion anchor's fine search corrects a climb within 28 rows over the cut but leaves the cut uncorrected when feet climb further than that, and the body anchor moves frames sideways only.++The cut's seam and step count are measured on the held frames. The report records `size_hold` with `padding_ltrb`, and records `size_hold.feet` when size is held. Fixed cuts with `--anchor motion` record the shifted target boxes in `size_hold.anchor_regions`. Automatic searches under `--anchor body`, `feet`, or `none`, `--cycle pinned`, and cuts of states that are not a walk or run are not held. A held cut is not restored from its source frames by `video-loop-repair`.++Passing `--size-hold off` on a fixed cut keeps the filmed frames pixel for pixel and records `size_hold: {"applied": false, "why": "--size-hold off"}`. Under `--anchor motion-auto`, `--size-hold off` searches the filmed frames first, but if the first search finds no cycle, the gait fallback still scales back a size change of 3 % or more with feet left where filmed and searches again.**A lead-in is left out of the search** (walk and run, `--cycle auto` or `periodic`). A videomodel may reframe a small subject in a clip's first frames: the body grows (or shrinks) by a thirddiff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex fe33f92..d565bb5 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -2461,7 +2461,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--jolt-max", type=float, default=None, help=f"walk/run: fail the repaired loop when its jolt index (how far each step strays from its neighbours' mean, over the median step) exceeds this. Default: no gate — the index is reported and a value over {repair_mod.JOLT_REFERENCE} is a warning line")parser.add_argument("--head-step-max", type=float, default=None, help=f"walk/run: fail the repaired loop when the head's largest sideways move in one frame exceeds this %% of the body height. Default: no gate — reported, and over {repair_mod.HEAD_STEP_REFERENCE} is a warning line")parser.add_argument("--facing", choices=FACINGS, default="right", help="which way the body faces in the frames (default right): the jolt index's hair, and the size reading video-loop-compare's jump guard reads, are behind it; the jump repair reads the flow either way")- parser.add_argument("--size-hold", choices=SIZE_HOLD_MODES, default="auto", help="walk/run, --anchor motion-auto or --cycle fixed: auto (default) scales a clip whose height, read one cycle on (the same pose a cycle later), changes by 1 %% or more over the clip back to its first frame's size about its feet, and moves its feet back to the first frame's row where they climb or sink by 1 %% of its height or more (a walk away from the camera), before the cycle search or, for a fixed cut, before the cut is read — read over the whole clip — so the loop's last frame is the size of its first and stands where it stands (recorded as size_hold, with the evidence; a cut held is not restored from its source frames); off: the frames as filmed, but for motion-auto's gait fallback, which after a first search that finds nothing still scales back a change of 3 %% or more, by the same reading, its feet where they were filmed (recorded as gait_fallback)")+ parser.add_argument("--size-hold", choices=SIZE_HOLD_MODES, default="auto", help="walk/run, --anchor motion-auto or --cycle fixed: auto (default) scales a clip whose height, read one cycle on, changes by 1 %% or more over the clip back to its first frame's size about its feet, and moves its feet to the first frame's row where they climb or sink by 1 %% of the height or more, applied before the cycle search or over the whole clip before a fixed cut is read (recorded as size_hold; a held cut is not restored from source frames); off: the frames as filmed, except motion-auto's gait fallback, which after a first search that finds nothing still scales back a change of 3 %% or more by the same reading, its feet where they were filmed (recorded as gait_fallback)")parser.add_argument("--steps", type=int, choices=STEPS, default=None,help="--anchor motion-auto: how many steps the cut it takes without this holds, as counted by whoever looked ""at the loop (how often each foot lands) — the report's `cycle.step_screen` names a cut that may be one "