Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix: honor vertical centering in pixel-unfake rows
Soohong Kim72a2bf163c84
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4e2e12b..242846e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## v1.59.0 - Contributor Collection-This release incorporates accepted work from seven community pull requests. Thanks to [@devswha](https://github.com/devswha) for chroma color preservation, [@bokjk](https://github.com/bokjk) for portable manifest paths, [@Dongkyu-ES](https://github.com/Dongkyu-ES) for deterministic CLI tests, engine export, and subject-aware sparse-frame handling, and [@napkn34](https://github.com/napkn34) for the Windows provider and publish-lock fixes.+This release incorporates accepted work from eight community pull requests. Thanks to [@devswha](https://github.com/devswha) for chroma color preservation, [@bokjk](https://github.com/bokjk) for portable manifest paths, [@Dongkyu-ES](https://github.com/Dongkyu-ES) for deterministic CLI tests, engine export, and subject-aware sparse-frame handling, [@napkn34](https://github.com/napkn34) for the Windows provider and publish-lock fixes, and [@monibu1548](https://github.com/monibu1548) for pixel-unfake vertical centering and grounding controls.- Added `sprite-gen export-aseprite` for Phaser-compatible Aseprite JSON and Flame-compatible hash files split by state. Curated frame geometry and timing remain canonical, and exports are confined to the run's `exports/` directory.- Added a Windows `LockFileEx` backend that preserves shared readers and exclusive publishers across processes without weakening the fail-loud isolation contract.diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.mdindex 47b8a82..cae47f6 100644--- a/CONTRIBUTORS.md+++ b/CONTRIBUTORS.md@@ -21,4 +21,8 @@ The following external contributors have changes incorporated into the current `- [PR #7](https://github.com/aldegad/sprite-gen/pull/7): fixed Windows provider CLI resolution and UTF-8 subprocess I/O.- [PR #9](https://github.com/aldegad/sprite-gen/pull/9): added the Windows `LockFileEx` backend for shared readers and exclusive publishers.+## [@monibu1548](https://github.com/monibu1548)++- [PR #11](https://github.com/aldegad/sprite-gen/pull/11): made vertical centering work in the pixel-unfake row-placement path and exposed per-frame vertical grounding through the CLI.+Thank you for testing the project in real environments, documenting the failures clearly, and contributing fixes that now ship as part of `sprite-gen`.diff --git a/docs/pixel-unfake.md b/docs/pixel-unfake.mdindex ab14065..a29e5dc 100644--- a/docs/pixel-unfake.md+++ b/docs/pixel-unfake.md@@ -14,7 +14,7 @@ Optional `fit` object (opt-in; absent means legacy behavior). For pixel-art targ- `align_x` — `bbox-center` | `centroid` | `foot-centroid` (default) | `alpha-centroid`. Bbox-centering shifts the body left/right whenever a pose's content bbox width changes (extended arm/leg), which reads as per-frame horizontal jitter. `centroid` aligns the whole-alpha centroid; `foot-centroid` aligns the bottom-20% alpha (the legs), so trailing hair/capes do not pull the body off the cell axis — use it when the runtime mirrors the cell for left/right facing (flip pivots on the leg axis instead of teleporting the body). `alpha-centroid` (opt-in, perfectpixel-studio port — github.com/gykim80/perfectpixel-studio `internal/sprite/extract.go`, MIT) aligns the alpha-weighted centroid ignoring soft-matte fringe (α ≤ 10); crucially, in the `pixel_unfake` row path it is applied **per frame** instead of once per row union, so residual registration jitter from `register_row_frames` is cancelled (upstream measured σ 27.2px → 0.2px; jump arcs stay preserved via `ground_frames: false`).- `align_y` — `center` (default) | `bottom`. Bottom pins feet to a shared baseline (`cell_height - safe_margin_y`).-`prepare_sprite_run.py` exposes these as `--fit-resample`, `--fit-align-x`, `--fit-align-y`, plus the `pixel_unfake` family below as `--fit-pixel-unfake`, `--fit-logical-height`, `--fit-palette-size`, `--fit-detail-bias`, `--fit-outline {on,off,STRENGTH}`, `--fit-pitch-hint`. CLI flags override the same keys in `--request` JSON; either way the merged result is recorded in the run's `sprite-request.json` `fit` object (SSoT).+`prepare_sprite_run.py` exposes these as `--fit-resample`, `--fit-align-x`, `--fit-align-y`, and `--fit-ground-frames` / `--no-fit-ground-frames`, plus the `pixel_unfake` family below as `--fit-pixel-unfake`, `--fit-logical-height`, `--fit-palette-size`, `--fit-detail-bias`, `--fit-outline {on,off,STRENGTH}`, `--fit-pitch-hint`. CLI flags override the same keys in `--request` JSON; either way the merged result is recorded in the run's `sprite-request.json` `fit` object (SSoT).## `pixel_unfake` modediff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex 4fc92ce..d0e2d22 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -60,6 +60,7 @@ def _add_prepare(p: argparse.ArgumentParser) -> None:p.add_argument("--fit-resample", choices=["lanczos", "nearest", "kcentroid"], default=None)p.add_argument("--fit-align-x", choices=["bbox-center", "centroid", "foot-centroid", "alpha-centroid"], default=None)p.add_argument("--fit-align-y", choices=["center", "bottom"], default=None)+ p.add_argument("--fit-ground-frames", action=argparse.BooleanOptionalAction, default=None)p.add_argument("--fit-pixel-unfake", action=argparse.BooleanOptionalAction, default=None)# 은퇴한 이름. 조용한 별칭으로 살려두지 않는다 — 두 이름이 공존하면 문서와 스크립트가# 갈라진다. 대신 무엇으로 바뀌었는지 말하며 죽는다 (숨은 인자라 --help 를 어지럽히지 않음).diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.pyindex 9f5f103..93e887c 100644--- a/sprite_gen/frames/extract.py+++ b/sprite_gen/frames/extract.py@@ -1861,6 +1861,12 @@ def register_row_frames(frames: list, slack_x: int = 8, slack_y: int = 3) -> lisreturn registered+def _content_center_top(sprite: Image.Image, cell_height: int) -> int:+ bbox = sprite.getbbox()+ content_top, content_bottom = bbox[1::2] if bbox else (0, sprite.height)+ return round((cell_height - (content_bottom - content_top)) / 2) - content_top++def row_placement(frames: list, cell_width: int, cell_height: int, safe_margin_y: int, scale: int, fit: dict[str, Any]) -> tuple[int, int]:# 가로 배치 오프셋은 행 union 기준으로 1회 계산해 전 프레임에 동일 적용한다# (플립 대칭·수평 안정). 세로는 place_row_frame 이 프레임별로 접지한다.@@ -1881,13 +1887,15 @@ def row_placement(frames: list, cell_width: int, cell_height: int, safe_margin_yleft = (cell_width - sprite.width) // 2left = max(0, min(cell_width - sprite.width, left))left -= left % scale+ if str(fit.get("align_y", "bottom")).lower() == "center":+ return left, _content_center_top(sprite, cell_height)bbox = sprite.getbbox()content_bottom = bbox[3] if bbox else sprite.heighttop = max(0, cell_height - safe_margin_y - content_bottom)return left, top-def place_row_frame(frame: Image.Image, cell_width: int, cell_height: int, scale: int, left: int, top: int, safe_margin_y: int | None = None, ground: bool = True) -> Image.Image:+def place_row_frame(frame: Image.Image, cell_width: int, cell_height: int, scale: int, left: int, top: int, safe_margin_y: int | None = None, ground: bool = True, align_y: str = "bottom") -> Image.Image:# 2026-07-04 (maintainer): 세로는 프레임마다 콘텐츠 바닥을 공유 기준선에 접지한다 —# 행 union 공동 top 만 쓰면 소스 스트립의 상하 요동이 이동으로 남아 프레임 간# "무게감"(발밑 높이)이 들쭉해진다. perfectpixel-studio 의 프레임별 알파 가중@@ -1898,7 +1906,9 @@ def place_row_frame(frame: Image.Image, cell_width: int, cell_height: int, scalereturn targetsprite = frame.resize((frame.width * scale, frame.height * scale), Image.Resampling.NEAREST)frame_top = top- if ground and safe_margin_y is not None:+ if ground and str(align_y).lower() == "center":+ frame_top = _content_center_top(sprite, cell_height)+ elif ground and safe_margin_y is not None:bbox = sprite.getbbox()content_bottom = bbox[3] if bbox else sprite.heightframe_top = max(0, cell_height - safe_margin_y - content_bottom)@@ -3057,11 +3067,12 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):# alpha-centroid 는 프레임별 가로 배치 — 행 union 공동 left 로는# register_row_frames 의 정합 잔차가 지터로 남는다.per_frame_centroid = str(fit_config.get("align_x", "foot-centroid")).lower() == "alpha-centroid"+ align_y = str(fit_config.get("align_y", "bottom")).lower()frames = [place_row_frame(frame, cell_width, cell_height, pp_scale,_alpha_centroid_row_left(frame, cell_width, pp_scale) if per_frame_centroid else left,- top, safe_margin_y, ground_frames)+ top, safe_margin_y, ground_frames, align_y)for frame in quantized]# 전/후 비교 쌍둥이: 픽셀 언페이크 프레임의 최종 콘텐츠 bbox 와 같은 풋프린트에diff --git a/sprite_gen/gen/prepare.py b/sprite_gen/gen/prepare.pyindex a1abd6c..112e927 100644--- a/sprite_gen/gen/prepare.py+++ b/sprite_gen/gen/prepare.py@@ -1029,7 +1029,8 @@ def _build_parser() -> argparse.ArgumentParser:parser.add_argument("--chroma-key", default="auto", help="auto or #RRGGBB")parser.add_argument("--fit-resample", choices=["lanczos", "nearest", "kcentroid"], default=None, help="frame downscale filter; nearest keeps pixel-art edges crisp, kcentroid keeps 1px outlines readable")parser.add_argument("--fit-align-x", choices=["bbox-center", "centroid", "foot-centroid", "alpha-centroid"], default=None, help="horizontal frame anchor; centroid stabilizes body position across variable-width poses, foot-centroid anchors on the bottom-20%% alpha (legs), alpha-centroid is the perfectpixel-studio per-frame alpha-weighted centroid (fringe-insensitive, per-frame in the pixel unfake row path)")- parser.add_argument("--fit-align-y", choices=["center", "bottom"], default=None, help="vertical frame anchor; bottom pins feet to a shared baseline")+ parser.add_argument("--fit-align-y", choices=["center", "bottom"], default=None, help="vertical frame anchor; bottom pins feet to a shared baseline, center pins content to the cell center")+ parser.add_argument("--fit-ground-frames", action=argparse.BooleanOptionalAction, default=None, help="re-anchor each frame to the shared vertical line; disable to preserve deliberate vertical travel")parser.add_argument("--fit-pixel-unfake", action=argparse.BooleanOptionalAction, default=None, help="unfake the AI dots: pitch detection -> grid snap -> kCentroid -> shared palette -> integer NEAREST (see docs/pixel-unfake.md)")# 은퇴한 이름 (조용한 별칭 금지 — 두 이름이 공존하면 문서·스크립트가 갈라진다)parser.add_argument("--fit-pixel-perfect", "--no-fit-pixel-perfect", dest="_retired_pp",@@ -1150,6 +1151,7 @@ def _run(args: argparse.Namespace):"resample": args.fit_resample,"align_x": args.fit_align_x,"align_y": args.fit_align_y,+ "ground_frames": args.fit_ground_frames,"pixel_unfake": args.fit_pixel_unfake,"logical_height": args.fit_logical_height,"palette_size": args.fit_palette_size,diff --git a/tests/frames/test_row_placement_align_y.py b/tests/frames/test_row_placement_align_y.pynew file mode 100644index 0000000..a164a2d--- /dev/null+++ b/tests/frames/test_row_placement_align_y.py@@ -0,0 +1,63 @@+# SPDX-License-Identifier: Apache-2.0+"""Vertical centering in the pixel-unfake row-placement path."""++from PIL import Image++from sprite_gen.frames.extract import place_row_frame, row_placement+++def _disc(size: int, canvas: int = 40) -> Image.Image:+ frame = Image.new("RGBA", (canvas, canvas), (0, 0, 0, 0))+ start = (canvas - size) // 2+ for y in range(start, start + size):+ for x in range(start, start + size):+ frame.putpixel((x, y), (255, 160, 40, 255))+ return frame+++def _content_center_y(cell: Image.Image) -> float:+ bbox = cell.getbbox()+ assert bbox is not None+ return (bbox[1] + bbox[3]) / 2+++GROWING = [_disc(8), _disc(24), _disc(12)]+++def test_row_placement_defaults_to_bottom() -> None:+ _, default_top = row_placement(GROWING, 64, 64, 2, 1, {})+ _, explicit_top = row_placement(GROWING, 64, 64, 2, 1, {"align_y": "bottom"})+ assert default_top == explicit_top+++def test_growing_subject_climbs_when_bottom_anchored() -> None:+ left, top = row_placement(GROWING, 64, 64, 2, 1, {})+ centers = [+ _content_center_y(place_row_frame(frame, 64, 64, 1, left, top, 2, True, "bottom"))+ for frame in GROWING+ ]+ assert max(centers) - min(centers) > 4+++def test_center_holds_the_center_while_the_subject_grows() -> None:+ left, top = row_placement(GROWING, 64, 64, 2, 1, {"align_y": "center"})+ centers = [+ _content_center_y(place_row_frame(frame, 64, 64, 1, left, top, 2, True, "center"))+ for frame in GROWING+ ]+ assert max(centers) - min(centers) <= 1+ assert all(abs(center - 32) <= 1 for center in centers)+++def test_center_without_ground_uses_the_shared_row_offset() -> None:+ left, top = row_placement(GROWING, 64, 64, 2, 1, {"align_y": "center"})+ placed = [+ place_row_frame(frame, 64, 64, 1, left, top, 2, False, "center")+ for frame in GROWING+ ]+ assert len({cell.getbbox()[1] for cell in placed if cell.getbbox() is not None}) > 1+++def test_empty_frame_stays_empty() -> None:+ blank = Image.new("RGBA", (40, 40), (0, 0, 0, 0))+ assert place_row_frame(blank, 64, 64, 1, 0, 0, 2, True, "center").getbbox() is Nonediff --git a/tests/packaging/test_pipeline_smoke.py b/tests/packaging/test_pipeline_smoke.pyindex 7fcef1d..60330cb 100644--- a/tests/packaging/test_pipeline_smoke.py+++ b/tests/packaging/test_pipeline_smoke.py@@ -36,6 +36,8 @@ def test_prepare_records_fit_cli_flags_in_request(tmp_path: Path) -> None:"--request-json", '{"fit": {"resample": "lanczos", "palette_size": 24}}',"--fit-resample", "kcentroid","--fit-align-x", "foot-centroid",+ "--fit-align-y", "center",+ "--no-fit-ground-frames","--fit-pixel-unfake","--fit-logical-height", "64","--fit-outline", "0.5",@@ -46,6 +48,8 @@ def test_prepare_records_fit_cli_flags_in_request(tmp_path: Path) -> None:assert request["fit"] == {"resample": "kcentroid", # CLI overrides the --request-json value"align_x": "foot-centroid",+ "align_y": "center",+ "ground_frames": False,"pixel_unfake": True,"logical_height": 64,"outline": 0.5,