Skip to content

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

Merge plan/edge-contact-halfbody-1021 (frames: a drawing cut by its own frame is read as its border; a refused run hands nothing over) for 2.46.0, validated in sprite-gen/edge-contact-halfbody-1021

Soohong Kim04678aafb6a7
diff --cc CHANGELOG.md
index fad6f0c,e5ad4e7..69cc864
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -4,61 -4,9 +4,64 @@@ 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.
+
+ - **Default change: A drawing cut by its own frame is no longer refused as framed too tight.** A bust or half-length drawing runs off the frame itself (its sleeve cut off at the left, its hair at the top), so in every frame of its clip the subject touches those edges and no canvas gives it room there. In 2.45.2 the default `video-frames` edge check refused every frame of such a clip with "the subject touches the frame edge ... framed too tight". Only a flag let it through: `--allow-subject-edge-contact`, which also lets through a subject that really leaves the frame, or `--allow-edge-contact`, which turns the check off. The default (`edge_policy` is now `border`, was `refuse`) reads the drawing's own border on the clip's first frame, keyed with its specks erased: a side (top, left, right) whose outermost row or column the subject covers for at least 2 % of its length (`frames.BORDER_MIN_FRACTION`) is a border side. Subject contact there is accepted in every frame, wherever along the side. Subject contact on any other side is still refused as framed too tight (a bust cut at the top and left whose hand leaves the right). The top / left / right numbers in a refusal are now the pixels the border does not take, so a caller that reads them to choose a taller or wider canvas reads the side that needs room. Leftover key is still refused, except the body's rim the matte cut loose: a key-only piece is accepted only on a border side the same frame's subject reaches, holding fewer than 8 pixels in all (`SPECK_MIN_PX`) and lying wholly within 10 px of the frame's body (`frames.RIM_REACH`, counted each way and diagonally; the body is the largest piece holding a pixel off the key). A thin outline blended with the key leaves such pieces at the edge between strands. Larger pieces, farther pieces, pieces on other sides or on a side the frame's subject left, and a detached stain beside a sleeve on the same side are refused as in 2.45.2. A clip whose first frame crosses no side is judged and worded exactly as in 2.45.2, byte for byte. The two flags judge as in 2.45.2. Taking a side as the border prints one stderr line. The report gains `edge_border` (`frame`, `sides`, `outer_px`, `min_fraction`, `rim_reach`, `rim_under_px`); each contact row gains `rim`, and under the default `border` (pixels taken) and `off` (pixels not taken, by side). Known limit: a hand that newly leaves the frame on a side that is already a border side is accepted; by position it cannot be told from the sleeve moving along the edge. [video pipeline](docs/video-pipeline.md), section 3.
+ - **Default change: A refused run hands nothing over.** A caller that does not read the exit code used a refused run's output as if it had passed. In 2.45.2 a refused `video-frames` run left its keyed frames in `keyed/` and wrote no report. `keyed/` was not emptied before keying, so a pass after a longer earlier run in the same folder also held the earlier run's extra frames. A refused `video-loop` run could leave a mixed set: for example after the pin gate refused, `cycle/` and the strip were the refused run's while the GIF and WebP were an earlier run's; a refusal before the cut left the earlier run's whole set. Now `video-frames` keys into a hidden working folder and hands over `keyed/` only when the run passes. A refused run (the edge check, or a frame keyed to 0 % transparency) leaves its frames as `keyed.refused/` and no `keyed/`, not even an earlier run's. A pass removes `keyed.refused/`. The report is written either way, with `status` (`passed` or `refused`); a refused report adds `error`, `refused_dir` and `keyed_dir: null`. Keyed frames that pass are the same bytes as before. Every `video-loop` refusal that writes `status: failed` (selection, motion anchor, jump repair, jolt, pin, seam, a strip with no body, a GIF or WebP that could not be written or verified) removes `cycle/`, `<name>.strip.png`, `<name>.strip.json`, `<name>.gif`, `<name>.webp`, `cycle.source/` and `follow.source.png` from the output folder. A cut it had already written is kept as `cycle.refused/`, which the next pass removes. A strip with no body and a GIF or WebP that could not be written now also write the failed report. Argument errors touch nothing. [video pipeline](docs/video-pipeline.md), sections 3 and 4.
+ - **Tests** - `tests/video/test_edge_border.py` (a bust cut at the top and left passes and the report names its border; a padded jump whose head leaves the top and a first frame with a 2 px wisp on the top are refused with the 2.45.2 message, byte for byte; a key-only patch with no border is worded as in 2.45.2; a hand leaving the right of a bust is framing, its message counting only the right; a hand leaving a border side elsewhere is accepted (the known limit); leftover key that is not the body's rim is refused (a patch on the right, a 48 px fringe beside the sleeve, a patch where the sleeve left, a detached 20 x 90 stain, 2 px pieces 11 and 14 px from the sleeve, pieces of 8 px and more, stripes hugging the head, stains beside the head, a fringe on a side that is not the border, a fringe above a head clear of the top band, a stain round a fleck of the body's colour); 1 px dots are judged piece by piece; 2 px pieces 2 to 10 px from the sleeve and a 7 px piece are the rim; an 8 px piece with 4 pixels in the band and a 7 px piece 11 px away are refused; the two flags judge as in 2.45.2; `classify_edge_contact` counts the rim; a refused `video-frames` run leaves `keyed.refused/`, no `keyed/` and a refused report; a pass after a refusal leaves `keyed/` alone; a pass over a longer run holds its own frames only; a frame keyed to 0 % transparency is refused the same way; an argument error touches nothing; a `video-loop` cut refused after it was written hands nothing over and keeps `cycle.refused/`, removed by the next pass; a cut refused before it was written hands nothing over; a loop argument error touches nothing), `tests/video/test_canvas_key_normalize.py` and `tests/video/test_fit_tight.py` (the 2.45.2 default's framing and mixed-contact tests now move the contact after the first frame and read the refused frames from `keyed.refused/`), `tests/video/test_edge_speck_lead_in.py` (the default policy is named `border`, and the refused frames are read from `keyed.refused/`), `tests/frames/test_chroma_key_relative.py` (the edge-contact split states the `rim` count `classify_edge_contact` now gives).
- **Fix: Green screens that lean toward cyan or yellow are now recognised as border keys.** A green screen that leans toward cyan or yellow was not recognised as the key on the border. Examples: the studio chroma-key green `#00B140`, (0, 177, 64); (0, 200, 90), which leans toward cyan; (90, 210, 0), which leans toward yellow. Each sits more than 96 from pure green. With `--key green` the whole background stayed opaque, and `video-canvas` refused `--key green` on such a still; but with `--key auto` the old rule did not take the green route at all: `cutout` and `video-frames` routed the frame to the white (position-based) matte, and `video-canvas` treated the still as a non-key base and did not normalize it. `video-frames --spill auto` did not always choose `full`: when the reference still had the same leaning green, `auto` read the surviving background as key material and chose `small`; when it chose `full` (a reference whose own background the old rule did recognise), the clip's surviving background was despilled to a blue-grey instead of being erased. The cause was that the border rule `extract.is_border_key_candidate` held every unkeyed channel under 64. That bar was set between magentas, whose one unkeyed channel (green) tells a painted magenta from hot pink. Green has two unkeyed channels, and a green screen leans on one of them. For the fix, the darkest unkeyed channel keeps the bar (under 64, and at most 35 % of the brightest keyed channel). The brightest one only has to stay under half of the brightest keyed channel (`extract._BORDER_KEY_MAX_LEAN_RATIO`, 0.5), that is a hue nearer green than yellow or cyan (between 90 and 150 degrees). The border detector, `extract.detect_background_key_rgb`, reads the lean second. It first counts, on their own, the candidates the 2.45.2 rule admitted. When those make up at least 12% of the samples, it returns the mean of their most populated bin, exactly the colour 2.45.2 returned. Below 12%, the samples only the lean admits join them, but their most populated bin gives the colour only where the declared key's own cut would leave that background on the border. Two conditions, both needed: the samples only the lean admits that lie farther from the declared key than the cut (the radius the caller keys with: the new `threshold` argument of `detect_background_key_rgb`, which the engine sets from `--key-threshold`, 96 by default), in that most populated bin or in a bin beside it on every channel, make up at least 2% of the samples; and the candidates outside that bin and the bins beside it make up less than 12% of the samples (the border holds one key-coloured background). Otherwise the declared key is kept, as in 2.45.2. A leaning border the declared key clears by itself gains nothing from the leaning colour; its ball would only reach further into a subject near that colour: (0, 210, 80) sits 91.8 from pure green, inside the cut of 96, so the declared key erases that background on its own, and a teal subject (0, 154, 149), 180 from the key, is kept; read as the painted colour, (0, 210, 80), 88.9 from the teal, let the ball reach the teal subject through the background and erase all of it, with no background gained. The 2% keeps the soft rim where a subject meets an edge of the frame (its blend with the background crossing the cut there) from being read as background the cut left; and a background whose tail past the cut is under 2% of the border keys as before the lean, the few pixels past the cut included. A second key-coloured colour on the border may be the subject's own (a leaf along an edge, another green); read as part of the background it would let the ball take a subject colour near the dominant one. `cutout`, the reference window `video-frames --spill auto` keys, and the YCbCr path's decontamination pass hand the detector the radius they key with, as the engine does. The painted key's erase ball, the spill judgment's subject window and the `video-frames` edge-contact split take the lean only from a painted colour that leans itself (`extract._painted_key_leans`). A colour found the first way never leans itself (magenta has no lean; for green the floor of the mean of one 8-wide bin of 2.45.2 candidates is always one of them), so they read it as 2.45.2 did. `cutout --key auto` and `video-canvas --key` classify the flat corner colour with the border rule, lean included (there the question is what the painted colour can be): a corner colour 2.45.2 took routes as before, and a leaning corner colour now routes to green. The magenta key is exactly as before (its one unkeyed channel is both the darkest and the brightest), so hot pink (250, 77, 150) and purple (213, 112, 246) are still refused. For green, nothing that was a candidate is dropped. Ivory, cyan, teal, sea green, a grey-green with both unkeyed channels lit and a green as near cyan as green are still refused. The interior rule `is_key_family` is unchanged. As a consequence, every image whose border the 2.45.2 rule recognised (its candidates at least 12% of the corner and border samples) keys byte for byte as in 2.45.2 under the same key, whatever leaning green is mixed into that border and in whatever share. Under the same key, every image is keyed either exactly as in 2.45.2 or exactly as with the leaning colour read. As in 2.45.2: wherever the 2.45.2 rule recognised the border (its candidates at least 12% of the corner and border samples), wherever the declared key's cut clears a leaning border by itself, and wherever the border holds a second key-coloured colour. With the leaning colour: where the key's cut leaves the border's one leaning background. Read together, a sample admitted only through the lean can share the 8-wide bin of a background 2.45.2 already found and move its mean, while leaning samples in a bin of their own that outnumber the background would take the mode. A leaning-green part of the subject on the corners and the border can be taken as the painted colour only where the 2.45.2 rule's candidates make up less than 12% of the samples, the key's cut leaves it and no other key-coloured colour holds 12% of the border, that is, only where the subject crowds the border. A leaning-green patch buried in the subject on such a background is kept. [chroma-alpha](docs/chroma-alpha.md), the 2026-10-21 paragraph.
- **Tests** - `tests/frames/test_chroma_key_relative.py` (the border table with the three leaning greens accepted and a grey-green and a cyan-midpoint green refused; the detector still refuses hot pink, purple, ivory, cyan, (30, 60, 30), teal, sea green and those two; over the whole RGB cube the lean adds nothing for magenta, drops nothing for either key, and adds for green only hues between 90 and 150 degrees; without the lean the candidate field is the old rule colour for colour over the whole RGB cube; the engine and `cutout --key green` key the leaning greens out with the subject byte-identical; `cutout --key auto` routes a leaning green to `extract:green`; a leaning-green patch ((0, 160, 75) or (10, 120, 50)) buried in the subject is kept byte for byte on (8, 162, 24) and keyed with the background on (0, 200, 90); the edge-contact split reads a leaning piece as residual when the frame was keyed from a leaning background and as the subject's when it was keyed from (8, 162, 24); on (0, 200, 64) with a leaning green, (0, 200, 71) in its bin or (0, 200, 90) in a bin of its own, over the top-left corner (20.5% of the samples) or everywhere but a 32 x 32 block of the background (77.3%), the detector returns (0, 200, 64) and the frame keys exactly as from that colour pinned, a teal subject (0, 154, 149) just outside the ball keeping every pixel; a leaning-green border on (0, 200, 90), past the cut, with no 2.45.2 candidate, or with a block of one under 12% of the samples, is found through the lean and keys out; and over every 8-wide bin of green, the floor of the mean of 2.45.2 candidates is one of them; on (0, 210, 80), inside the key's cut, with no 2.45.2 candidate on the border or with 11% of the samples an interior-family green, the detector keeps the declared key and the frame keys exactly as with the key pinned, a teal subject (0, 154, 149) losing no pixel; a leaning-green leaf of the subject along the bottom edge over a leaning background the key clears, a second leaning green in a corner, and a soft rim crossing the cut where the subject meets the side edges each keep the declared key; with 1.5% of the border a step past the cut the key is kept, and with 2.5% the leaning colour is read; (0, 200, 90) is read with a cut of 96 and not with a cut of 110; over a sweep of borders around the cut every answer is the 2.45.2 answer or the answer that reads the lean, and both occur, as do borders where the two differ and the key is kept), `tests/frames/test_key_detect_banded.py` (the whole-image reference now states this rule, and leaning-green borders (past, across and inside the cut, and two leaning greens on one border) join the images the banded detector is checked against), `tests/video/test_canvas_key_normalize.py` (`video-canvas` repaints a leaning-green still to the exact key and accepts `--key green` on it), and `tests/video/test_video_spill.py` (on a leaning green, `--spill auto` reads the reference as `full` with no key material, and the frame keys with no opaque background pixel and no edge contact, the subject byte-identical, with `--decontam off` and `palette`).