Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(decontam): the video fit's blend and still steps, the settle's bounded catch-up; scene, cost and counter numbers redone; no release number
Soohong Kim552e1d4b6c4b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4f1804e..1a24e34 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased-**Upgrading from 2.45.3: Release 2.46.0 changes defaults for video frames.**+**Upgrading from 2.45.3: This release changes defaults for video frames.**Outputs that change bytes are frames from `video-frames` and `video-set` on a green or magenta key.These changes occur within 6 px inside the keyed silhouette only.@@ -18,7 +18,7 @@ To get the 2.45.3 frames back, pass:`--decontam off`- **Default change: `video-frames` and `video-set` now default to `--decontam auto` (before: `off`).**- Release 2.46.0 updates these defaults to clean chroma-bleed edges automatically.+ This release updates these defaults to clean chroma-bleed edges automatically.On a chroma key, H.264 4:2:0 chroma mixes key colour into strands one to three pixels wide.With decontamination off, a red hair strand on green keeps an olive rim.@@ -35,22 +35,23 @@ To get the 2.45.3 frames back, pass:Earlier fixes resolved the Grok-magenta regression through the key-hue cap and corrected the frame-edge interaction.No blocking defect remains known.- On synthetic diagnosis clips (CRF 18, `--spill small`, 6 frames, one machine), `auto` reduced key contamination on red strands on painted green from 24.2 % to 9.2 %, and on pure green from 27.4 % to 9.3 %.- Halo composite error on dark and white backgrounds shifted from 11.6/12.1 to 9.5/10.1 on painted green, and from 12.0/11.9 to 9.8/9.7 on pure green.+ On synthetic diagnosis clips (CRF 18, `--spill small`, 6 frames, one machine), `auto` reduced key contamination on red strands on painted green from 24.2 % to 10.2 %, and on pure green from 27.4 % to 10.9 %.+ Halo composite error on dark and white backgrounds shifted from 11.6/12.1 to 9.6/10.1 on painted green, and from 12.0/11.9 to 10.0/9.9 on pure green.Strand recall stayed at 91.4 % on painted green and 92.4 % on pure green.Strand recall no longer rises with the pass, because that gain came from the flank that the video fit no longer recovers.Halo gains are smaller than before for the same reason.+ On these moving scenes, key contamination is about one point higher than with the hold and settle alone, because a change of call now takes a few frames to reach the fit's colour.- Key contamination dropped from 3.4 % to 0.5 % on magenta, and from 5.4 % to 2.0 % on Grok darker magenta.- Halo shifted from 15.0/19.6 to 12.5/16.3 on magenta, and from 20.7/31.5 to 19.4/30.0 on Grok darker magenta (compared to 17.1/24.7 when flank recovery was present).- Strand recall stayed at 87.0 % on magenta and 73.3 % on Grok darker magenta.- Outline ink CIELAB error shifted from 19.3 to 20.8 on magenta, and from 21.7 to 24.1 on Grok darker magenta.+ Key contamination dropped from 3.4 % to 0.5 % on magenta, and from 5.4 % to 1.8 % on Grok darker magenta.+ Halo shifted from 15.0/19.6 to 12.7/16.4 on magenta, and from 20.7/31.5 to 19.3/30.0 on Grok darker magenta (compared to 17.1/24.7 when flank recovery was present).+ Strand recall shifted from 87.0 % to 86.9 % on magenta and from 73.3 % to 73.2 % on Grok darker magenta.+ Outline ink CIELAB error shifted from 19.3 to 20.2 on magenta, and from 21.7 to 22.6 on Grok darker magenta.Red hair counts as key-coloured material there, so the palette is not key-free and the warning line appears.- Contamination dropped from 20.6 % to 7.8 % on a translucent glow scene (halo 12.6/9.4 to 11.5/8.4, strand recall 85.7 %).- It dropped from 23.8 % to 10.4 % on a small green charm scene (halo 11.8/12.9 to 9.9/11.1, strand recall 90.7 %).+ Contamination dropped from 20.6 % to 8.8 % on a translucent glow scene (halo 12.6/9.4 to 11.7/8.5, strand recall 85.7 % to 85.4 %).+ It dropped from 23.8 % to 11.4 % on a small green charm scene (halo 11.8/12.9 to 10.0/11.1, strand recall 90.7 %).- Changed pixels make up about 2 % of each frame (4.5 % in translucent scenes).+ Changed pixels make up about 2.4 % of each frame (4.7 % in translucent scenes).All changed pixels lie within 6 px inside the silhouette.Nothing outside the silhouette changes any more.Interior pixels remain byte-identical.@@ -59,7 +60,7 @@ To get the 2.45.3 frames back, pass:The row extractor frames are a derived cache that `heal` re-derives, so changing their default would silently rewrite existing runs.Stills remain as they were.-- **Temporal fit: The video fit holds edge decisions across frames, settles still pixels, and drops flank recovery.**+- **Temporal fit: The video fit holds edge decisions across frames, blends a change of call over frames, settles still pixels, and drops flank recovery.**With default `auto`, the edge of a subject standing still sparkled from frame to frame where `--decontam off` remained calm.Codec noise pushed edge pixels across the pass's threshold tests from frame to frame.These tests decide blends, tints, material behind, explained pixels, palette colours, and flank coverage.@@ -73,10 +74,25 @@ To get the 2.45.3 frames back, pass:A palette colour picked in the previous frame stays unless another colour's line passes closer by 16.Moving pixels change their evidence far beyond 16 and are decided afresh.Only near-threshold calls stick.-- Still pixels settle toward the current fit.- When a pixel was written in both frames in the same palette colour, and its source moved by at most 8 in any channel across its 3x3 box (`VIDEO_STILL`), it settles.- It moves a tenth of the way (`VIDEO_SETTLE` 0.1) from its previous value toward this frame's fit, capped at 12 per channel (`VIDEO_SETTLE_REACH`).+ With the hold alone, a call that did change could still move a still edge through the whole gap between the matte and the fit in one frame.++ The blend mixes two renderings made from this frame's evidence at every pixel the pass examines.+ One is the matte with its key hue capped, and the other is the fit's palette colour at the pixel's light, with the fit's coverage where the call refits coverage and the matte's coverage elsewhere.+ For a palette-colour change, the fit's rendering mixes the two colours' renderings.+ A new palette colour waits until the change in hand is done, while a return to the old colour turns that change around.+ The mix moves toward this frame's call by at most 0.2 a frame (`VIDEO_BLEND`).+ It moves less if needed to limit the output change to 4 (`VIDEO_STEP`) plus 0.25 (`VIDEO_STEP_MOTION`) per unit the source moved, measured in premultiplied colour or coverage across its 3x3 box.+ A pixel new to the band starts at its call if it was transparent in the previous frame, and otherwise starts from the matte.+ Both renderings follow a moving subject at once; the change of call is spread over frames.++ A still pixel whose mix moved, has not reached its call, or came into or left the band moves at most 4 a frame from its previous output, measured in premultiplied colour and coverage.+ Here, still means its source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`).+ A pixel the hard cut keyed in this frame stays transparent.++ Still pixels settle toward the current fit when their mix is at its call in both frames.+ When a pixel was written in both frames in the same palette colour, and its source is still, it settles.+ It moves a tenth of the way (`VIDEO_SETTLE` 0.1) toward this frame's fit and stays within 12 per channel (`VIDEO_SETTLE_REACH`) of it.+ When it must catch up to get within 12, it now moves at most 4 a frame in premultiplied colour and coverage instead of moving all at once.This dampens codec noise while following real slow changes within 12 levels.The video fit also drops flank recovery.@@ -91,20 +107,24 @@ To get the 2.45.3 frames back, pass:On a synthetic still scene under decoder noise (red strands 1 to 3 px wide on painted green, 8 frames, sigma 2):Mean edge change between frames on a dark background was 2.34 with `off` (99th percentile 8.3).- Before this fix, the pass gave a mean change of 2.75 (99th percentile 16.0).- With this fix, the mean change dropped to 2.27 (99th percentile 8.3).- Key contamination on that scene dropped from 6.5 % with `off` to 2.3 % now.+ With the hold and settle alone, the mean was 2.27 (99th percentile 8.3).+ With the blend and still steps, the mean is 2.25 (99th percentile 8.0).+ Key contamination on that scene was 6.5 % with `off`, 2.3 % with the hold and settle alone, and 2.4 % now.++ On a second synthetic scene, decoder noise changed between two frames and the source then stayed still for 19 frames.+ With the hold and settle alone, changed calls appeared in one frame and their pixels stopped moving when the source stopped.+ Now those edge pixels keep moving toward their new calls, by no more than 4.31 premultiplied a frame including uint8 rounding, and arrive by frame 14.- Per-frame stats and clip totals add `held_px` and `settled_px`.+ Per-frame stats and clip totals include `held_px`, `blending_px`, and `settled_px`.`held_px` counts pixels where a held outcome or colour differed from an independent fit.- `settled_px` counts pixels settled toward the current fit.+ `blending_px` counts pixels showing a mix of two calls rather than this frame's call.+ `settled_px` counts pixels the settle or a still step moved from the previous frame's output.In video, `recovered_px` is now 0.- Keying cost was remeasured on an Intel i5-7500 with a 1080x1920 synthetic clip, one process per run, in the same session.- Keying took 1.21 s a frame with `off` and 3.42 s with `auto` (the pass before this fix took 3.65 s).- Peak memory rose from 396 MB to 908 MB, adding about 247 MB per megapixel.- Because `video-set` keys three items at once by default, peak memory can rise by about 1.5 GB at that size.- These numbers replace the earlier 2.46.0 numbers.+ Keying cost was remeasured on an Intel i5-7500 with a 1080x1920 synthetic clip at CRF 18 and `--spill small`, six frames, one process per run, in the same session.+ Keying took 1.14 s a frame with `off`, 3.25 s with the hold and settle alone, and 3.36 s now.+ Peak memory was about 400 MB with `off`, 945 MB with the hold and settle alone, and 1155 MB now, adding about 365 MB over `off` per megapixel.+ Because `video-set` keys three items at once by default, it can use about 2.3 GB more than `off` at that size.- **Guards: Two new guards protect key-coloured details and material behind edges in the video fit.**The still fit output is unchanged byte for byte, but explicit `--decontam palette` runs in video also use these guards.@@ -119,8 +139,8 @@ To get the 2.45.3 frames back, pass:This applies to pixels near parts that are opaque, deeper than 6 px, and have key hue above 8.The key-hue cap leaves those pixels alone.- On synthetic tests, the share of the charm's key-coloured edge pixels that lost half their key hue or coverage was 0.77 with `off`, 0.82 now (the diagnosis measured 1.00 without the guard).- Its colour error was 41.7 with `off`, 46.2 now (64.9 without the guard in the diagnosis).+ On synthetic tests, the share of the charm's key-coloured edge pixels that lost half their key hue or coverage was 0.77 with `off` and 0.82 now.+ Its colour error was 41.7 with `off` and 45.6 now (64.9 without the guard in the diagnosis).The material-behind guard preserves edges where subject material continues to the silhouette boundary.A band pixel keeps the matte's bytes when its colour, observed directly or at its own luma, falls within the opaque margin of the mean colour of subject pixels right behind it.@@ -141,7 +161,7 @@ To get the 2.45.3 frames back, pass:`video-set` prefixes this warning line with the item name and records it under `warnings` in the set report.The JSON report adds `decontam.reason` for the first skip reason and `decontam.skipped_frames` when frames are skipped.- Per-frame stats and clip totals in the video fit add `key_part_kept_px`, `behind_kept_px`, `held_px`, and `settled_px`.+ Per-frame stats and clip totals in the video fit add `key_part_kept_px`, `behind_kept_px`, `held_px`, `blending_px`, and `settled_px`.Where `auto` cannot run, frames remain exactly as the matte keyed them.The report records "the white matte has no key colour to remove" for a white key.It records "no interior to learn the subject's colours from" when no pixel lies deeper than 6 px inside the silhouette.@@ -151,17 +171,21 @@ To get the 2.45.3 frames back, pass:Known limits apply to this release.The hold works on pixels that stay put.- A strand that moves is decided afresh in every frame.+ A change of call on a still edge arrives at most 4 a frame.+ The largest change, between the matte's full coverage and a faint fit, can take up to about 64 frames, or about 2.7 s at 24 fps.+ Until it arrives, the edge shows a mix of the matte's colour and the fit's.+ A strand that moves is decided afresh in every frame, while its change of call is spread over a few frames and both renderings follow it.A moving edge still changes from frame to frame as its colour does, so a red rim moving over a dark background changes more than the olive rim `off` leaves.+ Pixels whose call changes show a mix of the two calls for a few frames.- The settle follows a slow change within 12 levels per channel.+ The settle follows a slow change within 12 levels per channel and catches up past that at most 4 a frame.The video fit gives back no coverage the hard cut keyed.Outer pixels of a soft edge that the cut erased stay erased.Only on stills, outside a dark outline the flank can give a few faint pixels in the subject's colour.A thin feature whose colour is absent from the interior can be read as a palette colour plus key.- For example, a thin yellow line beside red hair with a pink highlight turned pink (colour error 26.2 with `off`, 48.0 now).+ For example, a thin yellow line beside red hair with a pink highlight turned pink (colour error 26.2 with `off`, 47.5 now).`--decontam off` keeps that line.A thin key-coloured detail farther than 6 px from any key-coloured interior is repainted in a palette colour.@@ -181,6 +205,11 @@ To get the 2.45.3 frames back, pass:The edge is still cleaned, with key contamination at most half of `off`'s.Clip totals count held and settled pixels, and the first frame has none.A frame given twice comes out with the same bytes both times.+ Another test decodes one frame of the red-strand scene, then holds a second noise draw (sigma 3) still for nineteen frames.+ After the source stops changing, the default keeps moving toward the calls the noise changed.+ No pixel moves more than `VIDEO_STEP` in one frame in premultiplied colour or coverage, plus one for uint8 rounding.+ It arrives by the last frame.+ Clip totals count `blending_px`, and the first frame has none.The video fit leaves every pixel the hard cut keyed transparent and recovers nothing.The still fit still recovers its flank.diff --git a/docs/chroma-alpha.md b/docs/chroma-alpha.mdindex d32f0a9..8d54cea 100644--- a/docs/chroma-alpha.md+++ b/docs/chroma-alpha.md@@ -102,7 +102,8 @@ B is the key background measured locally (mean of keyed pixels within 12 px). P| still fit: a keyed pixel within 3 px of the subject that fits a blend above the background's noise floor and chains to the subject | coverage recovered: the faint sides of a strand the hard cut erased || video fit: a keyed pixel within 3 px of the subject | stays transparent: the video fit recovers no flank coverage || video fit in a clip: each test at that pixel, unless this frame's evidence passes the test's bar the other way by 16 (an RGB distance, `VIDEO_HOLD`); and the palette colour picked in the previous frame, unless another palette colour's line passes closer by 16 | hold: keeps the outcome and palette colour it had in the previous frame |-| video fit in a clip: a pixel written in this frame and in the previous one in the same palette colour, whose source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`) | settle: moves a tenth of the way (`VIDEO_SETTLE` 0.1) from its previous value toward this frame's fit, and never farther than 12 per channel (`VIDEO_SETTLE_REACH`) from that fit |+| video fit in a clip: every pixel the pass examines, as its call or palette colour changes; a still pixel whose source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`) | blend: mixes this frame's matte and fit renderings, moving toward this frame's call by at most 0.2 a frame (`VIDEO_BLEND`) and by less when needed to limit the premultiplied output change to 4 (`VIDEO_STEP`) plus 0.25 (`VIDEO_STEP_MOTION`) per unit of source movement; a still pixel whose mix moved, is still changing, or entered or left the band moves at most 4 a frame from its previous output, and a pixel keyed in this frame stays transparent |+| video fit in a clip: a pixel written in this frame and the previous one in the same palette colour, whose mix is at its call in both frames and whose source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`) | settle: moves a tenth of the way (`VIDEO_SETTLE` 0.1) from its previous value toward this frame's fit, stays within 12 per channel (`VIDEO_SETTLE_REACH`) of that fit, and moves at most 4 a frame when it has to catch up to get within 12 || `video-frames`: within its edge band (4 px of the top, left and right edges), a pixel the matte left transparent | stays transparent: the pass adds no edge contact to a clip (below) |Interior pixels are never touched, `off` returns the engine's output byte for byte, and everything is integer-exact or a fixed sequence of float64 operations (no random seed, no iteration-order dependence). The palette is a histogram k-means with a greedy weighted farthest-point seed and a fixed iteration count. There is no new dependency.@@ -111,7 +112,7 @@ Licensing: the pass is plain numpy inside this Apache-2.0 repository and install**The frame edge.** A decoded frame's blur runs the subject on into the key as a smooth tail, and the pass reads that tail as a faint blend at every distance, on the keyed ring just past the flank as well as on the flank, so no floor tells a strand's side from it. The video fit now gives keyed pixels no coverage at all, so its frame-edge band holds by construction there. Along the frame's top, left and right edges it decides a clip: `video-frames` refuses one where any visible pixel in its edge band has key colour in the source, as the key surviving the matte, so a head a few pixels under the frame edge would pass with the pass off and fail with it on. `video-frames` therefore hands the pass its edge band (`decontam_edge_band`, the gate's `EDGE_ROWS`), and there a pixel the matte left transparent stays transparent. The still fit's flank keeps what it recovers.-Two fits. `still` chooses P per pixel. `video` chooses P on a 3x3 mean of the observation, whose chroma is blurred anyway, and averages the projection alpha with a luma-only alpha where P and B differ in luma. `video-frames` uses the video fit and learns one palette per clip on the first frame, so the colours an edge may take cannot change from frame to frame. In a clip, `video-frames` keeps a history across frames, so a frame's bytes depend on the frames before it in the order they were given. This stops the edge of a still subject sparkling from frame to frame when codec noise shifts pixels across the pass's tests and palette choices. With hold, each test keeps the outcome it had at that pixel in the previous frame until this frame's evidence passes the test's bar the other way by 16 (an RGB distance, `VIDEO_HOLD`), and the palette colour picked in the previous frame stays unless another palette colour's line passes closer by 16. With settle, a pixel written in this frame and in the previous one in the same palette colour, whose source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`), moves a tenth of the way (`VIDEO_SETTLE` 0.1) from its previous value toward this frame's fit, and never farther than 12 per channel (`VIDEO_SETTLE_REACH`) from that fit.+Two fits. `still` chooses P per pixel. `video` chooses P on a 3x3 mean of the observation, whose chroma is blurred anyway, and averages the projection alpha with a luma-only alpha where P and B differ in luma. `video-frames` uses the video fit and learns one palette per clip on the first frame, so the colours an edge may take cannot change from frame to frame. In a clip, `video-frames` keeps a history across frames, so a frame's bytes depend on the frames before it in the order they were given. This stops the edge of a still subject sparkling from frame to frame when codec noise shifts pixels across the pass's tests and palette choices. With hold, each test keeps the outcome it had at that pixel in the previous frame until this frame's evidence passes the test's bar the other way by 16 (an RGB distance, `VIDEO_HOLD`), and the palette colour picked in the previous frame stays unless another palette colour's line passes closer by 16. With blend, every examined pixel mixes this frame's matte rendering, with its key hue capped, and this frame's fit rendering, moving toward this frame's call by at most 0.2 a frame (`VIDEO_BLEND`) and by less when the premultiplied output change would exceed 4 (`VIDEO_STEP`) plus 0.25 (`VIDEO_STEP_MOTION`) per unit its source moved in its 3x3 box. A still pixel whose mix moved, is still on its way to its call, or came into or left the band moves at most 4 a frame from its previous output; a pixel keyed in this frame stays transparent. With settle, a pixel written in both frames in the same palette colour, whose mix is at its call in both frames and whose source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`), moves a tenth of the way (`VIDEO_SETTLE` 0.1) from its previous value toward this frame's fit and stays within 12 per channel (`VIDEO_SETTLE_REACH`) of that fit, catching up at most 4 a frame where needed.**Gold and yellow.** Gold sits between red and green, so a gold a little darker or yellower than the palette's own also fits as a warmer palette gold with some green mixed in. Up to v2.10.1 the still fit took that reading, and gold edges and small gold drops came out orange and partly see-through. Since v2.10.2 the still fit weighs the blend against the subject's own colour at the pixel's own light (the freedom the written colour already has), and a blend has to win by more than the subject's own spread: the 99th percentile of how far its confident interior sits from the palette, large for a textured gold and small for flat colour. A still's antialiased edge is at most two pixels deep, so deeper in the band a key share has to show as the key's hue: a pixel without it is the subject's own colour, and so is an edge pixel without it that has the colour of the material right behind it. Where the matte changed such a pixel, the source colour and coverage come back. The RGB matte (`cutout`'s default) needs that: it scores key tint on the channel average, which calls yellow green, so it unmixes gold as if it were a blend; the YCbCr matte (`gen`) does not. The video fit keeps its decisions, because a decoded frame's chroma is blurred and an edge pixel's colour is no evidence of what the subject is made of there.@@ -139,25 +140,28 @@ Measured on a procedural ground-truth set (red strands 0.5–3 px wide, outlineThe two still-fit rows are v2.10.2's; v2.10.0 measured 0.07 % · 1.14 / 1.14 and 0.16 % · 1.15 / 1.14 on the same set, with the same recall. The video-fit row was measured in September 2026 with the video fit as it was then, which recovered the keyed flank, and has not been re-measured since flank recovery was dropped because that benchmark's inputs and tools are not at hand. The still-fit rows of that table are unchanged, and the scene table under Defaults has the current video fit's numbers.-**Defaults.** In release 2.46.0, `sprite-gen video-frames` and `video-set` default to `--decontam auto` (before: `off`). Stills (`cutout`, `gen`) stay `off`: they defaulted to `auto` during development until a regression on Grok's darker magenta greyed warm palette colours; that cap and the frame-edge interaction were fixed, but the still measurements use a green key, so stills remain `off`. The row extractor (`extract`, `inspect`) stays `off` because its frames are a derived cache that `heal` re-derives from raw, so a changed default would silently rewrite every existing run, and pixel-art rows binarize alpha downstream anyway. Video defaulted to `off` until now out of caution rather than a known defect, because the pass was benchmarked on a green key only and the video fit is less decisive than the still fit (10.8 % residual key contamination against 0.03 % on the original benchmark); the Grok-magenta regression and the frame-edge interaction were fixed earlier, and no blocking defect is known. Video defaults to `auto` now because on a chroma key, H.264 4:2:0 chroma mixes the key into every strand one to three pixels wide, leaving an olive rim on red hair over green with the pass off, and the pass gives such edges the subject's own colour back. The video fit drops flank recovery, examining only subject pixels within 6 px of the keyed background, and holds calls and settles pixels across frames so still edges do not sparkle: on a still scene under decoder noise (red strands on painted green), the mean change of each keyed edge pixel from one frame to the next on a dark background was 2.34 with `off` (99th percentile 8.3), 2.75 with the pass before this fix (16.0), and 2.27 now (8.3), while key contamination fell from 6.5 % to 2.3 %. Where `auto` cannot run, it leaves frames exactly as the matte keyed them and records the reason in the report (`decontam.reason`, and per frame in `rows[].decontam`): a white key ("the white matte has no key colour to remove") or a subject with no pixel deeper than 6 px inside the keyed silhouette ("no interior to learn the subject's colours from"). With `--alpha-mode brightness` (emitted light on black, no chroma key), `auto` simply means off and records `decontam: {"mode": "auto", "applied_frames": 0, "reason": "brightness alpha has no key colour to remove"}`, while an explicit `--decontam palette` is refused. To keep the matte as it is, `--decontam off` returns the 2.45.3 bytes exactly. On stderr after its JSON summary, `video-frames` prints a one-line warning starting `video-frames: warning: decontam auto ...` when `auto` did not run on any frame (naming the reason and stating that frames match `--decontam off`), when `auto` skipped some frames, when the subject owns key-coloured material so the palette is not key-free (edges may be repainted in the key colour too), or when the key-coloured part guard kept edge pixels beside a small key-coloured part (stating how many, and that a thin detail of that colour farther out may be repainted); codec noise deep inside the subject guards no edge and raises no warning, brightness alpha prints no warning, and the line ends by naming `--decontam off` as the way to keep the matte as it is. `video-set` lists the same line prefixed by the item name under `warnings` in its set report. On an Intel i5-7500 (1080x1920 synthetic clip, CRF 18, `--spill small`, one process per run), keying took 1.21 s a frame with `off` and 3.42 s with `auto` (the pass before this fix took 3.65 s there), and peak memory rose from 396 MB to 908 MB, about 247 MB more per megapixel of frame; `video-set` keys three items at once by default, so at that size it can use about 1.5 GB more at a moment. Changed pixels are about 2 % of each frame (4.5 % in the translucent scene), all within 6 px inside the silhouette; nothing outside it changes any more, and the interior is byte-identical.+**Defaults.** In this release, `sprite-gen video-frames` and `video-set` default to `--decontam auto` (before: `off`). Stills (`cutout`, `gen`) stay `off`: they defaulted to `auto` during development until a regression on Grok's darker magenta greyed warm palette colours; that cap and the frame-edge interaction were fixed, but the still measurements use a green key, so stills remain `off`. The row extractor (`extract`, `inspect`) stays `off` because its frames are a derived cache that `heal` re-derives from raw, so a changed default would silently rewrite every existing run, and pixel-art rows binarize alpha downstream anyway. Video defaulted to `off` until now out of caution rather than a known defect, because the pass was benchmarked on a green key only and the video fit is less decisive than the still fit (10.8 % residual key contamination against 0.03 % on the original benchmark); the Grok-magenta regression and the frame-edge interaction were fixed earlier, and no blocking defect is known. Video defaults to `auto` now because on a chroma key, H.264 4:2:0 chroma mixes the key into every strand one to three pixels wide, leaving an olive rim on red hair over green with the pass off, and the pass gives such edges the subject's own colour back. The video fit drops flank recovery, examining only subject pixels within 6 px of the keyed background, and holds calls, blends changes of call, and settles still pixels across frames so still edges do not sparkle: on a still scene under decoder noise (red strands on painted green), the mean change of each keyed edge pixel from one frame to the next on a dark background was 2.34 with `off` (99th percentile 8.3), 2.27 with hold and settle only (8.3), and 2.25 now (8.0), while key contamination was 6.5 %, 2.3 %, and 2.4 %, respectively. Where `auto` cannot run, it leaves frames exactly as the matte keyed them and records the reason in the report (`decontam.reason`, and per frame in `rows[].decontam`): a white key ("the white matte has no key colour to remove") or a subject with no pixel deeper than 6 px inside the keyed silhouette ("no interior to learn the subject's colours from"). With `--alpha-mode brightness` (emitted light on black, no chroma key), `auto` simply means off and records `decontam: {"mode": "auto", "applied_frames": 0, "reason": "brightness alpha has no key colour to remove"}`, while an explicit `--decontam palette` is refused. To keep the matte as it is, `--decontam off` returns the 2.45.3 bytes exactly. On stderr after its JSON summary, `video-frames` prints a one-line warning starting `video-frames: warning: decontam auto ...` when `auto` did not run on any frame (naming the reason and stating that frames match `--decontam off`), when `auto` skipped some frames, when the subject owns key-coloured material so the palette is not key-free (edges may be repainted in the key colour too), or when the key-coloured part guard kept edge pixels beside a small key-coloured part (stating how many, and that a thin detail of that colour farther out may be repainted); codec noise deep inside the subject guards no edge and raises no warning, brightness alpha prints no warning, and the line ends by naming `--decontam off` as the way to keep the matte as it is. `video-set` lists the same line prefixed by the item name under `warnings` in its set report. On an Intel i5-7500 (1080x1920 synthetic clip, CRF 18, `--spill small`, six frames, one process per run), keying took 1.14 s a frame with `off`, 3.25 s with hold and settle only, and 3.36 s now; peak memory was about 400 MB, 945 MB, and 1155 MB, respectively, about 365 MB more than `off` per megapixel of frame now; `video-set` keys three items at once by default, so at that size it can use about 2.3 GB more than `off` at a moment. Changed pixels are about 2.4 % of each frame (4.7 % in the translucent scene), all within 6 px inside the silhouette; nothing outside it changes any more, and the interior is byte-identical.| scene | key contamination | halo dark / white | strand recall ||---|---|---|---|-| red strands 1 to 3 px on painted green | 24.2 % to 9.2 % | 11.6/12.1 to 9.5/10.1 | 91.4 % to 91.4 % |-| the same on pure #00FF00 | 27.4 % to 9.3 % | 12.0/11.9 to 9.8/9.7 | 92.4 % to 92.4 % |-| red hair on magenta | 3.4 % to 0.5 % | 15.0/19.6 to 12.5/16.3 | 87.0 % to 87.0 % |-| red hair on Grok's darker magenta | 5.4 % to 2.0 % | 20.7/31.5 to 19.4/30.0 | 73.3 % to 73.3 % |-| a translucent glow and a cyan wisp | 20.6 % to 7.8 % | 12.6/9.4 to 11.5/8.4 | 85.7 % to 85.7 % |-| a small green charm (0.04 % of the interior) | 23.8 % to 10.4 % | 11.8/12.9 to 9.9/11.1 | 90.7 % to 90.7 % |+| red strands 1 to 3 px on painted green | 24.2 % to 10.2 % | 11.6/12.1 to 9.6/10.1 | 91.4 % to 91.4 % |+| the same on pure #00FF00 | 27.4 % to 10.9 % | 12.0/11.9 to 10.0/9.9 | 92.4 % to 92.4 % |+| red hair on magenta | 3.4 % to 0.5 % | 15.0/19.6 to 12.7/16.4 | 87.0 % to 86.9 % |+| red hair on Grok's darker magenta | 5.4 % to 1.8 % | 20.7/31.5 to 19.3/30.0 | 73.3 % to 73.2 % |+| a translucent glow and a cyan wisp | 20.6 % to 8.8 % | 12.6/9.4 to 11.7/8.5 | 85.7 % to 85.4 % |+| a small green charm (0.04 % of the interior) | 23.8 % to 11.4 % | 11.8/12.9 to 10.0/11.1 | 90.7 % to 90.7 % |-Strand recall no longer rises with the pass because that gain came from the flank the video fit no longer recovers; halo gains are smaller for the same reason (on Grok's darker magenta, 19.4/30.0 now against 17.1/24.7 with the flank, off 20.7/31.5). On the small green charm, the share of key-coloured edge losing half its key hue or coverage was 0.77 with `off`, 1.00 without the guard in the diagnosis, and 0.82 now (colour error 41.7 with `off`, 64.9 without the guard, and 46.2 now). On the two magenta keys, red hair counts as key-coloured material so the palette is not key-free, the warning line appears, and outline ink CIELAB error goes from 19.3 to 20.8 on magenta and from 21.7 to 24.1 on Grok's darker magenta; a white key and a subject with no interior produce identical bytes to `off`, with the reason recorded. Reports add `decontam.reason` (first skip reason), `decontam.skipped_frames` when frames are skipped, and per-frame stats and clip totals add two counters, `held_px` (pixels where a held outcome or colour differed from what that frame alone would have given) and `settled_px` (pixels settled), alongside `key_part_kept_px` and `behind_kept_px`, while `recovered_px` is now 0 in video.+On these moving scenes, key contamination is about one point higher than with hold and settle only: a changed call takes a few frames to reach the fit's colour, where the previous version switched at once.++Strand recall no longer rises with the pass because that gain came from the flank the video fit no longer recovers; halo gains are smaller for the same reason (on Grok's darker magenta, 19.3/30.0 now against 17.1/24.7 with the flank, off 20.7/31.5). On the small green charm, the share of key-coloured edge losing half its key hue or coverage was 0.77 with `off`, 1.00 without the guard in the diagnosis, 0.82 with hold and settle only, and 0.82 now (colour error 41.7 with `off`, 64.9 without the guard, 46.2 with hold and settle only, and 45.6 now). On the two magenta keys, red hair counts as key-coloured material so the palette is not key-free, the warning line appears, and outline ink CIELAB error goes from 19.3 with `off` to 20.2 now on magenta (20.8 with hold and settle only) and from 21.7 to 22.6 on Grok's darker magenta (24.1 with hold and settle only); a white key and a subject with no interior produce identical bytes to `off`, with the reason recorded. Reports add `decontam.reason` (first skip reason), `decontam.skipped_frames` when frames are skipped, and per-frame stats and clip totals add three counters, `held_px` (pixels where a held outcome or colour differed from what that frame alone would have given), `blending_px` (pixels showing a mix of two calls, not yet at this frame's call), and `settled_px` (pixels the settle or a still step moved from the previous frame's output), alongside `key_part_kept_px` and `behind_kept_px`, while `recovered_px` is now 0 in video.Limitations:- An edge takes one of the subject's interior colours at its observed brightness. A thin feature whose colour appears nowhere inside the subject keeps the engine's pixels. On the RGB matte that includes the matte's reading of a thin yellow line or dot, with no pixel deeper than two pixels, as a green blend.- In video a thin strand's chroma is gone before keying, so its colour is chosen from blurred chroma; strands come back in the hair's hue, sometimes a shade darker or paler than drawn.-- The hold works on pixels that stay put. A strand that moves is decided afresh in every frame, so a moving edge still changes from frame to frame as its colour does; a red rim moving over a dark background changes more than the olive rim `off` leaves.-- The settle follows a slow change within 12 levels per channel.+- The hold works on pixels that stay put. A strand that moves is decided afresh in every frame, and its change of call is spread over a few frames while both renderings follow it, so a moving edge still changes from frame to frame as its colour does; a red rim moving over a dark background changes more than the olive rim `off` leaves, and pixels whose call changes show a mix of the two for a few frames.+- The settle follows a slow change within 12 levels per channel and catches up past that at most 4 a frame.+- A change of call on a still edge arrives at most 4 a frame. The largest change, from the matte's full coverage to a faint fit or back, can take up to about 64 frames, about 2.7 s at 24 fps; in between, the edge shows a mix of the matte's colour and the fit's.- The video fit gives back no coverage the hard cut keyed: the outer pixels of a soft edge that the cut erased stay erased (the halo figures above).- A subject that owns key-coloured material keeps it in its palette, and its edges are repainted with whatever explains them best, key colour included. Keep the default on stills, but pass `--decontam off` on video when that material matters.- The pixel-unfake path binarizes alpha downstream, so on pixel-art rows only edge colours change.diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex d12d655..c2eea12 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -690,9 +690,9 @@ reference costs more than that to judge. The report records `reference_size`,### Edges: `--decontam`-`--spill` fixes key colour painted into the subject, but strands and outlines at its edge are a different problem: H.264 4:2:0 chroma mixes the key into anything one to three pixels wide, leaving an olive rim on red hair or turning it orange under despill. In release 2.46.0, `video-frames` and `video-set` default to `--decontam auto` (before: `off`), which re-explains each edge pixel as a blend of the local key background with colours the subject owns and writes that colour at the pixel's observed luma, using the video fit and one palette per clip learned on the first frame. The video fit recovers no coverage on keyed pixels, examining band pixels only; across frames in a clip, near-threshold choices are held and still pixels are settled toward the fit to eliminate edge sparkle. Where `auto` cannot run (a white key or a subject with no interior deeper than 6 px) and under `--alpha-mode brightness`, it leaves frames exactly as keyed and records the reason in the report. On stderr, `video-frames` prints a one-line warning (and `video-set` lists it under `warnings`) when `auto` did not run on any frame, skipped frames, found key-coloured subject material, or triggered the key-coloured part guard.+`--spill` fixes key colour painted into the subject, but strands and outlines at its edge are a different problem: H.264 4:2:0 chroma mixes the key into anything one to three pixels wide, leaving an olive rim on red hair or turning it orange under despill. In this release, `video-frames` and `video-set` default to `--decontam auto` (before: `off`), which re-explains each edge pixel as a blend of the local key background with colours the subject owns and writes that colour at the pixel's observed luma, using the video fit and one palette per clip learned on the first frame. The video fit recovers no coverage on keyed pixels, examining band pixels only; across frames in a clip, near-threshold choices are held, changes of call are blended over frames, and still pixels are settled toward the fit to eliminate edge sparkle. Where `auto` cannot run (a white key or a subject with no interior deeper than 6 px) and under `--alpha-mode brightness`, it leaves frames exactly as keyed and records the reason in the report. On stderr, `video-frames` prints a one-line warning (and `video-set` lists it under `warnings`) when `auto` did not run on any frame, skipped frames, found key-coloured subject material, or triggered the key-coloured part guard.-Two video guards keep the matte's bytes for edge pixels beside small key-coloured parts and for pixels matching the material right behind them. Pass `--decontam off` to keep the matte as it is and return 2.45.3 bytes exactly. Keying time roughly triples (1.21 s to 3.42 s a frame on an Intel i5-7500 at 1080x1920) and peak memory rises by about 247 MB per megapixel of frame. Method, guards and measurements: [chroma-alpha.md](chroma-alpha.md#decontam--give-the-edge-the-subjects-own-colour-back).+Two video guards keep the matte's bytes for edge pixels beside small key-coloured parts and for pixels matching the material right behind them. Pass `--decontam off` to keep the matte as it is and return 2.45.3 bytes exactly. Keying time rises from 1.14 s to 3.36 s a frame on an Intel i5-7500 at 1080x1920, and peak memory rises from about 400 MB to 1155 MB, about 365 MB more than `off` per megapixel of frame. Method, guards and measurements: [chroma-alpha.md](chroma-alpha.md#decontam--give-the-edge-the-subjects-own-colour-back).## 3b. Canvas shape for raised limbs and wide costumes