Skip to content

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

3.4 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Subject profile — resolution-aware sparse-frame validation defaults.

The sparse-frame floor exists to catch empty frames and extraction debris.
"How many opaque pixels count as debris" is a property of the *subject*, not
of arithmetic: a character is expected to occupy more pixels than an effect,
but neither expectation is an absolute number independent of resolution.

`sprite-request.json` declares `"subject": "character" | "effect"`; no field
means character. The floor is derived from the cell geometry:

    equivalent_side = ceil(sqrt(width * height))
    character floor = equivalent_side
    effect floor    = ceil(equivalent_side / 2)

The geometric mean extends the same rule to rectangular cells without picking
one axis as truth. It deliberately uses the declared cell rather than safe
margins: integer margin rounding can grow by two pixels when a cell grows by
one, which would make a supposedly resolution-scaled floor decrease. Scaling a
cell by k scales the floor by k, not k². An explicit `--min-used-pixels` always
wins.
"""

from __future__ import annotations

from math import isqrt
from typing import Any

SUBJECT_DEFAULT = "character"
SUBJECTS = ("character", "effect")

# Multipliers over the cell's equivalent side. Effect is half the character
# floor at the formula level; integer ceilings can differ by 1.
SUBJECT_FLOOR_RATIOS = {"character": (1, 1), "effect": (1, 2)}


def subject_kind(request: dict[str, Any]) -> str:
    """The run's declared subject; absent field = character (legacy)."""
    kind = request.get("subject", SUBJECT_DEFAULT)
    if kind not in SUBJECTS:
        raise SystemExit(
            f"unknown subject kind: {kind!r} (expected one of {', '.join(SUBJECTS)})"
        )
    return kind


def cell_area(request: dict[str, Any]) -> int:
    """Declared cell area, validated without a silent clamp."""
    cell = request.get("cell")
    if not isinstance(cell, dict):
        raise SystemExit("sprite-request.json cell must be an object")
    width = int(cell.get("width", cell.get("size", 0)))
    height = int(cell.get("height", cell.get("size", 0)))
    if width <= 0 or height <= 0:
        raise SystemExit("sprite-request.json cell width/height must be positive")
    return width * height


def _ceil_ratio_sqrt(area: int, numerator: int, denominator: int) -> int:
    """Return ceil(numerator/denominator * sqrt(area)) with integer math."""
    scaled = area * numerator * numerator
    root = isqrt(scaled)
    if root * root < scaled:
        root += 1
    return (root + denominator - 1) // denominator


def default_min_used_pixels(request: dict[str, Any]) -> int:
    kind = subject_kind(request)
    numerator, denominator = SUBJECT_FLOOR_RATIOS[kind]
    return _ceil_ratio_sqrt(cell_area(request), numerator, denominator)


def sparse_frame_error(index: int, nontransparent: int, floor: int, kind: str) -> str:
    """Failure text that names the remedy — an unexplained rejection reads as a
    generation failure and gets the run abandoned (measured: 7 effect runs)."""
    remedy = (
        'small-subject run? declare "subject": "effect" in sprite-request.json, '
        "or pass --min-used-pixels"
        if kind == SUBJECT_DEFAULT
        else "pass --min-used-pixels if this frame is legitimate"
    )
    return (
        f"frame {index:02d} is empty or too sparse "
        f"({nontransparent} pixels < {floor}, {kind} profile floor — {remedy})"
    )