Skip to content

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

refactor(breathe): a loop's frames folder read, checked and written whole as one module, and the chest's weight and rise as functions — the same bytes, for Sway to share

Soohong Kim4fca95eceaa4
diff --git a/sprite_gen/effects/breathe.py b/sprite_gen/effects/breathe.py
index 6854d84..6465b05 100644
--- a/sprite_gen/effects/breathe.py
+++ b/sprite_gen/effects/breathe.py
@@ -66,9 +66,7 @@ AI 개입 0 — 같은 입력이면 항상 같은 출력.
from __future__ import annotations
import argparse
-import json
import math
-import shutil
from pathlib import Path
from PIL import Image
@@ -78,7 +76,7 @@ from sprite_gen.effects.anatomy import Anatomy, analyze
from sprite_gen.curate.curation import (BREATHE_MODES, BREATHE_SMOOTH_DEPTH, BREATHE_SMOOTH_DEPTH_X,
BREATHE_SMOOTH_SHAPE, normalize_transform, state_breathe)
from sprite_gen.frames.extract import BORDER_MIN_FRACTION, FRAME_SIDES, own_border, solid_alpha_bbox
-from sprite_gen.spec.runio import inside_folder, new_stage, same_folder
+from sprite_gen.frames.folder import open_frames, publish
# 강체 경계에서 변형 강도가 0 이 되기까지의 테이퍼 반폭 (콘텐츠 높이 비율).
# 이 테이퍼가 이음매를 없앤다 — 경계에서 강도가 계단이 아니라 경사로 떨어진다.
@@ -526,6 +524,21 @@ def smooth_chest_peak(anat: Anatomy, cfg: dict) -> tuple[float, float]:
return cx + along * cos_t - across * sin_t, cy + along * sin_t + across * cos_t
+def flat_cos2(r: np.ndarray, flat: float = 0.0) -> np.ndarray:
+ """가운데 1 에서 테두리 0 으로 떨어지는 cos² 무게 — `r` 은 가운데에서 테두리까지의 몫(0 가운데, 1 테두리, 넘으면
+ 밖). `flat` 은 가운데 둘레에서 전량(1)인 몫이고, 남은 길 (r − flat)/(1 − flat) 에서 cos² 로 떨어진다. 가슴 무게
+ (chest_flat)와 Sway 레이어 영역의 무게(`video-sway --region` 의 다섯째 값)가 이 한 식이다. `r` 의 자료형을 지킨다."""
+ if flat > 0.0:
+ r = np.clip((r - flat) / (1.0 - flat), 0.0, None)
+ return np.where(r < 1.0, np.cos(0.5 * np.pi * np.minimum(r, 1.0)) ** 2, 0.0)
+
+
+def smooth_lift(anat: Anatomy, cfg: dict) -> float:
+ """smooth 의 가슴이 들숨 꼭대기에서 오르는 px — depth × 기준 높이. Sway 레이어가 숨 박자를 받을 때(`video-sway
+ --breathe`) 같은 식으로 그 크기를 읽는다."""
+ return float(cfg.get("depth") if cfg.get("depth") is not None else DEFAULT_SMOOTH_DEPTH) * anat.basis_rows
+
+
def _smoothstep_array(a: float, b: float, x: np.ndarray) -> np.ndarray:
if b <= a:
return (x >= b).astype(np.float64)
@@ -570,17 +583,14 @@ def smooth_displacement(anat: Anatomy, cfg: dict, x: np.ndarray, y: np.ndarray,
pd = pu * du + pv * dv
reach = (-pd + np.sqrt(pd * pd + dd * (1.0 - pu * pu - pv * pv)))
r = np.where(dd > 0.0, dd / np.maximum(reach, 1e-300), 0.0)
- flat = shape["chest_flat"]
- if flat > 0.0:
- r = np.clip((r - flat) / (1.0 - flat), 0.0, None)
- w_chest = np.where(r < 1.0, np.cos(0.5 * np.pi * np.minimum(r, 1.0)) ** 2, 0.0)
+ w_chest = flat_cos2(r, shape["chest_flat"])
px, py = smooth_chest_peak(anat, cfg)
heading = math.radians(shape["chest_dir"])
neckness = 1.0 - _smoothstep_array(neck_half, 1.5 * neck_half, np.abs(x - neck_x))
across = np.minimum(1.0, np.abs(np.abs(x - axis) - SHOULDER_X * torso) / (SHOULDER_RX * torso))
down = np.minimum(1.0, np.abs(y - smooth_shoulder_row(anat)) / (1.4 * band)) # 양 어깨 높이가 달라도
w_shoulder = np.cos(0.5 * np.pi * down) ** 2 * np.cos(0.5 * np.pi * across) ** 2
- lift = float(cfg.get("depth") if cfg.get("depth") is not None else DEFAULT_SMOOTH_DEPTH) * anat.basis_rows
+ lift = smooth_lift(anat, cfg)
swell = float(cfg.get("depth_x") if cfg.get("depth_x") is not None else DEFAULT_SMOOTH_DEPTH_X)
# 어깨가 켜지는 구간은 오르는 양의 8배 이상 — 더 짧으면 그 사이가 행당 상한 넘게 눌린다.
quick = max(0.15 * band, 8.0 * shape["shoulder"] * lift)
@@ -1060,48 +1070,14 @@ def run(*, frames: str, out: str, mode: str | None = None, depth: float | None =
cfg = state_breathe({"states": {"frames": {"breathe": raw}}}, "frames")
except SystemExit as exc:
raise SystemExit(f"breathe: 사이드카와 같은 검사에서 거부됐다 — {exc}")
- paths = sorted(src_dir.glob("*.png"))
- if not paths:
- raise SystemExit(f"breathe: {src_dir} 에 PNG 프레임이 없다")
- # 무엇을 만들거나 지우기 전에 — 실경로와 폴더 동일성으로 본다(링크, 철자).
- src_real, out_real = src_dir.resolve(), out_dir.resolve()
- if same_folder(out_real, src_real):
- raise SystemExit("breathe: out 이 frames 와 같은 폴더다 — 원본 프레임 위에 덮어쓰지 않는다")
- if inside_folder(out_real, src_real):
- raise SystemExit(f"breathe: out 이 frames 안에 있다 ({out_real}) — 원본 폴더 안에는 쓰지 않는다")
- if inside_folder(src_real, out_real):
- raise SystemExit(f"breathe: frames 가 out 안에 있다 ({src_real}) — 원본이 든 폴더에 내놓지 않는다")
- if out_real.exists() and not out_real.is_dir():
- raise SystemExit(f"breathe: {out_dir} 는 폴더가 아니다")
- if out_real.exists() and any(out_real.iterdir()):
- raise SystemExit(f"breathe: {out_dir} 가 비어 있지 않다 — 새 폴더를 주라")
- images = []
- for path in paths:
- with Image.open(path) as opened:
- images.append(opened.convert("RGBA"))
- if len({im.size for im in images}) != 1:
- raise SystemExit(f"breathe: 프레임 크기가 서로 다르다 — {sorted({im.size for im in images})}")
+ folder = open_frames(src_dir, out_dir, "breathe") # 무엇을 만들거나 지우기 전에 — 실경로와 폴더 동일성으로 본다
+ images = folder.images
anat = resolve_anatomy(images[0], cfg) # 보고와 굽기가 같은 한 벌 — 큰 칸은 재는 데 0.5 초다
resolved = anatomy_report(images, cfg, anat)
baked, phases = bake_breathe_sequence(images, cfg, anat)
- # 다 굽고 나서 한 번에 내놓는다 — 굽기가 중간에 거부되면 반쯤 찬 폴더를 남기지 않는다. 같은 out 으로 도는
- # 실행들은 각자의 임시 폴더에 쓰고, rename 이 먼저 닿은 쪽이 내놓는다(늦은 쪽은 차 있는 out 에서 멈춘다).
- # 지우는 것은 이 실행의 임시 폴더뿐이고, 원본 폴더에는 아무것도 쓰지 않는다.
- out_real.parent.mkdir(parents=True, exist_ok=True)
- stage = new_stage(out_real, ".partial")
- try:
- for path, frame in zip(paths, baked):
- frame.save(stage / path.name)
- report = {"frames": len(paths), "source": str(src_dir), "config": cfg, "phases": phases,
- "resolved": resolved}
- (stage / "breathe.json").write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n",
- encoding="utf-8")
- if out_real.exists():
- out_real.rmdir() # 위에서 빈 것을 봤다 — 그새 무엇이 들어왔으면 OSError 로 멈춘다
- stage.rename(out_real)
- finally:
- if stage.exists():
- shutil.rmtree(stage)
- print(f"breathe: {len(paths)} frames, {breathe_mode(cfg)}, depth {cfg['depth']}, "
+ # 다 굽고 나서 한 번에 내놓는다 — 굽기가 중간에 거부되면 반쯤 찬 폴더를 남기지 않는다(frames.folder.publish).
+ publish(folder, baked, "breathe.json", {"frames": len(images), "source": str(src_dir), "config": cfg,
+ "phases": phases, "resolved": resolved})
+ print(f"breathe: {len(images)} frames, {breathe_mode(cfg)}, depth {cfg['depth']}, "
f"breaths {cfg['breaths']} -> {out_dir}")
return 0
diff --git a/sprite_gen/frames/folder.py b/sprite_gen/frames/folder.py
new file mode 100644
index 0000000..ef4faa2
--- /dev/null
+++ b/sprite_gen/frames/folder.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A folder of a loop's frames, worked on whole and written whole into a new folder.
+
+`sprite-gen breathe <frames> <out>` and `video-sway --frames <frames> --out <out>` read the frames — the folder's PNGs
+in name order, all one size — and write the same frames under the same names, with their record beside them, into a
+new folder. The new folder is never the frames folder, inside it or holding it, read by real paths (a link or another
+spelling of one folder is that folder), and it is new or empty; all of that is looked at before anything is made.
+Everything is written into a staging folder beside it and renamed into place once all of it is written: a run that
+stops on the way leaves no half folder, and of two runs on one out the later stops at the full out. Nothing is written
+in the frames folder.
+
+A frame's time is what a loop's strip meta writes (`delay_ms`), in ms rounded to hundredths (`frame_ms`). A loop's
+`cycle/` folder has it in the loop's strip meta; any other folder is given it (`--fps`)."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from sprite_gen.spec.runio import inside_folder, new_stage, same_folder
+
+
+def frame_ms(seconds: float, frames: float) -> float:
+ """One frame's time, ms, of `frames` frames in `seconds`, as a loop's strip meta writes it (`delay_ms`)."""
+ return round(1000 * seconds / frames, 2)
+
+
+@dataclass(frozen=True, eq=False)
+class Frames:
+ """A frames folder as read: its PNGs in name order, their pictures (RGBA), and the new folder's real path."""
+
+ paths: list[Path]
+ images: list[Image.Image]
+ out: Path
+
+ @property
+ def names(self) -> list[str]:
+ return [path.name for path in self.paths]
+
+
+def open_frames(frames: Path, out: Path, verb: str) -> Frames:
+ """The frames of `frames`, read, and the real path of `out` to write them into — refused before anything is made
+ where there are none, where the two folders overlap, where `out` is not a new or empty folder, or where the frames
+ are not all one size."""
+ paths = sorted(frames.glob("*.png"))
+ if not paths:
+ raise SystemExit(f"{verb}: {frames} 에 PNG 프레임이 없다")
+ src_real, out_real = frames.resolve(), out.resolve()
+ if same_folder(out_real, src_real):
+ raise SystemExit(f"{verb}: out 이 frames 와 같은 폴더다 — 원본 프레임 위에 덮어쓰지 않는다")
+ if inside_folder(out_real, src_real):
+ raise SystemExit(f"{verb}: out 이 frames 안에 있다 ({out_real}) — 원본 폴더 안에는 쓰지 않는다")
+ if inside_folder(src_real, out_real):
+ raise SystemExit(f"{verb}: frames 가 out 안에 있다 ({src_real}) — 원본이 든 폴더에 내놓지 않는다")
+ if out_real.exists() and not out_real.is_dir():
+ raise SystemExit(f"{verb}: {out} 는 폴더가 아니다")
+ if out_real.exists() and any(out_real.iterdir()):
+ raise SystemExit(f"{verb}: {out} 가 비어 있지 않다 — 새 폴더를 주라")
+ images = []
+ for path in paths:
+ with Image.open(path) as opened:
+ images.append(opened.convert("RGBA"))
+ if len({im.size for im in images}) != 1:
+ raise SystemExit(f"{verb}: 프레임 크기가 서로 다르다 — {sorted({im.size for im in images})}")
+ return Frames(paths, images, out_real)
+
+
+def publish(frames: Frames, images: list[Image.Image], record_name: str, record: dict[str, Any]) -> None:
+ """`images` under the frames' names and `record` (JSON) as `record_name`, written whole into `frames.out`.
+
+ Staged beside `out` and renamed into place: a run that stops on the way leaves no half folder. Runs on one out
+ each write their own staging folder and the first rename wins (a later one stops at the full out). Only this
+ run's staging folder is removed."""
+ out = frames.out
+ out.parent.mkdir(parents=True, exist_ok=True)
+ stage = new_stage(out, ".partial")
+ try:
+ for name, image in zip(frames.names, images):
+ image.save(stage / name)
+ (stage / record_name).write_text(json.dumps(record, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+ if out.exists():
+ out.rmdir() # seen empty before; anything that came in since stops this with an OSError
+ stage.rename(out)
+ finally:
+ if stage.exists():
+ shutil.rmtree(stage)
+
+
+def cycle_frame_ms(frames: Path, count: int, fps: float | None, verb: str) -> float | None:
+ """The frame time of the `count` frames in `frames`, ms: `--fps` given, as `frame_ms` writes it; a loop's `cycle/`
+ folder holding its whole cycle has it in the loop's strip meta (`cycle_seconds` over `cycle_frames`), and a
+ `--fps` that says another is refused. None when neither says it."""
+ asked = None
+ if fps is not None:
+ if not fps > 0: # a NaN is not
+ raise SystemExit(f"{verb}: --fps must be above 0, got {fps:g}")
+ asked = frame_ms(1, fps)
+ recorded = None
+ metas = sorted(frames.resolve().parent.glob("*.strip.json")) if frames.resolve().name == "cycle" else []
+ if len(metas) == 1:
+ meta = json.loads(metas[0].read_text(encoding="utf-8"))
+ if meta.get("cycle_frames") == count and meta.get("cycle_seconds"):
+ recorded = frame_ms(float(meta["cycle_seconds"]), count)
+ if asked is not None and recorded is not None and asked != recorded:
+ raise SystemExit(f"{verb}: --fps {fps:g} is a frame of {asked:g} ms, and the loop's {metas[0].name} says its "
+ f"{count} cycle frames are {recorded:g} ms each; give its own or none")
+ return recorded if asked is None else asked