Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(logo): which key — a key in the title's hue is not chosen and a title in both is refused at the key; see-through inside the letters, refused at the matte, and what it cannot see; the report's new keys and the cost of each refusal. CHANGELOG Unreleased. Text by the writing hand-off.
Soohong Kim9eac1fa6aa16
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 47f9d02..4a745aa 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,13 +4,17 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased-**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.+**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. **`sprite-gen logo` refuses a chroma key that is one of the title's own colours, and a cut that is see-through inside its letters.** A letter colour in the key's hue is, by its pixels, a mix with the key, so the matte cuts it see-through. `--chroma-key auto` now skips a key whose hue covers 5 % or more of the title's box in the mood image, or 1 % when the brief names a colour in that hue. When both keys are the title's colours, the run is refused at the new step `key` before the lettering image is bought. After the matte, see-through pixels walled in by the lettering, farther from it than the logo's own glow reaches, refuse the logo at `matte` on 1 % of the visible lettering or more. A run that went through before with a key in the title's hue, or with a see-through cut inside its letters, is now refused at `key` or at `matte` instead of passing with `status: ok`. Runs whose title carries neither key's hue pick the same key as before.- **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.+- **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.+- `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.## v3.0.0 - Remove rig layer compositiondiff --git a/docs/logo.md b/docs/logo.mdindex d99cc25..b67c3b5 100644--- a/docs/logo.md+++ b/docs/logo.md@@ -7,15 +7,20 @@ for inside the picture it belongs to — a game's title screen, a poster — theas part of that world: its letterforms, materials and light come from the scene. So a logois made in three steps:-1. **mood** — a title screen (16:9) or poster (2:3) in the brief's style with the title+1. **mood**: a title screen (16:9) or poster (2:3) in the brief's style with the titlelettered in it. The text check reads it back (a misreading is read once more); a title- the model dropped or misspelt is refused here, before the next image is bought.-2. **lettering** — that picture attached as the reference of an image edit that asks for+ the model dropped or misspelt is refused here, before the next image is bought. The+ check also returns the box round the title, on which `--chroma-key auto` picks the key+ ([Which key](#which-key)); a title with both keys' hues among its colours is refused+ there, before the lettering is bought.+2. **lettering**: that picture attached as the reference of an image edit that asks foronly its lettering, with the same letterforms, materials, colours, outlines, glows andeffects, on a flat chroma key.-3. **matte** — the key removed by the logo matte (soft glows and partial alpha kept, no key- hue left), trimmed to the lettering with a 2 px margin. The logo's text is read again on a- plain backdrop; letters that differ from the text asked are refused.+3. **matte**: the key removed by the logo matte (soft glows and partial alpha kept, no key+ hue left), trimmed to the lettering with a 2 px margin. A logo see-through inside its+ letters, past the reach of its own glow, is refused here, before its text is read+ ([See-through inside the letters](#see-through-inside-the-letters)). The logo's text is+ read again on a plain backdrop; letters that differ from the text asked are refused.Nothing in this path draws a font. A step that cannot be done fails and says why; it isnever replaced by rendered text or by another provider.@@ -48,7 +53,7 @@ sprite-gen logo --provider codex --text "STARFALL" --lettering logo/lettering.pn| `mood.png` | step 1: the picture with the title in it (or a copy of `--mood`) || `lettering.png` | step 2: the lettering alone on the key, as the model drew it || `logo.png` | step 3: the transparent logo, trimmed; written only when its text reads as asked (or could not be checked, below) |-| `logo.rejected.png` | the cut of a logo whose text did not read as asked, kept aside for a look |+| `logo.rejected.png` | the cut of a logo whose text did not read as asked, or that is see-through inside its letters, kept aside for a look || `logo.preview.png` | the logo on a dark and on a light backdrop, side by side: where a halo or a hard edge would show || `logo.report.json` | the report |@@ -58,17 +63,19 @@ file there is always this run's (an input named with `--mood` or `--lettering` i## The report`kind: sprite-gen-logo-report`, with `status`: `ok`; `unverified` (the logo was made but-its text could not be checked); `refused` (with `refused_at`: `mood-check`, `matte` or-`logo-check`, and `reason`); `failed` (a step failed: a provider refusal, a timeout). Then:+its text could not be checked); `refused` (with `refused_at`: `mood-check`, `key`, `matte`+or `logo-check`, and `reason`); `failed` (a step failed: a provider refusal, a timeout).+Then:-- `text`, `subtitle`, `language`, `style`, `scene`, `composition`, `provider` and how it was- resolved (`provider_resolved_from`, `provider_fallback`, as `gen`);-- `steps.mood` (`source`: `generated`, `given` or `none`; the prompt sent), `steps.key`,+- `steps.mood` (`source`: `generated`, `given` or `none`; the prompt sent), `steps.key`+ (`key`, `source`, `region` and both keys' `scores`: [Which key](#which-key)),`steps.lettering` (the prompt, the reference, `raw_alpha`), `steps.matte` (the matte's ownnumbers, below) and `steps.trim` (`bbox` in the lettering image, sizes, `pad_px`);- `logo`: `size`, `alpha` (`opaque_pct`, `partial_pct`, `empty_pct` of the trimmed logo and- `visible_opaque_share`) and `key_hue_left` (visible pixels whose colour still carries the- key's hue — 0 is the aim);+ `visible_opaque_share`), `key_hue_left` (visible pixels whose colour still carries the+ key's hue; 0 is the aim) and `see_through_inside` (`px`, `pct_of_visible`,+ `glow_reach_px`, `max_pct` and `wide`:+ [See-through inside the letters](#see-through-inside-the-letters));- `text_check.mood` and `text_check.logo` (below);- `calls`: every call in order — `mood`, `mood-check`, `lettering`, `logo-check`, a check'scall once for each reading it took, with its `reading` (1, 2) and the `effort` it was read@@ -134,15 +141,47 @@ config. The xAI and OpenAI checks read on their own fixed models, as the facing## Which keyThe lettering keeps the mood image's colours, and the matte needs a key no letter is made-of. The mood check also returns the box round the title, and `--chroma-key auto` scores the-two keys on the colours inside it (`logo_matte.choose_key`, the whole image when no box came-back): a pixel already in a key's hue (a pink letter on magenta) counts hard against that-key, and every other colour scores how long its mix with the key keeps the key's hue — which-is how long a glow of that colour keeps its fade ([the known limit](#known-limit)). A cyan-or yellow glow keeps green's hue to about 85 % coverage and magenta's to about half; an-orange one the other way; a white or cream glow keeps either. Magenta wins a tie.-`steps.key` records the key, `source` (`auto`, `explicit`, or `border` for `--lettering`),-`region` and both keys' scores. Name the key yourself when you know the lettering better.+of. The lettering image is drawn on a flat chroma key, magenta or green, and a letter colour+in the key's own hue is, by its pixels, a mix with the key: the matte cuts it see-through (a+mint fabric patch in a letter on the green key comes out a pale, half-transparent patch).+The mood check also returns the box round the title, and `--chroma-key auto` (the default)+measures inside it (`logo_matte.choose_key`, the whole image when no box came back) the+share of pixels in each key's hue. "In a key's hue" is `logo_matte.key_hued`: for magenta+min(R, B) - G, for green G - max(R, B), above 16 levels, or a pale colour whose small cast+is mostly the key's.++A key whose hue is 5 % or more of the box (`logo_matte.CLASH_HUED_PCT`) is one of the+title's colours and is not chosen. When the style or scene (`--style`, `--scene`) names a+colour in a key's hue, 1 % of the box (`logo_matte.NAMED_CLASH_HUED_PCT`) is already+enough. The words are `logo.KEY_COLOUR_WORDS`: green, mint, lime, emerald, jade and+chartreuse for green; magenta, fuchsia, pink, purple, violet, plum and orchid for magenta. A+plural or an -ish or -y ending counts ("pinkish"). Teal, cyan and lavender are not in the+list: their usual values are in neither key's hue. A word alone never rules a key out: the+box holds scenery too, so the pixels decide and a word only lowers the share they need.++Between the keys left, the share of pixels in a key's hue (a pink letter on magenta) counts+hard against it, and every other colour scores how long its mix with the key keeps the+key's hue, which is how long a glow of that colour keeps its fade+([the known limit](#known-limit)). A cyan or yellow glow keeps green's hue to about 85 %+coverage and magenta's to about half; an orange one the other way; a white or cream glow+keeps either. Magenta wins a tie.++When both keys are colours of the title there is no third key: the logo matte and the key+prompts know magenta and green only. The run is refused at the key step (`status: refused`,+`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: restyle the title without one of the two hues, or+name the key to lose with `--chroma-key`; `--mood <mood.png>` skips the mood image on the+next run.++An explicit `--chroma-key magenta` or `green` is kept as before; when that key is one of the+title's colours, a warning says so: its letters in that hue come out see-through. With+`--lettering`, `auto` reads the key off the image's border, and no colour check is made+there. Name the key yourself when you know the lettering better.++`steps.key` records `key` (`null` when refused), `source` (`auto`, `explicit`, or `border`+for `--lettering`), `region` (`lettering-box` or `image`), and for each key under `scores`:+`hued_pct`, `hold`, `score`, `named` (the brief's words in that key's hue), `clash_at_pct`+(5 or 1) and `clashes`.## The logo matte@@ -177,6 +216,39 @@ a letter colour), `unmix_px` (glow), `faint_px`, `partial_px`, `specks_cleared_ptransparent background (codex sometimes answers an edit with alpha) is kept on that alpha(`method: native-alpha`); a key painted as a transparency checkerboard is refused.+### See-through inside the letters++A letter colour in the key's hue is cut as a mix with the key and comes out see-through+inside the letter, where no glow reaches; a glow fades out beside the letters and pools in a+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).++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+call is made. The cut is kept aside as `logo.rejected.png` and `logo.preview.png` is+written. The message names the share and the key, and says: generate the lettering again on+the other key (`--chroma-key <the other key>`, with `--mood <mood.png>` when there is a mood+image), or restyle the title without that colour. There is no option that accepts it; the+rejected cut is there to look at. Only a cut made by the logo matte (`steps.matte.method:+logo-unmix`) is refused; a lettering image that came back with its own alpha+(`native-alpha`) is measured and reported, not refused.++`logo.see_through_inside` reports `px`, `pct_of_visible`, `glow_reach_px`, `max_pct` (1.0)+and `wide` (true when refused on it).++In the tests, patchwork letters (square pink, butter yellow, mint and sky-blue patches in a+plum outline, one letter with a counter) on green have their mint patches cut see-through,+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.+### Known limitThe dense part of a glow, past the coverage where its mix with the key still shows the@@ -185,19 +257,29 @@ opaque in it: a cyan glow pooled in an O's counter on magenta (past about half cthe ring round a small gold sparkle's white core on green (past about three quarters: afaint olive cast on a light backdrop). On the key whose hue the glow shares more it keepsits fade (`tests/frames/test_logo_matte.py` holds both sides): that is what-`--chroma-key auto` weighs, after the letters' own colours — a letter in the key's hue would-be lost entirely, so it counts more. When `logo.preview.png` shows such a ring where a glow-is dense, cut the same lettering on the other key's terms by generating it again with-`--chroma-key` (or accept the ring: at full size it sits inside the glow's brightest part).+`--chroma-key auto` weighs, after the letters' own colours, which count more because a+letter in the key's hue comes out see-through. When `logo.preview.png` shows such a ring+where a glow is dense, cut the same lettering on the other key's terms by generating it+again with `--chroma-key` (or accept the ring: at full size it sits inside the glow's+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+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.## CostFour to six calls a logo on the provider named: two images and two text checks, each readonce, or twice when its first reading would refuse. On a subscription (codex ChatGPT login,Grok login) nothing is billed per call; `calls[].route` says which route each ran on.-`--mood` saves the first image, `--lettering` both. Beyond a check's second reading, nothing-is sent again on its own: a call that fails is not asked again, and a refusal is said and-the run ends.+`--mood` saves the first image, `--lettering` both. A refusal at the key step costs the mood+image (unless given with `--mood`) and its text check; the lettering is not bought. A+refusal at the matte step costs both images, and no logo text check. Beyond a check's+second reading, nothing is sent again on its own: a call that fails is not asked again, and+a refusal is said and the run ends.## Related