Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
release: 3.5.0 — the CHANGELOG section named for the release, its two upgrade paragraphs made one, pyproject and SKILL.md at 3.5.0
Soohong Kimf390b36fb5b1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 871b2ff..900ce27 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,12 +2,19 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.-## Unreleased - A flat background of any colour is cut out from what the image painted, and a cutout that removes nothing fails+## v3.5.0 - Widened square canvas framing for side walk and run stride and trailing parts, measured background matte cutout for flat backgrounds of any colour, and failure when a cutout removes nothing-**Upgrading from 3.4.0: `video-set` now frames a walk or run filmed from the side on a square widened by the room its still lacks.** A still that leaves less than `GAIT_ROOM` clear in front of its silhouette (0.15 of the silhouette's height) or behind it (0.25) gains the columns it lacks on that side; the square gains the same number of rows above the still. A still that leaves the room keeps its canvas to the byte. Every other state, a front, back or diagonal view, `--shape` and `--fit tight` are framed as before. Each side walk or run's `canvas.report.json`, and its item in `set.report.json`, gains `room`. `video-canvas` gains `--view` and reads the room only with `--view side`.+**Upgrading from 3.4.0: `video-set` now frames a walk or run filmed from the side on a square widened by the room its still lacks, and a background the chroma engine did not recognise, which used to come out with nothing removed, is now cut out.** A still that leaves less than `GAIT_ROOM` clear in front of its silhouette (0.15 of the silhouette's height) or behind it (0.25) gains the columns it lacks on that side; the square gains the same number of rows above the still. A still that leaves the room keeps its canvas to the byte. Every other state, a front, back or diagonal view, `--shape` and `--fit tight` are framed as before. Each side walk or run's `canvas.report.json`, and its item in `set.report.json`, gains `room`. `video-canvas` gains `--view` and reads the room only with `--view side`. Backgrounds the chroma engine already recognised key byte for byte as before. A pure or recognised magenta/green background still goes to the chroma engine and a bright achromatic one to the white matte, with the same bytes.- **New: the walk's room (`canvas.gait_room`, `GAIT_ROOM`, `ROOM_VIEWS`).** Filmed from the side, a walk's stride reaches in front of the standing silhouette, and behind it the stride and a part that trails behind the body (a big tail, a long coat) swing past it. Where either met the left or right edge, `video-frames` refused the clip, and the walk had to be filmed again with `--shape wide`. The `walk` and `run` rows now read the still's room: the empty columns between the silhouette and the left and right edges of the square the row makes of the still, in front and behind, as a fraction of the silhouette's height. A side under its `GAIT_ROOM` (more behind than in front) gains what it lacks, and the frame stays square: the clip keeps the 1:1 a walk is filmed at, and the still is never scaled. The report's `room` records the view, the silhouette, the room on each side, the bound, `short`, `added_px` (columns per side) and `added_rows`, and a widened canvas's `why` says why. `--shape square` keeps the still's own square. `--shape wide` is still the walk's 16:9 row (`GAIT_WIDE`). See [video-pipeline](docs/video-pipeline.md) section 1.- **Changed: `canvas.subject_rows` is now `canvas.subject_box`**, which reads the columns as well as the rows. `--fit tight` reads its rows from it, byte for byte.+- **New: the measured background matte (`sprite_gen/frames/measured_matte.py`, rule in docs/chroma-alpha.md "The measured background").** It reads the background's colour and spread from a ring inside the image's edges, keys that colour and its hue in shade (a drop shadow, a gradient), thin dark strips along the edges, and enclosed pockets of a saturated background, then unmixes a 2 px edge between the local background and the nearest solid subject colour. No colour needs a route of its own: a muted yellow-green, an off-cyan, a grey or an off-white key the same way.+- **Fixed: `cutout --key green|magenta` and `extract_route` on a background the engine does not recognise as that key.** Such a background was keyed against the pure key and nothing came off, and `cutout` exited 0; a green behind dark edge strips was routed to the white matte. It is now measured (`route: measured`, `chroma_key_painted` the measured colour), so `video-canvas` repaints such a still to the exact key, and `cutout` keys the frames of such a clip one by one. `video-frames` keeps keying a clip from one exact key: it still refuses such a clip, with the same bytes and report, and its guidance to normalise the still with `video-canvas` now works on these backgrounds.+- **Fixed: `cutout` fails when it made nothing transparent**, like `gen/chroma.py`, instead of reporting success.+- CLI: `cutout --key measured` forces the measured matte; `auto` sends a corner that is neither a key nor bright and achromatic to it.+- Report fields (`route: measured`): `background`, `background_spread`, `background_ring_share`, `shade`, `tolerance`, `edge_strips`, `keyed_pixels`, `pocket_pixels`, `edge_pixels`, `band`, `key_residue_px`.+- Python callers: `extract_route(..., measure_unrecognised=True)` and `cutout(..., measure_unrecognised=True, refuse_empty=True)` (`video-frames` passes both False); new `cutout.key_recognised(image, kind)`, `measured_matte.measured_matte(image, band=2)`, `measured_matte.measure_background(rgb)`, `measured_matte.background_like(rgb, colour, tolerance, shade)`.+- **Tests**: new `tests/frames/test_measured_matte.py`, synthetic only: a subject with a dark outline, skin and hair colours on muted green, deep green, off-cyan and yellowish backgrounds with noise, a gradient, a darker shade round the subject, dark strips on two edges and a pocket of background inside; an off-white background measured on request; the routing of a green request on a muted green through `extract_route`, `cutout` and `video-canvas`; a cutout that keys nothing fails.- **Tests**: `tests/video/test_walk_canvas_room.py` covers these cases:- a side walk whose tail reaches 6 px of the edge behind, facing either way, gets a square widened behind and above by what it lacks, the still unscaled, through `video-set`'s item and report;- a person with room keeps the default row's canvas byte for byte;@@ -21,16 +28,6 @@ All notable public changes to `sprite-gen` are recorded here. Versions track theFour `video-set` tests' canvas stubs now take `view`, and `test_edge_speck_lead_in.py` reads the walk's own row.-**Upgrading: backgrounds the chroma engine already recognised key byte for byte as before; a background it did not recognise, which used to come out with nothing removed, is now cut out.** A pure or recognised magenta/green background still goes to the chroma engine and a bright achromatic one to the white matte, with the same bytes.--- **New: the measured background matte (`sprite_gen/frames/measured_matte.py`, rule in docs/chroma-alpha.md "The measured background").** It reads the background's colour and spread from a ring inside the image's edges, keys that colour and its hue in shade (a drop shadow, a gradient), thin dark strips along the edges, and enclosed pockets of a saturated background, then unmixes a 2 px edge between the local background and the nearest solid subject colour. No colour needs a route of its own: a muted yellow-green, an off-cyan, a grey or an off-white key the same way.-- **Fixed: `cutout --key green|magenta` and `extract_route` on a background the engine does not recognise as that key.** Such a background was keyed against the pure key and nothing came off, and `cutout` exited 0; a green behind dark edge strips was routed to the white matte. It is now measured (`route: measured`, `chroma_key_painted` the measured colour), so `video-canvas` repaints such a still to the exact key, and `cutout` keys the frames of such a clip one by one. `video-frames` keeps keying a clip from one exact key: it still refuses such a clip, with the same bytes and report, and its guidance to normalise the still with `video-canvas` now works on these backgrounds.-- **Fixed: `cutout` fails when it made nothing transparent**, like `gen/chroma.py`, instead of reporting success.-- CLI: `cutout --key measured` forces the measured matte; `auto` sends a corner that is neither a key nor bright and achromatic to it.-- Report fields (`route: measured`): `background`, `background_spread`, `background_ring_share`, `shade`, `tolerance`, `edge_strips`, `keyed_pixels`, `pocket_pixels`, `edge_pixels`, `band`, `key_residue_px`.-- Python callers: `extract_route(..., measure_unrecognised=True)` and `cutout(..., measure_unrecognised=True, refuse_empty=True)` (`video-frames` passes both False); new `cutout.key_recognised(image, kind)`, `measured_matte.measured_matte(image, band=2)`, `measured_matte.measure_background(rgb)`, `measured_matte.background_like(rgb, colour, tolerance, shade)`.-- **Tests**: new `tests/frames/test_measured_matte.py`, synthetic only: a subject with a dark outline, skin and hair colours on muted green, deep green, off-cyan and yellowish backgrounds with noise, a gradient, a darker shade round the subject, dark strips on two edges and a pocket of background inside; an off-white background measured on request; the routing of a green request on a muted green through `extract_route`, `cutout` and `video-canvas`; a cutout that keys nothing fails.-## v3.4.0 - Loop part pop retakes, cycle alignment walk beat repair and broken beats, ghost limb faults, and same foot, filmed jump, and seam jump retakes**Upgrading from 3.3.0: A walk or run loop in `video-loop` is cut to the same bytes, whether a part pops in it or not, and `video-cycle-align` changes only alignment outputs whose beat broke or where a made frame has a limb seen through under `--between auto`.** For `video-loop`, every walk and run report gains `part_pop` and `retake`; `--unfixed refuse` also refuses a loop recorded `retake` reason `part-pop`, whatever `--repair`; no flags are added, no frames are made and no other cut is taken. `video-cycle-align` now reads ghost bands in windows of the body to catch limbs seen through, keeps frames given way on the beat under `--between auto` by making them again at clean fractions or widening jolts across neighbouring frames, changing only alignment outputs whose beat broke (a jolt of 0.25 beat or more) or where a made frame has a limb seen through (ghost window over 1.4 %); loops keeping the beat, loops with no frame given way, and `video-loop` (and `video-set`) keep their bytes for strip PNG, GIF, WebP, and cycle frames, while gaining `beat`, `ghost_window`, (on back and back_diagonal views) `same_foot`, and `retake` reasons (`broken-beat`, `same-foot`) in alignment `strip.json` and reports; every aligned loop's `strip.json` and report gain `screen`, and loops whose cut jumps gain the reasons `filmed-jump` and `seam-jump`, frames unchanged; and `clip_feet` in `video-loop`'s `strip.json` and reports for every walk or run cut; all outputs from `video-loop-compare` and `video-loop-repair` are unchanged, bytes included, and `--same-foot` defaults to `warn` so nothing is refused by default.diff --git a/SKILL.md b/SKILL.mdindex 3fbf701..0ae53f3 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: sprite-gen-version: 3.4.0+version: 3.5.0description: "Generates images and game sprites through GPT or Grok with guided provider choices, separate saved defaults, automatic cleanup and optional curation. Handles sprite requests, ordinary image generation/editing, typography logos (로고, 타이포그래피, 타이틀 글자, 타이틀 로고, wordmark, logo, title lettering: a title screen drawn with the title in it, its lettering lifted out transparent), standalone image-to-video clips (i2v, animate this still, 그록 영상, 이매진 비디오, 스틸 움직여줘, first/last frame, reference-to-video, 영상 이어붙이기, 영상 편집, extend/edit a clip), clips from a video MCP on the agent (ZCRE, 지크 MCP), chroma removal, animation atlases, video loops, 큐레이션뷰, image candidates, 팔레트 스왑, palette swap, recolor, engine exports, repeating backgrounds, projected shadows, talking face layers over body motions (말하는 얼굴, 입 맞추기, 얼굴 층, lip sync, face pack), motion/contact inspection and optional scene composition from existing assets."license: Apache-2.0depends_on:diff --git a/pyproject.toml b/pyproject.tomlindex 58affa7..e9c0c1a 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"name = "sprite-gen"# Release discipline: keep this package metadata version synchronized with# SKILL.md's `version:` field in the same release commit.-version = "3.4.0"+version = "3.5.0"description = "Component-row pipeline for clean 2D game sprites and animation atlases"readme = "README.md"license = "Apache-2.0"