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: honor vertical centering in pixel-unfake rows

Soohong Kim72a2bf163c84
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.md
index 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` mode
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 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.py
index 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) -> lis
return 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_y
left = (cell_width - sprite.width) // 2
left = 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.height
top = 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, scale
return target
sprite = 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.height
frame_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.py
index 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.py
new file mode 100644
index 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 None
diff --git a/tests/packaging/test_pipeline_smoke.py b/tests/packaging/test_pipeline_smoke.py
index 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,