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(pixel-draw): G3, G4 and G5 ask the judgments sprite-gen already makes instead of their own - G3 the transparent-background verdict lifted unchanged out of classify_raw_alpha (alpha_verdict: a sprite or icon frame real-alpha, a tile no-alpha), G4 background-tile's join measure along x and y (inspect_tile; needs-review warns with its reasons), G5 the lone pixels lifted unchanged out of the YCbCr matte cleanup (isolated_dots: eight neighbours, so a diagonal stroke is joined); colors_used is the one list of a grid's colours

Soohong Kimd2a72e77a026
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.py
index 67186f6..ceb7af5 100644
--- a/sprite_gen/frames/extract.py
+++ b/sprite_gen/frames/extract.py
@@ -1000,21 +1000,13 @@ def key_residue_fraction_ycc(image: Image.Image, key: tuple[int, int, int]) -> f
return count / (width * height)
-def _cleanup_alpha_ycc(image: Image.Image) -> None:
- """Remove fully isolated opaque dots and fill nearly-enclosed pinholes.
-
- Decisions are made on an alpha snapshot so the pass cannot cascade; soft
- matte edges are untouched (only 0-neighbor dots and ≥7-neighbor holes).
- """
- width, height = image.size
- if width < 3 or height < 3:
- return
+def _neighbour_code(op: Image.Image) -> Image.Image:
+ """`op` (1 where opaque, 0 elsewhere) as one code per pixel: op*16 plus how many of its eight
+ neighbours are opaque (outside the image counts as clear)."""
+ width, height = op.size
# PIL 네이티브 스텐실 — 8이웃 불투명 카운트를 시프트-합으로 벡터화한다 (핫스팟:
# 상태당 추출의 ~17%, 1280×720 전체 순회). 정수 논리(임계 비교·이웃 카운트)라
# 픽셀 루프와 **바이트 동일**하며, numpy 없이 pillow 만으로 된다.
- alpha = image.getchannel("A")
- # op: 불투명 마스크 (0/1) — before 스냅샷과 같은 기준 (> EMPTY).
- op = alpha.point(lambda a: 1 if a > _YCC_ALPHA_EMPTY else 0)
# 1px zero-pad 후 8방향 크롭으로 이웃을 꺼내 합산 (경계 밖 = 0, 정수 덧셈은 순서 무관).
padded = Image.new("L", (width + 2, height + 2), 0)
padded.paste(op, (1, 1))
@@ -1023,9 +1015,37 @@ def _cleanup_alpha_ycc(image: Image.Image) -> None:
(-1, -1), (1, -1), (-1, 1), (1, 1)):
shifted = padded.crop((1 + dx, 1 + dy, 1 + dx + width, 1 + dy + height))
neighbors = shifted if neighbors is None else ImageChops.add(neighbors, shifted)
- # combined = op*16 + neighbors (둘 다 작아 24 이하) → 단일 LUT 로 두 마스크 분리.
- combined = ImageChops.add(op.point(lambda v: v * 16), neighbors)
- clear_mask = combined.point(lambda v: 255 if (v >> 4) == 1 and (v & 15) == 0 else 0)
+ # combined = op*16 + neighbors (둘 다 작아 24 이하) → 단일 LUT 로 마스크를 분리한다.
+ return ImageChops.add(op.point(lambda v: v * 16), neighbors)
+
+
+def _dots(code: Image.Image) -> Image.Image:
+ return code.point(lambda v: 255 if (v >> 4) == 1 and (v & 15) == 0 else 0)
+
+
+def isolated_dots(op: Image.Image) -> Image.Image:
+ """The lone pixels of `op` (an L mask, 1 where opaque): 255 where a pixel is opaque and none of
+ its eight neighbours is — one touching another only at a corner is joined to it. One judgment:
+ the YCbCr matte's cleanup erases a matte's dots by it (`_cleanup_alpha_ycc`), and `pixel-draw`'s
+ G5 counts a grid's stray pixels by it."""
+ return _dots(_neighbour_code(op))
+
+
+def _cleanup_alpha_ycc(image: Image.Image) -> None:
+ """Remove fully isolated opaque dots and fill nearly-enclosed pinholes.
+
+ Decisions are made on an alpha snapshot so the pass cannot cascade; soft
+ matte edges are untouched (only 0-neighbor dots — `isolated_dots` — and
+ ≥7-neighbor holes).
+ """
+ width, height = image.size
+ if width < 3 or height < 3:
+ return
+ alpha = image.getchannel("A")
+ # op: 불투명 마스크 (0/1) — before 스냅샷과 같은 기준 (> EMPTY).
+ op = alpha.point(lambda a: 1 if a > _YCC_ALPHA_EMPTY else 0)
+ combined = _neighbour_code(op)
+ clear_mask = _dots(combined)
fill_mask = combined.point(lambda v: 255 if (v >> 4) == 0 and (v & 15) >= 7 else 0)
# 원본은 알파만 바꾼다 (RGB 불변) — 스냅샷에서 시작해 두 disjoint 마스크만 덮어쓴다.
new_alpha = alpha.copy()
diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.py
index 21af241..fb3f971 100644
--- a/sprite_gen/gen/chroma.py
+++ b/sprite_gen/gen/chroma.py
@@ -83,15 +83,24 @@ def classify_raw_alpha(path: Path) -> dict[str, Any]:
when it has no alpha band or no alpha-0 pixel (a checkerboard, a key background,
an opaque RGBA); `ambiguous` for alpha-0 pixels that miss either bar. The alpha
band is the one `verify_native_alpha` reads, so a `real-alpha` raw is one it accepts.
+ The judgment of the band is `alpha_verdict`.
"""
with Image.open(path) as source:
mode = source.mode
has_alpha = "A" in source.getbands()
alpha = source.getchannel("A") if has_alpha else None
- width, height = source.size
stats: dict[str, Any] = {"mode": mode, "has_alpha_band": has_alpha}
if alpha is None:
return {**stats, "verdict": RAW_ALPHA_NONE, "alpha_zero_pct": 0.0, "border_alpha_zero_pct": 0.0}
+ return {**stats, **alpha_verdict(alpha)}
+
+
+def alpha_verdict(alpha: Image.Image) -> dict[str, Any]:
+ """Whether an alpha band is a real transparent background: `verdict` `real-alpha`,
+ `no-alpha` or `ambiguous` by the bars `classify_raw_alpha` names, with the two
+ shares it judged by. One judgment: `classify_raw_alpha` asks it of a generated raw,
+ and `pixel-draw`'s G3 of each frame it drew (docs/gen.md)."""
+ width, height = alpha.size
total = width * height
alpha_zero = alpha.histogram()[0]
edges = [(0, 0, width, 1), (0, height - 1, width, height),
@@ -108,7 +117,7 @@ def classify_raw_alpha(path: Path) -> dict[str, Any]:
verdict = RAW_ALPHA_REAL
else:
verdict = RAW_ALPHA_AMBIGUOUS
- return {**stats, "verdict": verdict, "alpha_zero_pct": round(alpha_zero_pct, 2),
+ return {"verdict": verdict, "alpha_zero_pct": round(alpha_zero_pct, 2),
"border_alpha_zero_pct": round(border_alpha_zero_pct, 2)}
diff --git a/sprite_gen/gen/pixel_gates.py b/sprite_gen/gen/pixel_gates.py
index c606002..1200c85 100644
--- a/sprite_gen/gen/pixel_gates.py
+++ b/sprite_gen/gen/pixel_gates.py
@@ -1,14 +1,23 @@
# SPDX-License-Identifier: Apache-2.0
"""Gates G2..G6 and G8 of `pixel-draw`, on the pixels of a grid that passed G1 (it parsed whole).
-- G2 palette: the opaque colours used are at most the rule's limit; a fixed palette allows only its
- own colours.
-- G3 alpha: a sprite or icon frame has opaque pixels, four transparent corners and a border at
- least half transparent; a tile frame is opaque everywhere.
-- G4 tile seam (warning): the colour step across the wrap edges over the mean step between
- neighbours inside the tile, at most 1.5. Mortar lines that meet the edge raise it on tiles that
- repeat cleanly, so it warns and never fails until the measure is refined.
-- G5 stray pixels (warning): opaque pixels of a sprite or icon with no opaque 4-neighbour.
+G3, G4, G5 and G8 ask the judgment sprite-gen already makes of the same question elsewhere — one
+function each, called here, never a copy (docs/pixel-draw.md "Gates"):
+
+- G2 palette: the opaque colours used (`colors_used`, also `palette.json`'s) are at most the rule's
+ limit; a fixed palette allows only its own colours.
+- G3 alpha: whether a frame's background is really transparent is `gen.chroma.alpha_verdict`, the
+ judgment `gen` reads a generated raw by — `real-alpha` at least 5 % of the pixels and half the
+ one-pixel border alpha 0, `no-alpha` none. A sprite or icon frame is `real-alpha` with something
+ drawn and its four corners clear; a tile frame is `no-alpha`.
+- G4 tile seam (warning): `background.tile.inspect_tile`, the join `background-tile` measures —
+ the wrap edge against the tile's own neighbours — asked of each tile frame along x and along y.
+ An axis it says needs review warns: a local measure, never proof that a tile repeats cleanly, so
+ look at `tiled-3x3.png`.
+- G5 stray pixels (warning): the lone pixels of a sprite or icon, `frames.extract.isolated_dots` —
+ opaque, with no opaque pixel among their eight neighbours, the dots the YCbCr matte cleanup
+ erases. A pixel that touches another only at a corner, as each pixel of a diagonal stroke does,
+ is joined to it.
- G6 frames: every frame stands on the same bottom row, heights differ by at most one pixel and
no two frames are the same. A sprite's or icon's rows and heights are measured inside its safe
area: a staff raised or a spark into the margin in one frame is not a taller figure (G8 notes
@@ -33,10 +42,9 @@ from __future__ import annotations
from typing import Any, Sequence
-from .pixel_grid import Pixel, PaletteRule
+from .pixel_grid import Pixel, PaletteRule, image_of
-SEAM_RATIO_MAX = 1.5
-BORDER_TRANSPARENT_MIN = 0.5
+OPAQUE_MIN = 128 # the alpha at which a pixel is solid, as the engine reads solid pixels
HEIGHT_SPREAD_MAX = 1
WALK_CONTACT_RATIO_MIN = 0.4
BODY_LINE_SHARE = 0.25
@@ -45,77 +53,78 @@ Frame = Sequence[Sequence[Pixel]]
def _opaque(pixel: Pixel) -> bool:
- return pixel[3] >= 128
+ return pixel[3] >= OPAQUE_MIN
def _hex(pixel: Pixel) -> str:
return "#{:02X}{:02X}{:02X}".format(*pixel[:3])
+def colors_used(frames: dict[str, Frame]) -> list[str]:
+ """The opaque colours of the frames, `#RRGGBB`, sorted: what G2 counts and `palette.json` lists."""
+ return sorted({_hex(p) for frame in frames.values() for row in frame for p in row if _opaque(p)})
+
+
def g2_palette(frames: dict[str, Frame], rule: PaletteRule) -> dict[str, Any]:
- used = sorted({_hex(p) for frame in frames.values() for row in frame for p in row if _opaque(p)})
+ used = colors_used(frames)
off = [c for c in used if rule.fixed and c not in rule.colors]
return {"ok": len(used) <= rule.limit and not off, "colors_used": len(used), "limit": rule.limit,
"palette": rule.name, "off_palette": off}
def _frame_alpha(frame: Frame) -> dict[str, Any]:
+ # Imported here: the judgment is `gen`'s, made in one place (`chroma` pulls in the matte).
+ from .chroma import alpha_verdict
+
height, width = len(frame), len(frame[0])
opaque = sum(1 for row in frame for p in row if _opaque(p))
- border = [frame[y][x] for y in range(height) for x in range(width) if x in (0, width - 1) or y in (0, height - 1)]
corners = (frame[0][0], frame[0][width - 1], frame[height - 1][0], frame[height - 1][width - 1])
return {
"opaque_pixels": opaque,
"opaque_fraction": round(opaque / (width * height), 4),
"corners_transparent": not any(_opaque(p) for p in corners),
- "border_transparent_fraction": round(sum(1 for p in border if not _opaque(p)) / len(border), 4),
+ **alpha_verdict(image_of(frame).getchannel("A")),
}
def g3_alpha(frames: dict[str, Frame], kind: str) -> dict[str, Any]:
+ from .chroma import RAW_ALPHA_NONE, RAW_ALPHA_REAL
+
per = {name: _frame_alpha(frame) for name, frame in frames.items()}
if kind == "tile":
- ok = all(m["opaque_fraction"] == 1.0 for m in per.values())
+ ok = all(m["verdict"] == RAW_ALPHA_NONE for m in per.values())
else:
- ok = all(m["opaque_pixels"] > 0 and m["corners_transparent"]
- and m["border_transparent_fraction"] >= BORDER_TRANSPARENT_MIN for m in per.values())
+ ok = all(m["opaque_pixels"] > 0 and m["corners_transparent"] and m["verdict"] == RAW_ALPHA_REAL
+ for m in per.values())
return {"ok": ok, "kind": kind, "frames": per}
-def _step(a: Pixel, b: Pixel) -> float:
- return sum(abs(a[i] - b[i]) for i in range(3)) / 3
+def g4_seam(frames: dict[str, Frame]) -> dict[str, Any]:
+ # Imported here: the measure is `background-tile`'s, made in one place.
+ from sprite_gen.background.tile import inspect_tile
+
+ per = {name: {axis: inspect_tile(image_of(frame), axis) for axis in ("x", "y")} for name, frame in frames.items()}
+ review = _needs_review(per)
+ return {"warn": bool(review), "needs_review": list(review), "frames": per}
-def seam_ratio(frame: Frame) -> float:
- height, width = len(frame), len(frame[0])
- inner = [_step(frame[y][x], frame[y][x + 1]) for y in range(height) for x in range(width - 1)]
- inner += [_step(frame[y][x], frame[y + 1][x]) for y in range(height - 1) for x in range(width)]
- wrap = [_step(frame[y][width - 1], frame[y][0]) for y in range(height)]
- wrap += [_step(frame[height - 1][x], frame[0][x]) for x in range(width)]
- inner_mean = sum(inner) / max(1, len(inner))
- wrap_mean = sum(wrap) / max(1, len(wrap))
- if inner_mean == 0:
- return 0.0 if wrap_mean == 0 else 99.0
- return round(wrap_mean / inner_mean, 3)
+def _needs_review(per: dict[str, dict[str, dict[str, Any]]]) -> dict[str, list[str]]:
+ """`<frame> <axis>` of every join `inspect_tile` did not pass, with the reasons it gave."""
+ return {f"{name} {axis}": report["review_reasons"] for name, axes in per.items() for axis, report in axes.items()
+ if report["status"] != "pass"}
-def g4_seam(frames: dict[str, Frame]) -> dict[str, Any]:
- ratios = {name: seam_ratio(frame) for name, frame in frames.items()}
- worst = max(ratios.values())
- return {"warn": worst > SEAM_RATIO_MAX, "seam_ratio": worst, "max": SEAM_RATIO_MAX, "frames": ratios}
+def _g4_line(g4: dict[str, Any]) -> str:
+ said = "; ".join(f"{where}: {' '.join(reasons)}" for where, reasons in _needs_review(g4["frames"]).items())
+ return f"G4 tile seam (look at tiled-3x3.png): {said}"
def isolated_pixels(frame: Frame) -> int:
- height, width = len(frame), len(frame[0])
- count = 0
- for y in range(height):
- for x in range(width):
- if not _opaque(frame[y][x]):
- continue
- neighbours = ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1))
- if not any(0 <= nx < width and 0 <= ny < height and _opaque(frame[ny][nx]) for nx, ny in neighbours):
- count += 1
- return count
+ # Imported here: the judgment is the matte cleanup's, made in one place.
+ from sprite_gen.frames.extract import isolated_dots
+
+ opaque = image_of(frame).getchannel("A").point(lambda a: 1 if a >= OPAQUE_MIN else 0)
+ return isolated_dots(opaque).histogram()[255]
def g5_isolated(frames: dict[str, Frame]) -> dict[str, Any]:
@@ -245,8 +254,7 @@ def evaluate(frames: dict[str, Frame], *, kind: str, rule: PaletteRule, walk_cyc
if kind == "tile":
gates["G4"] = g4_seam(frames)
if gates["G4"]["warn"]:
- warnings.append(f"G4 tile seam ratio {gates['G4']['seam_ratio']} > {SEAM_RATIO_MAX} "
- "(look at tiled-3x3.png: mortar lines on the edge raise it on tiles that repeat cleanly)")
+ warnings.append(_g4_line(gates["G4"]))
else:
gates["G5"] = g5_isolated(frames)
if gates["G5"]["warn"]: