Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Merge plan/idle-seam-repair-1021 (video-loop: the seam bridge, RIFE frames round a jumping wrap of a loop that is not a walk) for 2.46.0, after the wrap blend, validated in sprite-gen/idle-seam-repair-1021
Soohong Kim2fe9dace80e1
diff --cc CHANGELOG.mdindex c8c52fe,29d5c9b..c3c666d--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -4,56 -4,11 +4,61 @@@ All notable public changes to `sprite-g## Unreleased+**Upgrading from 2.45.3: Existing outputs change bytes for some clips.**+This affects only cuts made with `--anchor none` using:+`video-loop --cycle pinned`+whose pin the gate passes and whose pinned last frame redraws the first.+This is how `video-set` cuts idle and attack clips filmed with their first frame as the last.+A redraw occurs when the first cell differs from the pinned frame by more than `--seam-max` (default 2.0) times the cut's median step at full size.+Only these cuts now give different `cycle/` cells (the last half second), strip, GIF and WebP.+Every other cut gives the same bytes as 2.45.3:+a pinned cut whose pinned frame draws the first as it is,+every non-pinned cut (walk, run, auto, periodic, fixed, one-shot, once, once-return, lifetime),+a body-anchored pinned cut,+and anything cut with `--wrap-blend off`.+A pinned clip whose pin the gate refuses fails as before with the same message.+A source projection reads a blended strip as `source-processing-unsupported`.+No restoration schema changes.++- **Changed (default):** A video model given the first frame as the last draws that frame again (softer or sharper, another tone, hair strands a pixel over).+ The pin gate reads the pose and passes.+ The drawing stays, so the loop's wrap shows one jump in sharpness where every other step shows the motion.+ Over the cut's last half second (K = min(round(0.5 s x fps), floor(L / 4)) cells, 12 at 24 fps), wrap blending adds back j/(K+1) of the redraw's difference (first cell minus pinned frame, premultiplied) on the j-th cell.+ Each pose stays the cell's own, and its drawing turns into the first cell's by the wrap.+ Only a redraw is ramped.+ A pixel is held where the two ends hold a part, a line or a dot in different places, and where a ramp cell does not stand where the pinned frame stands.+ This check applies after one softness match of at most 0.7 px.+ A pixel is held if it is more than 12 levels outside what the other end holds within 1 px on a 7x7 mean or a 7 px run, over black and over white.+ It is also held if its value is more than 12 outside the other end's 1 px range where the other end has under half this end's range there, in any direction, length or width.+ Held pixels are widened 3 px and the weight feathered 7x7.+ A pixel of weight 0 is the filmed byte.+ A ramp that steps more than the cut already does, or that does not shrink the wrap, is not used: the cut is written as filmed and a `warning:` line says so.+ A wrap still over `--seam-max` after blending also gets a `warning:` line.+ New flag (default `auto`, and `video-set` takes the default):+ `video-loop --wrap-blend auto|off`+ New report key `wrap_blend` on every pinned cut (`applied`, `why`, `K`, `cells`, `residual_ratio`, `wrap_ratio_before`, `wrap_ratio_after`, `ramp_step_max_ratio`, `bound_ratio`, `pose_share`, `presence_share`, `never_settled`, `equalize`, `after_check`, `seconds`).+ `wrap_blend: {cells, K}` appears in the strip metadata where it applied, and in the CLI summary.+ [loop repair](docs/loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again)+- **Tests**: `tests/video/test_wrap_blend.py` on synthetic clips:+ a redraw of tone and 0.5 px softness has its wrap brought from 7.31x to 0.57x the median step and only the ramp's cells, strip, GIF and WebP differ from off;+ an arm still coming down in the ramp stays the filmed arm;+ a part moved 2 to 64 px, or present at one end only, is never drawn twice (the 14 px part on a flat figure is cut as filmed with a warning);+ 1 px lines moved 2 to 32 px on a flat figure are byte for byte;+ stripes swinging inside the ramp keep their swing;+ a strand against the silhouette is held over white where black alone lets it through;+ the softness match blurs the sharper end, never past 0.7 px;+ the idle-still fixture gives every output byte for byte;+ fixed cuts, body-anchored pinned cuts and refused pins are not touched;+ a ramp that steps past the cut is refused with a warning;+ a 1 px line at slope 1/3 moved 8 px is held line for line, thin structures change by at most 2 levels and busier quiet grounds by at most 3, strands off the silhouette by none.++- **Fix: every command prints on a Windows console or pipe in a legacy code page.** A line a command prints can hold an em dash, Korean or a path in any script; on cp949 (Korean Windows) or cp1252 Python could not encode it, and the command died at the print after its work was done (`background-tile` on Korean Windows). Each command's entry now reopens stdout and stderr as UTF-8 where they are not already (`sprite_gen.util.console.utf8_streams`, called first by every `main()` and by `sprite-gen`); importing sprite_gen leaves a program's streams alone. Test: `tests/util/test_console.py`.++ **Upgrading from 2.45.3: Walk and run loops give the same bytes as 2.45.3.** A loop that is not a walk whose wrap jumps may now come out with frames made round its wrap (different cells, strip, GIF, and WebP), or pass where 2.45.3 refused it, and every such loop's report reads `jump_repair.reading: "seam"` instead of `"why": "not a gait state (...)"`. A loop that needs a frame and finds no RIFE reports so in a `warning:` line. No flags are added and no restoration schemas change (`source-restoration-v5`, repair report `schema_version` 4, comparison `schema_version` 6). `--repair off` keeps the old behaviour.++ - **Changed: `video-loop` bridges a jumping wrap on idle and action loops (`repair.seam_bridge`).** Under `--repair auto` (the default) or `--repair on`, a loop whose state is not a gait (idle, jump, attack, or a generic in-place action) has its wrap read against the steps beside it; where it jumps, one, two, or four frames round the wrap are made again by RIFE between the frames either side; the loop is not read for its flow (an idle's own motion would leave it). See [loop repair](docs/loop-repair.md#the-seam-bridge-a-loop-that-is-not-a-walk-whose-wrap-jumps).+ - **Tests**: `tests/video/test_seam_bridge.py` covers the synthetic idle with wrap jump J = 2.6 closed by one frame and passing the gate, J = 5 tried at one and two frames then closed by four, J = 12 refused without frames made, J = 1 closed loop untouched without an interpolator, whole-pixel stepped motion not bridged, near-still loop under the noise floor not bridged, loop drawn on twos skipped, real RIFE (rife-v4.6 with augmentation) closing J = 2.6 without faults, frames made with a fault (a stand-in painting a dark patch: smear at every width, seven calls, nothing taken, gate refuses as before), missing RIFE where the wrap is cut as filmed with the install line in `jump_repair` and a `warning:` line, a wrap that reads as a step saying nothing, `--repair on` refusing with the install line, a pinned clip whose pin the gate refuses skipped without reading and refused on its pin, the CLI summary naming the frames made, and the report naming the RIFE that made them.+## v2.45.3 - The seam check reads the frames that play when the body anchor spreads a sideways slide; such a cut passes again, as it did in 2.44.0**Upgrading from 2.45.2: Every cut 2.45.2 passed, and every `--anchor motion-auto` run, gives the same bytes as 2.45.2.** Only `--anchor body` cuts that 2.45.2 refused because of the walk sliding sideways before the anchor can now pass, read on the frames that play. Refused cuts print the same error line as before, the report's `producer` field names the new version, and there are no restoration schema changes.diff --cc docs/loop-repair.mdindex 37978f9,8bbb468..526d329--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@@ -1,6 -1,6 +1,6 @@@# Loop repair — RIFE in-betweens for jump frames, the jolt index, one cycle per set- > Owns: Where RIFE runs and what it costs, which model and augmentation it runs with, how it is installed and what runs without it, jump-frame repair in `video-loop`, the flow reading (frames off a walk's way), the eased retime (a part that rushes on its way), the jolt index and its gate, cycle alignment across a direction set, the redrawn wrap of a pinned clip (`--wrap-blend`) · Index: [docs/README.md](README.md)-> Owns: Where RIFE runs and what it costs, which model and augmentation it runs with, how it is installed and what runs without it, jump-frame repair in `video-loop`, the flow reading (frames off a walk's way), the eased retime (a part that rushes on its way), the seam bridge (the wrap of a loop that is not a walk), the jolt index and its gate, cycle alignment across a direction set · Index: [docs/README.md](README.md)++> Owns: Where RIFE runs and what it costs, which model and augmentation it runs with, how it is installed and what runs without it, jump-frame repair in `video-loop`, the flow reading (frames off a walk's way), the eased retime (a part that rushes on its way), the seam bridge (the wrap of a loop that is not a walk), the jolt index and its gate, cycle alignment across a direction set, the redrawn wrap of a pinned clip (`--wrap-blend`) · Index: [docs/README.md](README.md)A walk loop cut from a generated clip can look right in every still and still hitch when itplays: the video model redraws thin hair a little differently every frame, and now and thendiff --cc sprite_gen/video/loop.pyindex 0412e77,4ed369d..ebb710f--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@@ -2024,9 -2081,8 +2114,9 @@@ def add_arguments(parser: argparse.Arguparser.add_argument("--body-height", type=int, help="scale so the STANDING height (the subject in the clip's first frame, i.e. the base still's pose) is this many px — the same value across states gives the same character size; --strip-height stays the cap")parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="motion-auto: automatic stable regions, local repeat selection and XY ramp (walk/run); motion: fixed cut with explicit regions; body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")parser.add_argument("--anchor-region", type=motion_anchor.parse_region, action="append", help="motion anchor only: repeat twice with head then torso x0,y0,x1,y1 in the first selected frame; requires --cycle fixed and at least 6 frames")- parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): take out the frames off the walk's flow (one or two drawings that lie 3x their region's usual step off the line between the frames either side) and make them again with RIFE between those frames, each at its own time, so the loop keeps its length; adopt only without smear/outline faults, at most 3 calls and never made from or beside a frame made (docs/loop-repair.md section 2). A rejected group keeps its frames. Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")+ parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): take out the frames off the walk's flow (one or two drawings that lie 3x their region's usual step off the line between the frames either side) and make them again with RIFE between those frames, each at its own time, so the loop keeps its length; adopt only without smear/outline faults, at most 3 calls and never made from or beside a frame made (docs/loop-repair.md section 2). A rejected group keeps its frames. A loop that is not a walk or run is not read for its flow: where its wrap steps over --seam-max times the mean of the three steps either side, one, two or four frames round it are made again by RIFE between the frames either side, the fewest first, taken only without faults and where every step from one to the other then reads within that limit (docs/loop-repair.md section 2, \"The seam bridge\"). Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")parser.add_argument("--overlap-wrap", choices=OVERLAP_WRAP_MODES, default="on", help="--anchor motion-auto, under --repair auto or on: on (default): a cut two steps long whose wrap a part on its own beat leaves open (the seam gate refuses it) has four to twelve frames beside its wrap made again between the clip's frames a cycle apart and its own, each read with RIFE's single passes for a part torn — 34 calls of the binary a frame, up to forty frames (docs/loop-repair.md section 2, \"The overlapped wrap\"); off: not tried, recorded `wrap_overlap.skipped` with a warning line, and the gate refuses the cut as filmed — for a host whose RIFE runs on a CPU, where one frame of a 960 px clip takes minutes")+ parser.add_argument("--wrap-blend", choices=wrap_blend_mod.MODES, default="auto", help="--cycle pinned with --anchor none: auto (default): where the pinned last frame draws the first again (the first frame and it differ by more than --seam-max times the cut's median step, at full size), the last half second of the cut takes the first frame's drawing back in a ramp, only where the two ends differ by a redraw and the cell stands where the pin stands; a ramp that steps more than the cut already does, or does not shrink the wrap, is not used and a warning line says so (report `wrap_blend`, docs/loop-repair.md section 6); off: the cut as filmed")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")