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.pyindex 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]) -> freturn 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.pyindex 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 alphaband 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.modehas_alpha = "A" in source.getbands()alpha = source.getchannel("A") if has_alpha else None- width, height = source.sizestats: 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.sizetotal = width * heightalpha_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_REALelse: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.pyindex 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 andno two frames are the same. A sprite's or icon's rows and heights are measured inside its safearea: 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 annotationsfrom 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 pixelsHEIGHT_SPREAD_MAX = 1WALK_CONTACT_RATIO_MIN = 0.4BODY_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_MINdef _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_cycif 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"]: