Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: outline_loss and --between auto; changelog
Soohong Kime96edb9b0a38
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5ad53ed..ae15c71 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,12 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased - A frame RIFE made whose legs melted is caught by the outline it lost, and the set alignment takes the nearer source frame there++- **Output change: which frames `video-cycle-align` keeps from RIFE.** `--between` gains `auto`, now the default (`video-set --align-between` too): every frame between two source frames is still made by RIFE and measured, and one that smeared or lost its outline takes the nearer source frame instead, named in the warnings. A set whose made frames all keep their outline comes out byte for byte as 2.27.0's; where one melted, that frame is now the nearer filmed frame, the loop's `cycle_align` gains `nearest_at` beside `made_at`, and `made_by_rife` counts only the frames kept. `--between rife` gives 2.27.0's frames, with the new warnings; `nearest` is unchanged.+- **Fix: a frame RIFE melted passed without a word.** Where two drawings are too far apart for the flow — legs crossing a long way, as a clip drawn on twos gives between its drawings — RIFE draws the legs as one shape of fill with no outline between or around them. 2.25.0's smear check warns only on dark pixels added, and a melted frame has fewer: it lost its outline. `rife.smear` now also measures `outline_loss`: of the frame's coverage edge (alpha from 0.1, so a pale ghost limb's edge counts), the share with no dark pixel within 2 px, beyond the less outlined neighbour's. Over 5 % (`align.OUTLINE_WARN`) the frame has the fault `outline`; over 0.1 % dark, as before, `smear` (`align.faults`). The dark count's other side does not do this: a clean frame half way between two drawings has fewer dark pixels than the darker one wherever they differ, and on two outlined legs RIFE's clean frames of a short step read `dark_excess` −1.3 %, lower than its melted frame of a long crossing (−1.1 %); `outline_loss` reads under 3 % and 32 % (`tests/video/test_rife.py`). `partial_excess` is still reported and not judged: a melted frame and a clean one read alike on it.+- **Every made frame says what became of it**: `cycle_align.smear` rows gain `method` (`rife`, kept, or `nearest`, the nearer source frame taken instead), `outline_loss` and `faults`; the report gains `replaced`, and `video-set`'s `cycle_align` per state too. A fault is a line in `warnings` under every `--between`: under `auto` it says the nearer source frame was taken there, under `rife` that the frame is kept and where to look. `auto` runs RIFE wherever `rife` does and needs it installed the same way. [docs/loop-repair.md](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto).+## v2.27.0 - A set is not aligned with a loop that may hold two cycles until someone counts them, and only that count takes one cycle out of it- **Output change: which sets `video-cycle-align` rewrites.** `video-loop`'s output is 2.25.0's and 2.26.0's: every cut keeps its period, length and start, whatever its legs or shading (the report gains `cycle.fundamental`, and `strip.json` gains `state`). `video-cycle-align` now **stops a set** — nothing rewritten, exit status 1 — where one of its loops may hold two or three cycles (a half or a third of it repeats and is no shorter than the gait floor), and 2.26.0 aligned it; the report is written with `applied: false`, `refused: "cycle-suspects"` and the typed `suspects`. A set with no suspect is aligned as before, every loop resampled from all of its filmed frames. `video-set --align-cycles auto` skips such a state with a warning (`applied: false`, `reason: "cycle-suspects"`, `suspects`) where it aligned it, and the RIFE skip now carries `reason: "rife-not-installed"`. The number of cycles in a loop changes only through the new `--cycles`.diff --git a/SKILL.md b/SKILL.mdindex ebd2ed7..fc9a8f7 100644--- a/SKILL.md+++ b/SKILL.md@@ -137,4 +137,4 @@ Scene creation consumes finished assets and remains optional. Asset metadata own## Contracts and advanced tools-[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)).+[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between auto` (the default: a made frame that melted takes the nearer source frame) or `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)).diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex 6280cae..edf6f3e 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -88,7 +88,10 @@ inside its solid edge — past a drawn outline — pushed out over the transparefine. A disagreement then reads as the body's fill. Where the frame has coverage its colour isits own, outline included, and it is taken from the colour run as it comes out (no division bythe coverage). A limb RIFE cannot follow at all still comes out pale and soft, never black;-`rife.smear` measures both (section 4).+and where two drawings are too far apart for the flow — legs crossing a long way, as a clip+drawn on twos gives between its drawings — the legs come out as one shape of fill with no+outline between them or around them. `rife.smear` measures all three, and a set alignment takes+the nearer source frame where a made frame melted (section 4).### Where — measured 2026-10-03@@ -258,7 +261,7 @@ same number of frames, starting on the same step.```bashsprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-walk/loop \--loop-dir set/back-walk/loop [--view front --view side@right --view back] [--start-foot right] \- [--between rife|nearest] [--length N] [--cycles back-walk=2] [--multi-cycle fail|warn] \+ [--between auto|rife|nearest] [--length N] [--cycles back-walk=2] [--multi-cycle fail|warn] \[--state walk] [--report set/walk.cycle-align.json]```@@ -301,18 +304,47 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-k·L/L*, cyclic. A time within 0.03 of a source frame takes that frame as filmed; only a timebetween two frames is made, by RIFE at that fraction (section 1). An offset of half a frame,which would remake every frame, is not offered (section 2).-- **Between two source frames** (`--between`): `rife` (default) makes the frame; `nearest` takes- the nearer source frame, so nothing is made and no RIFE is needed, and the motion keeps the- filmed frames at up to half a frame off their time (a loop stretched longer shows a frame+- **Between two source frames** (`--between`): `auto` (default) makes the frame with RIFE,+ measures it (below) and keeps it unless it has a fault, where the nearer source frame is taken+ instead and named; `rife` keeps every made frame and names the faulty ones; `nearest` takes the+ nearer source frame every time, so nothing is made and no RIFE is needed, and the motion keeps+ the filmed frames at up to half a frame off their time (a loop stretched longer shows a frametwice, which the GIF and WebP hold as one frame of twice the delay). `video-set` passes- `--align-between`.-- **Smear, per made frame**: `cycle_align.smear` lists, for every frame RIFE made, what it has- that neither source frame beside it has, as fractions of its solid pixels: `dark_excess`, dark- pixels (luma under 70/255) inside the body beyond the darker neighbour's count — a black smear- raises it, a dark part that only moved (a hat, a watch) does not — and `partial_excess`,- part-covered pixels beyond the more ragged neighbour's (a pale, soft limb). A frame whose- `dark_excess` is over 0.1 % is named in the report's `warnings` (and on stderr, and in- `video-set`'s `warnings`); look at it in `cycle/`, or align with `--between nearest`.+ `--align-between`. `auto` runs RIFE for every frame between two source frames, as `rife` does,+ and needs it installed the same way.+- **Smear and melt, per made frame**: `cycle_align.smear` lists every frame RIFE made, with its+ `method` — `rife` (kept) or `nearest` (the nearer source frame taken instead) — its `faults`,+ and what it has that neither source frame beside it has (`rife.smear`):+ - `dark_excess`: dark pixels (luma under 70/255) inside the body beyond the darker neighbour's+ count, as a fraction of its solid pixels — a black smear raises it, a dark part that only+ moved (a hat, a watch) does not. Over 0.1 % it is the fault `smear`.+ - `outline_loss`: of the frame's coverage edge (alpha from 0.1, so a pale ghost limb's edge+ counts), the share with no dark solid pixel within 2 px, beyond the less outlined+ neighbour's, as a fraction of its edge. Legs that crossed too far for the flow melt into one+ shape of fill and lose their outline where they meet the air; a limb left as a ghost has none.+ Over 5 % it is the fault `outline`. A step the flow follows keeps its outline; a figure drawn+ without outlines loses none against neighbours that have none, and is not judged by it.+ - `partial_excess`: part-covered pixels beyond the more ragged neighbour's, as a fraction of+ its solid pixels. Reported, not judged: a melted frame and a clean one read alike on it.++ Every fault is a line in the report's `warnings` (and on stderr, and in `video-set`'s+ `warnings`), whichever `--between`: under `auto` it says the nearer source frame was taken+ there; under `rife` that the frame is kept, to look at in `cycle/`. The report counts the+ frames kept from RIFE (`made_by_rife`) and those replaced (`replaced`); a loop row lists both+ (`made_at`, `nearest_at`).++ Why `outline_loss` and not the dark count's other side: a frame half way between two drawings+ has fewer dark pixels than the darker one wherever the two differ — a watch half hidden, an+ outline between overlapping legs — so a clean frame reads below zero too. On two outlined legs+ (`tests/video/test_rife.py`) RIFE's clean frames of a short step read `dark_excess` −1.3 %,+ lower than its melted frame of a long crossing (−1.1 %); `outline_loss` reads under 3 % for the+ short step at every fraction and 32 % for the melted frame. The 5 % line is where a frame stops+ reading as a little soft at a foot and starts reading as melted; it is a reference, not a+ measured optimum, and frames near it are worth a look either way.+- **What `auto` costs**: a frame replaced shows the nearer source frame, so the motion there+ steps as filmed, up to half a frame off its time, and the loop shows fewer distinct drawings a+ second than `rife` — but no melted one. A clip drawn on twos has a long step between drawings+ everywhere, so it is replaced most; the frames that land on a small step stay RIFE's.- **Foot strike**: each loop is then turned to start as a heel lands (`align.foot_strike`), readoff one signal smoothed 1-2-1 — never off the frame's top edge, which a long ear, a hat'spoint or an antenna owns and which flops on its own rhythm:@@ -363,7 +395,7 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-- **Rebuilt in place**: `cycle/`, `<name>.strip.png` / `.strip.json`, `.gif`, `.webp` arerewritten at the loop's own cell rules (`cell_height_cap`, body-height target, anchor), at theloop's frame rate, so the aligned cycle lasts L*/fps seconds. `strip.json` gains- `cycle_align` (`from`, `to`, `between`, `taken`, `made_by_rife`, `made_at`, `smear` or+ `cycle_align` (`from`, `to`, `between`, `taken`, `made_by_rife`, `made_at`, `smear` and/or`nearest_at`, `turned_by`, `turned_on`, `view`, `start_foot`, the seam ratio of the rebuiltcells, and the re-verified GIF/WebP).- **The cut as filmed is kept** in `cycle.source/` on the first alignment, and every laterdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 4c7d8ee..02d55ff 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -289,7 +289,9 @@ The set stage is the same step `video-set` runs after its loops are cut (`--aligdefault): one `--loop-dir` per direction of the same walk or run, one `--view` each in the sameorder, so that every loop starts as the same own foot lands wherever its view can tell the feetapart. A frame that falls between two source frames is made by RIFE, and the command fails where one-is needed and RIFE is not installed; `--between nearest` makes none.+is needed and RIFE is not installed; `--between nearest` makes none. A frame RIFE made that melted+(lost its outline where legs crossed too far) is replaced by the nearer source frame and named+(`--between auto`, the default; [loop repair](loop-repair.md) section 4).`--character` or `--motion` words that turn the subject another way than `--facing`, or put a`--handed` item on its other side, come back in `warnings`; the prompt is the same either way@@ -876,13 +878,14 @@ A front or back walk films from its base redrawn mid-step (`--walk-start redraw`image generation each, `--still-provider` picks the provider; see §2). After the loops are cut,every walk or run filmed in two or more directions is given one cyclelength: each loop is resampled to the set's median length (only the frames that fall between two-source frames are made, by RIFE; `--align-between nearest` takes the nearer source frame instead)+source frames are made, by RIFE, and one that melted takes the nearer source frame instead (`--align-between+auto`, the default; `rife` keeps every made frame, `nearest` makes none))and turned to start as the same own foot lands in every view — read off the legs, never off anear or a hat's point, and the foot told apart by the item's own view and facing (`--align-cyclesauto`, the default; `off` keeps each loop's own length). The same step stands alone as`sprite-gen video-cycle-align --loop-dir … --view …`. `set.report.json` carries `cycle_align`per state (with `start_foot` per item), a failed alignment is listed as `cycle-align:<state>`,-and a made frame with a smear or a loop whose foot could not be named is a line under+and a made frame with a smear, one that melted and was replaced, or a loop whose foot could not be named is a line under`warnings`. Two cases skip the alignment with a warning instead of failing it (`applied: false`,`reason`, and a line under the report's `warnings`): no RIFE (`rife-not-installed`), and a loopthat may hold more than one cycle (`cycle-suspects`, the loops under `suspects`; count them, then