Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Merge main 405f327 (v3.4.0, v3.5.0 and the round chest) into plan/walk-body-turn-mass-1027: the body turn beside the part pop and every cut's feet
Soohong Kim9b02f94d4279
diff --cc CHANGELOG.mdindex a6b2223,204eb09..fefd95e--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -4,16 -4,218 +4,228 @@@ All notable public changes to `sprite-g## Unreleased+ **Upgrading from 3.5.0: 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.**++ - **New: the round chest (pixel; `chest_round`, `arms_x`, flags `--chest-round`, `--arms-x`).** When either is above 0, a pixel row bakes the round chest instead of the envelope squash. Both are shares of the body below the neck (0 to 0.20). The rim of the chest ellipse (smooth's `chest_*` keys) moves out from its peak by `chest_round`. Inside the ellipse the body stretches evenly from the peak; outside it the body is pushed whole, so a 1 px outline stays 1 px. Above the peak the chest goes up and out; below the peak it goes sideways only, fading to nothing at the feet. The head above the rigid boundary keeps its place and bytes, as in smooth. Below the rigid boundary, the sideways share (the chest's sideways push and the arms) turns on over the longer of 0.15 of the neck band and 1.5 times the sideways px (`chest_round` plus `arms_x` in px), and the body's following of a held piece turns on over the longer of 0.15 of the neck band and 1.5 times the largest piece move in px (if it turns on over less, rows just below the head line slide more than one cell per row against each other and an outline crossing the head line breaks; with 1.5 times, no row slides more than about one cell against the next because the steepest slope of the smooth turn on is 1.5 over its length). The arms (the columns outside where appendage protection starts) are pushed whole by the chest and then sideways by `arms_x` on top, never stretched; the torso's sides take the stretch over 12 times that push. The breath is smooth's one-sided curve (`inhale`, `breaths`, `breath_peaks`, `loop_cells`, `start_cell`), so a cell at phase 0 is the source byte for byte. Every output cell is a cell of the source: no new colour, and no row or column is folded. A round row refuses `depth`, `depth_x`, `lag` and smooth-only shape keys; smooth refuses `chest_round` and `arms_x`. See [breathing](docs/breathing.md), "둥근 가슴".+ - **New: held cells (`--hold-mask`), held props (`--props-mask`), props behind the body (`--props-behind-mask`), and props grouping (`--props-groups`).** All are PNGs the size of the frames; their light opaque pixels (lightness 128 or more, alpha 128 or more) are the cells. A cell may be in only one of the three masks; a cell in two is refused. Empty cells inside a props mask are not drawn; only the drawing's opaque cells of a piece move. A held cell keeps its bytes in every frame, because the field is 0 there (smooth and round rows; an envelope row refuses). Each piece of the props mask (8-connected, cells within 2 px of each other joined, as a hilt and blade parted by the hand) moves whole and sideways, as far as the hand holding it: the chest's sideways push where the piece touches the body, plus the full `arms_x` of the arm on its side. The body within 2 px of it moves the same whole cells, so no gap opens between hand and grip. A whole arm can move as one rigid block by masking it from the sleeve below the shoulder down to the hand together with what it holds as one `--props-mask` piece (one colour), starting below the sideways turn on rows. Where a piece moves onto held cells, held cells stay on top and those cells are not drawn; the engine counts them per piece and per frame in `props.pieces[i].hidden` and `hidden_max` of `breathe.json`, printing one warning line on stderr of the form `breathe: warning: --props-mask piece K of N (C cells) goes under held cells in F of T frames, up to M cells (frame X); those cells are not drawn` followed by `breathe.json props.pieces[K-1].hidden`. In each row, the engine looks at the first cell right behind the moved piece: when that cell is a held cell, it repeats over the cells the piece left (water fills where a blade left the water band; a held back fills where a sleeve moved away), and otherwise the body fills it; no empty cell is made up. The engine counts cells a piece fills by repeating a cell or left by the field where the body does not follow fully rather than moving them in `props.pieces[i].filled` and `filled_max` of `breathe.json` (held cells themselves are never counted), printing one warning line on stderr of the form `breathe: warning: --props-mask piece K of N (C cells) leaves cells it fills by repeating a cell in F of T frames, up to M cells (frame X); those cells are made up, not moved` followed by a space and `breathe.json props.pieces[K-1].filled`. Pieces held behind the body (`--props-behind-mask`, off by default) take the same sideways move, but the body stays in front, does not follow, and the piece is drawn under held cells, under the body, and under pieces held in front; all pieces behind the body are drawn first, then all pieces in front, including pieces that do not move in that frame (so a resting front piece is not covered by a behind piece), and held cells are always on top; where it pulls out from behind the body, the piece's cell touching the body in that row repeats over the cells it left (making the piece look wider by that many cells, as the shield's edge column repeats), while cells left where nothing was in front become empty; the cells it fills by repeating a cell are counted in `props_behind.pieces[i].filled` and `filled_max` with a warning line on stderr of the form `breathe: warning: --props-behind-mask piece K of N (C cells) leaves cells it fills by repeating a cell in F of T frames, up to M cells (frame X); those cells are made up, not moved` followed by a space and `breathe.json props_behind.pieces[K-1].filled`; its hidden cells (under held cells, the body, or a front piece) are counted in `props_behind.pieces[i].hidden` and `hidden_max` with a warning line reading `goes under held cells, the body or a piece held in front of it` and naming `--props-behind-mask`. A piece ledger maintains a source map of which source cell each output cell shows, reading all counts off this map in every frame. Before drawing, each piece is checked at its whole-cell destination and refused if pushed off the cell (naming the mask flag, piece as i/n with its cell count, opaque cells leaving, side crossed with its count like `왼쪽 변 밖 3`, cell size, and move, advising to widen the cell margin or lower `chest_round` or `arms_x`; covering behind pieces, rows above the head line, and rounding edges); the body's own off-cell refusal now counts body cells only and names the side crossed with its count. Two pieces of one layer landing on one cell are refused (advising `--props-groups colour` or moving one to the other mask); a behind piece and the body in front moving apart to leave empty cells is refused (advising to mask only the part showing outside the body as `--props-behind-mask` or give it as `--props-mask`); and in every frame the cells shown at destination plus hidden cells must equal the piece's opaque cells in the still, refusing as an engine defect if not. With `--props-groups colour` (default `piece`; refused without a props mask), both props masks are read by colour: light opaque cells of one colour form one group moving by the whole cells read where the group touches the body, allowing unheld elements like reflections to follow a prop. `breathe.json` records `hold`, `props`, and `props_behind` (path, sha256, cells, each piece's `shift_px`, `hidden`, `hidden_max`, `filled`, `filled_max`), with each piece carrying `colour` and the mask carrying `groups: "colour"` and `colours` when grouped by colour. `sprite-gen breathe` also takes `--axis-x` and `--torso-half`, the sidecar's existing overrides, so a figure whose arms lie inside the measured torso can name them.+ - **Curator**: a round row is kept as written and its preview and video export are refused, as for smooth rows; the mirrored key lists are checked against the bake's.+ - **Tests**: `tests/effects/test_breathe_round.py` (on a synthetic figure: the rest is the source and the head never moves; the chest swells round from one point, the line above the peak rises and the line below it does not; no new colour, no fold, a 1 px outline; the arms move sideways whole; a bar held in the hand moves with it and no gap opens; held cells keep their bytes under the round chest and under smooth; a bar going under a held water band is counted per frame in `breathe.json` and warned on stderr, held cells keep their bytes and the cells it left in the water rows are water (no gap); a reflection painted the bar's colour with `--props-groups colour` follows the bar by the same cells in every frame, the cells it left show the still's water, and no new colour appears; a shield given as `--props-behind-mask` slides out from behind a held arm with its rim cell filling the space and no gap, while given as `--props-mask` the held arm's outline fills that space instead; `--props-groups` without a props mask is refused; the new keys off keep every byte; wrong keys are refused; the CLI bakes what the library bakes and records both masks; a piece pushed off the canvas, behind the body or in front, is refused with its name and the side, and no folder is left; a piece above the head line pushed off the canvas is refused; the body pushed off the canvas names the side; the cells a piece fills (a shield sliding out from behind an arm, a bar leaving a held water band) are recorded per frame in `breathe.json` and warned, and match a count made independently from a tag picture (every cell carries its own index); in eight scenes every cell of every piece is drawn at its destination or counted as hidden in every frame, and the filled count matches the independent count; two pieces of one layer landing on one cell are refused; a piece in front stays over a piece behind, whether it moves over it or the behind piece moves under it; a piece behind the body moving apart from it is refused; the ledger changes no byte of seven scenes baked before it (no masks, held legs only, the held bar, the bar in the water, the colour group reflection, the shield behind and in front); a row with only held cells records no piece ledger) and `tests/effects/test_breathe_round_curator.py` (the mirror refuses a round row; the round trip keeps a round sidecar as written and keeps a refused one with a notice; the mirrored key lists).++**Upgrading from 3.3.0: 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.**++- **New: `video-loop` detects torso turns in walk and run clips and avoids them during the cut search.** A video model asked to walk at the still's angle sometimes turns the body inside the clip: a back-diagonal walk turns to a full back view half way and back. A loop cut across the turn plays the body swinging round. Until now the engine had no reading of this: the cut search could not avoid it, and a clip that held no cycle for it was refused only as `video-loop: no periodic cycle found`, so an app could not name that the body turned as the reason to film it again. The new module `sprite_gen/video/body_turn.py` introduces reading `torso-side-v2` on every walk or run under `--anchor motion-auto`, reading each frame's torso crop against the clip's first frame, the still the clip was filmed from, a standing pose. It does so whether or not the clip opens on a lead-in (the video model reframing the still to the walk's size over the first frames, which the cut search leaves out). It does not read against the first frame after the lead-in: that frame is a stride's pose, and a walk draws the mirror of a stride's pose half a cycle later, so a synthetic walk that does not turn, read against it, read a turn every stride (least -0.34). Read against the still filmed small, the same synthetic walk (its first 8 frames filmed from 0.6 of its size) reads +0.87 at least where it does not turn (+0.92 without the lead-in); turning over frames 30 to 40, its turn over frames 32 to 38, the same frames as without the lead-in, least -0.71 (-0.63 without the lead-in). The torso crop runs from the neck down half the body below it, centred on the head's centre, as wide as the first frame's torso. Each crop is cut about the head's axis between pixels, and the still and every frame are read at their nearest about the axes within `GUARD` (2.5 px) and `TOL` (2 px), `STEP` (0.25 px) apart, so a piece beside the head that moves its centre 1.4 px moves no turn. Under the module constant `MASS_SHARE` = 0.01, the box's top is read as the row with more than a hundredth of the frame's solid pixels above it, and the still's torso width is read about the head's centre from the columns of the still's torso rows with more than a hundredth of those rows' solid pixels beside them. Reading them by mass prevents a piece apart from the body from moving the box or the torso width. The box's bottom is the frame's last solid row, the one end of the box not read by mass: where the legs cross each stride they lay their pixels over each other, and a bottom read by mass (the row with a hundredth of the frame's solid pixels under it, as the top is read) rises with them (on the lead-in walker, a row over its last solid row in most frames and 3 rows over where the legs cross, moving the crop's rows with it), though read either way, the walkers turning over frames 30 to 40 and the 4-frame turns drawn from 8 places, with the lead-in and without it, read their turns over the same frames. Under `HEAD_CORE` = 0.5, the head's centre is read as the middle of the head band's columns that hold at least half the solid pixels of the band's fullest column, before being read again within `HEAD_REACH` as before. This stops a fleck or a cut-loose ornament beside the head from shifting the head's centre and falsely reading a turn across the clip or hiding the walk's turn. The neck is the narrowest row of the first frame between 10 % and 55 % of its height (the topmost on a tie, or row 0.11 on a hooded walker). Each frame's `side` correlation is `(v.s - v.m) / (1 - s.m)`, where each correlation is taken at its nearest about the axes within `TOL`. Under module constants `SIDE_SHOWN_MIN` = 0.08, `TURN_SIDE_MAX` = 0, and `TURN_RUN_MIN` = 4 consecutive frames, candidate windows whose cut holds a frame of a turn are refused with `the body turns (clip frames a-b)`, two-step cuts holding one are left out (`step_count.turned_out`), and held-side windows two lengths long are excluded. A new bound, `HEAD_REACH` = 0.3, re-reads the head's centre (the middle of the solid pixels of the top 15 % of the body) on the pixels within `HEAD_REACH` of the body's height of it until it settles, leaving the plain mass centre as before where no pixel of those rows lies further out. Clips without turns (or unread) are searched once as before with the same cut and bytes. A walk that reads square against a still that shows a side is not read either and is cut the same way, with a warning line (`WALK_SIDE_MIN`). Where no window without the turn holds a cycle, `--body-turn warn` (the default) reruns the cut search as before and keeps the cut with a warning line naming the turn, or refuses as before (`video-loop: no periodic cycle found`) after a warning line if no cut holds a cycle; while `--body-turn refuse` (requiring `--anchor motion-auto`) prints `video-loop: the body turns in the walk` as its first line, prescribes filming it again with the torso and hips kept at the still's angle, hands over nothing, and sets `status: failed`, supporting app retake rules such as `loop-body-turned`.+- Report fields (`<name>.loop.report.json`): every walk or run report under `--anchor motion-auto` adds the `body_turn` object containing `reading` (`torso-side-v2`), `bounds` (`SIDE_SHOWN_MIN`, `WALK_SIDE_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_side`, `walk_side`, `read` (true or false), `why` (where not read), `neck`, `torso_still_side`, `side` (each frame's reading), `turns` (each `{from, to, least, at}`), `mode` (`warn` or `refuse`), `verdict`, `refused` (how many windows were refused for it), `cut` (`frames`, the cut's first and last clip frame, and `holds`, the turned frames it holds), `avoiding` (the search's refusal where the search that avoided the turn found nothing), and `unread` (a list of `{frames, why}`, each reason with the frames it applies to, appearing only where at least one frame was not read). The `verdict` field records one of `none` (read, no turn), `not-read` (a square still, a walk seen square, a first frame with no body, or a first frame the reading cannot read (no head to centre on, no solid pixel across its torso rows, or a crop of no width or with nothing in it)), `clear` (a turn, and the cut holds none of it without refusing anything), `avoided` (windows were refused for the turn and the cut leaves it out), `kept` (no cut without the turn holds a cycle; the cut taken before is kept, warned), `unfound` (no cycle with the turn or without it; refused as before, warned), or `refused` (`--body-turn refuse`). Where the still passes `SIDE_SHOWN_MIN` and the walk is seen square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing`. The command's JSON summary also gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.+- Python callers: new module `sprite_gen.video.body_turn` provides `read(frames)`, `square(reading)`, `turns(side)`, `turned(reading)`, `neck(body)`, `torso_rows(at)`, class `Turn(reading, skip=0)` (callable as `(start, length)`, returning the refusal reason or None, `held(start, length)`, counter `refused`), `refusal(...)`, `kept(...)`, `unfound(...)`, constants `READING`, `SIDE_SHOWN_MIN`, `WALK_SIDE_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`, `MODES` (`warn`, `refuse`), `NECK_RANGE` (0.10, 0.55), `HEAD_REACH` (0.3), `MASS_SHARE` (0.01, the same value as `frames.SPECK_MIN_FRACTION`), `HEAD_CORE` (0.5), `GUARD` (2.5), `TOL` (2.0) and `STEP` (0.25). Functions `local_cycle.detect`, `local_cycle.by_steps` and `local_cycle.counted` take a new keyword argument `turn` (a `Turn`, default None: as before). Function `loop.run_loop` takes `body_turn` (default `"warn"`).+- Output changes: a new named bound of the reading, `HEAD_REACH` = 0.3, re-reads the head's centre on the pixels within 0.3 of the body's height of it. The full test suite caught why it is needed: its side walker with a 60 px tail on a 45-frame beat (`tests/video/test_walk_steps.py`, the half-step case) read a turn on every swing (frames 8 to 15 and 53 to 60, least -0.19), because the tail swung up into the head's rows and pulled the head's centre aside. With `HEAD_REACH` it reads no turn (least +0.11) and is cut as before. Where no solid pixel of those rows lies within `HEAD_REACH` of their middle, the top's parts lie apart on either side of the middle (a prop held as high as the head and apart from it, or a body too small for any pixel to lie that near), and the top does not tell which part is the head, so the frame is not read instead of taking the largest part and centring on a prop that can weigh what the head does (on the test suite's 132 px synthetic staff walker, the ornament and the head hold the same number of solid pixels in those rows, 513 each, with no pixel within 39.6 px of the middle) and reading turns the body does not make. Where that frame is the first frame, the clip is not read and the cut search runs once as on any unread clip; cut by `video-loop` under default `--body-turn warn`, that synthetic staff walker is not read and is cut 11/24 (start 11, 24 frames), every byte as 3.3.0 cuts it.+- Output changes: a new named bound of the reading, `WALK_SIDE_MIN` = 0.045, and report field `walk_side` in `body_turn` keep front and back walks whose still shows a side (from arm swings or pieces beside the head) from reading turns every stride. For each frame after the still, its head and shoulders (top 45 % of body) cropped about its head are compared with the still's head and shoulders and their mirror within `GUARD` (2.5 px); `walk_side` is the median of frame nearness to the still minus nearness to the mirror (v.s - v.m), where a frame that flips under `HELD_MAX` (0.5 %) of the drawing last counted's solid pixels (alpha 128 or more) is not counted, so each drawing counts once and `walk_side` is the median of the walk's drawings, not of the time the clip gives each drawing; a clip in which every frame flips 0.5 % or more of the frame before's solid pixels reads exactly as before. The synthetic walker seen square from behind (the walker's still was taken 6 frames into its stride and the clip is 147 frames), each drawing of the first half of each stride held 3 frames and the second half 1 frame, previously lay 0.075 and read turns over frames 19 to 29, 67 to 77 and 115 to 125 that it does not make, but counting each drawing once it now lies 0.000 and is not read, with the warning line. Through the codec and keying (libx264 and `video-frames`), at most 2 of its 74 held frames came back the same pixels as the frame before, so it previously lay 0.076 to 0.083 and read turns that it does not make, but counted once under `HELD_MAX` it lies at most 0.013 and is not read. Held against the drawing last counted, a large or slow body is counted each time it has moved `HELD_MAX` from the drawing last counted; the synthetic walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels: seen square from behind (its still taken 6 frames into its stride) its `walk_side` lies under `WALK_SIDE_MIN` and it is not read; seen at an angle its `walk_side` lies over `WALK_SIDE_MIN` and it is read. Where the still passes `SIDE_SHOWN_MIN` and `walk_side` lies between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read`, `why` starts "the walk is seen square", and cuts match search alone. Angled walks lie 0.061 or more (the 447 synthetic turn windows 0.090 or more), whereas square walks now all lie at 0.000 (the front walker with a 70 px tail moved from 0.013 to 0.000). When square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side`, giving the still's side and `walk_side` in that parenthesis, naming a front or back walk or a body that turned for much of the walk to face the camera or to its mirror, saying its facing is not read, and ending `check the loop's facing`. Reading `walk_side` costs one more crop per frame.+- Named limits: a piece apart from the body over a hundredth of body pixels is read as body: on synthetic walkers (3849 solid pixels), a 7 px fleck over frames 30 to 39 (49 px) tops the box, reading a turn. The box bottom is the last solid row: pieces under the feet (3 to 10 px square, 1 to 45 px under, across frames 30 to 39) stop turn reads, or return a verdict of `not-read` from about 25 px under in the still. Neck rows spaced 2 % of height apart shift grid steps on 1 px box changes. A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: of 863, 372, 808 and 148 placements of a piece under a hundredth of the body about the heads and torsos of four walkers that do not turn (in the still alone, in every frame but the still, or over frames 30 to 39), 11, 1, 22 and 0 leave the clip unread, each a piece in the still alone (21 of 34 right or left of the head at 6 or 20 px, 13 beside an arm) laying the still's head and shoulders under 0.08 off their nearest mirror. The piece-in-the-still case is now closed by `WALK_SIDE_MIN`: that square walker's still is read when `SIDE_SHOWN_MIN` is lowered to 0.06 (or `GUARD` set to 2, or `STEP` to 1), but its walk is not (`walk_side` 0.000); only with `WALK_SIDE_MIN` also at 0 does it read turns (frames 15 to 21 and 39 to 43). `GUARD` and `TOL` are pixels of the frame, so a larger body's margin narrows: the plain walker drawn 1.5, 2 and 3 times as large, with the 3 by 12 px column drawn as many times as large beside its head in the still moving the centre 1.8, 2.7 and 4.0 px, the walk reads least +0.78, +0.44 and +0.31 without turning. (a) A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn. (b) A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read. (c) A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006. (d) A frame is counted once only where under `HELD_MAX` of the drawing last counted's solid pixels flip: a part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise over `HELD_MAX` (at crf 28, some of the synthetic walker's held frames), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; over `WALK_SIDE_MIN` it is read and reads turns it does not make. And a drawing that flips under `HELD_MAX` of the drawing last counted (a large or slow walker where its stride turns) is taken for that drawing held and is not counted.+- **Tests**: synthetic tests in new test file `tests/video/test_loop_body_turn.py` verify a 73-frame, 24-frame cycle back-diagonal walker seen from behind (legs side by side swinging half a cycle apart, arms either side swinging opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek toward the facing) whose turn moves its facing over to the still's mirror and back. Tests verify boundary turnovers: a torso reading of exactly 0 is not turned and one just under it is; three turned frames in a row are not a turn and four are; a frame not read ends a run; and `SIDE_SHOWN_MIN` set to the walker's own still side reads the clip and set just above it does not. The walker that turns reads one turn inside the frames it turns over and none elsewhere; the same walker not turning reads none; drawn square from behind it is not read. The same turn drawn on twos reads the same frames as on ones (within a frame), in fewer drawings. On a lead-in where the first 8 frames are filmed from 0.6 of the size (which the search leaves out), the report's `body_turn.reference` is 0, the turn reads over the frames it reads over without the lead-in (under -0.1), and the walk where it does not turn stays over +0.1; read from the first frame after the lead-in, the walk that does not turn is not read, and with `WALK_SIDE_MIN` at 0 it reads a turn every stride. A hooded walker with no neck reads its neck at the top row of the range (0.11) and finds the turn too, and finds none where it does not turn. The walker facing past its mirror 3 frames in a row reads no turn (however deep); 4 frames in a row read one turn of 4 frames. The suite's half-step side walker with a 60 px tail reads no turn at `HEAD_REACH` 0.3 and a turn every swing at 0.35. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.63), 3.3.0 cuts 22/24 (frames 22 to 45) across the turn, while this version refuses the windows that hold it and cuts 41/24 (frames 41 to 64); and turning over frames 14 to 24 and 24 to 34 where 3.3.0 cut 11/24 and 17/24 across the turn, this version cuts 35/24 and 41/24. When a walker turns in every cycle, `warn` keeps the cut the search took before, byte for byte, with the warning line, while `refuse` refuses it with `video-loop: the body turns in the walk` as the first line and hands nothing over. Walkers that do not turn and walkers drawn square are cut byte for byte as the search alone cuts them. The walker that turns (over frames 30 to 40) is cut with the cycle search replaced by one that finds no cycle in any window (as on a clip that holds no repeat), and its feet are not read; `warn` refuses it in the words it was refused in before (`video-loop: no periodic cycle found`), after the warning line naming the turn; `refuse` refuses it with `video-loop: the body turns in the walk`. Passing `--body-turn refuse` without `--anchor motion-auto` is refused. New synthetic tests in `tests/video/test_loop_body_turn.py` verify that the staff walker's still is not read; the staff over frames 20 to 29 and a 2 pixel sliver at frame 40 leave those frames null with their reason, every other frame reading as it reads without them; a pennant apart above the walker leaves the still's torso rows empty and the still unread; the pennant over frames 20 to 29 only leaves those frames' torso crops empty, so they are null, not 0; a head on a pole (one column under the head's centre) gives a crop of no width and the still is not read, and a frame of one solid pixel is null; a clip with no frames is not read; and under the default `warn`, the staff walker and the walker with the pennant in its first frame alone are cut byte for byte as the search alone cuts them, and the report says why they were not read. For `torso-side-v2`, new synthetic tests in `tests/video/test_loop_body_turn.py` verify that the 42 named walkers each read as drawn (a turn inside the frames it turns over, none where it does not, unread where the still cannot be read), the 7 px fleck reading its frames turned as the named limit; the antenna or whisker cut loose with a 3 px fleck at 186 placements reading no turn (marked slow); a piece apart under the feet over frames 30 to 39 (3, 6, 7 and 10 px; 1 to 45 px under) reading no turn; `MASS_SHARE` on both sides (the 6 px fleck and the antenna cut loose read no turn at 0.01, the 7 px fleck reads its frames turned at 0.01, the antenna tops the box and the walk reads three turns at 0.005, the 7 px fleck reads no turn at 0.0125, and the walker's 3849 px put a hundredth between 36 and 49); `HEAD_CORE` on both sides (at 0.5 neither the fleck beside the head in the still nor the ornament moves the still's centre, the fleck's walk reads no turn and the ornament walker reads its turn; at 0.3 the fleck moves the still's centre more than 1 px and less than `TOL` and the walk still reads no turn; at 0.35 the ornament moves it less than `TOL` and the turn still reads). The walker drawn in one grey crops as its own mirror about its head's axis (head and shoulders and torso under 1e-6 off it), and in its own tones its still lies 0.10 to 0.11 off its mirror; with the still's centre read 0.25 to 1 px off either way the walk reads no turn and no frame's side moves 0.07; a 6 by 6 px square or a 3 by 12 px column 6 px right of the head in the still, or the column over frames 30 to 39 of the lead-in walker, reads no turn, and the same walkers turning read their turn inside frames 30 to 40; the hooded, lead-in and plain stills lie between 0.08 and 0.11 off their nearest mirror, and the walker seen square with a 3 by 12 or 2 by 18 px column or a 6 by 6 px square against its head or 6 px from it in the still is not read (its side between 0.05 and 0.07); with `GUARD` 2, `STEP` 1 or `SIDE_SHOWN_MIN` 0.06 the square walker with the 3 by 12 px column has its still read but its walk not ("the walk is seen square"), and with `WALK_SIDE_MIN` at 0 as well it reads turns; `TOL` 0 reads the lead-in walker with the column over frames 30 to 39 turned there; and the side walker with a 60 px tail and its arms reads no turn with every frame's centre read 3 px left, where at `TOL` 1 it reads a turn with them 2.25 px left. The square walker taken 6, 3 or 9 frames into its stride, or 1, 2 or 11 frames with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still, has its still over `SIDE_SHOWN_MIN`, `walk_side` under 0.005, and is not read, while with `WALK_SIDE_MIN` at 0 it reads three turns. The walker seen square from behind whose still shows a side, each drawing of one half of its stride held 2, 3 or 4 frames and each of the other half 1 frame (taken 2, 3, 6, 9 or 11 frames into its stride; alone, or with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still), is not read, with the warning line, and its `walk_side` is the same as drawn on ones (within 0.002 with a piece); with `WALK_SIDE_MIN` at 0 it reads turns. The plain, hooded, turning and hooded turning walkers held the same way have the same `walk_side` as on ones, read their turn over the frames that hold the drawings they turn over (drawings 30 to 40), and read none where they do not turn. The square walker held 3 and 1 frames over the two halves of its stride (taken 6 frames into its stride, alone or with a 6 by 6 px piece beside its head in the still), each held frame with 6 of its edge pixels cleared (under 0.2 % of its solid pixels), has the same `walk_side` as without the noise and is not read (with `HELD_MAX` at 0 it is read, with turns), while the turning walker held the same way with the same noise has the same `walk_side` as without it and reads its turn over the frames that hold drawings 30 to 40. Through libx264 (its default crf 23) and `video-frames`' keying (a slow test, skipped without ffmpeg), the square walker held 3 and 1 lies under 0.02 and is not read, and the turning walker held the same way reads its turn over the frames that hold drawings 30 to 40. The walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels, seen square from behind (taken 6 frames into its stride) is not read (`walk_side` under `WALK_SIDE_MIN`), and seen at an angle is read (`walk_side` over `WALK_SIDE_MIN`). `walk_side` lies between 0.08 and 0.11 for the plain, hooded, lead-in, turning, hooded turning, turning-every-cycle and on-twos walkers, between 0.07 and 0.075 for the side walker with a 60 px tail on a 45-frame beat, and under 0.005 for the square walker taken 3, 6 or 9 frames on, and `WALK_SIDE_MIN` is 0.045. The walker turned to its mirror over frames 18 to 53 (36 of 73) is read with its turn over frames 20 to 51 and no warning, over 16 to 55 (40) is not read (`walk_side` under 0.005) and gets the warning (naming the turn to its mirror), as does the walker turned over 15 frames of each 24-frame cycle, and over 14 to 57 (44) is read with its turn over frames 16 to 55, `walk_side` under 0 and no warning. Cut by `video-loop`, the walker turned square at frame 24 and held to the end is not read (`verdict` `not-read`, `walk_side` under 0.01), prints exactly one warning line beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing` that gives the still's side and `walk_side` and names the turn to face the camera or to its mirror, and is cut every byte as the search alone cuts it, while the diagonal walker that does not turn and the walker drawn square print no such line.++ ## v3.5.0 - Widened square canvas framing for side walk and run stride and trailing parts, measured background matte cutout for flat backgrounds of any colour, and failure when a cutout removes nothing++ **Upgrading from 3.4.0: `video-set` now frames a walk or run filmed from the side on a square widened by the room its still lacks, and a background the chroma engine did not recognise, which used to come out with nothing removed, is now cut out.** A still that leaves less than `GAIT_ROOM` clear in front of its silhouette (0.15 of the silhouette's height) or behind it (0.25) gains the columns it lacks on that side; the square gains the same number of rows above the still. A still that leaves the room keeps its canvas to the byte. Every other state, a front, back or diagonal view, `--shape` and `--fit tight` are framed as before. Each side walk or run's `canvas.report.json`, and its item in `set.report.json`, gains `room`. `video-canvas` gains `--view` and reads the room only with `--view side`. Backgrounds the chroma engine already recognised key byte for byte as before. A pure or recognised magenta/green background still goes to the chroma engine and a bright achromatic one to the white matte, with the same bytes.++ - **New: the walk's room (`canvas.gait_room`, `GAIT_ROOM`, `ROOM_VIEWS`).** Filmed from the side, a walk's stride reaches in front of the standing silhouette, and behind it the stride and a part that trails behind the body (a big tail, a long coat) swing past it. Where either met the left or right edge, `video-frames` refused the clip, and the walk had to be filmed again with `--shape wide`. The `walk` and `run` rows now read the still's room: the empty columns between the silhouette and the left and right edges of the square the row makes of the still, in front and behind, as a fraction of the silhouette's height. A side under its `GAIT_ROOM` (more behind than in front) gains what it lacks, and the frame stays square: the clip keeps the 1:1 a walk is filmed at, and the still is never scaled. The report's `room` records the view, the silhouette, the room on each side, the bound, `short`, `added_px` (columns per side) and `added_rows`, and a widened canvas's `why` says why. `--shape square` keeps the still's own square. `--shape wide` is still the walk's 16:9 row (`GAIT_WIDE`). See [video-pipeline](docs/video-pipeline.md) section 1.+ - **Changed: `canvas.subject_rows` is now `canvas.subject_box`**, which reads the columns as well as the rows. `--fit tight` reads its rows from it, byte for byte.+ - **New: the measured background matte (`sprite_gen/frames/measured_matte.py`, rule in docs/chroma-alpha.md "The measured background").** It reads the background's colour and spread from a ring inside the image's edges, keys that colour and its hue in shade (a drop shadow, a gradient), thin dark strips along the edges, and enclosed pockets of a saturated background, then unmixes a 2 px edge between the local background and the nearest solid subject colour. No colour needs a route of its own: a muted yellow-green, an off-cyan, a grey or an off-white key the same way.+ - **Fixed: `cutout --key green|magenta` and `extract_route` on a background the engine does not recognise as that key.** Such a background was keyed against the pure key and nothing came off, and `cutout` exited 0; a green behind dark edge strips was routed to the white matte. It is now measured (`route: measured`, `chroma_key_painted` the measured colour), so `video-canvas` repaints such a still to the exact key, and `cutout` keys the frames of such a clip one by one. `video-frames` keeps keying a clip from one exact key: it still refuses such a clip, with the same bytes and report, and its guidance to normalise the still with `video-canvas` now works on these backgrounds.+ - **Fixed: `cutout` fails when it made nothing transparent**, like `gen/chroma.py`, instead of reporting success.+ - CLI: `cutout --key measured` forces the measured matte; `auto` sends a corner that is neither a key nor bright and achromatic to it.+ - Report fields (`route: measured`): `background`, `background_spread`, `background_ring_share`, `shade`, `tolerance`, `edge_strips`, `keyed_pixels`, `pocket_pixels`, `edge_pixels`, `band`, `key_residue_px`.+ - Python callers: `extract_route(..., measure_unrecognised=True)` and `cutout(..., measure_unrecognised=True, refuse_empty=True)` (`video-frames` passes both False); new `cutout.key_recognised(image, kind)`, `measured_matte.measured_matte(image, band=2)`, `measured_matte.measure_background(rgb)`, `measured_matte.background_like(rgb, colour, tolerance, shade)`.+ - **Tests**: new `tests/frames/test_measured_matte.py`, synthetic only: a subject with a dark outline, skin and hair colours on muted green, deep green, off-cyan and yellowish backgrounds with noise, a gradient, a darker shade round the subject, dark strips on two edges and a pocket of background inside; an off-white background measured on request; the routing of a green request on a muted green through `extract_route`, `cutout` and `video-canvas`; a cutout that keys nothing fails.+ - **Tests**: `tests/video/test_walk_canvas_room.py` covers these cases:+ - a side walk whose tail reaches 6 px of the edge behind, facing either way, gets a square widened behind and above by what it lacks, the still unscaled, through `video-set`'s item and report;+ - a person with room keeps the default row's canvas byte for byte;+ - front, back, diagonal and unnamed views are not read;+ - each bound flips one pixel either side of its `GAIT_ROOM`, the one behind larger than the one in front, and both short sides each gain their own lack;+ - a still taller than it is wide is read in its square;+ - a white base is read on its corner colour;+ - a run is read at the walk's bounds;+ - `--shape square`, `--shape wide`, `--fit tight` and another state are not read;+ - `--view` works from the command line.++ Four `video-set` tests' canvas stubs now take `view`, and `test_edge_speck_lead_in.py` reads the walk's own row.++ ## v3.4.0 - Loop part pop retakes, cycle alignment walk beat repair and broken beats, ghost limb faults, and same foot, filmed jump, and seam jump retakes++ **Upgrading from 3.3.0: A walk or run loop in `video-loop` is cut to the same bytes, whether a part pops in it or not, and `video-cycle-align` changes only alignment outputs whose beat broke or where a made frame has a limb seen through under `--between auto`.** For `video-loop`, every walk and run report gains `part_pop` and `retake`; `--unfixed refuse` also refuses a loop recorded `retake` reason `part-pop`, whatever `--repair`; no flags are added, no frames are made and no other cut is taken. `video-cycle-align` now reads ghost bands in windows of the body to catch limbs seen through, keeps frames given way on the beat under `--between auto` by making them again at clean fractions or widening jolts across neighbouring frames, changing only alignment outputs whose beat broke (a jolt of 0.25 beat or more) or where a made frame has a limb seen through (ghost window over 1.4 %); loops keeping the beat, loops with no frame given way, and `video-loop` (and `video-set`) keep their bytes for strip PNG, GIF, WebP, and cycle frames, while gaining `beat`, `ghost_window`, (on back and back_diagonal views) `same_foot`, and `retake` reasons (`broken-beat`, `same-foot`) in alignment `strip.json` and reports; every aligned loop's `strip.json` and report gain `screen`, and loops whose cut jumps gain the reasons `filmed-jump` and `seam-jump`, frames unchanged; and `clip_feet` in `video-loop`'s `strip.json` and reports for every walk or run cut; all outputs from `video-loop-compare` and `video-loop-repair` are unchanged, bytes included, and `--same-foot` defaults to `warn` so nothing is refused by default.++ - **New: The part reading and the `retake` record.** Squares 8 % of the body height are followed drawing to drawing and a part whose jerk leaves the curve its steps either side draw pops at the wrap. The cut stays and the report records a take to film again (`retake`, reason `part-pop`): `remedy` is `retake` where the engine's search chose the cut, and `recut-or-retake` where the cut was given (`--cycle fixed`, or `pinned`); `searched` says which. See [loop-repair](docs/loop-repair.md) section 2, "The part pop".+ - **New: a made frame's ghost band is now also read in windows of the body (`rife.ghost_window`, constant+ `rife.GHOST_BAND` = 0.10) to catch limbs seen through.** On frames the cycle alignment makes,+ `rife.ghost_window` counts the same part-covered pixels in regions at least `rife.GHOST_THICK` (5 px)+ thick that `rife.ghost` counts, but in windows a tenth of the body high sliding a quarter window at a+ time down the body, each as a share of the solid pixels in that window, reading the largest window's+ share and where it lies as fractions of the body from the top (`ghost_window_at`). Over+ `interpolation_quality.GHOST_WINDOW_WARN` = 0.014 (1.4 % of a window's solid pixels), the made frame has+ the fault `ghost` (though whole-body `ghost` stays under 0.3 %) and gives way, or is made again at another+ fraction, warning that it carries a limb seen through (for example: "carries a part-covered band over+ 2.40 % of the solid pixels in a band 10 % of its body high (60 to 70 % down it), at least 5 px thick,+ though 0.18 % of its whole body, a limb seen through, a ghost"). This catches RIFE blending coverages+ over a gap beside a limb; it is not read on `video-loop`'s jump repair frames or filmed frames.+ - **New: `video-cycle-align` reads the loop's beat and keeps frames given way on it under+ `--between auto`, checks for the same foot stepping twice, and `video-loop` records whether each cut+ steps the same foot twice (`clip_feet`).** On every aligned loop, `video-cycle-align` reads the leg+ path over the lowest `LEG_PATH_BAND` = 0.10 of the figure box (`BLOCK` 8 x 8 px, `SEARCH` 12 px,+ `MATCH_BAD` 40 of 255, `READ_HEIGHT` 410 px) and measures the beat jolt across each gap (`BEAT_JOLT`+ = 0.25 beat). Under `--between auto` (the default), where a loop's beat breaks from frames given way+ to the nearer source frame, the frames given way are taken in runs of neighbouring frames and made+ again at clean fractions (`align.RETIME_T` = 0.15 to 0.85, step 0.05) within `BEAT_JOLT` of their+ times, or their jolt is spread over neighbouring frames (`align.WIDEN` = 2, then 3 frames each side)+ moved off their own times and made by RIFE. A frame made only to keep the beat is taken only where+ its window reading is under `align.RETIME_WINDOW_MAX` = 0.006, well under the 1.4 % fault limit,+ besides having no fault. Runs that cannot be kept stay on the nearer source frame, are named in+ `beat.named`, and carry the `broken-beat` reason under `--between auto` in the `retake` record when+ beat gaps remain at `BEAT_JOLT` or more. On views where feet stand side by side (`STEP_VIEWS` = back,+ back_diagonal), `video-cycle-align` reads whether the same foot steps twice in a row (`FOOT_ROWS` = 0.03,+ `LIFT_MIN` = 0.010, `LIFT_CELLS` = 2, `DOWN_MAX` = 0.006), recording reason `same-foot`, and warns+ under `--same-foot warn` (the default) or stops the set before anything is rewritten under+ `--same-foot refuse`. Each reason has one warning line replacing earlier separate beat and same-foot+ lines, naming what is likely to fix it ("retake", "recut", or "recut-or-retake"), and the report's+ `retake` list carries these loops like the others (under `--between nearest` a broken beat is recorded+ in `beat` but is no reason). `video-loop` reads every cut of the cut's length on keyed frames of+ walks and runs, recording for every cut whether that cut, looped, steps the same foot twice (`clip_feet`)+ in `strip.json` and its report.+ - **New: `video-cycle-align` reads a jump the take films between two of its frames, or at the cut's seam,+ on the screen as well as the beat.** For each step of the cut's own frames (`cycle.source/`, step i+ from frame i to i + 1, the last step from the last frame to the first, which is the cut's seam),+ `cadence.screen_steps(frames)` reads the mean absolute luminance difference over white (0 to 255) of+ the box every frame's figure fits in (`whole`) and of its lowest `cadence.SCREEN_ROWS` = 0.30 (`legs`;+ a strip cell's lowest 125 of its 406 px), read at `READ_HEIGHT` 410 px. The beat reads only the leg+ path where the feet go (the lowest 10 % of the box); two drawings filmed a pose apart (legs wide apart+ in one, crossed in the next, the tail up) move the feet little and change the picture much, so the beat+ passes them, but the screen sees them. It is read on the cut's own frames, not on the aligned frames+ (an aligned frame spans two or three of the cut's frames, which spreads a jump over the drawing changes+ beside it and hides it), on every aligned loop whatever its view and whatever `--between`. Under+ `cadence.screen_record`, a step is a jump when, over the box or on its leg rows, it is at least+ `cadence.SCREEN_JUMP` = 2.0 times the cycle's typical step and at least `cadence.SCREEN_ALONE` = 1.3+ times every other step of the cycle. The typical step is the upper quartile of the cycle's steps: on+ ones every step is a drawing change, on twos or threes most steps change nothing and the upper quartile+ is a drawing change. A cycle whose drawing changes are all alike names none; so does a cycle with two+ steps alike however large (neither is 1.3 times the other). A jump inside the cut gives the `retake`+ reason `filmed-jump` (details `filmed_jump`: `steps`, `at`, `whole`, `legs`, `remedy`+ "recut-or-retake"), because the take jumps between two poses there and the alignment does not change+ the poses a take shows; where the clip films another cycle without the jump, a cut of the same clip+ from there removes it, and where it does not, a new take does. A jump at the seam gives `seam-jump`+ (details `seam_jump`, same keys, `remedy` "recut-or-retake"), because another cut of the clip may close+ on a pose it holds, or a new take may not need the cut to close there (limits `screen_jump`,+ `screen_alone`, `screen_rows`). Warning lines name what is likely to fix it (for example: "<loop>: cut+ it again or film this direction again (filmed-jump): the take jumps between two of its frames, from+ frame 30 to 31 of cycle.source/ the picture changes 22 of 255 over the figure's box and 36 on its legs,+ 2.10 and 2.50 times the cut's typical step and 1.50 and 1.80 times any other step (the loop's frames 13+ to 14); the alignment does not change the poses a take shows. Where the clip films another cycle+ without the jump, a cut there fixes it; where it does not, a new take does", or for a seam jump:+ "<loop>: cut it again or film this direction again (seam-jump): the cut's seam jumps, from frame ... ;+ another cut of the clip may close on a pose it holds, a new take may not need the cut to close there").+ - **Report fields:** `cycle_align.beat` in `strip.json` and report row `beat` record `jolt`, `gap`,+ `over`, `jolts`, `limit` (0.25), `band` (0.1), and `path` (`read`, `on-time`, or `unread` with+ `why`). Each `smear` row (and a frame made again, under `retimed`) records `ghost_window` and+ `ghost_window_at` ([from, to] fractions of the body); both are `null` where the ghost screen does not+ read the loop. A retimed frame's row in `smear` has `method: "retimed"` (beside `rife` kept and+ `nearest` given way), keeps its first frame's measures and `faults`, and gains `retimed`: `t`,+ `from_t`, `off`, measures, `faults: []`, `look`. Every frame given way in a loop whose beat broke gains+ `retime`: `between`, `tried` (each fraction recording `ghost_window`, and `window_over` where it had no+ fault but read over the bar), `off_nearest`. Retimed frames count in `made_at` and `made_by_rife`, not+ `nearest_at` or `replaced`; the report gains a set-wide `retimed` count, and `beat.retimed` lists them+ per loop. Widened runs record in `beat.widened` (`run`, `width`, and `moved` with `at`, `off`, new+ source or pair and fraction); moved frames carry `smear` `method: "moved"` with `moved` and count in+ `made_at`. Runs kept on the nearer source frame record in `beat.named`. `cycle_align.same_foot` in+ `strip.json` and the report row records `read`, `order`, `steps` (`half`, `frames`, `peak`, `lift`),+ `twice`, and `clip`. `clip_feet` in `strip.json` and the `video-loop` report records `length`, `cuts`,+ `same_foot`, `alternate`, `unread`, `seam_in_step`, and `same_foot_at`. Each loop row and `strip.json`+ `cycle_align` gain `screen`: `whole` and `legs` (every step), `typical` (per region), `jumps` (each: `step`+ [i, i + 1] as frames of cycle.source/, `seam` true for the last step, `whole` and `legs` each [change, times+ the typical step, times the next largest step], `at` the gaps [k, k + 1] of the aligned (turned) loop that show+ it), and `limits` (`jump`, `alone`, `rows`). Under `--same-foot refuse`, a+ refused report is written with `applied: false`, `refused: "same-foot"`, and `same_foot`; the report's+ `same_foot` key names the mode. A loop's `retake` record (keeping its shape: `reason` the first,+ `reasons` all, details under each reason's snake_case key, `limits`) gains reasons `filmed-jump`+ (details `filmed_jump`: `steps`, `at`, `whole`, `legs`, `remedy`), `seam-jump` (details `seam_jump`: `steps`,+ `at`, `whole`, `legs`, `remedy`; limits `screen_jump`, `screen_alone`, `screen_rows`), `broken-beat` under+ `--between auto` (details `broken_beat`: `jolt`, `gap`, `over`, `named`, `remedy`; limit `beat_jolt`)+ and `same-foot` (details `same_foot`: `order`, `twice`, `clip` counting `length`, `cuts`, `same_foot`,+ `alternate`, `unread`, `seam_in_step`, or null, `remedy`; limits `lift_min`, `lift_cells`, `down_max`),+ in order: held-drawings, filmed-ghost, filmed-jump, seam-jump, broken-beat, same-foot; `remedy` is "retake",+ "recut", or "recut-or-retake", and the report's `retake` list carries these loops like the others.+ - **Python callers:** new module `sprite_gen/video/cadence.py` with `leg_path`, `Beat`, `beat_record`,+ `turned`, `same_foot`, `clip_feet`, `view_reads_feet`, `screen_steps`, `screen_record` and constants+ `LEG_PATH_BAND` (0.10), `READ_HEIGHT` (410), `BLOCK` (8), `SEARCH` (12), `MATCH_BAD` (40.0),+ `BEAT_JOLT` (0.25), `STEP_VIEWS`, `FOOT_ROWS` (0.03), `LIFT_MIN` (0.010), `LIFT_CELLS` (2),+ `DOWN_MAX` (0.006), `SCREEN_ROWS` (0.30), `SCREEN_JUMP` (2.0), and `SCREEN_ALONE` (1.3); in+ `sprite_gen/video/rife.py` `ghost_window` and `GHOST_BAND` (0.10); in+ `sprite_gen/video/interpolation_quality.py` `GHOST_WINDOW_WARN` (0.014); in `sprite_gen/video/align.py`+ `measure_made(frame, a, b, t, reads=...)` (returning every measure a made frame is judged by),+ `retake(..., beat=None, feet=None, screen=None)`, `RETAKE_JUMP_REASON` ("filmed-jump"),+ `RETAKE_SEAM_REASON` ("seam-jump"), `RETAKE_BEAT_REASON`, `RETAKE_FEET_REASON`, `REMEDIES`,+ `RETIME_WINDOW_MAX` (0.006), `RETIME_T`, `WIDEN` (2, 3), `SAME_FOOT` ("warn", "refuse"),+ `align_set(..., same_foot="warn")`, and `resample` facts gaining `beat`.+ - **Output changes:** under default `--between auto`, alignment outputs where frames given way broke the+ beat change when retimed or widened to keep the beat under `BEAT_JOLT` (0.25 beat), or where a made+ frame has a limb seen through (ghost window over 1.4 %) and gives way or is made again; loops whose+ frames given way keep the beat, loops with no frame given way or faulty made frame, and all outputs+ under `--between nearest` and `rife` keep their exact bytes across strip PNG, GIF, WebP, and cycle+ frames (gaining the `beat` record, `ghost_window`, `retake` reasons, and where `--view` is back or+ back_diagonal `same_foot` in `strip.json` and reports; under `--between rife` the alignment keeps the+ made frame and names it a ghost); every aligned loop's `strip.json` and report gain `screen`, and loops+ whose cut jumps gain the reasons, frames unchanged. For `video-loop` (and the loops `video-set` cuts),+ `strip.json` and report files gain `clip_feet` on every walk or run cut, while strip PNG, GIF, WebP,+ and cycle frames keep their exact bytes. All outputs from `video-loop-compare` and `video-loop-repair`+ are unchanged, bytes included.+ - **Tests:** synthetic test suite in `tests/video/test_cycle_align_beat.py` uses figures with an+ outlined body over two outlined feet 16 px wide (two blocks) on the ground, sliding together by 8 px+ (a block) at each drawing forward half the cycle and back, with the interpolator drawing them at the+ fraction and smearing the body where told the pair breaks, and feet standing side by side lifting in+ turn. Tests cover: a cut of 54 frames on threes aligned to 24 where every fourth frame falls half way+ between drawings with RIFE smearing at fractions 0.45 to 0.55, the nearer source frame leaving a jolt+ of 2/3 of a beat (which 3.3.0 failed) and the fix making each again at 0.4 (0.13 of a beat early,+ largest jolt 0.13, nothing named); a fraction made again with no fault but a block the background shows+ through (its window between 0.6 % and 1.4 %) is passed over for the next clean fraction (0.6 instead of+ 0.4), its try recording `window_over`; a cut of 20 stretched to 30 with two neighbouring frames given+ way, where making each again nearest its own fraction jolts the gap between them 0.325 beat but the+ run's choice (0.55 and 0.2) keeps every gap under 0.25 beat (largest 0.2), and where 0.55 is not clean+ both stay on the nearer source frame (named, largest jolt 1.0); a frame whose pair breaks at every+ fraction within the limit, half a beat late on the nearer frame, where two frames each side are moved+ a third and a sixth of a beat late and made there (every gap jolting a sixth of a beat); a cut of 40+ squeezed to 24 with one frame given way a fifth of a beat off on the nearer frame delivered as before+ without remaking; every frame at its own time giving jolt 0 without reading legs; `--between nearest`+ recording the jolt it leaves; same foot detection on back loops reading "RRL" (twice) and alternating+ "RL" round the ring, dipping under `LIFT_MIN` without reaching `DOWN_MAX` reading one step and reaching+ `DOWN_MAX` reading two steps, front, front diagonal, side, and no view not read, one half stepping not+ read, the clip that steps the same foot twice every cycle reading 29 of its 49 cuts so and 20 with their+ seam inside a step, the alternating clip reading 33 cuts alternating and 16 with their seam inside a+ step, a cut shorter than the cycle whose seam joins two right lifts reads, as a loop, right then left+ (alternating), and a clip holding just that cut counts it apart (`seam_in_step` 1, neither alternating+ nor the same foot), and a cut 1.5 cycles long joining a step to the same foot's next; a loop whose+ beat still breaks and a loop that steps the same foot twice carrying reasons `broken-beat` and+ `same-foot` with remedies (`--between nearest` and a beat with no gap over being no reason);+ integration through `video-loop` and `video-cycle-align` recording `clip_feet`, `--same-foot refuse`+ stopping the set with strip untouched and report refused, and naming the same-foot loop "film this+ direction again (same-foot)", with `remedy` "retake" and the clip's counts. New synthetic test suite+ in `tests/video/test_inbetween_seen_through.py` uses a wide body over two legs, the near leg's outer+ 8 columns cut back over 60 rows in the first source frame (a gap open to the space between the legs)+ and whole in the second; the frame made between them has that strip at alpha 0.35 in the leg's colour:+ its whole-body ghost is under 0.3 % and its hole 0, so with no window reading (3.3.0) it has no fault;+ its window reads over 1.4 %, in the legs, and it is judged `ghost`; under `--between rife` the+ alignment keeps it and names it a ghost; a band at alpha just outside 0.1 to 0.9 is not read.+ In tests/video/test_inbetween_doubled.py the frame "drawn between, smeared along the step" (the mean+ of drawings from t 0.35 to 0.65) is no longer among the clean frames: its feet are part-covered over+ 4.5 % of their window, so it is now judged a ghost (smeared half as far it is not); and in+ tests/video/test_held_drawings.py and tests/video/test_ghost_retake.py, loops whose frames the stand-in+ interpolator cross-fades and gives way now also carry `broken-beat` among their `retake` reasons (a+ loop drawn every frame with frames given way, a held loop squeezed past on twos, the filmed-ghost+ loops), held-drawings and filmed-ghost staying first where they apply.+ New tests in `tests/video/test_screen_jump.py` exercise screen jumps synthetically with an outlined+ body over an outlined bar 80 px wide in the leg rows, sliding by the drawing: a cut on threes whose bar+ slides 4 px a drawing except one drawing change of 20 px names that one step a jump (not the seam);+ cuts whose drawing changes are all 4 px name none on ones, twos, and threes; a cut with two 20 px+ changes names none; a cut that slides out all the way and comes back in one step at the seam names a+ seam jump; retake records and warning lines are covered for both reasons; and through `video-loop` and+ `video-cycle-align` at the cut's own length, the jump is named with the aligned loop's frames that show+ it, recorded in `strip.json`, while a cut whose changes are alike names nothing. Also+ `tests/video/test_loop_prop_seam_held.py` now expects `screen` among `cycle_align`'s keys.+ - **Tests**: `tests/video/test_loop_part_pop.py` (the four bounds flip the pop; flung and stays; a pop over two steps reads as their mean; an ease through a fast bell does not pop; a fist jumping 2.5, 3.5 and 5 % passes the flow and surge readings and is named; a walk whose tail, foot and eye move across the wrap, and a run, have no pop; an ordinary walk is cut to the bytes it was; a cut given whose fist pops is named, `retake` `recut-or-retake`, `--unfixed refuse` refuses, and under `warn` it is the bytes it was; a clip whose fist drifts through every cut keeps the search's cut to the bytes it was, `retake` `retake`; a clip no part pops in is cut to the bytes it was).+## v3.3.0 - PyTorch RIFE backend for CUDA and CPU, executor for a GPU on another machine, and Linux CPU and cloud T4 release lanes**Upgrading from 3.2.0: Defaults stay unchanged, cache keys update once, reports show the backend, install checks model hashes, and schemas are unchanged.** With `SPRITE_GEN_RIFE_BACKEND` unset (the default), RIFE is the `rife-ncnn-vulkan` binary as before. Its frames are the same bytes as 3.2.0. Measured: the binary's frames and sixteen-pass readings through the changed engine equal the old engine's, byte for byte. A `--between-cache` directory kept by 3.2.0 is made again once. The key now names the backend (`backend: "ncnn"`). The engine's `rife.py` changed, and its sha256 is part of the key anyway. Reports take `interpolator.kind` from what made the frames: `rife-ncnn-vulkan` as before for the binary, or `rife-torch` for the new backend. The overlapped wrap's and the seam bridge's records count `binary_calls` for the binary as before, or `runs` for the torch backend. `SPRITE_GEN_RIFE_EXECUTOR` (new) is unset by default, and RIFE runs in this process. `sprite-gen rife install` now checks the model's two files (`rife-v4.6/flownet.param`, `flownet.bin`) against pinned SHA-256 after unpacking, for either backend. A model that differs installs nothing. The line a missing RIFE is reported with (`install` in records, warnings) is `sprite-gen rife install` for the binary. Where the torch backend is chosen, that line is: `pip install "sprite-gen[torch]" && sprite-gen rife install --backend torch`. No command-line flags of `video-loop` / `video-cycle-align` / `video-set` change. No restoration schemas change: `source-restoration-v5`, repair report `schema_version` 4, comparison `schema_version` 6.diff --cc sprite_gen/video/loop.pyindex 563d9df,7648a85..79ecf81--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@@ -49,9 -49,10 +49,11 @@@ from sprite_gen.spec.runio import atomifrom sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.util.resample import resize_cellfrom sprite_gen.video import motion_anchor, auto_motion, local_cycle, gait_fallback, nonloop, effect+ from sprite_gen.video import part_pop as part_pop_mod+ from sprite_gen.video import cadence as cadence_modfrom sprite_gen.video import crossings as crossings_modfrom sprite_gen.video import held as held_mod+from sprite_gen.video import body_turn as body_turn_modfrom sprite_gen.video import legs as legs_modfrom sprite_gen.video import period as period_modfrom sprite_gen.video import repair as repair_mod