Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: the in-breath share `inhale` — breathing (the key, its range, breath_peaks rests at it, the beat read on it), the Sway layer on the breath (the record's share, a record without it, the drive), CHANGELOG `## Unreleased`
Soohong Kimecfba1133c5c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3cfdcbe..3337eed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased-**Upgrading from 3.0.0: Bakes retain the same bytes for figures whose anatomy is unchanged. The `pixel` refusal message now names the sides and pixel counts. A figure that had `face-absent` may now have a face, with a lower rigid boundary only when that face ends below the neck. `video-sway-inspect` records use schema 3, and a cell whose every offset is 0 is now copied as it was, including colour under clear pixels with `--gain 0`; the other changes add options, and without them the strip, records and inspection stay as before.**+**Upgrading from 3.0.0: Bakes retain the same bytes for figures whose anatomy is unchanged. The `pixel` refusal message now names the sides and pixel counts. A figure that had `face-absent` may now have a face, with a lower rigid boundary only when that face ends below the neck. `video-sway-inspect` records use schema 3, and a cell whose every offset is 0 is now copied as it was, including colour under clear pixels with `--gain 0`; the other changes add options, and without them the strip, records and inspection stay as before.** Smooth bakes that leave the in-breath share out keep their bytes. A smooth `breathe.json` config and a breath sway's `drive` record now carry `inhale`, Python callers of `smooth_wave` and `smooth_shoulder_wave` must pass the share, and `breathe.INHALE` is gone.The Breathe layer still supports `pixel` and `smooth`.@@ -40,12 +40,27 @@ The Breathe layer still supports `pixel` and `smooth`.- **Changed: Inspection seams.** `video-sway-inspect` drops a pair's seam points covered by a third moving region.Its record uses `schema_version` 3.- **New: Breathe beat chosen to miss the hands.** In `smooth` mode, `--avoid-region` chooses a breath beat whose peaks keep the chest above the hands' own rise and records the choice in `breathe.json`.+- **New: The in-breath share.** The smooth sidecar key `inhale` is the share of one breath the in-breath takes; the in-breath peaks at that phase and the rest of the breath is the out-breath.+ Default 0.40, range 0.2 to 0.8 with both ends allowed; out-of-range values are refused, not clamped, and a pixel row refuses the key.+ With the key left out or at 0.40 every bake is byte-identical to before.+ With `breath_peaks`, the rest between peaks p and q is at p + (1 - inhale) x (q - p).+ `sprite-gen breathe --inhale S` sets it, and the normalized smooth config in `breathe.json` always carries it.+ `--avoid-region` scores every candidate on the row's own `inhale` curve, the curve the bake uses.+ Sway `--breathe` takes the chest curve, the late curve and the phase check at the record's share, so `breath_peaks` phases written at another share are accepted when they match.+ A record without the key reads as 0.40 and sways exactly as before, and a hand-written record for a breath made elsewhere can state its share.+ The sway record's `drive` now also carries `inhale`.+ The curator sidecar round trip keeps `inhale` as written and its range table mirrors 0.2 to 0.8.+- **Changed: Breath curve functions.** `breathe.smooth_wave(t, inhale)` and `breathe.smooth_shoulder_wave(t, lag, inhale)` now require the share.+ The module constant `breathe.INHALE` is removed; the default lives in `curation.BREATHE_SMOOTH_SHAPE["inhale"]`, and `breathe.smooth_inhale(cfg)` returns a row's share.+ `breath_beat.choose(images, lift, inhale, avoid, anchor, frame_ms)` and `breath_beat.nudged(n, k, inhale)` take it as well.- **Tests:** `tests/effects/test_breathe.py` checks border counts, advice, smooth edge preservation, and the second face search.`tests/effects/test_breathe_js_mirror.py` checks curator refusal wording and byte identity with the pixel bake.- `tests/effects/test_breathe_smooth.py` checks pixel and smooth byte goldens and shared anatomy and strain measurements.+ `tests/effects/test_breathe_smooth.py` checks pixel and smooth byte goldens and shared anatomy and strain measurements, and that the in-breath takes the row's share: at share 0.42 the cells at phases 0.21 and 0.42 are byte-identical to the default row's cells at 0.20 and 0.40, `breath_peaks` rests at the share, out-of-range and pixel values are refused, and the CLI flag is honoured.+ `tests/effects/test_breathe_smooth_curator.py` checks that the sidecar round trip keeps `inhale`.`tests/effects/test_breathe_publish.py` checks that the stand-in bake accepts the new argument.`tests/video/test_sway_frames.py`, `tests/video/test_sway_breath.py`, `tests/video/test_sway_flat_across.py`, and `tests/video/test_sway_seams.py` check the Sway paths, drives, weights, gains and seams.- `tests/effects/test_breath_beat.py` checks beat choice and refusals.+ `tests/video/test_sway_breath.py` also checks that the sway follows the share the record says for `breaths` and `breath_peaks`, that a record without the key sways as the default, and that the default breath sways the same bytes as before the change.+ `tests/effects/test_breath_beat.py` checks beat choice and refusals, and that each beat candidate is read on the row's share.`tests/video/test_follow_stretch_floor.py` and `tests/video/test_follow_inspect.py` cover the changed inspection schema and frames options.## v3.0.0 - Remove rig layer compositiondiff --git a/docs/breathing.md b/docs/breathing.mdindex 4768977..19e38f8 100644--- a/docs/breathing.md+++ b/docs/breathing.md@@ -17,7 +17,7 @@ smooth 모드의 고정 영역과 동작 방식은 다음과 같다.- rigid row, body axis, torso half width, basis rows로 이루어진 pixel 모드의 자동 해부학 측정에 강체 경계상의 목 너비를 추가해 사용한다. 모든 측정은 행의 첫 셀에서 한 번만 수행되며 해당 셀의 배치가 행 전체에 그대로 쓰인다. 비디오 셀 사이에서 정수리가 1픽셀 흔들려도 경계는 움직이지 않는다.- 가슴은 목 아래 몸통의 `chest_y` 지점, 몸통 중심축에 위치한 원형 가중치(cos^2)를 중심으로 호흡한다. 가중치 너비는 몸통 반폭의 `chest_rx`배, 높이는 목 아래 몸통 높이의 `chest_ry`배다. 들숨 시 가슴 중심은 기준 행의 `depth`배만큼 상승하고, 가슴 타원 중심이 아닌 정점 P에서 바깥쪽으로 `depth_x`만큼 부풀어 오른다.- 목 바로 아래 중심축 양쪽에 위치한 원형 어깨 가중치 두 개는 가슴 상승량의 `shoulder`배만큼, 가슴보다 `shoulder_lag` 호흡 주기만큼 늦게 올라간다. 측정된 너비 안쪽의 목과 목과 어깨 사이의 칼라(collar)는 움직이지 않는다. 행 전체가 통째로 오르내리지 않는다.-- 한 번의 호흡은 정지 상태에서 솟아오르는 형태다 (들숨 40%, 날숨 60%). 위상 0의 셀이 원본과 바이트 단위로 일치하므로 루프의 이음매와 루프 간 연결부가 온전히 유지된다. `breaths`는 1부터 8까지의 정수로 루프 길이에 정확히 맞춘다. 외부에서 호흡 타이밍을 맞추기 위해(예: 클립 내 큰 손 동작을 피하려는 경우) 각 들숨이 정점에 도달하는 셀 목록인 `breath_peaks`를 지정할 수 있다. 호흡 횟수는 정점의 개수가 되며, `breaths`를 함께 지정할 경우 일치해야 한다. 첫 셀은 정지 상태를 유지하고 루프는 정지 상태로 끝난다. 호흡은 셀 0, 두 정점 사이에서 날숨이 간격의 60%를 차지하고 다음 들숨이 40%를 차지하는 지점, 루프 끝의 정지 상태로 구분된다.+- 한 번의 호흡은 정지 상태에서 솟아오르는 형태다. 들숨이 호흡에서 차지하는 비율은 `inhale` 키로 정한다 (기본값 0.40, 따라서 기본적으로 들숨 40%, 날숨 60%). 다른 곳에서 만든 호흡은 이 키로 자신의 들숨 비율을 명시할 수 있다. 위상 0의 셀이 원본과 바이트 단위로 일치하므로 루프의 이음매와 루프 간 연결부가 온전히 유지된다. `breaths`는 1부터 8까지의 정수로 루프 길이에 정확히 맞춘다. 외부에서 호흡 타이밍을 맞추기 위해(예: 클립 내 큰 손 동작을 피하려는 경우) 각 들숨이 정점에 도달하는 셀 목록인 `breath_peaks`를 지정할 수 있다. 호흡 횟수는 정점의 개수가 되며, `breaths`를 함께 지정할 경우 일치해야 한다. 첫 셀은 정지 상태를 유지하고 루프는 정지 상태로 끝난다. 호흡은 셀 0, 두 정점 사이에서 날숨이 간격의 1 - inhale을 차지하고 다음 들숨이 inhale을 차지하는 지점(기본값에서는 60%와 40%), 루프 끝의 정지 상태로 구분된다.몸이 한쪽으로 돌아간 경우 다음 키들을 조절한다.- `chest_tilt`: 가슴 가중치를 회전한다 (도 단위, 화면 기준 시계 방향).@@ -45,11 +45,12 @@ smooth 모드의 고정 영역과 동작 방식은 다음과 같다.| `chest_dir` | 0 | -90에서 90 | 가슴 이동 방향 각도 (도 단위, 음수는 위쪽 왼쪽) || `chest_x` | 0 | -1에서 1 | 몸통 중심축 기준 가슴 타원 중심 이동 (몸통 반폭 단위) || `chest_flat` | 0 | 0에서 0.9 | 정점 P에서 가장자리까지 완전히 상승하는 구간 비율 |+| `inhale` | 0.40 | 0.2에서 0.8 | 한 번의 호흡에서 들숨이 차지하는 비율. 들숨은 이 위상에서 정점에 이르고 나머지는 날숨이다 || `breaths` | - | 1에서 8 | 루프에 들어맞는 정수 호흡 횟수 || `breath_peaks` | - | - | 각 들숨 정점 셀 목록 (외부 타이밍 조절용) |거부 조건은 다음과 같다.-- 허용 범위를 벗어난 값은 무시되지 않고 거부된다. pixel 행에 smooth 전용 형상 키(`chest_y`, `chest_rx`, `chest_ry`, `shoulder`, `shoulder_lag`, `chest_tilt`, `chest_bias`, `chest_bias_y`, `chest_dir`, `chest_x`, `chest_flat`)나 `breath_peaks`를 지정해도 무시되지 않고 거부된다.+- 허용 범위를 벗어난 값은 무시되지 않고 거부된다. pixel 행에 smooth 전용 형상 키(`chest_y`, `chest_rx`, `chest_ry`, `shoulder`, `shoulder_lag`, `chest_tilt`, `chest_bias`, `chest_bias_y`, `chest_dir`, `chest_x`, `chest_flat`, `inhale`)나 `breath_peaks`를 지정해도 무시되지 않고 거부된다.- 정점 P는 타원 내부에 머물러야 하므로, `chest_bias`와 `chest_bias_y`를 합쳐 반지름의 0.9를 초과하면 거부된다.- `breath_peaks`에 셀 0의 정점이 포함되거나, 정점이 증가하는 순서가 아니거나, 정점 간격이 2셀보다 가깝거나, 마지막 정점이 루프 끝에서 1셀 이내인 경우 거부된다. `breaths`가 함께 지정되었으나 정점 개수와 일치하지 않는 경우도 거부된다.- smooth 모드에 `lag`(pixel 모드의 진행파)를 지정하면 첫 셀을 움직이게 되므로 무시되지 않고 거부된다.@@ -60,7 +61,7 @@ smooth 모드의 고정 영역과 동작 방식은 다음과 같다.비디오 루프 셀처럼 큐레이션 실행이 아닌 프레임 폴더를 처리할 때는 독립 명령어를 사용한다.```bash-sprite-gen breathe <frames> <out> [--mode pixel|smooth] [--depth D] [--depth-x D] [--breaths N] [--breath-peaks ...] [--lag L] [--rigid-row R] [--chest-y ...] [--chest-rx ...] [--chest-ry ...] [--shoulder ...] [--shoulder-lag ...] [--chest-tilt ...] [--chest-bias ...] [--chest-bias-y ...] [--chest-dir ...] [--chest-x ...] [--chest-flat ...] [--avoid-region X0,Y0,X1,Y1 [--avoid-anchor X0,Y0,X1,Y1] [--fps F]]+sprite-gen breathe <frames> <out> [--mode pixel|smooth] [--depth D] [--depth-x D] [--breaths N] [--breath-peaks ...] [--lag L] [--rigid-row R] [--chest-y ...] [--chest-rx ...] [--chest-ry ...] [--shoulder ...] [--shoulder-lag ...] [--chest-tilt ...] [--chest-bias ...] [--chest-bias-y ...] [--chest-dir ...] [--chest-x ...] [--chest-flat ...] [--inhale S] [--avoid-region X0,Y0,X1,Y1 [--avoid-anchor X0,Y0,X1,Y1] [--fps F]]````<frames>`는 파일 이름 순서대로 재생되는 PNG 프레임 폴더다. 사이드카와 동일한 검증과 베이크 처리를 거치므로 같은 값이면 동일한 바이트를 출력한다. 변환된 프레임들을 원본과 동일한 이름으로 저장하고, 적용된 설정과 위상 및 해부학 측정값을 담은 `breathe.json`을 새 폴더에 한 번에 작성한다. 심볼릭 링크를 추적하고 대소문자를 구분하지 않는 디스크의 서로 다른 표기를 동일하게 취급하는 실제 위치를 기준으로, `<out>`과 `<frames>`가 같은 폴더이거나 어느 한쪽이 다른 쪽 내부에 있는 경우 및 이미 존재하면서 비어 있지 않은 폴더는 아무것도 생성하거나 삭제하지 않고 거부하되 기존의 빈 폴더는 허용한다. `<frames>` 폴더에는 어떤 파일도 새로 쓰지 않으며, 프레임을 비롯한 기존 파일을 변경하거나 삭제하지 않는다. 결과물은 `<out>` 옆에 다른 폴더와 겹치지 않는 고유한 이름의 자체 임시 폴더에서 빌드한 뒤 한 번에 제자리로 이동하며, 작업을 완료하지 못했을 때도 오직 직접 만든 임시 폴더만 삭제하고 이전 작업의 잔여 폴더처럼 직접 만들지 않은 폴더는 그대로 둔다.@@ -69,10 +70,10 @@ sprite-gen breathe <frames> <out> [--mode pixel|smooth] [--depth D] [--depth-x D- `--avoid-region`은 손의 사각형을 지정하며, 좌표는 그림 크기에 대한 0부터 1까지의 비율이다. `--avoid-anchor X0,Y0,X1,Y1`은 손 자체의 움직임을 읽을 기준 몸통 사각형을 지정한다. 생략하면 손의 열에서 손 높이의 0.65배만큼 위쪽부터 그림 높이의 0.02배만큼 위쪽까지의 띠를 쓴다.- 두 사각형은 첫 셀을 기준으로 동작 앵커와 같은 마스크 NCC를 쓰는 `auto_motion.track_box`로 추적한다. 각 프레임은 사각형에 탐색 반경을 더한 범위로 잘라 읽으며, 반경은 그림의 긴 변의 5%, 최소 8픽셀이다. 위치는 정수 픽셀이다. 손 자체의 상승량은 손의 상승량에서 몸통의 상승량을 뺀 값이며, 위쪽을 양수로 둔다.-- 후보 호흡 횟수는 한 번의 호흡이 1.5초부터 4초가 되도록 고른다. 따라서 `--fps` 또는 비디오 루프 `cycle/` 폴더의 프레임 시간이 필요하다. 먼저 정점을 균등하게 둔다. 선택된 횟수의 각 들숨 정점은 최대 3셀까지 옮겨 볼 수 있다. 호흡이 3번 이하면 정점을 각각 옮기고, 더 많으면 모두 함께 옮긴다. 곡선은 베이크와 같은 `smooth_wave`를 쓴다.+- 후보 호흡 횟수는 한 번의 호흡이 1.5초부터 4초가 되도록 고른다. 따라서 `--fps` 또는 비디오 루프 `cycle/` 폴더의 프레임 시간이 필요하다. 먼저 정점을 균등하게 둔다. 선택된 횟수의 각 들숨 정점은 최대 3셀까지 옮겨 볼 수 있다. 호흡이 3번 이하면 정점을 각각 옮기고, 더 많으면 모두 함께 옮긴다. 모든 후보는 그 행 자체의 `inhale` 곡선, 즉 베이크가 쓰는 것과 같은 `smooth_wave` 곡선으로 평가한다.- 점수는 호흡 곡선과 몸통 상승량의 상관에서 호흡 곡선과 손 자체의 상승량의 상관을 뺀 값이다. 각 들숨 정점의 앞뒤 2셀 안에서 가슴 상승량인 `lift x w`가 손 자체의 상승량보다 작지 않아야 한다. 조건을 만족하는 균등 후보 중 점수가 가장 높은 것을 고르며, 동점이면 호흡 횟수가 적은 것을 고른다. 정점을 옮긴 후보는 점수가 0.1보다 더 높을 때만 채택한다. 조건을 만족하는 후보가 없으면 조용히 박자를 고르지 않고 거부한다. 0.1의 차이와 기본 띠는 적은 수의 루프에서 정했으며, 루프가 늘면 다시 측정해야 한다.- 선택한 `breaths` 또는 `breath_peaks`는 사이드카 검사를 다시 거쳐 베이크된다. `breathe.json`의 `beat`에는 비율과 픽셀 단위의 사각형, 탐색 반경, 프레임 시간, 상승량, 셀별 손 자체의 상승량과 몸통 상승량, 선택 규칙의 수치가 기록된다. 모든 균등 후보의 호흡 횟수, 정점, 점수, 손과 몸통의 상관, `margin_px`, `keeps`와 가장 좋은 이동 정점 후보 및 `chosen`도 기록된다. `--avoid-region`이 없으면 이 과정은 실행되지 않고 `beat`도 쓰이지 않는다.-- `--avoid-region`은 `--breaths` 또는 `--breath-peaks`와 함께 쓸 수 없고, `pixel` 모드에서도 거부된다. `--avoid-anchor`와 `--fps`는 `--avoid-region` 없이 쓸 수 없다. 프레임 시간이 없거나 사각형을 추적할 수 없어도 거부된다. 이 `breathe.json`을 읽는 스웨이(Sway) 레이어는 같은 박자로 움직이며, 그 기록의 `drive`에는 선택된 `breaths` 또는 `breath_peaks`가 담긴다.+- `--avoid-region`은 `--breaths` 또는 `--breath-peaks`와 함께 쓸 수 없고, `pixel` 모드에서도 거부된다. `--avoid-anchor`와 `--fps`는 `--avoid-region` 없이 쓸 수 없다. 프레임 시간이 없거나 사각형을 추적할 수 없어도 거부된다. 이 `breathe.json`을 읽는 스웨이(Sway) 레이어는 같은 박자로 움직이며 그 `inhale`도 따른다. 그 기록의 `drive`에는 선택된 `breaths` 또는 `breath_peaks`와 `inhale`이 담긴다.비디오 루프 셀 처리 예시는 다음과 같다.diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 8605c4c..db967a4 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -1454,11 +1454,11 @@ A loop's strip holds at most 64 cells and 32,000 px across. Cells 960 px wide alA breathing idle can move its body only a pixel or two while its head stays still. Reading the outline turns that motion into whole-pixel steps; the damped mass answers those steps, so the part barely moves at its default settings or sways to the steps when pushed further. `--breathe <breathe.json>` drives the part from the Breathe layer's breath instead.-- **The record** is the `breathe.json` written beside breathed frames. It supplies config, phases and `resolved.anatomy`. Only `mode: smooth` is accepted; a pixel breath is refused because its travelling wave moves the first cell. The config passes `state_breathe` checks, `fit_breathe_pattern` recomputes the phases and compares them with the record, and `frames`, the phase count and the swayed cell count must agree. A hand-written record is checked the same way.-- **The drive** uses the Breathe layer's own functions. Chest lift is `lift x w`, where `w` is `smooth_wave`, from 0 at rest to 1 at the in-breath peak, and `lift = depth x (anatomy height - basis_row)` is given by `breathe.smooth_lift`. The part follows the late curve `w_late = smooth_shoulder_wave`, whose time is warped by `t - lag x sin(π t)`. Its offset is `gain x lift x (w - w_late)`, against the chest's rise in the record's `chest_dir`; 0 points straight up, so that offset points straight down.+- **The record** is the `breathe.json` written beside breathed frames. It supplies config, phases and `resolved.anatomy`. Its config's `inhale` is the in-breath share; a record without the key, as every record written before the key existed, reads as the default 0.40, as a sidecar that leaves it out does, so it sways exactly as before. Only `mode: smooth` is accepted; a pixel breath is refused because its travelling wave moves the first cell. The config passes `state_breathe` checks, `fit_breathe_pattern` recomputes the phases at the record's share and compares them with the record, so `breath_peaks` phases written at another share are accepted when they match, and `frames`, the phase count and the swayed cell count must agree. A hand-written record is checked the same way and can state the in-breath share of a breath made elsewhere.+- **The drive** uses the Breathe layer's own functions. Chest lift is `lift x w`, where `w` is `smooth_wave` at the record's in-breath share, from 0 at rest to 1 at the in-breath peak, and `lift = depth x (anatomy height - basis_row)` is given by `breathe.smooth_lift`. The part follows the late curve `w_late = smooth_shoulder_wave` at the same share, whose time is warped by `t - lag x sin(π t)`. Its offset is `gain x lift x (w - w_late)`, against the chest's rise in the record's `chest_dir`; 0 points straight up, so that offset points straight down.- **The rest** has `w = w_late = 0`, so the first cell, rests between breaths and the close have zero offset. On a synthetic loop, the step across the close is 3-4% of the largest inner step. The body's outline still determines each cell's carried ellipse.- **The lag** is a share of one breath, above 0 and below `1/π`; its default is 0.15. At `1/π` warped time stops, and beyond it runs backwards. On a synthetic 144-cell loop at 24 fps with two breaths, lags 0.1, 0.15 and 0.2 reach 0.28, 0.44 and 0.59 of lift at gain 1. The part peaks 7, 11 and 14 cells late, or 0.29, 0.46 and 0.58 s. Reach depends on lag rather than breath length.-- **The settings and record** use a default `--gain` of 1 on the breath, against 2.5 on body motion. `--freq` and `--zeta` are refused with `--breathe`; `--fps` is refused with `--breathe --frames`; `--lag` requires `--breathe`. The record's `drive` carries `kind: breath`, `breathe_sha256`, `lag`, `lift_px`, `heading_deg`, and `breaths` or `breath_peaks` in place of `freq_hz`, `zeta` and `harmonics`. Its way is `common-lay/breath-late/cos2-bilinear/1`. `--loop-dir` also accepts this drive when its strip has one cell per phase.+- **The settings and record** use a default `--gain` of 1 on the breath, against 2.5 on body motion. `--freq` and `--zeta` are refused with `--breathe`; `--fps` is refused with `--breathe --frames`; `--lag` requires `--breathe`. The record's `drive` carries `kind: breath`, `breathe_sha256`, `lag`, `lift_px`, `heading_deg`, `inhale`, and `breaths` or `breath_peaks` in place of `freq_hz`, `zeta` and `harmonics`. Its way is `common-lay/breath-late/cos2-bilinear/1`. `--loop-dir` also accepts this drive when its strip has one cell per phase.```bashsprite-gen breathe <cycle> <breathed> --mode smooth --breaths 2