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/logo-reader-variance-1023 (logo: a text check reads a misreading once more before it refuses, codex reads it on a named model and effort, the report keeps every reading) into main, validated in sprite-gen/logo-reader-variance-1023 — CHANGELOG: the branch's block follows the earlier landings in the one ## Unreleased section

Soohong Kim540786596aac
diff --cc CHANGELOG.md
index bccd0b5,47f9d02..2e7b149
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -4,39 -4,14 +4,47 @@@ All notable public changes to `sprite-g
## Unreleased
+**Upgrading from 3.0.0: Bakes retain the same bytes for figures whose anatomy is unchanged. The `pixel` refusal message now names the sides and pixel counts. A figure that had `face-absent` may now have a face, with a lower rigid boundary only when that face ends below the neck.**
+
+The Breathe layer still supports `pixel` and `smooth`.
+
+- **Changed: Pixel refusal.** `pixel` still refuses stretched content past the top, left, or right of a cell instead of cropping it.
+ The message names each side and its opaque pixel count. A pixel past a corner counts on both sides.
+ When an overflowing side is the drawing's own border, the message also gives the number of pixels covering that edge.
+ It advises `--mode smooth` or sidecar `mode: "smooth"` for an illustration cut by its frame.
+ It advises a wider cell margin or lower `depth` for a pixel sprite.
+ It warns that padding, baking, and cropping back silently loses pushed off content.
+ The curator preview uses the same refusal wording.
+ The border reading follows the 2% rule in [video pipeline](docs/video-pipeline.md) section 3.
+ See [breathing](docs/breathing.md) for behavior at frame edges.
+- **New: Second eye pair search.** It runs only when the existing search finds no pair.
+ Its minimum eye area is 0.2% of opaque pixels above the neck.
+ Its eye width to height limit is 3.0, and its minimum eye center distance from the body axis is 0.02 of content width.
+ Pair placement, separation, size similarity, and row overlap conditions remain the same.
+ A face found by this search clears `face-absent`. It lowers the boundary only if the face ends below the neck.
+- **Faster: Breathe bakes.** Array operations speed up pixel outline thinning, appendage weights, and row mapping.
+ `smooth` solves displacement only for pixels that move.
+ Anatomy and settings checks run once per row, and `sprite-gen breathe` shares one anatomy measurement between its report and bake.
+ On synthetic 960 x 960 cells with Apple M1, bake time fell from 0.20 s to 0.10 s for `smooth`.
+ For an outlined figure with arms in `pixel`, it fell from 0.98 s to 0.05 s.
+ These measurements exclude PNG reading and writing.
+ `bake_breathe_sequence(images, cfg, anat=None)` and `anatomy_report(images, cfg, anat=None)` accept measured anatomy.
+ `protect(anat)` accepts one column or an array of columns.
+- **Tests:** `tests/effects/test_breathe.py` checks border counts, advice, smooth edge preservation, and the second face search.
+ `tests/effects/test_breathe_js_mirror.py` checks curator refusal wording and byte identity with the pixel bake.
+ `tests/effects/test_breathe_smooth.py` checks pixel and smooth byte goldens and shared anatomy and strain measurements.
+ `tests/effects/test_breathe_publish.py` checks that the stand-in bake accepts the new argument.
+
+- **Tests**: A plain `pytest` runs a fast bundle: tests marked `slow` are deselected, the header points to `pytest --full`, and the summary counts deselections. `pytest --full` runs every test. The release lane, `scripts/linux_lane.sh`, passes `--full` to both `pytest` calls, including `-m real_rife`, so its gate still runs every test. `tests/release/test_fast_bundle.py` checks both calls and probes selection with and without `--full`. The `slow` rule in `pyproject.toml` is 1 s per case or 5 s across a function's cases on an 8-core M1 running the whole suite; marking a function marks every case. Five tests remain unmarked as the only fast callers of `video-stop`, `workflow`, `defaults`, `video-sway`, and `export-aseprite`. Three fixture-first tests remain unmarked because other fast tests build their fixtures. In `tests/frames/test_ui_kit.py`, the fast bundle keeps 16 of 512 scattered-drawing grid seeds, 8 of 256 full-size-frame band grid seeds, 9 of 256 missing-element sets, 2 of 17 counterexample sheets, and one placement and start in each publish sweep. `tests/curate/test_anchor_selection.py` extracts each run once per module instead of repeating 1.5 to 2.6 s of setup per test; 25 of 27 affected tests are now fast. Removed `tests/video/test_loop_overlap.py::test_a_tail_on_its_own_beat_is_closed_at_the_wrap_with_the_clips_frames_a_cycle_apart[on]`; its wordless case makes the same call with the default "on". Removed `tests/video/test_walk_steps.py::test_cycle_align_takes_a_loop_cut_two_steps_as_one_cycle` and `tests/video/test_one_step_cut.py::test_cycle_align_takes_the_loop_cut_again_on_its_count`; `tests/video/test_loop_prop_seam_held.py::test_cycle_align_aligns_a_two_step_loop_as_the_one_cycle_it_is` covers alignment from recorded `steps: 2`. Merged `tests/video/test_loop_overlap.py::test_the_cli_passes_overlap_wrap_off_and_on_is_its_default` into `tests/video/test_loop_overlap.py::test_with_the_overlapped_wrap_off_nothing_is_read_for_the_wrap_and_the_gate_refuses_the_cut_as_filmed`, retaining both sets of assertions on one CLI cut with `--overlap-wrap off`. In a new virtual environment, the former suite ran 7,881 tests (7,880 passed, 1 skipped) in 21 minutes 54 seconds; `pytest --full` now runs 7,881, including two new release tests, and the fast bundle runs 6,555 in about 6 minutes. Package code, commands, and outputs are unchanged.
+
+ **Upgrading from 3.0.0: the `sprite-gen logo` text checks read a refused image once more before refusing it, and on codex they read on a fixed model and effort.** A mood or logo reading of `mismatch` or `no-text` is read again, up to `logo.MAX_READS` readings, which is 2. One reading that spells the asked text passes. An image is refused only when every reading differs. A logo now costs four to six calls: two images and two text checks, each read once or twice. Beyond a check's second reading nothing is sent again on its own. On codex the text checks no longer follow the login's `~/.codex/config.toml`. They read on `gpt-6-sol` at reasoning effort `high`, and the report names the model and effort of every reading.
+
+ - **A misreading is read once more before it refuses an image.** Before, each check read the image once, and one misreading refused it. A model reading stylised lettering can read the same picture two ways, so a correctly drawn title could be refused on one reading. Both checks use the one rule, `logo.read_text`. A call that fails is not asked again. With no reading before it, the check is `unverified` as before. With a misreading before it, the misreading stands and the image is refused. A refusal message names every reading, for example `the mood image reads ['IO'] and then ['I0'], not ['ION']`. docs/logo.md records a measurement on a synthetic pixel title drawn one stroke short (the Hangul syllable 쿠 drawn as 구, the middle bar of ㅋ left out). The codex reader at gpt-6-sol/high read it as 구 in 10 readings of 10 and never as 쿠, so neither one reading nor a check of two readings (0 of 5) passed the wrong picture. A second reading can only pass a wrong picture if the reader writes a stroke that is not drawn.
+ - `logo.report.json`: `text_check.mood` and `text_check.logo` keep the deciding reading's `verdict` and `read` and gain `max_reads` and `readings`, each reading in order with its `reading` number, `verdict` and `read` lines, or `reason` when it could not be read. `calls` lists a check's call once per reading, each with `reading` (1 or 2) and `effort` (`null` where the provider names none).
+ - Codex reader: the text checks run `codex exec --model gpt-6-sol -c model_reasoning_effort="high"`, named on each call, so a check's verdict does not change with the machine it runs on. Before, each machine read on its own config and the report recorded `model: null`. The values are `facing_vision.CODEX_READ_MODEL` and `facing_vision.CODEX_READ_EFFORT`. `--model` still names the images' model only. The facing check still runs on the login's config, unchanged. The xAI and OpenAI text checks read on their own fixed models, as before.
+ - Python callers: `logo.read_text` returns `(check, calls)`, a list of call records, instead of `(check, call)`. `facing_vision.codex_inspect` takes optional `model` and `effort` keyword arguments. Without them its command line is as before.
+ - **Tests**: `tests/gen/test_logo.py` checks that one matching reading is the whole check, that a misreading read again as asked passes at either check, that two misreadings refuse the mood image and refuse the logo and keep it aside with a refusal naming both, that a check reads no more than `MAX_READS` (set to 3, a third reading is taken), that a failed call is not asked again, that a misreading stands when the second call failed, and that the report names the reader model and effort of every reading. The existing refusal tests now script two misreadings. `tests/gen/test_vision_read.py` checks that codex reads on the named model and effort, passed before the image list, that docs/logo.md names both values, and that the facing check's command carries neither.
+
## v3.0.0 - Remove rig layer composition
**Upgrading from 2.46.0: `sprite-gen compose-layers` and its other launch forms are removed, and rig layer declarations are no longer read.** `compose-atlas` no longer writes a manifest `rig` block or `animation.rows.<state>.track` for a run that declared a rig. Runs that never declared `rig`, `layers` or a state `track` get the same manifest as before. Existing run files and `layers/` folders stay on disk.