Skip to content

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

10.1 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Synthetic title lettering on a key background, with the ground truth it was made from.

No font is drawn: the "letters" are strokes and rings drawn with ImageDraw shapes, so the
fixture is the same on every machine. A glow is the letters' mask blurred and laid under
them in its own colour, which is how a lettering model paints one. The composite onto the
key is exact alpha blending, so the truth (coverage and colour of every pixel) is known.
"""

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass

import numpy as np
from PIL import Image, ImageDraw, ImageFilter

MAGENTA_PAINTED = (250, 6, 245)
GREEN_PAINTED = (8, 248, 12)


@dataclass
class Lettering:
    image: Image.Image  # the RGB picture a model would return: lettering on the key
    alpha: np.ndarray  # (H, W) true coverage 0..1
    colour: np.ndarray  # (H, W, 3) true colour where alpha > 0
    letters: np.ndarray  # (H, W) bool: inside a letter's solid body (eroded by 2 px)
    background: np.ndarray  # (H, W, 3) the key field the lettering was laid on


def _letter_mask(size: tuple[int, int], *, pixel: bool = False) -> Image.Image:
    """Three thick 'letters' (an I, an O ring and an L) as a soft or hard mask."""
    width, height = size
    scale = 4 if not pixel else 1
    mask = Image.new("L", (width * scale, height * scale), 0)
    draw = ImageDraw.Draw(mask)
    s = scale
    top, bottom = int(height * 0.32) * s, int(height * 0.68) * s
    stroke = max(4, int(height * 0.09)) * s
    left = int(width * 0.18) * s
    draw.rectangle((left, top, left + stroke, bottom), fill=255)
    cx, cy, r = int(width * 0.47) * s, (top + bottom) // 2, (bottom - top) // 2
    draw.ellipse((cx - r, cy - r, cx + r, cy + r), fill=255)
    draw.ellipse((cx - r + stroke, cy - r + stroke, cx + r - stroke, cy + r - stroke), fill=0)
    lx = int(width * 0.68) * s
    draw.rectangle((lx, top, lx + stroke, bottom), fill=255)
    draw.rectangle((lx, bottom - stroke, lx + stroke * 3, bottom), fill=255)
    if scale > 1:
        mask = mask.resize((width, height), Image.Resampling.LANCZOS)
    return mask


def hollow_letters(size: tuple[int, int], *, pixel: bool = False) -> Image.Image:
    """Two big 'letters' whose counters the key shows through, as a soft or hard mask: an O ring, and an A whose
    crossbar closes its counter and whose legs stand open below it."""
    width, height = size
    s = 4 if not pixel else 1
    mask = Image.new("L", (width * s, height * s), 0)
    draw = ImageDraw.Draw(mask)
    top, bottom = int(height * 0.12) * s, int(height * 0.88) * s
    tall = bottom - top
    stroke = max(4, int(height * 0.12)) * s
    cx, cy, r = int(width * 0.28) * s, (top + bottom) // 2, tall // 2
    draw.ellipse((cx - r, cy - r, cx + r, cy + r), fill=255)
    draw.ellipse((cx - r + stroke, cy - r + stroke, cx + r - stroke, cy + r - stroke), fill=0)
    ax, half = int(width * 0.72) * s, tall * 55 // 100
    draw.polygon([(ax, top), (ax + half, bottom), (ax - half, bottom)], fill=255)

    def leg(y: float, side: int) -> float:  # a leg's inner edge at row y: its outer edge moved a stroke inward
        return ax + side * (half * (y - top) / tall - stroke)

    apex, bar_top, bar_bottom = top + stroke * tall / half, top + tall * 55 // 100, top + tall * 70 // 100
    draw.polygon([(ax, apex), (leg(bar_top, 1), bar_top), (leg(bar_top, -1), bar_top)], fill=0)
    draw.polygon([(leg(bar_bottom, -1), bar_bottom), (leg(bar_bottom, 1), bar_bottom),
                  (leg(bottom + s, 1), bottom + s), (leg(bottom + s, -1), bottom + s)], fill=0)
    if s > 1:
        mask = mask.resize((width, height), Image.Resampling.LANCZOS)
    return mask


def lettering(
    *,
    size: tuple[int, int] = (320, 160),
    fill: tuple[int, int, int] = (250, 246, 236),
    outline: tuple[int, int, int] | None = None,
    glow: tuple[int, int, int] | None = (255, 255, 255),
    glow_radius: float = 9.0,
    glow_strength: float = 0.95,
    key: tuple[int, int, int] = MAGENTA_PAINTED,
    gradient: float = 0.0,
    noise: float = 2.0,
    pixel: bool = False,
    seed: int = 7,
    shapes: Callable[..., Image.Image] = _letter_mask,
) -> Lettering:
    width, height = size
    mask = np.asarray(shapes(size, pixel=pixel), dtype=np.float64) / 255.0
    body = mask
    colour = np.broadcast_to(np.array(fill, dtype=np.float64), (height, width, 3)).copy()
    if outline is not None:
        grown = np.asarray(shapes(size, pixel=pixel).filter(ImageFilter.MaxFilter(7)), dtype=np.float64) / 255.0
        inner = np.asarray(shapes(size, pixel=pixel).filter(ImageFilter.MinFilter(3)), dtype=np.float64) / 255.0
        body = grown
        # outline ink where the grown mask covers and the eroded fill does not
        colour = inner[..., None] * np.array(fill, dtype=np.float64) + (1 - inner[..., None]) * np.array(outline, dtype=np.float64)
    alpha_glow = np.zeros((height, width))
    if glow is not None:
        blurred = Image.fromarray(np.uint8(np.round(body * 255))).filter(ImageFilter.GaussianBlur(glow_radius))
        alpha_glow = np.asarray(blurred, dtype=np.float64) / 255.0 * glow_strength
    alpha = 1 - (1 - body) * (1 - alpha_glow)
    glow_rgb = np.array(glow if glow is not None else (0, 0, 0), dtype=np.float64)
    true_colour = np.where(alpha[..., None] > 0,
                           (body[..., None] * colour + (1 - body[..., None]) * alpha_glow[..., None] * glow_rgb)
                           / np.maximum(alpha[..., None], 1e-9), 0.0)
    yy, xx = np.mgrid[0:height, 0:width]
    vignette = gradient * (((xx / width - 0.5) ** 2 + (yy / height - 0.5) ** 2) / 0.5)
    background = np.clip(np.array(key, dtype=np.float64) - vignette[..., None] * np.array([1.0, -0.4, 1.0]), 0, 255)
    rng = np.random.default_rng(seed)
    observed = alpha[..., None] * true_colour + (1 - alpha[..., None]) * background
    observed = observed + rng.normal(0.0, noise, observed.shape)
    image = Image.fromarray(np.uint8(np.clip(np.round(observed), 0, 255)), "RGB")
    solid = np.asarray(Image.fromarray(np.uint8(body >= 0.999) * 255).filter(ImageFilter.MinFilter(5))) > 0
    return Lettering(image=image, alpha=alpha, colour=true_colour, letters=solid, background=background)


PINK, BUTTER, MINT, SKY = (240, 140, 200), (250, 230, 140), (150, 235, 190), (140, 200, 240)
PLUM = (90, 40, 80)
QUILT = (PINK, BUTTER, MINT, SKY)  # pink and plum are in magenta's hue, mint in green's


def quilt(*, size: tuple[int, int] = (320, 160), key: tuple[int, int, int] = GREEN_PAINTED,
          colours: tuple[tuple[int, int, int], ...] = QUILT, outline: tuple[int, int, int] = PLUM, noise: float = 2.0,
          patch: int = 14, seed: int = 7) -> tuple[Image.Image, np.ndarray]:
    """Patchwork pixel letters: three outlined blocks (the middle one with a counter the key shows through)
    filled with square fabric patches (pink, butter yellow, mint and sky blue in a plum outline), on a key.
    Returns (the RGB picture, the mint patches' mask)."""
    width, height = size
    rgb = np.broadcast_to(np.array(key, dtype=np.float64), (height, width, 3)).copy()
    mint = np.zeros((height, width), dtype=bool)
    top, bottom, wide, rim = int(height * 0.18), int(height * 0.82), int(width * 0.2), 4
    for number, left in enumerate((int(width * 0.08), int(width * 0.4), int(width * 0.72))):
        rgb[top:bottom, left:left + wide] = outline
        for row, y in enumerate(range(top + rim, bottom - rim, patch)):
            for column, x in enumerate(range(left + rim, left + wide - rim, patch)):
                y1, x1 = min(y + patch, bottom - rim), min(x + patch, left + wide - rim)
                colour = colours[(row + column + number) % len(colours)]
                rgb[y:y1, x:x1] = colour
                mint[y:y1, x:x1] = colour == MINT
        if number == 1:  # a counter, outlined, with the key showing through it
            cy, cx, half_h, half_w = (top + bottom) // 2, left + wide // 2, height // 8, wide // 6
            rgb[cy - half_h - rim:cy + half_h + rim, cx - half_w - rim:cx + half_w + rim] = outline
            rgb[cy - half_h:cy + half_h, cx - half_w:cx + half_w] = key
            mint[cy - half_h - rim:cy + half_h + rim, cx - half_w - rim:cx + half_w + rim] = False
    rgb += np.random.default_rng(seed).normal(0.0, noise, rgb.shape)
    return Image.fromarray(np.uint8(np.clip(np.round(rgb), 0, 255)), "RGB"), mint


NAVY, KEY_GREEN = (30, 34, 70), (0, 255, 0)


def walled_patch(*, patch: tuple[int, int, int, int] = (65, 135, 100, 220), holes: tuple[tuple[int, int, int], ...] = (),
                 opening: tuple[int, int] | None = None) -> Image.Image:
    """One navy letter block (rows 20-180, columns 20-300 of a 200x320 picture) on pure green, flat and without
    noise, with a mint patch walled in by it (`patch`: top, bottom, left, right), which the matte cuts see-through on
    green. `holes` (top, left, side) are squares of the key painted into the letter, which it cuts to nothing;
    `opening` (row, column) is one pixel of the key. The default patch is the end validator's counterexample."""
    rgb = np.full((200, 320, 3), KEY_GREEN, dtype=np.uint8)
    rgb[20:180, 20:300] = NAVY
    top, bottom, left, right = patch
    rgb[top:bottom, left:right] = MINT
    for y, x, side in holes:
        rgb[y:y + side, x:x + side] = KEY_GREEN
    if opening is not None:
        rgb[opening] = KEY_GREEN
    return Image.fromarray(rgb, "RGB")


def key_excess(rgb: np.ndarray, key: str = "magenta") -> np.ndarray:
    """How much of the key's hue a colour carries: min(R,B)-G for magenta, G-max(R,B) for green."""
    rgb = np.asarray(rgb, dtype=np.float64)
    if key == "magenta":
        return np.minimum(rgb[..., 0], rgb[..., 2]) - rgb[..., 1]
    return rgb[..., 1] - np.maximum(rgb[..., 0], rgb[..., 2])


def over(rgba: np.ndarray, backdrop: tuple[int, int, int]) -> np.ndarray:
    """An RGBA array composited over a flat backdrop, as float RGB."""
    rgba = np.asarray(rgba, dtype=np.float64)
    a = rgba[..., 3:4] / 255.0
    return a * rgba[..., :3] + (1 - a) * np.array(backdrop, dtype=np.float64)


def truth_over(item: Lettering, backdrop: tuple[int, int, int]) -> np.ndarray:
    a = item.alpha[..., None]
    return a * item.colour + (1 - a) * np.array(backdrop, dtype=np.float64)