Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(breathe): smooth's chest can sit off the body axis and breathe from a forward peak — `chest_x`, `chest_bias` as the peak's move with a ray-falling weight, `chest_bias_y`, `chest_flat` — and its breath can be timed from outside (`breath_peaks`)
Soohong Kim3b3b79a275cf
diff --git a/sprite_gen/curate/curation.py b/sprite_gen/curate/curation.pyindex be1674f..36204e4 100644--- a/sprite_gen/curate/curation.py+++ b/sprite_gen/curate/curation.py@@ -233,12 +233,20 @@ BREATHE_SMOOTH_DEPTH_X = 0.028# shoulder: 어깨가 오르는 양 (가슴의 배), shoulder_lag: 어깨가 늦는 정도 (한 호흡 비율, 1/π 미만이라# 시간이 되감기지 않는다). 몸이 향한 쪽 — chest_tilt: 가슴 무게를 화면에서 시계방향으로 돌린 각(도),# chest_bias: 무게를 긴 축 따라 한쪽으로 키움 (음수 = 화면 왼쪽이 크게), chest_dir: 가슴이 가는 방향-# (바로 위에서 잰 각(도), 음수 = 왼쪽 위). 셋 다 0 이면 몸이 정면을 본다.+# (바로 위에서 잰 각(도), 음수 = 왼쪽 위). 셋 다 0 이면 몸이 정면을 본다. chest_bias 는 무게의 꼭대기를+# 가슴 타원의 긴 축 따라(타원 가로 반지름 비율), chest_bias_y 는 그 축을 가로질러(세로 반지름 비율, 양수 =+# 아래) 옮긴다 — 무게는 꼭대기에서 테두리까지 반직선으로 줄어 가까운 쪽이 짧고 돌아간 쪽이 길다.+# chest_x: 가슴 중심을 몸통 축에서 옮김 (몸통 반폭 비율 — 긴 머리처럼 한쪽으로 쏠린 것이 축을 끌 때),+# chest_flat: 꼭대기 둘레에서 전량으로 오르는 몫 (꼭대기에서 테두리까지의 비율).BREATHE_SMOOTH_SHAPE = {"chest_y": 0.31, "chest_rx": 0.83, "chest_ry": 0.28, "shoulder": 0.5, "shoulder_lag": 0.08,- "chest_tilt": 0.0, "chest_bias": 0.0, "chest_dir": 0.0}+ "chest_tilt": 0.0, "chest_bias": 0.0, "chest_dir": 0.0, "chest_x": 0.0, "chest_bias_y": 0.0,+ "chest_flat": 0.0}BREATHE_SMOOTH_SHAPE_RANGES = {"chest_y": (0.05, 0.95), "chest_rx": (0.2, 3.0), "chest_ry": (0.05, 1.5),"shoulder": (0.0, 1.5), "shoulder_lag": (0.0, 0.3), "chest_tilt": (-60.0, 60.0),- "chest_bias": (-0.9, 0.9), "chest_dir": (-90.0, 90.0)}+ "chest_bias": (-0.9, 0.9), "chest_dir": (-90.0, 90.0), "chest_x": (-1.0, 1.0),+ "chest_bias_y": (-0.9, 0.9), "chest_flat": (0.0, 0.9)}+# 꼭대기는 타원 안쪽이어야 한다 — 테두리에 닿으면 그쪽으로 무게가 줄어들 거리가 없다.+BREATHE_SMOOTH_PEAK_REACH = 0.9RETIRED_BREATHE_KEYS = {"splits": "분할선은 봉투 경계로 대체됐다 — 경계는 자동 검출되고 `rigid_row` 로만 덮어쓴다",@@ -300,7 +308,7 @@ def state_breathe(curation: dict[str, Any] | None, state: str) -> dict[str, Any]f"curation: states.{state}.breathe.mode = {mode!r} 를 모른다 — "f"{' | '.join(BREATHE_MODES)} 중 하나다 (생략하면 pixel). 조용히 pixel 로 굽지 않는다.")smooth = mode == "smooth"- stray = sorted(k for k in BREATHE_SMOOTH_SHAPE if k in raw)+ stray = sorted(k for k in (*BREATHE_SMOOTH_SHAPE, "breath_peaks") if k in raw)if stray and not smooth:raise SystemExit(f"curation: states.{state}.breathe 의 {', '.join(stray)} 는 smooth 의 모양 값이다 — "@@ -315,7 +323,8 @@ def state_breathe(curation: dict[str, Any] | None, state: str) -> dict[str, Any]raw_dx = raw.get("depth_x")depth_x = None if raw_dx is None else float(raw_dx)lag = float(raw.get("lag", 0.0 if smooth else 0.10))- breaths = _exact_int("breaths", raw.get("breaths", 1), state)+ peaks = raw.get("breath_peaks") if smooth else None+ breaths = _exact_int("breaths", raw.get("breaths", len(peaks) if isinstance(peaks, list) else 1), state)except (TypeError, ValueError) as exc:# 폐기 키는 요란하게 거부하면서 형식 오류만 조용히 호흡을 꺼버리면 계약이 어긋난다# — 둘 다 "이 사이드카는 그대로 못 쓴다" 이고, 조용한 쪽은 사용자가 못 알아챈다.@@ -356,6 +365,20 @@ def state_breathe(curation: dict[str, Any] | None, state: str) -> dict[str, Any]raise SystemExit(f"curation: states.{state}.breathe.lag = {raw.get('lag')!r} — smooth 에는 진행파가 없다. "f"위상 0 인 칸이 원본 그대로여야 루프·묶음 이음이 안 바뀐다. lag 를 지워라.")+ if peaks is not None:+ # 들숨 꼭대기 칸 — 숨 박자를 바깥에서 받는다. 첫 칸은 쉼이어야 하므로 1 부터, 꼭대기 사이는+ # 날숨과 다음 들숨이 나눠 쓸 두 칸 이상. 루프 길이는 굽기가 알므로 끝은 거기서 본다.+ if not isinstance(peaks, list) or not peaks:+ raise SystemExit(f"curation: states.{state}.breathe.breath_peaks = {peaks!r} — 들숨 꼭대기 칸 목록이어야 한다")+ peaks = [_exact_int("breath_peaks", p, state) for p in peaks]+ if peaks[0] < 1 or any(b - a < 2 for a, b in zip(peaks, peaks[1:])):+ raise SystemExit(+ f"curation: states.{state}.breathe.breath_peaks = {peaks} — 1 부터, 커지는 순서로, 서로 두 칸 이상 "+ f"떨어져야 한다 (첫 칸은 쉼이고, 꼭대기 사이에 날숨과 들숨이 들어간다).")+ if "breaths" in raw and breaths != len(peaks):+ raise SystemExit(+ f"curation: states.{state}.breathe.breaths = {breaths} 인데 breath_peaks 는 {len(peaks)}개다 — "+ f"숨 횟수는 꼭대기 수다. breaths 를 지우거나 맞춰라.")shape = {}for name, default in BREATHE_SMOOTH_SHAPE.items():given = raw.get(name, default)@@ -369,9 +392,14 @@ def state_breathe(curation: dict[str, Any] | None, state: str) -> dict[str, Any]f"curation: states.{state}.breathe.{name} = {given!r} 가 범위 [{lo}, {hi}] 밖이다. "f"조용히 깎지 않는다 — 사이드카를 고쳐라.")shape[name] = value+ if math.hypot(shape["chest_bias"], shape["chest_bias_y"]) > BREATHE_SMOOTH_PEAK_REACH:+ raise SystemExit(+ f"curation: states.{state}.breathe.chest_bias {shape['chest_bias']:g}, chest_bias_y "+ f"{shape['chest_bias_y']:g} — 꼭대기가 가슴 타원 테두리에 너무 가깝다 (반지름 비율 "+ f"{BREATHE_SMOOTH_PEAK_REACH:g} 안이어야 한다).")return {"mode": mode, "depth": depth,"depth_x": BREATHE_SMOOTH_DEPTH_X if depth_x is None else depth_x,- "breaths": breaths, **shape, "rigid_row": rigid_row, "axis_x": axis_x,+ "breaths": breaths, "breath_peaks": peaks, **shape, "rigid_row": rigid_row, "axis_x": axis_x,"torso_half": torso_half, "anatomy": frozen if isinstance(frozen, dict) else None}cfg = {"depth": depth, "depth_x": depth_x, "breaths": breaths, "lag": lag,"rigid_row": rigid_row, "axis_x": axis_x, "torso_half": torso_half,diff --git a/sprite_gen/effects/breathe.py b/sprite_gen/effects/breathe.pyindex f9ead57..02704d5 100644--- a/sprite_gen/effects/breathe.py+++ b/sprite_gen/effects/breathe.py@@ -470,9 +470,30 @@ def _shape(cfg: dict) -> dict:def smooth_chest(anat: Anatomy, cfg: dict) -> tuple[float, float]:- """가슴 가운데 (콘텐츠 bbox 기준 x, y) — 몸통 축 위, 목 아래 몸통의 `chest_y` 비율 높이."""+ """가슴 타원의 가운데 (콘텐츠 bbox 기준 x, y) — 몸통 축에서 `chest_x` × 몸통 반폭, 목 아래 몸통의+ `chest_y` 비율 높이."""+ shape = _shape(cfg)top = float(anat.rigid_row)- return anat.axis_x + 0.5, top + _shape(cfg)["chest_y"] * (anat.height - top)+ return anat.axis_x + 0.5 + shape["chest_x"] * anat.torso_half, top + shape["chest_y"] * (anat.height - top)+++def _chest_frame(anat: Anatomy, cfg: dict) -> tuple[float, float, float, float, float, float]:+ """(가운데 x, y, 가로 반지름, 세로 반지름, cos 기울기, sin 기울기) — 가슴 타원."""+ shape = _shape(cfg)+ cx, cy = smooth_chest(anat, cfg)+ tilt = math.radians(shape["chest_tilt"])+ top = float(anat.rigid_row)+ return (cx, cy, shape["chest_rx"] * anat.torso_half, shape["chest_ry"] * (anat.height - top),+ math.cos(tilt), math.sin(tilt))+++def smooth_chest_peak(anat: Anatomy, cfg: dict) -> tuple[float, float]:+ """무게의 꼭대기 P (콘텐츠 bbox 기준 x, y) — 타원 가운데에서 긴 축 따라 `chest_bias` × 가로 반지름,+ 가로질러 `chest_bias_y` × 세로 반지름. 둘 다 0 이면 가운데다."""+ shape = _shape(cfg)+ cx, cy, rx, ry, cos_t, sin_t = _chest_frame(anat, cfg)+ along, across = shape["chest_bias"] * rx, shape["chest_bias_y"] * ry+ return cx + along * cos_t - across * sin_t, cy + along * sin_t + across * cos_tdef _smoothstep_array(a: float, b: float, x: np.ndarray) -> np.ndarray:@@ -500,21 +521,33 @@ def smooth_displacement(anat: Anatomy, cfg: dict, x: np.ndarray, y: np.ndarray,band = band_end - topheight = float(anat.height)torso = float(anat.torso_half)- cx, cy = smooth_chest(anat, cfg)+ cx, cy, rx, ry, cos_t, sin_t = _chest_frame(anat, cfg)+ axis = anat.axis_x + 0.5neck_x, neck_half = _neck(anat)- rx = shape["chest_rx"] * torso- ry = shape["chest_ry"] * (height - top)- # 몸이 향한 쪽: 타원을 기울이고(chest_tilt), 긴 축 따라 한쪽을 키우고(chest_bias), 가슴이 가는 쪽을- # 바로 위에서 돌린다(chest_dir). 셋 다 0 이면 아래 식은 기울이기 전 식과 비트 같다 (곱 1·0 과 합 0).- tilt = math.radians(shape["chest_tilt"])- along = (x - cx) * math.cos(tilt) + (y - cy) * math.sin(tilt)- across_axis = (y - cy) * math.cos(tilt) - (x - cx) * math.sin(tilt)- r = np.sqrt((along / rx) ** 2 + (across_axis / ry) ** 2)- w_round = np.where(r < 1.0, np.cos(0.5 * np.pi * np.minimum(r, 1.0)) ** 2, 0.0)- w_chest = w_round * (1.0 + shape["chest_bias"] * np.clip(along / rx, -1.0, 1.0))+ # 몸이 향한 쪽: 타원을 기울이고(chest_tilt), 꼭대기를 앞쪽으로 옮기고(chest_bias, chest_bias_y), 가슴이+ # 가는 쪽을 바로 위에서 돌린다(chest_dir). 모두 0 이면 아래 식은 이 값들이 생기기 전 식과 비트 같다.+ along = (x - cx) * cos_t + (y - cy) * sin_t+ across_axis = (y - cy) * cos_t - (x - cx) * sin_t+ u, v = along / rx, across_axis / ry # 타원을 단위원으로 편 좌표+ pu, pv = shape["chest_bias"], shape["chest_bias_y"]+ if pu == 0.0 and pv == 0.0:+ r = np.sqrt(u ** 2 + v ** 2)+ else:+ # 꼭대기 P 에서 이 점을 지나 테두리에 닿는 반직선 위의 몫 — P 에서 0, 테두리에서 1. 가까운 쪽은+ # 짧은 거리에서, 돌아간 쪽은 긴 거리에서 0 으로 떨어진다.+ du, dv = u - pu, v - pv+ dd = du * du + dv * dv+ 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)+ 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 - cx) - SHOULDER_X * torso) / (SHOULDER_RX * torso))+ 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) ** 2lift = float(cfg.get("depth") if cfg.get("depth") is not None else DEFAULT_SMOOTH_DEPTH) * anat.basis_rows@@ -524,10 +557,10 @@ def smooth_displacement(anat: Anatomy, cfg: dict, x: np.ndarray, y: np.ndarray,u = np.clip((y - top) / (quick + (band - quick) * neckness), 0.0, 1.0) if band > quick else \np.clip((y - top) / quick, 0.0, 1.0)guard = u * u * (3.0 - 2.0 * u) * (1.0 - _smoothstep_array(height - 0.5 * band, height, y))- rise = lift * (chest * w_chest * math.cos(heading) + shape["shoulder"] * shoulders * w_shoulder * (1.0 - w_round))+ rise = lift * (chest * w_chest * math.cos(heading) + shape["shoulder"] * shoulders * w_shoulder * (1.0 - w_chest))forward = lift * chest * w_chest * math.sin(heading)puff = swell * chest * w_chest- return (puff * (x - cx) + forward) * guard, (puff * (y - cy) - rise) * guard+ return (puff * (x - px) + forward) * guard, (puff * (y - py) - rise) * guarddef smooth_strain(anat: Anatomy, cfg: dict) -> tuple[float, float]:@@ -805,10 +838,33 @@ def fit_breathe_pattern(seq_len: int, cfg: dict) -> list[float]:(validator 검증 2026-07-25: 시트 1344x192 -> 576x192)."""if seq_len <= 0:return []+ if cfg.get("breath_peaks"):+ return _peaked_phases(seq_len, list(cfg["breath_peaks"]))breaths = max(1, int(cfg.get("breaths", 1)))return [((i * breaths) % seq_len) / seq_len for i in range(seq_len)]+def _peaked_phases(seq_len: int, peaks: list[int]) -> list[float]:+ """들숨 꼭대기 칸을 바깥에서 받은 위상 (smooth) — 숨 k 는 쉼에서 시작해 `peaks[k]` 칸에서 가득 차고(위상+ INHALE) 다음 쉼으로 돌아간다. 쉼은 0 칸, 꼭대기 사이를 날숨 1-INHALE : 들숨 INHALE 로 나누는 자리, 그리고+ 루프 끝이다 — 첫 칸이 쉼이고 루프가 쉼에서 닫힌다. 숨마다 위상은 [0, 1) 이다."""+ if peaks[-1] > seq_len - 2:+ raise SystemExit(f"breathe: breath_peaks 의 마지막 {peaks[-1]} 가 {seq_len}칸 루프의 끝에 너무 가깝다 — "+ f"꼭대기 뒤에 날숨이 들어갈 칸이 있어야 루프가 쉼에서 닫힌다 ({seq_len - 2} 까지).")+ rests = [0.0] + [p + (1.0 - INHALE) * (q - p) for p, q in zip(peaks, peaks[1:])] + [float(seq_len)]+ phases = []+ k = 0+ for i in range(seq_len):+ while i >= rests[k + 1]:+ k += 1+ start, peak, end = rests[k], peaks[k], rests[k + 1]+ if i <= peak:+ phases.append(INHALE * (i - start) / (peak - start))+ else:+ phases.append(INHALE + (1.0 - INHALE) * (i - peak) / (end - peak))+ return phases++def fitted_breath_count(seq_len: int, cfg: dict) -> int:"""실제 적용되는 호흡 횟수 — 연속 위상이라 요청값이 그대로 성립한다."""if seq_len <= 0:@@ -872,6 +928,13 @@ def bake_breathe_sequence(images: list[Image.Image], cfg: dict) -> tuple[list[Im# ── CLI: 프레임 폴더에 굽기 (`sprite-gen breathe`) ─────────────────+def _cells(text: str) -> list[int]:+ try:+ return [int(part) for part in text.split(",") if part.strip()]+ except ValueError:+ raise argparse.ArgumentTypeError(f"cell numbers separated by commas, not {text!r}")++def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("frames", help="folder of the loop's frames (*.png, played in name order)")parser.add_argument("out", help="new folder for the breathing frames (same names) and breathe.json")@@ -905,20 +968,33 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:help="one side of the chest breathes more, -0.9..0.9, negative the screen's left (0)")shape.add_argument("--chest-dir", type=float, default=None,help="where the chest moves, degrees from straight up, negative up-left (0)")+ shape.add_argument("--chest-x", type=float, default=None,+ help="the chest's centre moved off the body axis, times the torso half width (0)")+ shape.add_argument("--chest-bias-y", type=float, default=None,+ help="the chest's peak moved across its long axis, times its half height, positive down (0)")+ shape.add_argument("--chest-flat", type=float, default=None,+ help="share of the way from the peak to the rim that rises in full (0)")+ shape.add_argument("--breath-peaks", type=_cells, default=None, metavar="CELL,CELL,...",+ help="smooth: the cells where each in-breath peaks (the breath count is how many); the first "+ "cell stays at rest and the loop closes at rest")def run(*, frames: str, out: str, mode: str | None = None, depth: float | None = None,depth_x: float | None = None, breaths: int | None = None, lag: float | None = None,rigid_row: int | None = None, chest_y: float | None = None, chest_rx: float | None = None,chest_ry: float | None = None, shoulder: float | None = None, shoulder_lag: float | None = None,- chest_tilt: float | None = None, chest_bias: float | None = None, chest_dir: float | None = None) -> int:+ chest_tilt: float | None = None, chest_bias: float | None = None, chest_dir: float | None = None,+ chest_x: float | None = None, chest_bias_y: float | None = None, chest_flat: float | None = None,+ breath_peaks: list[int] | None = None) -> int:"""프레임 폴더에 Breathe 레이어를 굽는다 — 큐레이션 사이드카 `breathe` 와 같은 값, 같은 정규화,같은 굽기(`bake_breathe_sequence`). 영상 루프의 칸처럼 큐레이션 런이 아닌 프레임이 이 길로 온다."""src_dir, out_dir = Path(frames), Path(out)raw = {k: v for k, v in (("mode", mode), ("depth", depth), ("depth_x", depth_x), ("breaths", breaths),("lag", lag), ("rigid_row", rigid_row), ("chest_y", chest_y), ("chest_rx", chest_rx),("chest_ry", chest_ry), ("shoulder", shoulder), ("shoulder_lag", shoulder_lag),- ("chest_tilt", chest_tilt), ("chest_bias", chest_bias), ("chest_dir", chest_dir))+ ("chest_tilt", chest_tilt), ("chest_bias", chest_bias), ("chest_dir", chest_dir),+ ("chest_x", chest_x), ("chest_bias_y", chest_bias_y), ("chest_flat", chest_flat),+ ("breath_peaks", breath_peaks))if v is not None}try:cfg = state_breathe({"states": {"frames": {"breathe": raw}}}, "frames")diff --git a/sprite_gen/serve/curator/src/store.js b/sprite_gen/serve/curator/src/store.jsindex 8c174ad..3fc7e8a 100644--- a/sprite_gen/serve/curator/src/store.js+++ b/sprite_gen/serve/curator/src/store.js@@ -14,7 +14,7 @@ function isNumericScalar(v) {// 굽기 방식 — 파이썬 curation.BREATHE_MODES 미러. 생략 = pixel.const BREATHE_MODES = ["pixel", "smooth"];// smooth 모양 값의 허용 범위 — 파이썬 curation.BREATHE_SMOOTH_SHAPE_RANGES 미러.-const BREATHE_SMOOTH_SHAPE_RANGES = { chest_y: [0.05, 0.95], chest_rx: [0.2, 3.0], chest_ry: [0.05, 1.5], shoulder: [0.0, 1.5], shoulder_lag: [0.0, 0.3], chest_tilt: [-60.0, 60.0], chest_bias: [-0.9, 0.9], chest_dir: [-90.0, 90.0] };+const BREATHE_SMOOTH_SHAPE_RANGES = { chest_y: [0.05, 0.95], chest_rx: [0.2, 3.0], chest_ry: [0.05, 1.5], shoulder: [0.0, 1.5], shoulder_lag: [0.0, 0.3], chest_tilt: [-60.0, 60.0], chest_bias: [-0.9, 0.9], chest_dir: [-90.0, 90.0], chest_x: [-1.0, 1.0], chest_bias_y: [-0.9, 0.9], chest_flat: [0.0, 0.9] };function breatheRangeProblems(raw) {const bounds = [["depth", 0.005, 0.20, 0.06], ["breaths", 1, 8, 1], ["lag", 0, 0.45, 0.1]];@@ -32,6 +32,14 @@ function breatheRangeProblems(raw) {const v = isNumericScalar(raw[key]) ? Number(raw[key]) : NaN;if (!Number.isFinite(v) || v < lo || v > hi) bad.push(`${key}=${JSON.stringify(raw[key])}`);}+ // 들숨 꼭대기 칸(smooth): 1 부터 커지는 정수, 서로 두 칸 이상 — 파이썬 state_breathe 미러.+ if (raw.breath_peaks !== undefined) {+ const p = raw.breath_peaks;+ const ok = raw.mode === "smooth" && Array.isArray(p) && p.length > 0 && p.every(Number.isInteger)+ && p[0] >= 1 && p.every((v, i) => i === 0 || v - p[i - 1] >= 2)+ && (raw.breaths == null || Number(raw.breaths) === p.length);+ if (!ok) bad.push(`breath_peaks=${JSON.stringify(p)}`);+ }for (const [key, lo, hi, dflt] of bounds) {// 생략(undefined)은 기본값. 명시적 null 은 굽기가 `float(None)` 으로 거부하므로// **키와 무관하게** 여기서도 문제로 본다 — `Number(null) = 0` 이라 하한이 0 인 `lag`