Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: the Sway layer on a cycle's frames, on the breath, with a flat share and a gain across; inspection seams under a third region (schema 3); Breathe's beat chosen to miss the hands; SKILL Script Map; CHANGELOG `## Unreleased`
Soohong Kime18c905b4964
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b8e295b..3cfdcbe 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.**+**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.**The Breathe layer still supports `pixel` and `smooth`.@@ -30,10 +30,23 @@ The Breathe layer still supports `pixel` and `smooth`.These measurements exclude PNG reading and writing.`bake_breathe_sequence(images, cfg, anat=None)` and `anatomy_report(images, cfg, anat=None)` accept measured anatomy.`protect(anat)` accepts one column or an array of columns.+- **New: Sway on a cycle's frames.** `video-sway --frames` moves full-size frames and writes them with `sway.json` to a new folder.+ A whole `cycle/` can supply its frame time; other damped-mass runs require `--fps`.+- **New: Sway on the breath.** `--breathe` drives the move from a checked smooth `breathe.json`, with `--lag` setting how late the part follows.+ The first cell, rests and close have zero offset.+- **New: A region moved whole.** A fifth `--region` number, `flat`, keeps the centre at full weight before the weight falls to the rim.+- **New: Across apart from down.** `--gain-across` sets the across gain separately from `--gain`, which sets the gain down.+- **Changed: Zero-offset cells.** A cell where no region moves is copied byte for byte, including colour under clear pixels.+- **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`.- **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_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_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/SKILL.md b/SKILL.mdindex 582698d..28eab0b 100644--- a/SKILL.md+++ b/SKILL.md@@ -115,8 +115,8 @@ hold the arms still, and check the loop with `handed-check --state walk`.| Continue or edit an existing clip | `video-extend`, `video-edit` | [video](docs/video.md) || A clip run left unfinished (its line or report names a `request_id`): ask for it again, never submit it again | `video-resume --request-id <id>` | [video](docs/video.md#sprite-gen-video-resume--ask-again-for-an-unfinished-generation) || Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) |-| A soft part of a walk loop sways with the body (the Sway layer; a chest, a belly): an ellipse in the first cell, after `video-cycle-align`, `--read-on <sha256>` where it was read on the cut the loop was aligned from; `--stretch-floor D` to keep a least area | `video-sway` (old name `video-follow`) | [video-pipeline](docs/video-pipeline.md#6-the-sway-layer--video-sway) |-| Where that ellipse is carried in every other cell, and what the move changes there (an arm crossing a chest moves with it; the stretch, the bend and the seam): a record and boards of every cell, nothing moved | `video-sway-inspect` (old name `video-follow-inspect`) | [video-pipeline](docs/video-pipeline.md#inspecting-a-sway--video-sway-inspect) |+| A soft part of a walk loop or cycle frames sways with the body (the Sway layer): an ellipse after `video-cycle-align`, `--read-on <sha256>` for a cut, `--stretch-floor D` for least area, `--frames` for full frames, `--breathe` for the breath drive, a flat share to move a region whole, and `--gain-across` for across gain | `video-sway` (old name `video-follow`) | [video-pipeline](docs/video-pipeline.md#6-the-sway-layer--video-sway) |+| Where an ellipse is carried in every other cell, and what the move changes there (an arm crossing a chest moves with it; the stretch, the bend and the seam): a record and boards of every cell, nothing moved; a seam under a third moving region is not counted | `video-sway-inspect` (old name `video-follow-inspect`) | [video-pipeline](docs/video-pipeline.md#inspecting-a-sway--video-sway-inspect) || A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import): rows in compass order S SW W NW N NE E SE from each loop's `--view`, one cell size, every row as cut, an optional centre picture (`--center`) at the rows' standing height; loops of different lengths are laid and said to differ (`same_length` false) — align the set first | `video-set-sheet` | [video-pipeline](docs/video-pipeline.md#7-one-sheet-for-a-set--video-set-sheet) || A walk or run that stops, from the clip's own start played backwards: a one-shot strip (`loop: false`, `hold_last: true`), GIF, WebP and report beside the loop, ending on the still as filmed; leaves the loop from the cell nearest the entry (`from_cell`), drift taken out across the frames by a straight share; a seam past 1.4 steps (`--seam-max`), a run-up that comes back to a pose it left (another motion, however short) or one over 1.5 cycles (`--run-up-max`) refused; ghost screen checked, cells placed and anchored to match the loop's pivot | `video-stop` | [video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop) || Compare the currently displayed loop with a final candidate, including after follow-through | `video-loop-compare` | [loop-comparison](docs/loop-comparison.md) |@@ -130,7 +130,7 @@ hold the arms still, and check the loop with `handed-check --state walk`.| Curation view or existing image candidates | `curation`, `unpack-atlas --pngs-dir` | [curation](docs/curation.md) || Uniform background removal or imported sheets | `cutout`, `slice-sheet` | [sheet-slicing](docs/sheet-slicing.md) || Palette swap | `sprite-gen recolor-palette`, `sprite-gen recolor` | [recolor](docs/recolor.md) |-| Idle breathing as a post-processing layer (the Breathe layer): pixel (default, pixel art) or smooth (large illustrations, video frames: head fixed, chest breathes, shoulders follow; facing values for a turned body) | curation sidecar, baked by compose; or `sprite-gen breathe <frames> <out>` on a folder of loop frames | [breathing](docs/breathing.md) |+| Idle breathing as a post-processing layer (the Breathe layer): pixel (default, pixel art) or smooth (large illustrations, video frames: head fixed, chest breathes, shoulders follow; facing values for a turned body); smooth can choose a beat that misses the hands with `--avoid-region` | curation sidecar, baked by compose; or `sprite-gen breathe <frames> <out>` on a folder of loop frames | [breathing](docs/breathing.md) || Engine exports | `export-aseprite`, `export-pngs` | [engine-export](docs/engine-export.md) || Background recipe or repeating tile | existing `gen` / `cutout`, then optional `background-tile` | [asset-tools](docs/asset-tools.md#background-recipe) || Ground tile that repeats both ways | `gen` (opaque), then `background-tile --axis xy` | [asset-tools](docs/asset-tools.md#both-axes-a-ground-tile) |diff --git a/docs/breathing.md b/docs/breathing.mdindex 11ccedf..4768977 100644--- a/docs/breathing.md+++ b/docs/breathing.md@@ -60,11 +60,20 @@ 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 ...]+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]]````<frames>`는 파일 이름 순서대로 재생되는 PNG 프레임 폴더다. 사이드카와 동일한 검증과 베이크 처리를 거치므로 같은 값이면 동일한 바이트를 출력한다. 변환된 프레임들을 원본과 동일한 이름으로 저장하고, 적용된 설정과 위상 및 해부학 측정값을 담은 `breathe.json`을 새 폴더에 한 번에 작성한다. 심볼릭 링크를 추적하고 대소문자를 구분하지 않는 디스크의 서로 다른 표기를 동일하게 취급하는 실제 위치를 기준으로, `<out>`과 `<frames>`가 같은 폴더이거나 어느 한쪽이 다른 쪽 내부에 있는 경우 및 이미 존재하면서 비어 있지 않은 폴더는 아무것도 생성하거나 삭제하지 않고 거부하되 기존의 빈 폴더는 허용한다. `<frames>` 폴더에는 어떤 파일도 새로 쓰지 않으며, 프레임을 비롯한 기존 파일을 변경하거나 삭제하지 않는다. 결과물은 `<out>` 옆에 다른 폴더와 겹치지 않는 고유한 이름의 자체 임시 폴더에서 빌드한 뒤 한 번에 제자리로 이동하며, 작업을 완료하지 못했을 때도 오직 직접 만든 임시 폴더만 삭제하고 이전 작업의 잔여 폴더처럼 직접 만들지 않은 폴더는 그대로 둔다.+손이 가슴 앞에서 크게 움직이는 idle에서는 들숨의 정점이 손의 상승과 겹치면 호흡이 손을 따라가거나 가슴이 손 아래로 가라앉는 것처럼 보인다. `--mode smooth --avoid-region X0,Y0,X1,Y1`은 손의 움직임을 피해 호흡 박자를 고른다.++- `--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`를 쓴다.+- 점수는 호흡 곡선과 몸통 상승량의 상관에서 호흡 곡선과 손 자체의 상승량의 상관을 뺀 값이다. 각 들숨 정점의 앞뒤 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`가 담긴다.+비디오 루프 셀 처리 예시는 다음과 같다.```bashdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex abf569c..8605c4c 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -1291,7 +1291,9 @@ A clip model draws a walk's body moving, but a soft part hanging off it (a chest```bashsprite-gen video-sway --loop-dir set/front-walk/loop --region 136,164,60,50 [--region ...] \[--gain 2.5] [--on-fold refuse|lower] [--freq 2.4] [--zeta 0.6] [--board follow.png] \- [--read-on <sha256>] [--stretch-floor D]+ [--read-on <sha256>] [--stretch-floor D] [--gain-across G]+sprite-gen video-sway --frames set/front-idle/loop/cycle --out swayed --region cx,cy,rx,ry[,flat] [--fps F] \+ [--breathe breathed/breathe.json [--lag 0.15]] [--gain G] [--gain-across G] [--on-fold ...] [--stretch-floor D]```- **The region** is an ellipse over the part in the strip's first cell, in cell pixels@@ -1334,6 +1336,7 @@ sprite-gen video-sway --loop-dir set/front-walk/loop --region 136,164,60,50 [--rat the centre and 0 at the rim (cos²), sampled as premultiplied bilinear colour; outside it nopixel changes. A move so large that the weight's slope folds the picture over(offset × π / (2 · radius) ≥ 1) is refused: lower `--gain` or give the region larger radii.+ A cell in which every region's offset is 0 is copied byte for byte, including colour under clear pixels; this holds for every sway, including `--gain 0`. A move clears that colour because the WebP check refuses it.- **`--on-fold lower`** lowers the gain for you instead of refusing, region by region. The moveis the gain times the move at gain 1, so the gain at which a region folds is2 · radius / (π · move at gain 1), and a region that folds at `--gain` takes the largest gain@@ -1437,6 +1440,39 @@ What carries a region into a cell is the lay of the body's outline (`carry_basiscarried alike, whatever moved inside the outline; whose pixels are inside a carried ellipse is notread, and nothing here moves a region on a guess of it.+#### A cycle's frames at their own size: `--frames <folder> --out <new folder>`++A loop's strip holds at most 64 cells and 32,000 px across. Cells 960 px wide allow 33 of them, so a cycle of large frames must be cut down to fit. The strip stays the delivery format; `video-sway --frames <folder> --out <new folder> [--fps F]` sways the full cycle before that cut.++- **The frames** are PNGs in name order, all one size, from a `video-loop` `cycle/` folder or the output of `sprite-gen breathe`. Regions are given in frame pixels. `--frames` and `--loop-dir` are alternatives, and one is required.+- **The output** contains the moved frames under their original names and `sway.json` beside them. The folder checks and whole writing are the same as `sprite-gen breathe`: real paths rule out an output equal to, inside, or containing the frames folder; the output must be new or empty; and unequal frame sizes are refused before anything is made. The command writes in a staging folder beside the output and renames it into place when complete. A failed run leaves nothing, and the frames folder is only read.+- **The move** uses `solve_cells` for both paths. A strip cut from these frames at scale 1, with no cell left out and each region moved by the crop origin `source_rect`, moves cell for cell exactly as the frames path does, byte for byte once cut back, at the frame time written in the strip meta. `--fps F` uses `round(1000 / F, 2)` milliseconds: 24 fps is 41.67 ms. The exact `1000/24` ms gives another sway.+- **The time** comes from `--fps` or, for a whole `video-loop` `cycle/`, from the loop strip meta's `cycle_seconds` and `cycle_frames`. A conflicting `--fps` is refused. The damped mass requires a frame time, so other frames folders need `--fps` unless `--breathe` supplies the drive. `--read-on` is refused with `--frames`; `--frames` requires `--out`; `--out` and `--fps` are refused with `--loop-dir`.+- **The record** in `sway.json` has `frames`, `frame_ms` (null on the breath), and the same record as the loop's `follow`, with `source` naming the frames folder. Body motion is read at the frames' full size by `body_motion`. Reducing them changes that reading and its offsets. On large frames, reading can take minutes. The old name `video-follow --frames ...` writes the same bytes.++#### On the breath: `--breathe <breathe.json>`++A 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 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.++```bash+sprite-gen breathe <cycle> <breathed> --mode smooth --breaths 2+sprite-gen video-sway --frames <breathed> --out <swayed> --breathe <breathed>/breathe.json --region <cx,cy,rx,ry>+```++#### A region moved whole, and across apart from down: `cx,cy,rx,ry,flat`, `--gain-across G`++`--region cx,cy,rx,ry[,flat]` gives a region an optional fifth number, `flat`, from 0 to 0.9. It is the share of the way from centre to rim that moves in full. Over the remaining distance the weight falls from 1 to 0 by cos², using the Breathe layer's `breathe.flat_cos2`. A large region weighted by cos² alone presses its outer part inward; one flat region can move the part whole instead of laying many small circles over it. On a synthetic chest, one flat region gave a least part weight of 0.82 and a mean of 0.99, against 0.84 and 0.97 for 112 circles, at a fifth of the move time.++The fold rule reads the radius left after the flat centre: the smaller radius x `(1 - flat)`. It folds at `offset x π / (2 x radius x (1 - flat)) >= 1`. `--stretch-floor` reads the least area as `1 - (π/2)/(1 - flat) x hypot(ox/rx, oy/ry)`. Both closed forms stay on the safe side of measured values by 0.004 to 0.013. The record's `fold.regions[i].radius_px` is that reduced radius. A `flat` of 0, or one left out, gives the four-number region's strip, record and inspection byte for byte. Values outside the range are refused.++`--gain-across G` sets the gain across independently; `--gain` then sets the gain down. Without it, across uses `--gain` as before, byte for byte. When `--on-fold lower` or the floor lowers a region's gain, its across move falls in the same proportion. The existing area rule reads moves with different across and down components and stays on the safe side by 0.0004 to 0.008. `--gain 0` with non-zero `--gain-across` is refused. The record carries `gain_across`, the across gain the strip's `gain` moved by, and carries `gain_across_requested` only when given.+### Inspecting a sway — `video-sway-inspect`The ellipse is given in the first cell, where somebody looked. Into every other cell it is carried by the body's motion, and there nobody looked: an arm that swings across a chest is inside the chest's ellipse in those cells and moves with it, and so does a sleeve of the chest's own colour, which no count of colours finds. The Sway layer does not read what a pixel belongs to. `video-sway-inspect` (old name `video-follow-inspect`) writes what somebody needs in order to look, and moves nothing:@@ -1444,7 +1480,7 @@ The ellipse is given in the first cell, where somebody looked. Into every other```bashsprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,50 [--region …] \[--gain 2.5] [--on-fold refuse|lower] [--freq 2.4] [--zeta 0.6] [--read-on <sha256>] [--stretch-floor D] \- --out-dir inspect/front-run [--scale 2] [--columns 8]+ [--breathe <breathe.json> [--lag 0.15]] [--gain-across G] --out-dir inspect/front-run [--scale 2] [--columns 8]```- **Asked as `video-sway` is, answered by the same code.** It takes `video-sway`'s arguments@@ -1453,6 +1489,7 @@ sprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,(`follow.read_request`, `follow.solve`): the carry, each region's gain, the offsets and themoved cells are computed in one place, and both commands read them there. What `video-sway`refuses it refuses in the same words under its own name, and then writes nothing.+ It takes `--breathe`, `--lag`, `--gain-across` and flat regions as `video-sway` does, and stays on a loop directory without `--frames`.- **The loop directory is read and never written**: not the strip, not its meta, and not the`follow.source.png` that `video-sway` keeps on its first run. An `--out-dir` at or under theloop directory is refused. Run before `video-sway`, it changes nothing `video-sway` writes.@@ -1462,7 +1499,7 @@ sprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,pixels they are. Saying which cells hold the part alone is for a person or a model that looksat the board of the cells as cut, and for a second reader apart from the first.`video-sway` takes no such list: it moves every cell.-- **`follow-inspect.json`** (`kind: video-follow-inspection`, `schema_version: 2`):+- **`follow-inspect.json`** (`kind: video-follow-inspection`, `schema_version: 3`):| key | what it holds ||---|---|@@ -1470,14 +1507,14 @@ sprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,| `inputs.strip` | `file`, `sha256`, `bytes`: the strip as cut that was read || `inputs.meta` | `file`, `sha256`, `bytes`: `<name>.strip.json` as read; `cut_sha256`: its sha256 without the `follow` record `video-sway` adds (keys sorted, no spaces); `follow_recorded` || `inputs.cut` | `frames`, `w`, `h`, `delay_ms`, as read from the meta |- | `inputs.regions`, `inputs.settings` | the ellipses in the order given; `gain`, `on_fold`, `freq_hz`, `zeta`, `read_on` and `stretch_floor` (null where not asked) |- | `inputs.policy`, `inputs.engine` | the way the motion is read and a region moved, by name (`follow.POLICY`) with the constants it is fixed by, and the ways a reading is carried (`transport`) and a floor kept (`stretch_floor`), by name; the engine's `name` and `version` |+ | `inputs.regions`, `inputs.settings` | the ellipses in the order given, with five numbers when a region has a flat share; `gain`, `on_fold`, `freq_hz`, `zeta`, `read_on` and `stretch_floor` (null where not asked); `gain_across`, `breathe_sha256` and `lag` only when asked |+ | `inputs.policy`, `inputs.engine` | the way the motion is read and a region moved, by name (`follow.POLICY`) with its constants, and the ways a reading is carried (`transport`) and a floor kept (`stretch_floor`), by name; `inputs.policy.name` follows the drive and is `common-lay/breath-late/cos2-bilinear/1` on the breath; the engine's `name` and `version` || `follow` | the follow-through as `video-sway` records it in the strip's meta, without `gif` and `webp` || `carry_basis` | `{"reading": "outline-lay", "region": "unverified"}`: what carries a region, and that whose pixels it holds is not read || `regions[i]` | `index`, `ellipse` as given, `radius_px`, `gain` (0 when held), `held`, `gain_limit`; over all cells the largest `reach_px`, `fold_ratio`, `bend` and `bend_deg`, the least `jacobian_min`, the sum of `changed_px`; `ring`, its colour on the boards || `seams` | per pair of moving regions that meet in some cell (`regions`: [i, j]), the largest seam: `jump`, `deg`, the `cell` and the point `at` (x, y) || `cells[k]` | `index`, `carry_px` (across, down), `changed_px`, `jacobian_min`, `seams` (as above, per pair that meets in that cell), `box` (x0, y0, x1, y1: the cell's picture on both boards) and `regions[i]` |- | `cells[k].regions[i]` | `ellipse`: the region carried (centre plus `carry_px`, the radii as given); `offset_px` (across, down) and `reach_px`: the region's own move in that cell, 0 when held; `fold_ratio`; `jacobian_min` and `jacobian_min_at` (x, y); `bend` and `bend_deg`; `ellipse_px`, `solid_px`; `changed_px`; `ownership` |+ | `cells[k].regions[i]` | `ellipse`: the region carried (centre plus `carry_px`, the radii as given, and a fifth value where the region has a flat share); `offset_px` (across, down) and `reach_px`: the region's own move in that cell, 0 when held; `fold_ratio`; `jacobian_min` and `jacobian_min_at` (x, y); `bend` and `bend_deg`; `ellipse_px`, `solid_px`; `changed_px`; `ownership` || `boards` | `scale`, `columns`, `size`, `ground`; `source` and `moved`, each `file`, `sha256` (the PNG file) and `pixels_sha256` (its pixels) |- **`carry_px`** is how far the cell's body lies from the first cell's, in whole pixels: what@@ -1503,12 +1540,15 @@ sprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,region moving along its long axis keeps D high while G stays near 1, so neither stands for theother. And where two regions overlap, `video-sway` moves each pixel by the larger of theirweighted moves (by the larger weight where they move by one gain), so across the curve where the- two are equal the move's gradient jumps from one region's to the other's and a straight line- bends there: `seams`, the largest jump on that curve — the norm of the difference of the two- gradients, each the offset times the weight's gradient — and its angle `deg`. It is looked for- along rows a quarter pixel apart, between points inside both ellipses where the larger move- changes hands, and found there by halving. A held region has no seam. Quality is read from these- three, not from `fold.ratio`; a floor lowers the bend and the seam only as it lowers the gain.+ two are equal the move's gradient jumps from one region's to the other's and a straight line bends+ there: `seams`, the largest jump on that curve, the norm of the difference of the two gradients,+ each the offset times the weight's gradient, and its angle `deg`. It is looked for along rows a+ quarter pixel apart, between points inside both ellipses where the larger move changes hands, and+ found there by halving. A point is dropped if a third moving region has a weighted move, `|offset|+ x weight`, larger than both of the pair's. The seam is the largest jump among the points left; if+ none remain, that pair has no seam in that cell. With two regions, the values stay the same. A+ held region has no seam. Quality is read from these three, not from `fold.ratio`; a floor lowers+ the bend and the seam only as it lowers the gain.- **The record names what it was read from.** It holds no path, no time and nothing of themachine: the same loop asked the same way writes the same record, byte for byte, anywhere.`input_id` is the same before and after `video-sway` is run on the loop, and another after a