Skip to content

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

docs(logo): see-through inside the letters — only what is joined to the picture's edge is outside, however narrowly; a transparent hole walled in by the letters opens no way out and lends the glow no reach, and transparent pixels are never counted; the new synthetic shapes and their numbers, and the limits. CHANGELOG Unreleased. Text by the writing hand-off.

Soohong Kim09cbac9fba81
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a745aa..7c52062 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,10 +11,10 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- 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.
- **With `--chroma-key auto`, a key in the title's hue is not chosen.** `logo_matte.choose_key` rules out a key whose hue is 5 % or more of the title's box (`logo_matte.CLASH_HUED_PCT`), or 1 % (`logo_matte.NAMED_CLASH_HUED_PCT`) when `--style` or `--scene` names a colour in its hue (`logo.KEY_COLOUR_WORDS`: green, mint, lime, emerald, jade, chartreuse for green; magenta, fuchsia, pink, purple, violet, plum, orchid for magenta). A word alone never rules a key out; the pixels decide. The keys left are scored as before. When both keys are the title's colours there is no third: the run is refused at `key` (`refused_at: key`) before the lettering image is bought. The message gives each key's share and the brief's words for it and says to restyle the title without one of the two hues or to name the key to lose with `--chroma-key` (`--mood <mood.png>` skips the mood image). An explicit `--chroma-key` is kept; when it is one of the title's colours, a warning says so. Before, such a cut passed with `status: ok`, no warning, `key_hue_left` 0 and a matching text check.
-- **A cut that is see-through inside its letters is refused at `matte`.** `logo_matte.see_through_inside` measures see-through pixels (coverage under 240 of 255) walled in by opaque lettering and farther from it than the logo's own glow reaches beside it. On 1 % of the visible lettering or more (`logo_matte.INSIDE_MAX_PCT`) the logo is refused before its text is read, the cut is kept as `logo.rejected.png` and the preview is written. The message says to generate the lettering again on the other key or to restyle the title without that colour. Only the logo matte's own cut (`method: logo-unmix`) is refused; a lettering image returned with its own alpha is measured, not refused. A glow fades out beside the letters and pools in a counter no farther than it reaches there, so glows are not counted.
+- **A cut that is see-through inside its letters is refused at `matte`.** `logo_matte.see_through_inside` measures see-through pixels (coverage under 240 of 255) walled in by opaque lettering and farther from it than the logo's own glow reaches beside it. Walled in means no way out to the picture's edge except across opaque pixels: the way out starts from the transparent pixels on the edge of the trimmed logo and runs through transparent pixels and see-through ones; a see-through gap of 2 px or narrower does not count as a way, a transparent gap of any width does. A hole joined to the outside, even through one pixel, is outside; a transparent hole walled in by the letters (an O's counter, or a letter colour cut all the way to nothing) is no way out, and a see-through patch round such a hole is still counted inside. Transparent pixels are never counted, only see-through ones. The same way out decides the glow's reach (`glow_reach_px`): the 99th percentile of how far the see-through pixels that have a way out to the picture's edge lie from the opaque lettering, and at least 2 px. On 1 % of the visible lettering or more (`logo_matte.INSIDE_MAX_PCT`) the logo is refused before its text is read, the cut is kept as `logo.rejected.png` and the preview is written. The message says to generate the lettering again on the other key or to restyle the title without that colour. Only the logo matte's own cut (`method: logo-unmix`) is refused; a lettering image returned with its own alpha is measured, not refused. A glow fades out beside the letters and pools in a counter no farther than it reaches there, so glows are not counted.
- `logo.report.json`: `steps.key.scores.<key>` gains `named`, `clash_at_pct` and `clashes`, and `steps.key.key` is `null` when refused at `key`. `logo` gains `see_through_inside` with `px`, `pct_of_visible`, `glow_reach_px`, `max_pct` and `wide`. `refused_at` can now be `key`.
- Python callers: `logo_matte.choose_key(mood, box=None, named=None)` takes `named`, the brief's colour words per key from `logo.named_colours(style, scene)`, and returns `key: None` when both keys are the title's colours. `logo_matte.see_through_inside(image)` is new.
-- **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. `tests/frames/test_logo_matte.py` checks that a title in both keys' hues (synthetic patchwork letters: pink and plum in magenta's hue, mint in green's) gets neither key, that a colour in a key's hue rules the key out, that a colour the brief names rules it out at the smaller share while the same share unnamed and the word with no such pixels do not, that on green the mint patches are cut see-through and found inside (9.5 % of the visible lettering) while the other key keeps them and finds nothing, and that six glow fixtures (a white glow, an outlined cyan glow, a cyan glow pooled in an O's counter on green and on magenta, an orange glow on green, pixel lettering) find nothing inside. `tests/gen/test_logo.py` checks that a title in both keys' hues is refused at `key` before the lettering is bought, that a named key in the title's hue is kept and the warning says so, that a see-through cut is refused at `matte` and kept aside with no text check, and that a glowing title is not see-through inside. `tests/logo_lettering.py` gains the `quilt` fixture: square fabric patches in outlined pixel letters, one with a counter, on a key.
+- **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. `tests/frames/test_logo_matte.py` checks that a title in both keys' hues (synthetic patchwork letters: pink and plum in magenta's hue, mint in green's) gets neither key, that a colour in a key's hue rules the key out, that a colour the brief names rules it out at the smaller share while the same share unnamed and the word with no such pixels do not, that on green the mint patches are cut see-through and found inside (9.5 % of the visible lettering) while the other key keeps them and finds nothing, that six glow fixtures (a white glow, an outlined cyan glow, a cyan glow pooled in an O's counter on green and on magenta, an orange glow on green, pixel lettering) find nothing inside, that a mint patch walled in by a navy letter on green is still found inside, with the glow's reach at 2 px, when one or four squares of the key in it are cut to nothing, that a hole glued to the letter's edge is inside while sealed and outside once one pixel joins it to the key round the letter, and that big hollow O and A letters find nothing inside, plain or with a glow pooled round a counter whose middle stays clear (three glows). `tests/gen/test_logo.py` checks that a title in both keys' hues is refused at `key` before the lettering is bought, that a named key in the title's hue is kept and the warning says so, that a see-through cut is refused at `matte` and kept aside with no text check, with or without a 9x9 square of the key in the middle of its patch, and that a glowing title is not see-through inside. `tests/logo_lettering.py` gains the `quilt` fixture: square fabric patches in outlined pixel letters, one with a counter, on a key. It also gains `walled_patch` (a navy letter with a mint patch on pure green, with squares or a pixel of the key painted in) and `hollow_letters` (the big O and A shapes), which `lettering` draws through its new `shapes` argument.
## v3.0.0 - Remove rig layer composition
diff --git a/docs/logo.md b/docs/logo.md
index b67c3b5..a328c2d 100644
--- a/docs/logo.md
+++ b/docs/logo.md
@@ -223,11 +223,22 @@ inside the letter, where no glow reaches; a glow fades out beside the letters an
counter no farther than it reaches beside them. After the matte and trim,
`logo_matte.see_through_inside` measures the logo on that difference: the see-through pixels
(coverage under 240 of 255, `INSIDE_ALPHA8`) that are walled in by opaque lettering (no way
-out to a transparent pixel except across opaque ones; a gap of 2 px or narrower does not
-count as a way out) and lie farther from the opaque lettering than the logo's own glow
-reaches beside it. The glow's reach (`glow_reach_px`) is the 99th percentile of how far the
-see-through pixels that do have a way out lie from the opaque lettering, and at least 2 px
-(a letter's antialiased rim).
+out to the picture's edge except across opaque pixels) and lie farther from the opaque
+lettering than the logo's own glow reaches beside it. The way out starts from the
+transparent pixels on the edge of the trimmed logo and runs through transparent pixels and
+see-through ones; a see-through gap of 2 px or narrower does not count as a way, a
+transparent gap of any width does. Only what is joined to the picture's edge is outside,
+however narrowly: a hole joined to the outside, even through one pixel, is outside. A
+transparent hole walled in by the letters is no way out: an O's counter, or a letter colour
+cut all the way to nothing, such as a square of the key's colour painted inside a
+see-through patch; the see-through patch round such a hole is therefore still counted
+inside. Transparent pixels are never counted, only see-through ones: a letter's own counter,
+transparent and walled in by the letter, adds nothing, so big hollow letters with no glow
+give 0. The same way out decides both things: which see-through pixels are inside, and the
+glow's reach. The glow's reach (`glow_reach_px`) is the 99th percentile of how far the
+see-through pixels that have a way out to the picture's edge lie from the opaque lettering,
+and at least 2 px (a letter's antialiased rim); a see-through pixel whose only way out would
+be a hole inside the letters does not count toward the reach.
When that share is 1 % (`INSIDE_MAX_PCT`) of the visible lettering or more, the logo is
refused at the matte step (`refused_at: matte`) before its text is read; no logo text check
@@ -247,7 +258,22 @@ plum outline, one letter with a counter) on green have their mint patches cut se
and 9.5 % of the visible lettering is found inside; the same letters with no colour in
magenta's hue, on magenta, give 0 %. A white glow, dark-outlined gold letters with a cyan
glow, a cyan glow pooled in an O's counter on green and on magenta, an orange glow on green,
-and pixel lettering with no glow give 0 % each.
+and pixel lettering with no glow give 0 % each. A navy letter block on green, in flat
+colours, with a mint patch walled in by it, has the mint cut see-through and 17.1 % of the
+visible lettering found inside; with one 9x9 square of the key's colour in the middle of the
+patch, cut to nothing, 16.9 %; with four such squares, two of them glued to the patch's
+wall, 16.6 %. The glow's reach stays 2 px in all three (there is no glow). Run through
+`sprite-gen logo` with `--lettering`, the letter with one square is refused at `matte`
+before its text is read, as the one without is. With the mint patch filling the letter but
+for a 4 px outline and a hole glued to the letter's edge, one pixel of the letter left
+between the hole and the key round the letter, the hole is sealed and 88.6 % of the visible
+lettering is found inside; when that one pixel is the key's colour, the hole is joined to
+the outside, the patch has a way out through it, and nothing is found. Big hollow O and A
+letters, whose counters are transparent and walled in by the letters, find nothing with no
+glow (0 px). With a glow pooled round a counter whose middle stays transparent, a white
+glow on magenta gives 0 %, dark-outlined gold letters with a cyan glow on green 0 %, and an
+orange glow on green 0.02 %; a sweep of white glows from 3 to 16 px on both keys finds at
+most 0.04 %.
### Known limit
@@ -264,11 +290,13 @@ again with `--chroma-key` (or accept the ring: at full size it sits inside the g
brightest part).
The see-through check has limits of its own. A letter colour cut all the way to nothing
-leaves a hole that looks like a counter and is not found; keeping such a key off the
-lettering is the key choice's job. See-through within the glow's reach of the opaque
+everywhere leaves holes that look like counters, and transparent pixels are not counted, so
+it is not found; keeping such a key off the lettering is the key choice's job. A see-through
+patch round such a hole is found. See-through within the glow's reach of the opaque
lettering is taken for glow, so in a glowing title a key-hued patch narrower than about
-twice that reach is not found. A see-through patch on a letter's outer edge with no outline
-walling it in has a way out and is not inside.
+twice that reach is not found. A see-through patch with a way out to the picture's edge is
+not inside: one on a letter's outer edge with no outline walling it in, or one that a hole
+joins to the outside, even through one pixel.
## Cost