Skip to content

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

fix(logo): a key whose hue is one of the title's colours is not chosen (5 % of the title's box, 1 % when the style or scene names a colour of it) and a title in both keys' hues is refused at the key, before the lettering is bought; a named key in it is kept with a warning; a cut see-through inside its letters beyond the glow's reach, on 1 % of the visible lettering or more, is refused at the matte and kept aside before the text check

Soohong Kimdfd54bbd247a
diff --git a/sprite_gen/frames/logo_matte.py b/sprite_gen/frames/logo_matte.py
index 5692541..44fea3b 100644
--- a/sprite_gen/frames/logo_matte.py
+++ b/sprite_gen/frames/logo_matte.py
@@ -50,6 +50,11 @@ cast). A glow keeps the key's hue far longer on the key whose hue it shares more
a yellow glow on green, an orange one on magenta; a white glow on either): `--chroma-key`
picks it; the letters' own colours weigh more in that choice, since a letter in the key's
hue is lost entirely.
+
+The other side of it: a letter's own colour in the key's hue (mint on green) is, by its
+pixels, a mix with the key, and is cut see-through. `choose_key` keeps such a key off the
+lettering, and `see_through_inside` finds what was cut see-through inside the letters, where
+no glow reaches.
"""
from __future__ import annotations
@@ -59,7 +64,8 @@ from typing import Any
from PIL import Image
from sprite_gen._deps import np
-from sprite_gen.frames.decontam import _box_sum, learn_palette
+from sprite_gen.frames.decontam import _box_sum, _ring_depth, learn_palette
+from sprite_gen.frames.extract import _grow_into
KEYS: dict[str, tuple[int, int, int]] = {"magenta": (255, 0, 255), "green": (0, 255, 0)}
KEY_FAMILY_DIST = 64.0 # CbCr distance from the declared key that a background sample may sit at
@@ -97,6 +103,17 @@ PALETTE_MIN_PX = 32 # fewer solid pixels at a steep edge than this: no palette,
FAINT_FLOOR = 4.0 # the background model's own error (levels): a faint mean below it is not lettering
CHOICE_KEY_EXCESS = 240.0 # the key's own excess as a model paints it (#FF00FF a few levels off)
CHOICE_HUED_WEIGHT = 4.0 # a lettering pixel in the key's hue costs this much more than a glow held less long
+# A key whose hue is this share of the title's box in the mood image is one of the title's colours, and is not chosen
+# (a letter in the key's hue comes out see-through on it); when the brief names a colour of the key's hue, this smaller
+# share already is (the box holds scenery too: a word alone never rules a key out)
+CLASH_HUED_PCT = 5.0
+NAMED_CLASH_HUED_PCT = 1.0
+INSIDE_ALPHA8 = 240 # coverage under this is see-through (`see_through_inside`)
+INSIDE_CHANNEL_PX = 2 # a channel this narrow or narrower between see-through pixels and the background is no way out
+INSIDE_EDGE_PX = 2 # see-through this close to the opaque lettering is its antialiased rim
+INSIDE_REACH_QUANTILE = 0.99 # how far a glow reaches beside the letters: this quantile of its distance from them
+INSIDE_MAX_REACH_PX = 64
+INSIDE_MAX_PCT = 1.0 # see-through inside the letters on this share of the visible lettering is wide: refused
_LUMA = (0.299, 0.587, 0.114)
@@ -128,15 +145,18 @@ def _check_key(key: str) -> tuple[int, int, int]:
return KEYS[key]
-def choose_key(mood: Image.Image, box: list[float] | None = None) -> dict[str, Any]:
+def choose_key(mood: Image.Image, box: list[float] | None = None,
+ named: dict[str, list[str]] | None = None) -> dict[str, Any]:
"""The key the lettering is redrawn on, from the colours of the mood image's lettering (`box`: left,
top, right, bottom as shares of the image, where the text check found the title; the whole image
- without one).
-
- The lettering keeps those colours on the key. A letter in the key's own hue is lost to it, so the
- share of key-hued pixels counts hard against a key; and a glow's mix with the key keeps the key's
- hue (and so its fade) up to a coverage that depends on the pair (`hold`): the key that keeps more
- of it wins. Magenta on a tie: it is the engine's default key."""
+ without one), or None when the title's colours carry both keys' hues.
+
+ The lettering keeps those colours on the key. A letter in the key's own hue is lost to it: a key
+ whose hue is CLASH_HUED_PCT of the box is one of the title's colours and is not chosen, and one the
+ brief names a colour of (`named`: the words, per key) already at NAMED_CLASH_HUED_PCT. Between the
+ keys left, the share of key-hued pixels counts hard against a key, and a glow's mix with the key
+ keeps the key's hue (and so its fade) up to a coverage that depends on the pair (`hold`): the key
+ that keeps more of it wins. Magenta on a tie: it is the engine's default key."""
rgb = np.asarray(mood.convert("RGB"), dtype=np.float64)
region = "image"
if box is not None:
@@ -152,9 +172,13 @@ def choose_key(mood: Image.Image, box: list[float] | None = None) -> dict[str, A
hold = np.where(excess < KEY_HUE_TOL,
np.clip((CHOICE_KEY_EXCESS - KEY_HUE_TOL) / np.maximum(CHOICE_KEY_EXCESS - excess, 1e-9), 0, 1),
0.0)
+ words = list((named or {}).get(key, []))
+ clash_at = NAMED_CLASH_HUED_PCT if words else CLASH_HUED_PCT
scores[key] = {"hued_pct": round(hued * 100, 2), "hold": round(float(hold.mean()), 4),
- "score": round(float(hold.mean()) - CHOICE_HUED_WEIGHT * hued, 4)}
- key = "green" if scores["green"]["score"] > scores["magenta"]["score"] else "magenta"
+ "score": round(float(hold.mean()) - CHOICE_HUED_WEIGHT * hued, 4), "named": words,
+ "clash_at_pct": clash_at, "clashes": hued * 100 >= clash_at}
+ left = [key for key in KEYS if not scores[key]["clashes"]]
+ key = max(left, key=lambda k: (scores[k]["score"], k == "magenta")) if left else None
return {"key": key, "region": region, "scores": scores}
@@ -469,6 +493,32 @@ def key_hue_left(image: Image.Image, key: str) -> dict[str, Any]:
return {"px": int(hued.sum()), "pct_of_visible": round(float(hued.sum()) / max(int(seen.sum()), 1) * 100, 3)}
+def see_through_inside(image: Image.Image) -> dict[str, Any]:
+ """See-through pixels inside the letters (coverage under INSIDE_ALPHA8): walled in by opaque lettering — no way
+ out to a transparent pixel but across opaque ones, a channel of INSIDE_CHANNEL_PX or less not counting as a way
+ out — and farther from the opaque lettering than its glow reaches beside it (`glow_reach_px`: the
+ INSIDE_REACH_QUANTILE of how far the see-through pixels with a way out lie from it, at least INSIDE_EDGE_PX for
+ a letter's antialiased rim). A glow fades out beside the letters and pools in a counter no farther than it
+ reaches there; a letter's own colour in the key's hue, cut as a mix with the key, is see-through inside the
+ letter. `wide` when that is INSIDE_MAX_PCT of the visible lettering or more."""
+ alpha = np.asarray(image.convert("RGBA"))[..., 3]
+ transparent = alpha == 0
+ not_opaque = alpha < 255
+ see = ~transparent & (alpha < INSIDE_ALPHA8)
+ r = INSIDE_CHANNEL_PX // 2 # a pixel of a wider channel has its whole (2r+1)^2 window in the channel
+ wide = not_opaque & (_box_sum(not_opaque.astype(np.float64), r) >= (2 * r + 1) ** 2)
+ way_out = _grow_into(transparent, wide | transparent)
+ way_out |= not_opaque & (_box_sum(way_out.astype(np.float64), INSIDE_CHANNEL_PX) > 0)
+ depth = _ring_depth(alpha == 255, INSIDE_MAX_REACH_PX)
+ beside = depth[see & way_out]
+ reach = max(INSIDE_EDGE_PX, int(np.quantile(beside, INSIDE_REACH_QUANTILE)) if len(beside) else 0)
+ inside = see & ~way_out & (depth > reach)
+ visible = int((~transparent).sum())
+ share = float(inside.sum()) / max(visible, 1) * 100
+ return {"px": int(inside.sum()), "pct_of_visible": round(share, 2), "glow_reach_px": reach,
+ "max_pct": INSIDE_MAX_PCT, "wide": share >= INSIDE_MAX_PCT}
+
+
def preview(image: Image.Image, *, dark: tuple[int, int, int] = (22, 24, 32),
light: tuple[int, int, int] = (238, 236, 230), pad: int = 24) -> Image.Image:
"""The logo on a dark and on a light backdrop, side by side: where a halo or a hard edge shows."""
diff --git a/sprite_gen/gen/logo.py b/sprite_gen/gen/logo.py
index c521610..22cde45 100644
--- a/sprite_gen/gen/logo.py
+++ b/sprite_gen/gen/logo.py
@@ -11,11 +11,13 @@ materials and light. So a logo is made in three steps:
2. **lettering** — that picture as the reference of an edit asking for only its lettering,
the same letterforms, materials and effects, on a flat chroma key (`gen --ref`). The key
is chosen from the title's colours in the mood image (the box its text check finds) unless
- `--chroma-key` names one.
+ `--chroma-key` names one: never a key whose hue is one of the title's colours, and a title
+ in both keys' hues is refused here, before the lettering is bought.
3. **matte** — the key removed by the logo matte (`frames.logo_matte`: soft glows and partial
- alpha kept, no key hue left), trimmed to the lettering. The logo's text is read again on a
- plain backdrop; letters that differ from the text asked are refused and the cut is kept
- aside as `logo.rejected.png`.
+ alpha kept, no key hue left), trimmed to the lettering. A cut see-through inside its
+ letters (a colour of theirs in the key's hue, cut as a mix with it) is refused. The logo's
+ text is read again on a plain backdrop; letters that differ from the text asked are refused.
+ A refused cut is kept aside as `logo.rejected.png`.
Nothing in this path draws a font. A step that cannot be done fails; it is never replaced.
Every call is listed in the report with the route it ran on (a subscription login, or a
@@ -67,6 +69,13 @@ MOOD_READ_PROMPT = READ_PROMPT[:-1] + (
"of the image's width or height from 0 to 1."
)
REFUSED = ("mismatch", "no-text") # the verdicts a text check refuses on
+# Colour words a brief may name, per key whose hue the colour is (`logo_matte.key_hued` of its usual value; teal, cyan
+# and lavender are not): a colour the style or scene names is looked for in the title's box at a smaller share
+# (`logo_matte.choose_key`).
+KEY_COLOUR_WORDS = {
+ "green": ("green", "mint", "lime", "emerald", "jade", "chartreuse"),
+ "magenta": ("magenta", "fuchsia", "pink", "purple", "violet", "plum", "orchid"),
+}
# How many readings one text check may take: a reading that would refuse is read again, up to this many, and one
# that spells the text passes (docs/logo.md, the text check).
MAX_READS = 2
@@ -194,6 +203,17 @@ def parse_answer(answer: str) -> tuple[list[str] | None, list[float] | None]:
return lines, [float(v) for v in box] if box else None
+def named_colours(*texts: str | None) -> dict[str, list[str]]:
+ """The colour words of each key's hue the brief names (`KEY_COLOUR_WORDS`, a plural or an -ish or -y
+ ending kept), in the order written."""
+ brief = " ".join(text for text in texts if text)
+ found = {}
+ for key, words in KEY_COLOUR_WORDS.items():
+ pattern = re.compile(rf"\b(?:{'|'.join(words)})(?:e?s|ish|y)?\b", re.IGNORECASE)
+ found[key] = list(dict.fromkeys(match.group(0).lower() for match in pattern.finditer(brief)))
+ return found
+
+
def route_of(auth_source: str | None) -> str:
"""Which way a call was paid: on a subscription login, or a per-call API charge."""
if auth_source in SUBSCRIPTION_AUTH:
@@ -250,6 +270,18 @@ def _reads(check: dict[str, Any]) -> str:
return " and then ".join(repr(reading["read"]) for reading in check["readings"] if "read" in reading)
+def _in_hue(choice: dict[str, Any], *keys: str) -> str:
+ """Where the key was chosen and how much of it is in each key's hue, with the brief's words for it: "the
+ title's box in the mood image is 8.0 % green-hued (the brief names mint)"."""
+ where = "the title's box in the mood image" if choice["region"] == "lettering-box" else "the mood image"
+ shares = []
+ for key in keys:
+ score = choice["scores"][key]
+ named = f" (the brief names {', '.join(score['named'])})" if score["named"] else ""
+ shares.append(f"{score['hued_pct']:.1f} % {key}-hued{named}")
+ return f"{where} is {' and '.join(shares)}"
+
+
def _call(step: str, provider: str, details: dict[str, Any], elapsed: float | None = None) -> dict[str, Any]:
auth = details.get("auth_source")
entry = {"step": step, "provider": provider, "model": details.get("model"), "auth_source": auth,
@@ -416,9 +448,18 @@ def _draw_lettering(provider: str, backend, report: dict[str, Any], files: dict[
# 2. lettering
with Image.open(files["mood.png"]) as mood_image:
- choice = logo_matte.choose_key(mood_image, check.get("box"))
+ choice = logo_matte.choose_key(mood_image, check.get("box"), named_colours(style, scene))
key = choice["key"] if chroma_key == "auto" else chroma_key
report["steps"]["key"] = {**choice, "key": key, "source": "auto" if chroma_key == "auto" else "explicit"}
+ if key is None:
+ raise _Refusal("key", f"logo: the title's colours carry both keys' hues — "
+ f"{_in_hue(choice, 'green', 'magenta')}; a letter in the key's hue comes out see-through on "
+ "it, and there is no third key. Restyle the title without one of them, or name the key to lose "
+ f"with --chroma-key (--mood {files['mood.png']} skips the mood image; the lettering was not "
+ "bought)")
+ if chroma_key != "auto" and choice["scores"][key]["clashes"]:
+ warn(f"the {key} key named is one of the title's colours ({_in_hue(choice, key)}): its letters in that hue "
+ "come out see-through")
prompt = lettering_prompt(text, subtitle=subtitle, composition=composition, language=language, key=key)
result = gen_pkg.generate_image(provider, prompt, work / "lettering.png", refs=[files["mood.png"]],
model=model, aspect_ratio=ratio, quality=quality, resolution=resolution,
@@ -450,13 +491,24 @@ def _cut(files: dict[str, Path], report: dict[str, Any], work: Path, backend, ra
report["steps"]["matte"] = stats
report["steps"]["trim"] = trim_stats
cover = logo_matte.coverage(logo)
- report["logo"] = {"size": list(logo.size), "alpha": cover, "key_hue_left": logo_matte.key_hue_left(logo, key)}
+ inside = logo_matte.see_through_inside(logo)
+ report["logo"] = {"size": list(logo.size), "alpha": cover, "key_hue_left": logo_matte.key_hue_left(logo, key),
+ "see_through_inside": inside}
+ other = "green" if key == "magenta" else "magenta"
if cover["visible_opaque_share"] < logo_matte.SEE_THROUGH_WARN_SHARE:
- other = "green" if key == "magenta" else "magenta"
warn(f"only {cover['visible_opaque_share'] * 100:.0f}% of the visible lettering is opaque; if the letters "
f"are drawn in the {key} key's colour, run again with --chroma-key {other}")
_publish(logo_matte.preview(logo), files["logo.preview.png"])
report["files"]["preview"] = str(files["logo.preview.png"])
+ if inside["wide"] and stats["method"] == "logo-unmix":
+ _publish(logo, files["logo.rejected.png"])
+ report["files"]["rejected"] = str(files["logo.rejected.png"])
+ again = f" --mood {files['mood.png']}" if files["mood.png"].is_file() else ""
+ raise _Refusal("matte", f"logo: the logo is see-through inside its letters ({inside['pct_of_visible']:.1f} % "
+ "of the visible lettering, walled in by opaque letters) — a colour of the letters is in the "
+ f"{key} key's hue and was cut as a mix with it; kept aside as {files['logo.rejected.png'].name} "
+ f"(see {files['logo.preview.png'].name}). Generate the lettering again on the other key "
+ f"(--chroma-key {other}{again}), or restyle the title without that colour")
reading = work / "logo-read.png"
_publish(logo_matte.reading_backdrop(logo), reading)
check, calls = read_text(backend, reading, work, text, subtitle)
@@ -506,8 +558,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
"again: nothing is generated (its text is still read)")
parser.add_argument("--chroma-key", choices=KEY_CHOICES, default="auto",
help="the key the lettering is redrawn on; auto (default) picks it from the title's colours "
- "in the mood image (the box its text check finds): the key no letter shares and a glow "
- "keeps the hue of longest. With --lettering, auto reads the key off its border")
+ "in the mood image (the box its text check finds): never a key whose hue is one of the "
+ "title's colours (a title in both is refused before the lettering is bought), else the "
+ "key a glow keeps the hue of longest. With --lettering, auto reads the key off its border")
parser.add_argument("--provider", choices=gen_pkg.PROVIDERS, default=None,
help="generation backend for both images and both text checks; resolved as `gen` resolves "
"it (openai only when chosen: it bills per call)")
diff --git a/tests/frames/test_logo_matte.py b/tests/frames/test_logo_matte.py
index e0c852d..dddefc9 100644
--- a/tests/frames/test_logo_matte.py
+++ b/tests/frames/test_logo_matte.py
@@ -13,7 +13,8 @@ import numpy as np
import pytest
from PIL import Image, ImageFilter
-from logo_lettering import BUTTER, GREEN_PAINTED, MAGENTA_PAINTED, MINT, SKY, key_excess, lettering, over, quilt, truth_over
+from logo_lettering import (BUTTER, GREEN_PAINTED, MAGENTA_PAINTED, MINT, SKY, key_excess, lettering, over, quilt,
+ truth_over)
from sprite_gen.frames import logo_matte