Skip to content

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

docs(breathe): the breath's size as strength or width and height minimum and maximum, in docs/breathing.md and the CHANGELOG's Unreleased

Soohong Kim6ce998eafbc2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41f10f3..534c656 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased
+
+**Upgrading from 3.6.0: a Breathe row's breath can now be sized by the two ends it travels between, across and up, instead of a strength (`width_min`, `width_max`, `height_min`, `height_max`; flags `--width-min`, `--width-max`, `--height-min`, `--height-max`). Every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar; the curator's breathe editor shows four range inputs in place of the two depth selects.**
+
+- **New: a breath's width and height as minimum and maximum (pixel and smooth).** Each is a share of the original. Width is how much the torso widens at the row where the breath is fullest (pixel: the row where the envelope peaks; smooth: the chest's peak P), negative narrower. Height is how far the head top (pixel) or the chest (smooth) rises, as a share of the body below the neck, negative down. Each lies in -0.20 to 0.20 with minimum at most maximum; a bound left out is 0, and null is left out. A minimum of 0 keeps the breath from going under the original size. The curve's shape and beat (`breaths`, `breath_peaks`, `lag`, `inhale`) are unchanged. In pixel, one gain widens a row by 1 + g and shortens it by 1 / (1 + g), so the top of the curve is (`width_max`, `height_min`) and its bottom is (`width_min`, `height_max`). In smooth, rest is at both minimums and the top of the in-breath is at both maximums, so a minimum other than 0 moves the rest cell off the source.
+- A strength converts exactly. A pixel row of `depth` d has height [-0.9009 d, 0.9009 d] (0.9009 is the breath curve's peak, `breathe.WAVE_PEAK`) and width [-a, a], with a = 0.9009 × `depth_x` (or `depth`) × the amplitude norm × the envelope's peak; a smooth row has height [0, `depth`] and width [0, `depth_x`]. Written as minimum and maximum, these bake the same bytes. `sprite-gen breathe` records the row's `range` (`{"width": [min, max], "height": [min, max]}`) in `breathe.json` for that conversion. Pixel rows move whole rows and columns, so the extremes measured on a plate are within one cell of the values written.
+- Refused, not silently resolved: a row with both a strength (`depth`, `depth_x`) and minimum or maximum keys, a value out of range or not a number (booleans included), a minimum above its maximum, and minimum or maximum keys on a round chest row. The row strain limit (0.25) is checked at the largest gain the curve reaches, and its refusal names the keys to reduce. The pixel clip refusal now says to reduce the breath's size (depth, or minimum and maximum) where it said depth.
+- Python callers: `breathe.WAVE_PEAK`, `breathe.envelope_peak`, `breathe.pixel_gains`, `breathe.breathe_range`, `curation.BREATHE_RANGE_KEYS`, `curation.BREATHE_RANGE_MAX`. `breathe.smooth_lift` is the chest's rise from rest to the top, which `video-sway --breathe` and `--avoid-region` read: (`height_max` - `height_min`) × the basis height for a minimum and maximum row.
+- **Curator**: the breathe editor's two depth selects are four inputs (width minimum to maximum, height minimum to maximum, in %, 0.1 % steps, -20 to 20). A strength row shows the range its strength travels; editing one input moves the row to the four keys, the untouched ones carried at their exact values so that axis bakes the same bytes. The inputs are off for a round chest row and, on a pixel strength row, until the anatomy arrives. Loading a sidecar now keeps a strength row's `depth_x`, `axis_x` and `torso_half`, which the first autosave dropped before. A new row inherits a sibling row's minimum and maximum keys as it inherited a depth. The preview mirror bakes minimum and maximum rows byte for byte as the bake does.
+- **Tests**: `tests/effects/test_breathe_min_max.py` (synthetic figures: strength rows keep their bytes and normalized sidecar; minimum 0 is never narrower nor taller on any row or phase; the written extremes are what the plate measures, within one cell; a strength's range written as minimum and maximum bakes its bytes; smooth from 0 is the old smooth; refusals and the strain limit), new cases in `tests/effects/test_breathe_js_mirror.py` (minimum and maximum parity, `breatheRange`), the value-shape matrix over the four keys and the kept `depth_x` and band in `tests/effects/test_breathe_sidecar_roundtrip.py`, and the mirrored constants in `tests/effects/test_breathe_reference_key.py`.
+
## v3.6.0 - Two step walk and run loop cuts with half step warnings, loop search past untracked anchor frames, body turn loop exclusion, round chest breathing with sideways arms, and sway region mass movement
**Upgrading from 3.5.0: `video-loop` walk and run cuts change for two-step cuts and half steps under `--anchor motion-auto`, opening frames the motion anchor cannot track, and body turns, while new `sprite-gen breathe` and `video-sway` options are off by default.** In `video-loop`, a walk or run cut shorter than its state's gait floor, its steps not counted, is now cut two steps long under `--anchor motion-auto` where the clip as filmed comes back nearer two lengths on than one, and says so where it does not (`cycle.half_step` and a warning line); every other cut keeps every byte. A walk or run whose first frames the automatic motion anchor cannot track is now searched after them, as after a lead-in, where it was refused; every clip the anchor tracks from its first frame keeps every cut and byte. A clip whose cut held a turn is now cut where a window without the turn holds a cycle, while clips with no turn, clips that are not read, and clips with a turn and no turn-free cycle under `warn` keep every cut and byte. A pixel Breathe row can now breathe round from the chest, with the arms moving sideways (`chest_round`, `arms_x`), and `sprite-gen breathe` takes cells held still (`--hold-mask`), what the arms hold (`--props-mask`), pieces held behind the body (`--props-behind-mask`), and props grouping (`--props-groups`). All are off by default: every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar. `video-sway` can move each region as one mass with `--band`. When `--band` is left out, strips, frames, and records remain byte for byte what they were. Passing `--band PX|auto` moves each region's ellipse and an outer margin at full weight, with the weight falling to 0 by cos² over a band of pixels around it, while carrying the region by its own pixels rather than the body's outline lay. The fifth region number `flat` and `--stretch-floor` are refused when `--band` is specified. In the strip's metadata, `follow` gains `band` (and `sway.json` gains `band` for `--frames`), while stdout JSON gains `band` with `band_px`, `margin_px`, and `lay_cells`. The legacy command name `video-follow` accepts the same flags. `video-sway --band` can now hold pixels with `--hold-mask`, leaving them as they are while regions move round them. It is off by default, and when not given, strips, frames, and records remain byte for byte as before. `video-sway` can now move a region's own pixels with `--region-mask`, holding every visible pixel outside it and its soft edge while the weight falls over an inner rim read off the move. It is off by default, and when not given, strips, frames, and records remain byte for byte what they were (with `--band`, with `--band` and `--hold-mask`, and with neither).
diff --git a/docs/breathing.md b/docs/breathing.md
index 0cdb088..b0c6045 100644
--- a/docs/breathing.md
+++ b/docs/breathing.md
@@ -10,7 +10,7 @@ Breathe 레이어는 큐레이션 사이드카의 행마다 `states.<state>.brea
- `pixel`: 기본값이다 (`mode` 키를 생략하거나 `"pixel"`로 지정). 픽셀 아트를 위한 모드로, 정수 행과 열 단위의 워프를 사용해 픽셀 그리드를 온전히 유지한다. 출력 바이트와 정규화된 사이드카는 기존과 동일하며 기본 동작도 바뀌지 않았다. 작은 스프라이트와 픽셀 아트에 적합하다.
- `smooth`: 대형 일러스트, 채색된 캐릭터, 비디오 프레임에 사용한다. 픽셀 워프를 적용했을 때 몸통과 함께 머리 전체가 들리거나, 복제된 행이 셀 사이에서 깜빡임(flicker)으로 읽히는 문제를 해결한다.
-`pixel`은 늘어난 내용이 셀의 위쪽, 왼쪽, 오른쪽 밖으로 나가면 자르지 않고 굽기를 거부한다. 거부 메시지는 넘어간 변마다 셀 밖의 불투명 픽셀 수를 밝히며, 모서리 밖의 픽셀은 두 변에 모두 센다. 넘어간 변이 그림 자체의 테두리인지도 굽는 프레임에서 읽는다. 바깥 행이나 열을 그림이 그 변 길이의 2% 이상 덮으면 테두리로 본다([docs/video-pipeline.md](video-pipeline.md) 3절). 이때 메시지는 그림이 그 변에서 덮는 픽셀 수를 밝히고, 프레임에 잘린 큰 그림이나 비디오 셀에는 머리와 프레임 가장자리가 제자리에 남는 `--mode smooth`(사이드카에서는 `mode: "smooth"`)를 안내한다. 셀에 여백을 더해 구운 뒤 다시 자르면 밖으로 밀린 부분이 알림 없이 사라지므로 그렇게 처리하지 않는다. 픽셀 스프라이트에는 셀 여백을 넓히거나 `depth`를 낮추라고 안내하며, 큐레이터 미리보기도 같은 프레임을 같은 문구로 거부한다. 프레임의 왼쪽이나 오른쪽에 닿은 소매는 `pixel`의 가로 늘림에서 셀 밖으로 밀려 거부될 수 있고, 내쉬는 단계에서는 안으로 당겨져 가장자리에 틈이 생긴다. 아래쪽에 닿은 그림에서는 1 px 윤곽선 가늘게 만들기가 잘린 단면을 윤곽선으로 읽어 변형된 프레임의 픽셀 몇 개를 지울 수 있다.
+`pixel`은 늘어난 내용이 셀의 위쪽, 왼쪽, 오른쪽 밖으로 나가면 자르지 않고 굽기를 거부한다. 거부 메시지는 넘어간 변마다 셀 밖의 불투명 픽셀 수를 밝히며, 모서리 밖의 픽셀은 두 변에 모두 센다. 넘어간 변이 그림 자체의 테두리인지도 굽는 프레임에서 읽는다. 바깥 행이나 열을 그림이 그 변 길이의 2% 이상 덮으면 테두리로 본다([docs/video-pipeline.md](video-pipeline.md) 3절). 이때 메시지는 그림이 그 변에서 덮는 픽셀 수를 밝히고, 프레임에 잘린 큰 그림이나 비디오 셀에는 머리와 프레임 가장자리가 제자리에 남는 `--mode smooth`(사이드카에서는 `mode: "smooth"`)를 안내한다. 셀에 여백을 더해 구운 뒤 다시 자르면 밖으로 밀린 부분이 알림 없이 사라지므로 그렇게 처리하지 않는다. 픽셀 스프라이트에는 셀 여백을 넓히거나 숨의 크기(`depth`, 또는 아래 "숨의 크기" 절의 최소와 최대)를 줄이라고 안내하며, 큐레이터 미리보기도 같은 프레임을 같은 문구로 거부한다. 프레임의 왼쪽이나 오른쪽에 닿은 소매는 `pixel`의 가로 늘림에서 셀 밖으로 밀려 거부될 수 있고, 내쉬는 단계에서는 안으로 당겨져 가장자리에 틈이 생긴다. 아래쪽에 닿은 그림에서는 1 px 윤곽선 가늘게 만들기가 잘린 단면을 윤곽선으로 읽어 변형된 프레임의 픽셀 몇 개를 지울 수 있다.
smooth 모드의 고정 영역과 동작 방식은 다음과 같다.
- 머리와 강체 경계(해부학 측정이 찾은 목 라인) 위의 모든 픽셀은 모든 셀에서 바이트 단위로 제자리를 유지한다. 인물 하단 역시 제자리에 고정된다.
@@ -53,6 +53,8 @@ smooth 모드의 고정 영역과 동작 방식은 다음과 같다.
| `breath_peaks` | - | - | 각 들숨 정점 셀 목록 (외부 타이밍 조절용) |
| `chest_round` | 0 (꺼짐) | 0에서 0.20 | pixel 둥근 가슴: 들숨 정점에서 가슴 테두리가 꼭대기 P 에서 바깥으로 나가는 양 (목 아래 몸통 높이 비율, 아래 "둥근 가슴" 절) |
| `arms_x` | 0 (꺼짐) | 0에서 0.20 | pixel 둥근 가슴: 들숨 정점에서 팔이 몸 바깥쪽으로 가로로 통째 밀리는 양 (목 아래 몸통 높이 비율) |
+| `width_min`, `width_max` | - (세기를 쓴다) | -0.20에서 0.20 | 숨의 크기를 세기 대신 양 끝으로 적는다: 몸통 가로의 최소와 최대 (아래 "숨의 크기" 절). 두 모드 공통 |
+| `height_min`, `height_max` | - (세기를 쓴다) | -0.20에서 0.20 | 같은 방식의 세로 최소와 최대. `depth`, `depth_x`와 같이 적으면 거부된다 |
거부 조건은 다음과 같다.
- 허용 범위를 벗어난 값은 무시되지 않고 거부된다. 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`, 또는 역시 smooth 전용인 `start_cell`과 `loop_cells`를 지정해도 무시되지 않고 거부된다. 예외는 둥근 가슴 pixel 행(`chest_round`나 `arms_x`가 0보다 큼)이다. 이 행은 가슴 타원 키(`chest_y`, `chest_rx`, `chest_ry`, `chest_tilt`, `chest_bias`, `chest_bias_y`, `chest_x`)와 `inhale`, `breath_peaks`, `start_cell`, `loop_cells`를 smooth 와 같은 검사로 받는다.
@@ -60,6 +62,7 @@ smooth 모드의 고정 영역과 동작 방식은 다음과 같다.
- 정점 P는 타원 내부에 머물러야 하므로, `chest_bias`와 `chest_bias_y`를 합쳐 반지름의 0.9를 초과하면 거부된다.
- `breath_peaks`에 셀 0의 정점이 포함되거나, 정점이 증가하는 순서가 아니거나, 정점 간격이 2셀보다 가깝거나, 마지막 정점이 루프 끝에서 1셀 이내인 경우 거부된다. `breaths`가 함께 지정되었으나 정점 개수와 일치하지 않는 경우도 거부된다.
- smooth 모드에 `lag`(pixel 모드의 진행파)를 지정하면 첫 셀을 움직이게 되므로 무시되지 않고 거부된다.
+- 세기(`depth`, `depth_x`)와 최소, 최대(`width_min`, `width_max`, `height_min`, `height_max`)를 한 행에 같이 적으면 어느 쪽을 따를지 고르지 않고 거부한다. 최소가 최대보다 큰 축, 수가 아닌 값(참거짓 포함)도 거부한다.
- 행별 변형 한도(0.25)를 넘는 신장, 접히는(fold) 변위장, 불투명 픽셀이 캔버스 밖으로 밀려나는 경우는 조용히 한도 내로 자르지 않고 즉시 거부한다.
- 기본 형상에서는 가슴 가중치가 몸체 내부에서 0으로 떨어지므로, 인물이 화면 가장자리나 하단에서 잘려 있어도 거부되지 않으며 픽셀이 손실되지 않는다.
- 합성한 960 x 960 셀을 Apple M1에서 측정한 굽기 시간은 셀당 `smooth` 약 0.1초, 1 px 윤곽선이 있는 그림의 `pixel` 약 0.05초다. PNG 읽기와 쓰기는 측정에서 제외했다.
@@ -67,13 +70,33 @@ smooth 모드의 고정 영역과 동작 방식은 다음과 같다.
비디오 루프 셀처럼 큐레이션 실행이 아닌 프레임 폴더를 처리할 때는 독립 명령어를 사용한다.
```bash
-sprite-gen breathe <frames> <out> [--mode pixel|smooth] [--depth D] [--depth-x D] [--breaths N] [--breath-peaks ...] [--lag L] [--rigid-row R] [--axis-x X] [--torso-half T] [--chest-y ...] [--chest-rx ...] [--chest-ry ...] [--shoulder ...] [--shoulder-lag ...] [--chest-tilt ...] [--chest-bias ...] [--chest-bias-y ...] [--chest-dir ...] [--chest-x ...] [--chest-flat ...] [--inhale S] [--loop-cells N] [--start-cell K] [--reference FRAME.png] [--avoid-region X0,Y0,X1,Y1 [--avoid-anchor X0,Y0,X1,Y1] [--fps F]] [--chest-round S] [--arms-x S] [--hold-mask MASK.png] [--props-mask MASK.png] [--props-behind-mask MASK.png] [--props-groups piece|colour]
+sprite-gen breathe <frames> <out> [--mode pixel|smooth] [--depth D] [--depth-x D] [--width-min W] [--width-max W] [--height-min H] [--height-max H] [--breaths N] [--breath-peaks ...] [--lag L] [--rigid-row R] [--axis-x X] [--torso-half T] [--chest-y ...] [--chest-rx ...] [--chest-ry ...] [--shoulder ...] [--shoulder-lag ...] [--chest-tilt ...] [--chest-bias ...] [--chest-bias-y ...] [--chest-dir ...] [--chest-x ...] [--chest-flat ...] [--inhale S] [--loop-cells N] [--start-cell K] [--reference FRAME.png] [--avoid-region X0,Y0,X1,Y1 [--avoid-anchor X0,Y0,X1,Y1] [--fps F]] [--chest-round S] [--arms-x S] [--hold-mask MASK.png] [--props-mask MASK.png] [--props-behind-mask MASK.png] [--props-groups piece|colour]
```
`<frames>`는 파일 이름 순서대로 재생되는 PNG 프레임 폴더다. 사이드카와 동일한 검증과 베이크 처리를 거치므로 같은 값이면 동일한 바이트를 출력한다. 변환된 프레임들을 원본과 동일한 이름으로 저장하고, 적용된 설정과 위상 및 해부학 측정값을 담은 `breathe.json`을 새 폴더에 한 번에 작성한다. 심볼릭 링크를 추적하고 대소문자를 구분하지 않는 디스크의 서로 다른 표기를 동일하게 취급하는 실제 위치를 기준으로, `<out>`과 `<frames>`가 같은 폴더이거나 어느 한쪽이 다른 쪽 내부에 있는 경우 및 이미 존재하면서 비어 있지 않은 폴더는 아무것도 생성하거나 삭제하지 않고 거부하되 기존의 빈 폴더는 허용한다. `<frames>` 폴더에는 어떤 파일도 새로 쓰지 않으며, 프레임을 비롯한 기존 파일을 변경하거나 삭제하지 않는다. 결과물은 `<out>` 옆에 다른 폴더와 겹치지 않는 고유한 이름의 자체 임시 폴더에서 빌드한 뒤 한 번에 제자리로 이동하며, 작업을 완료하지 못했을 때도 오직 직접 만든 임시 폴더만 삭제하고 이전 작업의 잔여 폴더처럼 직접 만들지 않은 폴더는 그대로 둔다.
`--axis-x X`와 `--torso-half T`는 사이드카의 `axis_x`·`torso_half`(큐레이터 영역 UI 가 쓰는 사람의 오버라이드)와 같은 값이다. 몸통 축 열과 몸통 반폭을 주면 그 반폭 밖의 열이 부속(팔)이 된다. 둘 다 생략하면 이전과 같이 잰다.
+## 숨의 크기: 세기, 또는 가로와 세로의 최소와 최대
+
+숨이 얼마나 크게 오가는지는 두 방식 중 하나로 적는다. 곡선의 모양과 박자(`breaths`, `breath_peaks`, `lag`, `inhale`)는 어느 방식이든 같고, 크기를 적는 법만 다르다.
+
+- 세기: `depth`와 `depth_x`(CLI `--depth`, `--depth-x`). pixel은 원래 크기를 가운데 두고 양쪽으로 같은 만큼 오가고, smooth는 쉼(원본)에서 들숨 꼭대기까지 오른다. 기존 방식이며 출력 바이트는 바뀌지 않았다.
+- 가로와 세로 최소와 최대: `width_min`, `width_max`, `height_min`, `height_max`(CLI `--width-min`, `--width-max`, `--height-min`, `--height-max`). 숨이 오가는 양 끝을 원본 대비 비율로 직접 적는다. 0이 원래 크기라 최소를 0으로 두면 숨이 원본보다 작아지지 않는다.
+
+단위는 다음과 같다.
+- 가로: 숨이 가장 큰 행에서 몸통이 원래 폭보다 넓어지는 몫이다. pixel은 봉투가 가장 큰 행, smooth는 가슴이 부푸는 정점 P다. 음수는 좁아짐이다.
+- 세로: 목 아래 몸 높이(기준 행 아래) 대비 pixel은 머리 끝이, smooth는 가슴이 올라가는 몫이다. 음수는 내려감이다.
+- 범위는 -0.20에서 0.20이고 축마다 최소 ≤ 최대다. 적지 않은 경계는 0이고 null은 적지 않은 것과 같다.
+
+두 끝이 곡선의 어디에 놓이는지는 모드마다 다르다.
+- pixel: 같은 이득이 행을 가로로 1 + g 배, 세로로 1 / (1 + g) 배 하므로 몸통은 넓어질 때 낮아진다. 곡선 꼭대기에서 가로는 `width_max`, 세로는 `height_min`이고, 바닥에서 가로는 `width_min`, 세로는 `height_max`다. 행마다 이득은 봉투를 따라 줄고 진행파 지연(`lag`)도 그대로다.
+- smooth: 쉼(곡선 0)이 두 최소, 들숨 꼭대기가 두 최대다. 최소가 0이 아니면 쉼 칸도 원본에서 그만큼 옮겨지므로 위상 0 칸이 원본 바이트가 아니다.
+
+세기로 적은 줄과 최소와 최대로 적은 줄은 서로 옮겨 적을 수 있다. 세기 d인 pixel 줄은 세로 [-0.9009 d, 0.9009 d], 가로 [-a, a]와 같다. 0.9009는 숨 곡선의 꼭대기 값(`WAVE_PEAK`)이고, a는 0.9009 × `depth_x`(생략하면 `depth`) × 진폭 정규화 계수 × 봉투 최대다. smooth 세기 줄은 세로 [0, `depth`], 가로 [0, `depth_x`]와 같다. 이 값을 최소와 최대로 적으면 같은 바이트가 구워진다. `sprite-gen breathe`는 `breathe.json`의 `range`에 그 줄의 `{"width": [최소, 최대], "height": [최소, 최대]}`를 적는다. 세기로 구운 판을 최소와 최대로 옮길 때는 이 수를 그대로 쓴다. pixel은 정수 행과 열로 옮기므로 구운 판에서 잰 극값은 적은 값과 한 칸 안에서 맞는다.
+
+행별 변형 한도(0.25)는 곡선이 닿는 가장 큰 이득으로 검사하고, 넘으면 줄일 키(`width_min`, `width_max` 또는 `height_min`, `height_max`)를 밝혀 거부한다. Sway 레이어(`video-sway --breathe`)와 박자 고르기(`--avoid-region`)는 smooth 가슴이 쉼에서 꼭대기까지 오르는 폭, 곧 (`height_max` - `height_min`) × 기준 높이를 읽는다.
+
`--reference FRAME.png`(모든 모드)를 주면 행의 해부학 측정값(머리 선, 가슴, 상승 높이, 프레임 안에서 해부학이 차지하는 위치)을 행의 첫 프레임 대신 그 프레임에서 측정한다. 프레임들과 같은 크기여야 하며 다르면 거부된다. 루프 세트의 첫 셀을 지정하면, 첫 프레임이 루프와 다른 토막(예: 머리를 든 상태로 시작하는 경우)도 루프의 해부학으로 베이크된다. 이때 `breathe.json`에는 그 파일의 `path`와 `sha256`을 담은 `reference`가 기록된다. 예를 들어 두 번 호흡하는 96셀 루프의 셀 40에서 시작하는, 루프에서 빠져나가는 토막은 다음과 같이 베이크한다.
```bash
@@ -107,7 +130,7 @@ pixel 의 봉투 스쿼시는 가로줄을 통째로 눌렀다 늘인다. 머리
- 팔: 부속 경계(봉투 스쿼시의 부속 보호가 시작하는 자리 — 사람이 준 `torso_half`면 그 반폭, 아니면 해부가 잰 몸통 반폭의 1.15배) 바깥의 열은 가슴이 미는 대로 통째로 밀리고, 거기에 더해 몸통 축에서 먼 쪽으로 `arms_x` × 기준 높이 px 만큼 가로로 통째 간다. 팔은 늘지 않는다. 팔 몫이 켜지는 길은 팔이 아니라 몸통 쪽에 둔다. 부속 경계 안쪽으로 그 px 의 12배(몸통 축을 넘지 않는다)에 걸쳐 옆구리가 팔을 따라 벌어진다. 더 짧으면 어깨가 행당 상한을 넘게 늘어난다. 해부가 부속을 못 찾았고 `torso_half`도 주지 않았으면 팔 몫은 없다. 팔이 몸통 실루엣 안에 붙어 있으면 `torso_half`로 몸통 반폭을 주거나, 팔이 쥔 것을 `--props-mask`로 준다.
- 숨: smooth 와 같은 한쪽 혹 곡선이고 `inhale`, `breaths`, `breath_peaks`, `loop_cells`, `start_cell`을 같은 뜻으로 받는다. 위상 0인 셀은 원본과 바이트 단위로 같아서 루프 이음이 쉼에 놓인다. 진행파(`lag`)는 없다.
- 정수 칸: 정사상의 역을 고정점 반복으로 풀고, 그 자리에 놓인 원본 칸 하나를 통째로 옮긴다. 사잇값이 없어서 출력의 칸은 모두 원본에 있던 칸이고 새 색이 생기지 않는다. 장의 기울기가 행당 변형 상한(0.25) 아래라 어느 행과 열에서도 칸 순서가 뒤집히지 않는다.
-- 거부: smooth 행의 `chest_round`, `arms_x`, 둥근 가슴 행의 `depth`, `depth_x`, `lag`(봉투 값), smooth 만 쓰는 모양 값(`shoulder`, `shoulder_lag`, `chest_dir`, `chest_flat`), 범위 밖 값, 행당 변형 상한 초과, 셀 밖으로 밀리는 불투명 칸, 그리고 해부가 팔(부속)을 못 찾았고 쥔 물건도 없는데 준 `arms_x`는 모두 조용히 넘기지 않고 거부된다. 몸 자체의 셀 밖 거부는 고정 칸이나 조각 칸을 빼고 몸 칸만 세며 pixel 봉투 거부와 같은 형식(`왼쪽 변 밖 3`, 모서리 칸은 양쪽 변 모두에 셈)으로 건넌 변과 그 수를 밝힌다. 조각이 셀 밖으로 밀리는 경우, 무엇이든 그리기 전에 각 조각을 자신의 온전한 칸 목적지(조각의 칸에 조각이 움직이는 온전한 칸 수를 더한 자리)에서 검사한다. 이 거부는 마스크 플래그, 조각의 i/n과 칸 수, 벗어난 불투명 칸 수, pixel 봉투 거부와 같은 형식(`왼쪽 변 밖 3`, 모서리 칸은 양쪽 변 모두에 셈)으로 건넌 변과 그 수, 셀 크기, 조각의 이동량을 밝히고, 셀 여백을 넓히거나 `chest_round` 또는 `arms_x`를 줄이라고 안내한다. 이는 몸 뒤 조각(장이 건너뜀), 머리선 위처럼 몸이 온전히 따르지 않는 행의 조각, 그리고 둥글림 가장자리를 포괄한다.
+- 거부: smooth 행의 `chest_round`, `arms_x`, 둥근 가슴 행의 `depth`, `depth_x`, `lag`, `width_min`, `width_max`, `height_min`, `height_max`(봉투 값), smooth 만 쓰는 모양 값(`shoulder`, `shoulder_lag`, `chest_dir`, `chest_flat`), 범위 밖 값, 행당 변형 상한 초과, 셀 밖으로 밀리는 불투명 칸, 그리고 해부가 팔(부속)을 못 찾았고 쥔 물건도 없는데 준 `arms_x`는 모두 조용히 넘기지 않고 거부된다. 몸 자체의 셀 밖 거부는 고정 칸이나 조각 칸을 빼고 몸 칸만 세며 pixel 봉투 거부와 같은 형식(`왼쪽 변 밖 3`, 모서리 칸은 양쪽 변 모두에 셈)으로 건넌 변과 그 수를 밝힌다. 조각이 셀 밖으로 밀리는 경우, 무엇이든 그리기 전에 각 조각을 자신의 온전한 칸 목적지(조각의 칸에 조각이 움직이는 온전한 칸 수를 더한 자리)에서 검사한다. 이 거부는 마스크 플래그, 조각의 i/n과 칸 수, 벗어난 불투명 칸 수, pixel 봉투 거부와 같은 형식(`왼쪽 변 밖 3`, 모서리 칸은 양쪽 변 모두에 셈)으로 건넌 변과 그 수, 셀 크기, 조각의 이동량을 밝히고, 셀 여백을 넓히거나 `chest_round` 또는 `arms_x`를 줄이라고 안내한다. 이는 몸 뒤 조각(장이 건너뜀), 머리선 위처럼 몸이 온전히 따르지 않는 행의 조각, 그리고 둥글림 가장자리를 포괄한다.
### 고정 칸, 쥔 물건, 등 뒤 물건, 묶음: `--hold-mask`, `--props-mask`, `--props-behind-mask`, `--props-groups`
@@ -148,10 +171,10 @@ The same deterministic bake applies to front, side, and back views of any silhou
- **에이전트 주도 호흡** (사용자가 "숨쉬기 적용해서 뽑아줘" 라고만 해도 됨): 호흡은 사이드카 필드라 뷰 없이도 켤 수 있다 — (1) `states.<state>.breathe = {"depth": 0.06, "breaths": 1, "lag": 0.1}` 만 쓰면 된다. **경계는 선언하지 않는다** — `sprite_gen/anatomy.py` 가 검출한다. 큐레이터를 거치면 그 결과가 사이드카 `anatomy` 에 얼려지고(`GET /api/breathe-anatomy`), 뷰 없이 에이전트가 `breathe` 만 쓴 런은 `anatomy` 가 비어 있어 **굽기가 매번 다시 잰다** — 굽기는 사이드카에 쓰지 않는다. 어느 쪽이든 동작한다. **굽기는 얼린 값을 신뢰하지 않는다 — 언제나 자기 기준 프레임에서 다시 잰다** (얼린 값은 큐레이터 프리뷰용 캐시다). 사이드카와 어긋나면 manifest 의 `sidecar_drift` 로 값을 실어 보고한다. 그 캐시가 아직 유효한지는 기준 프레임의 **입력** 지문(원본 파일 스탬프·픽셀편집·변형·변종)으로 판정하고, 어긋나면 큐레이터가 프리뷰·영상 내보내기를 **거부하며 갱신하라고 알린다** — 조용히 낡은 숫자로 그리지 않는다. 사람이 특정 행에 고정하고 싶을 때만 `rigid_row` 를 준다. (에이전트 직접 쓰기는 `load_curation`→`stamp_curation` 도장 경로 필수, 열린 탭은 새로고침 안내 — 함정 상세: [`troubleshooting.md`](troubleshooting.md)), (2) `compose_sprite_gif.py`/`compose_sprite_atlas.py` 가 자동으로 굽는다. 검증: gif-manifest 의 `breathe.phases`. **구 `splits`/`amplitude`/`subpixel` 은 요란하게 거부된다** — 옮기려면 `sprite-gen migrate-breathe <run-dir> --apply`.
- **정지 자세(sit/lie/carry_idle 등) 행 레시피** — 정지 1컷 + 링크 복제 @ 4fps + 허리선 호흡(breaths 3) + 눈 보이는 방향만 깜빡임. **복제 수 = `recommended_breathe_frames(breathe) − 1`** (호흡당 `SMOOTH_CYCLE_FRAMES`=6 프레임 확보; breaths 3 → 총 18컷) — 짧은 루프(옛 11컷)에 다수 호흡을 우겨넣으면 1px 위상이 매 프레임 토글해 진동으로 읽히던 걸 막는다 (maintainer 2026-07-24). 깜빡임은 **시퀀스 끝 근처**(맨 끝 아님, 뒤에 눈뜬 rest ≥2)에 배치해 루프 이음새 전에 다시 떠 스냅을 없앤다. 실측 도출 근거·자동 적용 절차·프레임 게이트: 아래 "정지 자세(Static-Pose) 행 레시피" 절 (maintainer 확정 2026-07-19, 이징 게이트 2026-07-24).
-- 호흡(idle breathing)은 **후처리 레이어**다 (maintainer 확정 2026-07-18) — 스크립트가 아니라 curation.json 사이드카 `states.<state>.breathe = {depth, depth_x?, breaths, lag, rigid_row?, anatomy}` 로 선언하고, compose/GIF 가 재생 시퀀스 위에 결정론(봉투 워프, `sprite_gen/breathe.py`)으로 굽는다. 깜빡임 프레임도 그대로 숨쉰다 (프레임 선택과 직교).
+- 호흡(idle breathing)은 **후처리 레이어**다 (maintainer 확정 2026-07-18) — 스크립트가 아니라 curation.json 사이드카 `states.<state>.breathe = {depth, depth_x?, breaths, lag, rigid_row?, anatomy}`(세기 대신 `width_min`, `width_max`, `height_min`, `height_max` 도 된다. "숨의 크기" 절) 로 선언하고, compose/GIF 가 재생 시퀀스 위에 결정론(봉투 워프, `sprite_gen/breathe.py`)으로 굽는다. 깜빡임 프레임도 그대로 숨쉰다 (프레임 선택과 직교).
- **변형은 자르지 않고 강도를 떨군다** (2026-07-25 교체): 스프라이트 전체에 연속 변형장을 걸고 그 강도를 강체 경계에서 0 으로 테이퍼한다. `env=0` 인 행은 가로 사상이 항등이고 세로 누적이 정확히 1씩 늘어 **그 구간이 프레임 간 비트 동일**하다 — 눈·입이 몇 도트뿐이라 근사로는 표정이 뭉갠다. 가로는 행 안에서 밀도를 적분하므로 사상이 단조라 접힘이 없고, 날개 같은 부속은 밀리기만 하고 안 늘어난다.
- **강체 경계는 가슴이 아니라 목이다.** 가슴은 해부학 개념이라 몬스터마다 다르지만 목은 기하학적 병목이라 안정적으로 잡힌다. 얼굴이 몸통에 있는 버섯, 슬라임은 대칭 눈쌍을 찾아 경계를 얼굴 아래로 내린다. 기존 탐색에서 눈쌍을 찾지 못하면 같은 어두운 픽셀을 다시 살피되, 최소 눈 면적은 목 위 불투명 픽셀의 0.2%, 눈의 너비 대 높이 상한은 3.0, 눈 중심과 몸통 축 사이의 최소 거리는 내용 너비의 0.02로 둔다. 프레임을 채운 흉상의 작은 눈, 4분의 3 방향 얼굴에서 가는 선처럼 보이는 먼쪽 눈, 긴 머리 때문에 먼쪽 눈에 가까워진 몸통 축을 읽기 위한 탐색이며, 두 눈이 축의 양쪽에 있고 쌍의 중심이 축에 가까우며 간격과 크기와 행 겹침이 맞아야 하는 조건은 그대로다. 기존 탐색이 읽던 그림은 바뀌지 않고, 두 번째 탐색이 얼굴을 찾아도 얼굴 끝이 목보다 아래에 있을 때만 경계가 내려간다. 병목도 얼굴도 없으면 어깨-기울기로 떨어지고 그 사실이 `anatomy.warnings` 에 남는다.
- - 큐레이션 뷰: 줄 헤더 호흡 체크박스(즉시 on/off) + 라벨 클릭 편집기(실재생 위 **강체 경계 1개 드래그** · 세로 진폭 `depth` · 가로 진폭 `depth_x`(기본 "=세로", 0 = 가로 끄기 — maintainer 요청 2026-07-30 가로/세로 분리) · 루프당 호흡 횟수 · `auto` 되돌리기 — 즉시 반영, Esc 복원, 최종 굽기 필름스트립). 루프 길이는 시퀀스 그대로 불변이고 위상이 연속값이라 breaths 는 요청 그대로 적용된다 (범위 1~8이고 **정수여야 한다**; 밖이거나 비정수면 조용히 깎지 않고 요란하게 거부한다 — `depth` 0.005~0.20, `depth_x` null|0~0.20, `lag` 0~0.45 도 같다). 재추출/굽기 대기 없음.
+ - 큐레이션 뷰: 줄 헤더 호흡 체크박스(즉시 on/off) + 라벨 클릭 편집기(실재생 위 **강체 경계 1개 드래그** · 가로 최소~최대와 세로 최소~최대(% 입력, 0.1% 단위, -20~20. 2026-10-29 진폭 셀렉트를 대체했다. 세기만 적힌 줄은 그 세기가 오가는 범위를 보여 주고, 손잡이 하나를 고치면 줄이 네 키로 옮겨진다. 손대지 않은 손잡이는 반올림하지 않은 값 그대로라 그 축은 같은 바이트로 구워진다. pixel 세기 줄의 가로는 해부가 와야 보이고, 둥근 가슴 줄에서는 꺼진다) · 루프당 호흡 횟수 · `auto` 되돌리기 — 즉시 반영, Esc 복원, 최종 굽기 필름스트립). 루프 길이는 시퀀스 그대로 불변이고 위상이 연속값이라 breaths 는 요청 그대로 적용된다 (범위 1~8이고 **정수여야 한다**; 밖이거나 비정수면 조용히 깎지 않고 요란하게 거부한다 — `depth` 0.005~0.20, `depth_x` null|0~0.20, 최소와 최대 -0.20~0.20, `lag` 0~0.45 도 같다). 재추출/굽기 대기 없음.
- 세로선(몸통 밴드)을 **사람이 조정하면** 보호 램프가 밴드 자체에 앵커된다 — 밴드 밖 열은 늘어나지 않고 밀리기만 한다. 자동 검출 밴드는 부속(날개·긴 팔)이 실재할 때만 켜지는 기존 계약 그대로다 (블롭에서 밴드 조정이 무력했던 버그 수리, 2026-07-30).
## 정지 자세(Static-Pose) 행 레시피
diff --git a/sprite_gen/serve/curator/src/i18n.js b/sprite_gen/serve/curator/src/i18n.js
index 70e2980..2e2a5eb 100644
--- a/sprite_gen/serve/curator/src/i18n.js
+++ b/sprite_gen/serve/curator/src/i18n.js
@@ -52,8 +52,8 @@ const STR = {
fpsSet: (s, f) => `${s}: ${f}fps`, fpsFail: "fps change failed: ",
rowBreathe: "Breathe", tRowBreathe: "breathing is a POST-PROCESS LAYER, orthogonal to frame selection — a blink frame breathes too. Check: turn it on (instant, saved to the sidecar; compose/GIF bake it deterministically). Uncheck: turn it off. Click the label to drag the rigid boundary and tune the width / height range and breaths over the LIVE playing sequence.",
tRowBreatheEdit: "open the breathing editor — adjustments apply instantly over the playing sequence; Esc restores the previous setting",
- breatheWidth: "width", breatheHeight: "height", breatheMin: "min — the smallest the breath gets on this axis",
- breatheMax: "max — the largest the breath gets on this axis",
+ breatheWidth: "width", breatheHeight: "height", breatheMin: "min: the smallest the breath gets on this axis",
+ breatheMax: "max: the largest the breath gets on this axis",
tBreatheWidth: "how much the torso widens at the row where the breath is fullest, as a share of the original (0 = original width, -20..20%). Pixel: the widest moment is also the lowest head",
tBreatheHeight: "how far the head top (smooth: the chest) rises, as a share of the body below the neck (negative = down, 0 = original height, -20..20%)",
breatheCountLabel: "breaths/loop", breatheFitted: (n) => n === 0 ? "→ no room to breathe" : `→ ${n} applied`,
@@ -223,10 +223,10 @@ const STR = {
unlinked: (s) => `${s} 와 링크 해제 — 독립 프레임이 됐습니다`,
tFpsStepper: "줄 전체 재생 속도 (state fps — sprite-request 에 저장). 특정 프레임을 길게 보여주려면 프레임 복제를 쓰세요 (복제는 아틀라스 셀 공유 = 부하 0)",
fpsSet: (s, f) => `${s}: ${f}fps`, fpsFail: "fps 변경 실패: ",
- rowBreathe: "호흡", tRowBreathe: "호흡은 프레임 선택과 직교하는 후처리 레이어입니다 — 깜빡임 프레임도 그대로 숨쉽니다. 체크: 켜기 (즉시, 사이드카 저장 — 아틀라스/GIF 굽기에 결정론 반영), 해제: 끄기. 라벨 클릭: 실제 재생 위에서 강체 경계·가로·세로 범위·호흡 횟수 조정.",
+ rowBreathe: "호흡", tRowBreathe: "호흡은 프레임 선택과 직교하는 후처리 레이어입니다 — 깜빡임 프레임도 그대로 숨쉽니다. 체크: 켜기 (즉시, 사이드카 저장 — 아틀라스/GIF 굽기에 결정론 반영), 해제: 끄기. 라벨 클릭: 실제 재생 위에서 강체 경계, 가로와 세로 범위, 호흡 횟수 조정.",
tRowBreatheEdit: "호흡 편집기 열기 — 조정은 재생 중인 시퀀스에 즉시 반영됩니다. Esc = 이전 설정 복원",
- breatheWidth: "가로", breatheHeight: "세로", breatheMin: "최소 — 이 축에서 숨이 가장 작을 때",
- breatheMax: "최대 — 이 축에서 숨이 가장 클 때",
+ breatheWidth: "가로", breatheHeight: "세로", breatheMin: "최소: 이 축에서 숨이 가장 작을 때",
+ breatheMax: "최대: 이 축에서 숨이 가장 클 때",
tBreatheWidth: "숨이 가장 큰 줄에서 몸통이 넓어지는 비율, 원본 대비 (0 = 원래 폭, -20~20%). pixel 은 가장 넓을 때 머리가 가장 낮다",
tBreatheHeight: "목 아래 몸 높이 대비 머리 끝(smooth 는 가슴)이 올라가는 비율 (음수 = 내려감, 0 = 원래 높이, -20~20%)",
breatheCountLabel: "호흡/루프", breatheFitted: (n) => n === 0 ? "→ 숨쉴 자리 없음" : `→ 적용 ${n}회`,