Skip to content

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

Merge origin/main (v3.8.0, 8343059) into plan/qipao-recut-cell-record-1029: the held fill and --out-fps beside the strip's record of its cells

Soohong Kim2e5beac82a73
diff --cc CHANGELOG.md
index 6a33d66,fbc09cb..b20191b
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -2,17 -2,36 +2,96 @@@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased
+
- **Upgrading from 3.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.**
++**Upgrading from 3.8.0: `video-loop` writes `cell_record` into every strip record `<name>.strip.json`, and `video-sway` gains options that shape a `--region-mask` region alongside `--read-on-cut`. Strips, frames and records keep their bytes by default, but `video-sway --read-on-cut` reads cuts by that record alone and refuses cuts made without it.** New options `--region-over` and `--region-shear` shape the region mask and its rim; both are off by default, and when not given, strips, frames, and records remain byte for byte what they were. With `--region-crease` the wear wears the crease in as before; laid over the figure the region reaches down to the crease again in every cell, changing those runs' output. Runs with `--region-over` and runs with `--region-membrane` draw differently than before this change; the four new membrane options are off by default and byte for byte as before when not given. New options `--region-over-solid`, `--region-rim-round`, `--region-membrane` and `--read-on-cut` are off by default; when not given, strips, frames, and records remain byte for byte what they were. Runs with `--read-on` alone behave as before, except that its no-match message now names `--read-on-cut`. The refusal for `--region-over` or `--region-shear` given without `--region-mask` keeps refusing the same runs, and its message now names the new options too: "--region-over, --region-over-solid, --region-rim-round, --region-shear and --region-membrane shape a region mask; they need --region-mask" (it was "--region-over and --region-shear shape a region mask; they need --region-mask").
+
- - **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).
++- **New: laying a region over the figure and widening the rim for shear (`--region-over`, `--region-shear`).** `--region-over` lays the region over the figure under it instead of pinning its lower edge, freeing held pixels under the edge (solid or not), moving the band within reach, drawing the layer over the band by alpha, drawing the air by the move, and showing the figure under its lower edge at the move where it lifts. Its soft edge moves with the region (except under the lower edge where touching a solid pixel outside keeps it in the band), its solid outline against air goes with the layer, and `--hold-mask` leaves pixels the region mask does not cover out of the layer and band while pixels it covers move with the region. `--region-shear S` widens the rim across and down so a move one way rises across the rim the other way by at most S px per px (`shear_floor`), preventing tears along the sides. With either option, the ledger records move steps between neighbouring pixels, still strips left standing, and tip outline shapes, and `--region-over` records `lifted_px`. Both require `--region-mask`, are off by default, and leave strips, frames, and records byte for byte what they were when not given. See [video-pipeline](docs/video-pipeline.md) section 6.
++- **Changed: wearing the crease row in like every other edge of the mask and reaching down to the crease only when laying a region over the figure (`--region-crease`, `--region-over`).** Removed: the step that filled each crease column back down to the crease row after the mask was worn in (`crease_kept` is gone). Now `--region-crease` ends the mask on the crease before the wear and the wear (`--region-shrink`) wears the whole mask in, the crease row too, like every other edge. So the record's `mask.box` ends `--region-shrink` rows above the crease row (2 rows at the default), as it did before `crease_kept`. New, under `--region-over` only: in every cell the region reaches down to the crease again (`crease_reach`): the crease's rows (its columns and rows on the cell the mask was drawn on; a column between two crease columns takes the nearer one's row, the left one's on a tie) are carried into the cell by the mask's carry there (the column rounded to the nearest, half to even; the row rounded down), and in each crease column where the region holds a pixel, the cell's solid pixels from the region's lowest pixel down to the crease's row join the region. The crease is the picture's own edge, so the layer reaches it in every cell while the wear still wears the mask in everywhere else. Without `--region-over` nothing reaches back down: the worn mask is the region.
++- **New: solid under-edges, round rims, figure membranes, and recut strip pairing (`--region-over-solid`, `--region-rim-round`, `--region-membrane`, `--read-on-cut`).** `--region-over-solid` frees only solid pixels (alpha 128 or more) under the lower edge into the band while keeping softer pixels as anchors, and carries the region's soft edge with it under the lower edge. `--region-rim-round` holds the rim round beside the region across the wider of its two widths (`max(Lx, Ly)`), preventing steep downward steps below corners where the lower edge runs lower. `--region-membrane N` moves the figure under the lower edge within N + 1 px as a membrane by solving 4-neighbour figure means in passes instead of conjugate gradients (from a cos² start, at most 1200 passes, leaving no piece out) so the figure stretches rather than slides, drawing membrane pixels by their move and reporting membrane-specific fold refusals. `--read-on-cut STRIP` pairs regions read on another cut of the same clip by matching source frame numbers and applying a whole-pixel shift across crops on unaligned and aligned loops alike. The shift is taken on the frame as filmed, less where each cut's body or motion anchor moved that frame. Each cut is now read by its record of its cells alone: `cell_record` in the strip's record (`<name>.strip.json`), which `video-loop` now writes, bound to the strip by `cell_record.strip_sha256` (the sha256 of the strip PNG), with one entry per cell: `source_frame`, `anchor_move_px` (where the anchor moved that frame before the crop, whole px across and down), `scale` (`size_hold` and `gait_fallback`: the factor each step that holds a clip's frames to one size scaled that frame by, 1 where it did not hold them) and `as_filmed` (true where the cell's pixels at the end of the cut are its pixels anchored before any repair, the receipt `source_projection.before_repair_pixels_sha256` in the cut's report, and no step held the clip's frames to one size). On a loop aligned from its cut it reads the cut's own record, which `video-cycle-align` now keeps beside the cut's frames as filmed (`cycle.source/<name>.strip.json`) and which must be bound to the strip the alignment's origin names (`cycle_align.origin.strip_sha256`). It refuses, no-match, saying which and naming the field: a cut with no `cell_record` (any cut made before this release), a record bound to another strip, a record that does not give its cells as `video-loop` writes them (a field missing or not of its kind, in any cell), a loop aligned from its cut with no kept record, a paired cell a hold scaled or not cut as filmed, and two paired cells that are not the same pixels where they overlap at the shift (a record changed to call a cell as filmed is held to the cell's pixels). The report beside a cut is no longer looked for or read. All four options are off by default and leave strips, frames, and records byte for byte what they were when not given. See [video-pipeline](docs/video-pipeline.md) section 6.
++- **New: the membrane's own keys (`--region-membrane-unpin`, `--region-clear-alpha`, `--region-floor-beside`, `--region-own-outline`).** `--region-membrane-unpin` makes what the membrane moves no anchor of the rim either, so the region's move does not fall to none at its first rows under its lower edge. `--region-clear-alpha A` (a whole number from 1 to 127) reads a pixel under alpha A as clear by the sets the region moves and holds and by the membrane's figure while the cell's bytes stay its own, so a speck of dust beside the figure holds nothing. `--region-floor-beside N` sets the lower edge beside the region's columns to the lowest pixel of its columns within N px of that side, not that of its nearest column alone. `--region-own-outline G` grows the region G 4-neighbour steps over the cell's solid pixels within G 4-neighbour steps of a clear pixel before the sets (never under its lower edge's line and never over pixels `--hold-mask` leaves out), moving the outline its carried mask leaves out with the region. All four require `--region-mask`, shape nothing without `--region-membrane` (leaving the same bytes and record, naming none of them), are off by default, and leave strips, frames, and records byte for byte what they were when not given. See [video-pipeline](docs/video-pipeline.md) section 6.
++- **Output change: `cell_record` in strip records, `source_projection` for motion anchors, and kept cut strip records.** `video-loop` now writes `cell_record` into every strip record it writes (the fields above). The strip PNG, the GIF, the WebP and the frames of `cycle/` keep their bytes; the strip record gains this one key. A cut's report gains `source_projection` (`recipe`, `wrap_dx_px`, `before_repair_pixels_sha256`) at `--anchor motion` and `--anchor motion-auto` too, with `recipe` `motion-anchor-correction-v1` there; it was written only at `--anchor none` and `body` before (unchanged there). `cell_record` is written in the strip record only, not in the report's copy of it. `video-cycle-align`'s first alignment of a loop now also writes `cycle.source/<name>.strip.json`, the loop's strip record as cut, byte for byte, before it rewrites `<name>.strip.json`; later alignments leave it as it is, and a new cut with `video-loop` removes it with `cycle.source/`. The aligned strip's record does not carry `cell_record` (it is the record of another strip). The pair policy `RECUT_POLICY` is now `same-clip/source-frame/whole-px-shift/2`. At `--out-fps` (3.8.0: cells each made at a time of their own, more cells than the cut has frames), the report's `held_fill.out_fps` gains `shows` (per cell, the frame of the cut it is, or null where it was made), and `cell_record` still holds one entry per cell: `source_frame` is the frame the cell is, and for a cell made between two frames the cut's frame at or before its time (the frame the seam reads it as), with that frame's `anchor_move_px` and `scale`. `as_filmed` is true only where the cell's pixels are that frame's pixels anchored before any repair, so a cell that repeats a frame unchanged is as filmed, and a cell made between two frames is not, and `video-sway --read-on-cut` does not pair it.
++- Python callers: `sway_loop`, `sway_frames`, `read_request` and `read_ask` accept `region_over` (bool; default False) and `region_shear` (float; None: off). New in `sprite_gen.video.sway`: `shear_floor`, `layer_sets`, `lay_over`, `cover_depth`, `still_strip`, `tip_shape` and `move_steps`; constants `OVER_POLICY`, `TIP_COLS`, `TIP_AIR`, `TIP_RING`, `TIP_OFF` and `TIP_SEARCH`; `RegionMask` gains `over`, `shear`, `hold` and `edges()`; `Masked` gains `sheared`, `left_out` and `left_out_in(k)`; `rim_bands` gains `floor` (None: as before).
++- Python callers: `sway_loop`, `sway_frames`, `read_request` and `read_ask` accept `region_over_solid` (bool; default False), `region_rim_round` (bool; default False) and `region_membrane` (int; None: off); `sway_loop` and `read_request` accept `read_on_cut` (Path; None: off, refused by `sway_frames`). New in `sprite_gen.video.sway`: `membrane_sets`, `membrane_move(free, figure, own, outline, move, reach)`, `recut_pair`, `recut_ask` and `read_cut`; new in `sprite_gen.video.loop`: `ramp_offset`; new in `sprite_gen.video.motion_anchor`: `laid_at`; constants `OVER_SOLID_POLICY`, `MEMBRANE_POLICY`, `RECUT_POLICY`, `RECUT_DRIFT` and `RIM_ROUND_POLICY`; `RegionMask` gains `over_solid`, `membrane` and `rim_round`; `Request` gains `read_on_cut`; `layer_sets(..., solid_only=False)` gains `solid_only` and returns the new set `below`; `read_on_relation(..., cut=False)` gains `cut`; and `transported_motion(..., paired=None)` gains `paired`. New in `sprite_gen.video.sway`: `cell_record(record, strip_sha256)` (the record of a strip's cells, a ValueError naming what it does not give), `recut_same(pair, cut_cell, cell, read_on)` (refuses two paired cells that are not the same pixels at the shift) and `aligned_from(loop_dir, meta_path, meta)` (the cut's record an alignment kept, or None); `recut_pair(meta, cut, read_on, *, strip_sha256, kept=None)` takes this loop's strip sha256 and the kept record; `read_cut` returns the strip picture under `strip`; `Request` gains `aligned_from`; new in `sprite_gen.video.loop`: constants `CELL_RECORD`, `CELL_SCALE_STEPS` and `MOTION_RECIPE`.
++- **Tests**: new file `tests/video/test_sway_region_over.py` covers these cases on synthetic figures (the region test's body and its striped part over the torso's right side and past it over the air, with a dark crease under it on the torso; an arm block beside the part's lower left; a dark outline row under the part where it hangs over the air). Each case first reads what a sway writes with the new options (its cells, its record), so on a release without them the same input fails on what comes out:
++ - without the new options nothing of them is read or written (cells and record as before, from Python with them passed off);
++ - with `--region-crease` the wear wears the crease in with the rest (the worn mask's lowest row on the torso 2 rows over the crease, its box ending there), nothing under the crease moves, and laid over the figure the region reaches down to the crease again in every cell (its lowest pixel on the crease's row in each crease column);
++ - laid over the figure under it, the lower edge moves as much as the part above it does (at gain 2.5 and 1.25), while without `--region-over` the crease pins it;
++ - the layer draws the band where it lands, no read of the move taken there, and keeps its bytes elsewhere; the move draws the air (reads are taken there); a read in the air that takes the held figure beside it (the torso's soft side past the band) is walked back, in the air alone and never on the band (4, 9 and 6 reads in three cells, none in the others); nothing outside the region, its soft edge, the air and the band changes; the layer covers no deeper than the band; nothing folds;
++ - where the part lifts it shows the figure under it: each pixel there is read at its whole move, none read short, its alpha the source's read there; read wholly on opaque pixels it stays opaque and shows the torso and the crease, not the stripes; beside the torso's soft side one column of the part's, within 2 px of that side, is as soft as its read of that side and the air past it (in 7 of the 12 lifting cells); in the rows the part leaves, its column over the torso's soft side shows thinner than that side in exactly the cells where the part moves toward the torso;
++ - its outline against the air goes with it and leaves the air behind, and its outline against the figure (the crease) keeps its bytes;
++ - two new cases for `--hold-mask` with `--region-over`: the pixels it names that the region mask covers (a piece in the arm's colour inside the part) are the region's, no anchors, and move with the part (one PNG carried and a folder per cell); the pixels it names that the region mask does not cover keep their bytes in every cell, and on a band (`--band auto` with the same `--hold-mask`) every pixel it names keeps its bytes while the part moves round them;
++ - where the part lifts off a piece in the arm's colour right under its lower edge, left out with `--hold-mask`, the part's reads that would take the piece are read from their other pixels (10 in every lifting cell), none of them lifted and all opaque: no hole opens and the piece keeps its bytes;
++ - `--region-shear` 0.5 and 0.25 widen the rim to the least it asks, so the drawn move's step across the rim stays within the bound, and less than without it;
++ - the still strip is read from the region to its side (beside the arm, the px the mask left short; over the air, 0);
++ - the tip is read on the side over the air; a tip moved whole is 0 px off its own shape, its shift found;
++ - `move_steps` reads the most step both ways where both pixels are shown;
++ - `--frames` gives the strip's cells and the same record;
++ - each refusal leaves the loop as it was.
++ `tests/video/test_sway_region.py`'s crease case now reads the worn mask's box ending 2 rows over the crease row. `tests/video/test_follow_inspect.py` now names `--region-over` and `--region-shear` among the arguments `video-sway` takes and `video-sway-inspect` does not.
++- **Tests**: updates to `tests/video/test_sway_region_over.py` and new file `tests/video/test_sway_read_on_recut.py` cover these cases on synthetic figures (the region tests' body with a striped part over the torso's right side and past it over the air; the read-on runner):
++ - over-solid: only solid pixels under the lower edge are free and drawn over; the not-opaque rest stays, an anchor, with bytes kept; the soft edge under the lower edge beside the torso goes with the part, while sliding over without the flag it belongs to the figure;
++ - the membrane at reach 3 and 6: under the lower edge within reach + 1 px, never the outline over the band; each pixel's move is the mean of its figure 4-neighbours' to within less than `MEMBRANE_STEP` (what one more pass would move it), and the record names `step_px` and `passes_most`; the seam step down from the part's last row is at most half of the one sliding over; drawn by the move, never laid over;
++ - the membrane never moves a piece left out (stops at its sides); without the membrane the layer is as it was;
++ - a membrane too short for the move is refused by its name, writing nothing;
++ - below the corner of a part whose lower edge falls from its left side, with `--region-rim-round` the move rises down by at most pi/2 of its size over the rim's wider width, and more than that without the flag;
++ - the refusals list gains each new option's refusal;
++ - without the membrane the four new options shape nothing (the same bytes and record);
++ - the four new options' refusals (each without `--region-mask`, and the values `--region-clear-alpha` 0 and 128, `--region-floor-beside` -1, `--region-own-outline` -2) leave the loop as it was;
++ - two defect shapes, each red on the engine before this change: a part laid over the figure with a few pixels not opaque (alpha 60 and 30) a few rows under its lower edge over the air and a near-clear speck (alpha 3), with `--region-over-solid`, `--region-membrane 6` and `--region-shear 0.35`: with `--region-membrane-unpin` and `--region-clear-alpha 8` the lower edge over the air moves with the part (lag 0.25 px or under), without them it stays short of the move (0.5 px or more), and under the clear alpha the speck is neither held nor the membrane's; and a part whose outline over the air takes one or two pixels past its mask in a row that changes from cell to cell, with `--band-up 0.4` and `--region-membrane 6`: with `--region-own-outline 2` those pixels are the region's and the side moves by each row's share of the move (lag 0.25 px or under), without it they are anchors and the side bends at a row that changes from cell to cell (0.5 px or more);
++ - `--region-floor-beside`: beside a region whose lower edge falls 1 px a column, the lower edge past each side is that of its lowest column within N of that side (directly on `layer_sets`);
++ - the frames path gives the strip's cells with `--region-membrane 6`;
++ - in new file `tests/video/test_sway_read_on_recut.py`, a cut again at the same frame with a wider crop moves the regions and the mask by the crop's shift and gives the sway on the regions drawn there by hand;
++ - a cut again at another start moves the mask onto the cell that is that frame, pixel for pixel, with every pixel outside it kept;
++ - a cell elsewhere in either cut that its record calls scaled or not as filmed leaves the pair as it is;
++ - a loop aligned from the cut again carries the pair through the alignment; the alignment keeps the cut's strip record byte for byte beside its frames (`cycle.source/<name>.strip.json`), bound to the strip its origin names, and a second alignment keeps it as it was; the aligned strip's record holds no `cell_record`;
++ - on a loop aligned from its cut, these are refused, each saying which: a kept record that is gone, a kept record that holds no `cell_record`, a kept record bound to another strip, a paired cell its kept record calls not as filmed, and the read cut's cell drawn between the frames either side with its record changed to call it as filmed;
++ - two cuts at `--anchor body` whose ramps move frame 4 by nothing in the first and by -6 px in the second pair that frame where each ramp moved it: shift (0, 0), no drift, the moved mask is the patch where the second cut drew that frame, pixel for pixel; the crops alone set it 6 px apart;
++ - two cuts at `--anchor body` whose ramps move no frame (both `wrap_dx_px` 0) pair by their crops alone, as before, the mask landing on the patch there;
++ - two cuts at `--anchor motion` (head and torso regions on each cut's first frame) pair the frame where each correction laid it: the shift is the crops' less where the first correction laid that frame plus where the second laid it, not the crops' alone, and the mask lands on the patch there; each cell's `anchor_move_px` is the correction's place and every cell is as filmed; the report's `source_projection` names the motion recipe;
++ - `video-loop` records each cell of its strip in the strip's record bound to its PNG: the source frame, the body ramp's move, no hold's scale, as filmed; the record is written beside the strip and not into the report, whose receipt holds one digest per frame;
++ - a cell the jump repair gave way (a filmed ghost, no RIFE) is recorded not as filmed, every other cell as filmed;
++ - refusals: a frame this loop does not hold, a record with no clip it is cut from, and without `--read-on-cut` the relation's refusal as ever, each leaving the loop as it was;
++ - a record of its cells not there or not as `video-loop` writes it is refused naming the field, on either cut: none, not an object, bound to another strip or none, no cells or one too few, a cell's entry, its `source_frame`, `anchor_move_px`, `scale`, and `as_filmed` missing or not of its kind (float, text, boolean, zero, NaN);
++ - a paired cell its record calls scaled by the size hold or the gait fallback, or not as filmed, is refused saying which, on either cut;
++ - a cell an interpolator made, on either cut, is refused whatever its record says: as `video-loop` records it (not as filmed), and with its record changed to call it as filmed (its pixels are not the other cut's at the shift);
++ - a loop aligned from its cut (`video-cycle-align`) named by `--read-on-cut`, and a cut of another clip, are refused, and what the key is refused for leaves the loop as it was;
++ - the walk away from the camera of the gait fallback tests, cut by `video-loop` with and without the size hold: the record gives the factor the size hold scaled each cell by, equal to the report's `size_hold.cut_frames`, and calls none of the held cells as filmed;
++ - the same walk cut twice by `video-loop` as a walk with the size hold on for one cut, for the other, and for both is refused, leaving the loop as it was, the record of the held cell naming its factor;
++ - the same walk held in one cut with every trace of the hold and walk taken out of the report and strip record (the report's `size_hold`, the report's `state`, the report's strip's `state`, the strip record's `state`) is refused by the record of its cells; with the record's factors and `as_filmed` taken out too, refused naming the field; with the strip record's `cell_record` taken out, refused as a record with none; with the record changed to call every cell as filmed, refused by its pixels on either cut;
++ - the command line reads the relation `recut`.
++ `tests/video/test_follow_inspect.py` now names `--region-over-solid`, `--region-membrane`, `--read-on-cut`, `--region-rim-round`, `--region-membrane-unpin`, `--region-clear-alpha`, `--region-floor-beside` and `--region-own-outline` among the arguments `video-sway` takes and `video-sway-inspect` does not.
++
+ ## v3.8.0 - Held cells found and filled with in-betweens by default, and a cut given above its clip's frame rate (--out-fps)
+
+ **Upgrading from 3.7.0: `video-loop` (and so `video-set`) now finds neighbour cells of a cut that show the same picture and, by default, makes them again with RIFE's frames between. A cut with no such cell comes out byte for byte as before. A cut with them comes out with its held cells made, its length, beat, first and last cells and wrap unchanged. `--fill-held off` cuts as before. Every cut's report and strip metadata gain `held_fill`.**
+
+ - **New: held cells found on every cut.** A frame shown twice or three times in a row (a model that stalls, a rate carried to another by repeating frames, a cut mapped to a higher rate by taking the nearer frame) is read on the analysis thumbnail used to choose the cut and on the frames as cut. A step where at most 0.5 % of the subject's pixels change by more than 0.1 in both readings is the same picture. The report and the strip metadata record `held_fill`: the cells, the poses (the cells less those showing the picture before them again), and the held runs (first cell, how many), before and after. `video-loop` prints `poses/cells` in its summary and `video-set` puts `loop.poses` on each item.
+ - **New: held cells filled by default (`--fill-held auto`).** Each run's cells are made between the run's first cell and the next pose at their own times (a run of three a third and two thirds of the way), judged as `video-cycle-align`'s frames are (smear, outline, ghost, hole, doubled) and for a part standing still on both sides (a foot planted, a hand on a ledge: its outline must stand where it stood, the fault `contact`). A frame refused is made again at a nearby fraction, else the run stays as filmed with a warning. Kept as filmed: a run longer than three cells (a hold the motion means), the opening and closing pose of a cut played once, a loop's last cells (their next pose is across the wrap), and every run of a cut drawn on twos or threes. In that case, its held-drawings reading (`cycle_drawings`, as `video-cycle-align` reads it) holds 2 or 3 and every run is that long (`held_fill.drawn`): limited animation, as filmed. A clip carried to a higher rate by repeating frames reads a hold too, but its runs are two and three cells by turns, and it is filled. With no RIFE the cells are delivered as filmed, never a failure, and a warning names the motion and `sprite-gen rife install`.
+ - **New: `video-loop --out-fps F` and `video-set --out-fps F`.** A cut given above its clip's rate is made of frames between at each cell's own time, never frames shown again: a loop keeps its cycle's seconds, a cut played once runs from its first frame to its last. The strip metadata says `out_fps` and `source_fps`, and `source_cut.times` in place of `samples`. With no RIFE the cut is delivered at its own rate with a warning. `video-cycle-align` and `video-stop` refuse such a loop; `video-set` refuses it with the cycle alignment on (pass `--align-cycles off`).
+ - A cut whose cells were made is read by the seam gate on its rendered cells, is not restored from its source frames (`video-loop-repair`: `source-processing-unsupported`), and `video-cycle-align` reads its drawings on its own cells.
+ - Python callers: `sprite_gen.video.held_fill` (`same_steps`, `runs`, `reading`, `fill`, `upsample`, `times`, `still_kept`, `judge`, `public`, `said`); `loop.run_loop(..., fill_held=, out_fps=)`; `batch.run_set(..., fill_held=, out_fps=)`.
+ - **Docs**: [loop-repair.md](docs/loop-repair.md) section 7 (the reading, the fill, the higher rate, the paths that give frames at a higher rate, what it takes from sprite-gen); [video-pipeline.md](docs/video-pipeline.md) section 4 (the default step: find, fill, read again; poses over cells in one line); `SKILL.md`.
+ - **Tests**: `tests/video/test_held_fill.py` (synthetic clips and a stand-in interpolator that draws the clip again at the time asked: six cuts with no held cell pinned to their decoded pictures on the engine before the change (commit 886936e); a stalled walk filled at a half, a third and two thirds, every other cell as filmed; `--fill-held off` byte for byte as before; no RIFE delivered as filmed with the motion named; a hold of five kept; a walk drawn on twos kept as filmed, byte for byte as `--fill-held off`; a walk carried from 24 to 60 fps by repeating frames filled to 60 poses in 60 cells; a once and a one-shot cut filled; a planted foot kept still, and a frame between that drags it or cross-fades two poses refused; the ends of a cut played once and a loop's last cells kept; codec-like copies are the same picture and a pixel's move is not; a whole figure moving under a thumbnail pixel is not the same picture; a walk at 60 fps made of 60 poses in 60 cells; a one-shot at 60 fps keeping its first and last frames; no RIFE at its own rate; a rate under the clip's refused; the switches through `video-loop` and `video-set`; restoration, the alignment and a stop refusing what they cannot read).
+
+ ## v3.7.0 - Breathe row width and height minimum and maximum sizing, and curator breathe editor range inputs
+
+ **Upgrading from 3.6.0: a Breathe row's breath can now be sized by the two ends it travels between, across and up, instead of a strength (`width_min`, `width_max`, `height_min`, `height_max`; flags `--width-min`, `--width-max`, `--height-min`, `--height-max`). Every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar; the curator's breathe editor shows four range inputs in place of the two depth selects.**
+
+ - **New: a breath's width and height as minimum and maximum (pixel and smooth).** Each is a share of the original. Width is how much the torso widens at the row where the breath is fullest (pixel: the row where the envelope peaks; smooth: the chest's peak P), negative narrower. Height is how far the head top (pixel) or the chest (smooth) rises, as a share of the body below the neck, negative down. Each lies in -0.20 to 0.20 with minimum at most maximum; a bound left out is 0, and null is left out. A minimum of 0 keeps the breath from going under the original size. The curve's shape and beat (`breaths`, `breath_peaks`, `lag`, `inhale`) are unchanged. In pixel, one gain widens a row by 1 + g and shortens it by 1 / (1 + g), so the top of the curve is (`width_max`, `height_min`) and its bottom is (`width_min`, `height_max`). In smooth, rest is at both minimums and the top of the in-breath is at both maximums, so a minimum other than 0 moves the rest cell off the source.
+ - A strength converts exactly. A pixel row of `depth` d has height [-0.9009 d, 0.9009 d] (0.9009 is the breath curve's peak, `breathe.WAVE_PEAK`) and width [-a, a], with a = 0.9009 × `depth_x` (or `depth`) × the amplitude norm × the envelope's peak; a smooth row has height [0, `depth`] and width [0, `depth_x`]. Written as minimum and maximum, these bake the same bytes. `sprite-gen breathe` records the row's `range` (`{"width": [min, max], "height": [min, max]}`) in `breathe.json` for that conversion. Pixel rows move whole rows and columns, so the extremes measured on a plate are within one cell of the values written.
+ - Refused, not silently resolved: a row with both a strength (`depth`, `depth_x`) and minimum or maximum keys, a value out of range or not a number (booleans included), a minimum above its maximum, and minimum or maximum keys on a round chest row. The row strain limit (0.25) is checked at the largest gain the curve reaches, and its refusal names the keys to reduce. The pixel clip refusal now says to reduce the breath's size (depth, or minimum and maximum) where it said depth.
+ - Python callers: `breathe.WAVE_PEAK`, `breathe.envelope_peak`, `breathe.pixel_gains`, `breathe.breathe_range`, `curation.BREATHE_RANGE_KEYS`, `curation.BREATHE_RANGE_MAX`. `breathe.smooth_lift` is the chest's rise from rest to the top, which `video-sway --breathe` and `--avoid-region` read: (`height_max` - `height_min`) × the basis height for a minimum and maximum row.
+ - **Curator**: the breathe editor's two depth selects are four inputs (width minimum to maximum, height minimum to maximum, in %, 0.1 % steps, -20 to 20). A strength row shows the range its strength travels; editing one input moves the row to the four keys, the untouched ones carried at their exact values so that axis bakes the same bytes. The inputs are off for a round chest row and, on a pixel strength row, until the anatomy arrives. Loading a sidecar now keeps a strength row's `depth_x`, `axis_x` and `torso_half`, which the first autosave dropped before. A new row inherits a sibling row's minimum and maximum keys as it inherited a depth. The preview mirror bakes minimum and maximum rows byte for byte as the bake does.
+ - **Tests**: `tests/effects/test_breathe_min_max.py` (synthetic figures: strength rows keep their bytes and normalized sidecar; minimum 0 is never narrower nor taller on any row or phase; the written extremes are what the plate measures, within one cell; a strength's range written as minimum and maximum bakes its bytes; smooth from 0 is the old smooth; refusals and the strain limit), new cases in `tests/effects/test_breathe_js_mirror.py` (minimum and maximum parity, `breatheRange`), the value-shape matrix over the four keys and the kept `depth_x` and band in `tests/effects/test_breathe_sidecar_roundtrip.py`, and the mirrored constants in `tests/effects/test_breathe_reference_key.py`.
- **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.**
+ ## v3.6.0 - Two step walk and run loop cuts with half step warnings, loop search past untracked anchor frames, body turn loop exclusion, round chest breathing with sideways arms, and sway region mass movement
+ **Upgrading from 3.5.0: `video-loop` walk and run cuts change for two-step cuts and half steps under `--anchor motion-auto`, opening frames the motion anchor cannot track, and body turns, while new `sprite-gen breathe` and `video-sway` options are off by default.** In `video-loop`, a walk or run cut shorter than its state's gait floor, its steps not counted, is now cut two steps long under `--anchor motion-auto` where the clip as filmed comes back nearer two lengths on than one, and says so where it does not (`cycle.half_step` and a warning line); every other cut keeps every byte. A walk or run whose first frames the automatic motion anchor cannot track is now searched after them, as after a lead-in, where it was refused; every clip the anchor tracks from its first frame keeps every cut and byte. A clip whose cut held a turn is now cut where a window without the turn holds a cycle, while clips with no turn, clips that are not read, and clips with a turn and no turn-free cycle under `warn` keep every cut and byte. A pixel Breathe row can now breathe round from the chest, with the arms moving sideways (`chest_round`, `arms_x`), and `sprite-gen breathe` takes cells held still (`--hold-mask`), what the arms hold (`--props-mask`), pieces held behind the body (`--props-behind-mask`), and props grouping (`--props-groups`). All are off by default: every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar. `video-sway` can move each region as one mass with `--band`. When `--band` is left out, strips, frames, and records remain byte for byte what they were. Passing `--band PX|auto` moves each region's ellipse and an outer margin at full weight, with the weight falling to 0 by cos² over a band of pixels around it, while carrying the region by its own pixels rather than the body's outline lay. The fifth region number `flat` and `--stretch-floor` are refused when `--band` is specified. In the strip's metadata, `follow` gains `band` (and `sway.json` gains `band` for `--frames`), while stdout JSON gains `band` with `band_px`, `margin_px`, and `lay_cells`. The legacy command name `video-follow` accepts the same flags. `video-sway --band` can now hold pixels with `--hold-mask`, leaving them as they are while regions move round them. It is off by default, and when not given, strips, frames, and records remain byte for byte as before. `video-sway` can now move a region's own pixels with `--region-mask`, holding every visible pixel outside it and its soft edge while the weight falls over an inner rim read off the move. It is off by default, and when not given, strips, frames, and records remain byte for byte what they were (with `--band`, with `--band` and `--hold-mask`, and with neither).
+
+ - **New: `video-loop` names a half-step cut.** A walk or run loops on an even number of steps (two, one cycle). The half-period guard reads the gait floor (`LoopProfile.min_seconds`) in whole frames, rounded, so a run cut 8 frames long at 24 fps (0.33 s, under the run's 0.35 s) is taken as two steps. Such a periodic cut whose steps nothing counted (no `cycle.steps`) is kept, recorded in `cycle.half_step` (`rule`, `state`, `seconds`, `gait_floor`, `why`, `two_steps`; in the stdout summary too) and named in a warning line that suggests `--steps 1`; the line repeats no refusal's words. Python callers: `loop.half_step`, `loop.half_step_verdict`, `loop.HALF_STEP_RULE`. Docs: [video-pipeline.md](docs/video-pipeline.md) section 4. **Tests**: `tests/video/test_loop_half_step.py`.
+ - **Changed: `video-loop --anchor motion-auto` cuts such a cut two lengths long where the clip says it holds two steps.** One step on, the legs are back in place with near and far swapped, and where they are drawn alike the silhouette repeats; the body's turn, the shading across the torso and the folds of the clothes come back only two steps on. Each length of [2L − 1, 2L + 1] is cut as `--steps 1` cuts it, and about each cut's wrap (two frames either side of its first) the frames as filmed are read two lengths on over one length on; the nearest at most 0.85 (`period.STEP_RATIO_MAX`, the step screen's bound) whose seam and seam pop gates pass is taken, recorded `cycle.steps` `{"count": 2, "by": "two-lengths", ...}` and `cycle.two_lengths` (`first_cut`, `tried`, `cut`, `taken`; in the stdout summary too). It is read on the frames as filmed, not on the search's distances, which move every frame by one vertical slope fitted over the clip: a slope tilted by frames that open higher moves frames two steps apart further than one step apart where the body runs in place, so two lengths on read no nearer there. A cut the clip gives no two is kept and named as above, the warning line saying why (`cycle.half_step.two_lengths`). Python callers: `loop.two_lengths_on`, `loop.TWO_LENGTHS_AROUND`. **Tests**: `tests/video/test_loop_two_lengths.py`.
+ - **Fixed: `video-loop --anchor motion-auto` no longer refuses a walk or run for its opening frames alone.** Where `auto_motion.discover` finds no two regions through the whole clip (`automatic motion anchor needs two separated regions trackable throughout the clip`, or `found no stable textured region`), the analysis is read again on the clip after the fewest frames it opens on, fewer than the window's shortest cut, with which the anchor finds its two regions through the rest (`auto_motion.analyse_after_opening`, new exception `auto_motion.RegionsUnfound`). A clip filmed from a still opens on that still and on the standing pose the body sets off from, and the regions the middle of the clip shows may be out of the anchor's reach there; the refusal came before the search, so the gait fallback never ran. Those frames are left out of the search as a lead-in is (`lead_in.search_from`, every frame number the clip's own), recorded in the report's new `untracked_opening` (`frames`, `first`, `shorter_than`, `refused`) and, once a cut is found, a warning line `video-loop: warning: the automatic motion anchor found its two regions from frame <k> on, not from the clip's first frames: ...` that does not repeat the refusal's words. Where no such opening leaves the clip tracked, it is refused in the same words as before, followed by ` — nor through the clip after any of its first 1 to <n> frames left out (an opening shorter than the shortest cut, <n + 1> frames)`; where the cut the search took holds no two regions when its frames are read again for the correction, the refusal now ends ` — on the cut the search took (frames <a>-<b>)`. Tests: `tests/video/test_auto_motion_opening.py` (a synthetic walker whose first three frames carry its head and torso 90 px forward: refused as filmed before, now cut after them with every frame number the clip's own; the same walker without them unchanged; the lean again mid-clip refused with the new words).
- **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"`).
diff --cc docs/loop-repair.md
index 4745222,2f63c90..9157a64
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@@ -2741,6 -2746,99 +2746,101 @@@ The loop report records `wrap_blend` o
A `video-loop: warning:` line is emitted under two conditions. When the after check refuses the blend because a step into or through the ramp exceeds the bound or the wrap does not shrink, the cut is written as filmed, `wrap_blend.after_check` is set to "refused", and the warning states that the wrap blend was not used, why, and the measured numbers. When the wrap remains over `--seam-max` after blending because the two ends hold a part apart, the blend is applied anyway and a warning line reports that condition along with the share of the figure held as filmed.
+ ## 7. Held cells: a picture shown again, and a cut at a higher rate
+
+ A clip can show one frame two or three times in a row: a video model that stalls, a rate carried to another by
+ repeating frames (20 fps carried at 24 repeats one frame in six), or a cut mapped to a higher rate by taking the
+ nearer frame. Played, the motion stops on that picture and jumps on. `video-loop` reads every cut it makes for held
+ cells (loops that are periodic, fixed, or pinned; one-shot, once, and once-return cuts; and so every cut `video-set`
+ makes and every clip of `video` cut through `video-frames` and `video-loop`). By default, it makes those cells again
+ as the frames between the pose before them and the pose after (`sprite_gen/video/held_fill.py`). The default step
+ of the pipeline is: find the held cells, fill them, read the cut again; the cut's line to the person is its poses
+ over its cells.
+
+ ### The reading
+
+ | Rule | Value | Why |
+ |---|---|---|
+ | The same picture | A step where at most `CHANGED_MAX` 0.5 % of the subject's pixels change by more than `PIXEL_SAME` 0.1 (premultiplied RGBA). This is read twice: on the analysis thumbnail used to choose the cut (96 px on the longer side) and on the frames as cut. It is the same picture only where both readings say so. | A textured synthetic figure, each pose shown three times, is encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`. A frame shown again changes no thumbnail pixel by more than 0.008, 0.020 and 0.051, and changes 0.012 %, 0.049 % and 0.11 % of the frame's subject pixels by more than 0.1. An arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the thumbnail's subject pixels over 0.1 and 0.38 % of the frame's: the thumbnail separates it. |
+ | Not a distance over the mass | `nonloop.STABLE_MAX` (0.025), the once cut's settled end, is not the rule | The arm's pixel reads 0.003 of the subject's mass: under it, so the rule would call it held. |
+ | Where read | On the cut's frames as loaded, before an anchor moves each frame apart, and again on the cells delivered | An anchor shifts each frame of a pair by its own amount: a picture shown again would no longer read as one. |
+ | Not read across the wrap | A loop's last cell and its first are not a run | The wrap is the seam gate's, not a hold. |
+ | A move under a thumbnail pixel | A whole figure that moves less than a thumbnail pixel is read on the frame as cut. It is not the same picture. A small part moved a pixel or so reads as the same picture on both. | A synthetic walker moving away in a frame 280 px wide changes 4.9 % of the frame's subject pixels over 0.1 in a step that changes none of the thumbnail's. Two or three pixels of a hand on a large frame play as a hold. Made again between its neighbours, it plays the same. |
+
+ The record, `held_fill` in the loop report and in the strip metadata (the strip's without each try): `cells`,
+ `poses` (the cells less the ones showing the picture before them) and `held_runs` (each run's first cell and how
+ many) of the cells as delivered; `before`, the same of the cut as filmed with each run `filled` or `why` not (and
+ the `faults` its frames between were refused for); `made`, the cells made; `unmade`, the cells left for want of
+ RIFE with the install line; `out_fps`, the rate asked (below). `video-loop` prints `held_fill.poses_cells` (`27/27`)
+ and `before` in its summary; `video-set` puts `loop.poses` on each item. In the curation view (a loop's `cycle/`
+ imported with `unpack-atlas --pngs-dir`), the card of each cell made says `(made)` and of each cell still showing the
+ picture before it `(held)`. A stop (`video-stop`) is read the same way and records `held_fill` with `mode` off: it
+ plays the clip's filmed frames, none made between two others, and names a run it shows in a warning.
+
+ ### The fill: `--fill-held auto` (default), `off`
+
+ | Rule | Value | Why |
+ |---|---|---|
+ | A run's cells made | Cell c of a run from cell a to the next pose b, at t = (c - a)/(b - a) between a and b: a run of two half way, of three a third and two thirds | The cut keeps its length, its beat, its first and last cells and its wrap: a made cell stands where a held cell stood, on its own time. |
+ | Kept: a hold the motion means | A run longer than `HOLD_MAX` 3 cells | A drawing held on threes is three frames ([held.py](../sprite_gen/video/held.py)); longer is a pause the motion makes. A shorter pause meant as one is filled: `--fill-held off` keeps it. |
+ | Kept: a cut drawn on twos or threes (`drawn`) | Every run, where the cut's held-drawings reading (`cycle_drawings`, else the clip's `drawings`: [held.py](../sprite_gen/video/held.py), which `video-cycle-align` reads) gives a hold of 2 or 3 and every run is that many cells, but one cut short at the cut's first or last cell | Limited animation: each drawing shown as long as the next, played at its own rate as filmed (section 4). A clip carried to a higher rate by repeating frames reads a hold too (a synthetic walk at 24 fps carried to 60 by the frame under each time reads a hold of 2), but its runs are two and three cells by turns: it is filled (60 poses over 60 cells). A clip that stalls now and then reads no hold (hold 1). |
+ | Kept: the ends of a cut played once | A run that opens or closes a one-shot, once or once-return cut | The rest before the action and the pose it ends on are the cut's. |
+ | Kept: a loop's last cells | A run that ends on a loop's last cell | Its next pose is across the wrap: made, the last cell would change and with it the wrap. A run that opens a loop is made (its first cell stays). A periodic cut chooses its wrap where the steps either side read alike, so a held run seldom closes it; a fixed cut whose last cells are held keeps them, and its wrap then steps from a held picture (cut it elsewhere, or `--fill-held off` to keep the whole cut as filmed). |
+ | A frame made, judged | `align.measure_made` and `interpolation_quality.faults` (smear, outline, ghost, hole, doubled), the alignment's own | One acceptance policy for every frame RIFE makes (section 4). |
+ | A part standing still, kept still (`still_kept`) | The outline pixels both frames draw in one place in one colour (solid at alpha 128, within 24 levels) must be drawn there in the frame made, within a pixel, for at least `STILL_KEPT_MIN` 0.8 of them in every window a tenth of the body high that holds 12 or more; else the fault `contact` | A foot planted or a hand on a ledge stays where it stood. A synthetic in-between that drags a planted foot 3 px along the floor keeps 0.50 of its window; one off by a pixel, 1.00. |
+ | A frame refused | Made again at the fraction of `RETIME_T` nearest its own within half a cell of it, its ghost band under `RETIME_WINDOW_MAX` (section 4's bar for a frame made off its time); else the run is kept as filmed, with a warning naming the cells and the faults | A frame half way that RIFE cannot draw is often clean nearer one side. |
+ | Whole or not at all | A run is made whole or kept whole | Half made, it would step back to the held picture and on again. |
+ | Order | After the anchor and `source_projection`, before the ghost screen, the wrap blend, the part pop and the jump repair | Everything that reads the flow and the wrap reads the cut as it will play. |
+ | No RIFE | The held cells are delivered as filmed, the cut passes, and a `warning:` line names the motion, the cells and `sprite-gen rife install`; `held_fill.unmade` records them | Never a failure, never silent. |
+ | `--fill-held off` | Cut as filmed, byte for byte as before; the reading is recorded all the same | |
+ | Byte for byte | A cut with no held cell is delivered as before: six synthetic cuts (a fixed and a periodic walk, a one-shot hop, a pinned swing, a once fall, a once-return swing) are pinned to their decoded pictures on the engine before the change (commit 886936e): every frame of the strip PNG, the GIF, the WebP and the `cycle/` cells, decoded to RGBA, with each frame's size and the frame count. The test no longer pins the file bytes because the same pixels are written as different PNG bytes on Linux and on macOS (zlib differs), though on each platform the engine before the change and this one still write identical files (`tests/video/test_held_fill.py`). | |
+
+ A cut whose cells were made is read by the seam gate on its rendered cells (`seam_measurement`), restoration from
+ the source frames (`video-loop-repair`) reads it as `source-processing-unsupported`, and `video-cycle-align` reads
+ its drawings on its own cells, not on the clip's hold.
+
+ ### A rate above the clip's: `--out-fps F`
+
+ `video-loop --out-fps F` (and `video-set --out-fps F`) gives the cut at F, above the clip's `--fps`: every cell at a
+ time of its own, made by RIFE between the frames beside it, judged as the fill's frames are, never showing a frame
+ again. A loop has round(L x F / fps) cells over its cycle's seconds, at times k x L / cells; a cut played once runs
+ from its first frame to its last, round((L - 1) x F / fps) + 1 cells, each 1/F. A cell on a frame's time is that
+ frame; one between two frames showing one picture (a hold kept) is that picture; one no frame made is taken for is
-the nearer frame, named (`out_fps.shown_again`). `cycle/` holds every cell; the strip holds them up to its cell and
++the nearer frame, named (`out_fps.shown_again`). The record's `out_fps.shows` gives the frame each cell is (null
++where it was made), which the strip record's `cell_record` reads (`docs/video-pipeline.md` section 6). `cycle/` holds
++every cell; the strip holds them up to its cell and
+ width caps, subsampled past them as any strip is (`subsampled`). The strip metadata says `out_fps` and `source_fps`,
+ and `source_cut.times` in place of `samples`. With no RIFE the cut is delivered at its own rate with a `warning:` line
+ and `out_fps.applied` false. `video-cycle-align` and `video-stop` refuse such a loop (each makes its own frames
+ between from the cut at the clip's rate), and restoration reads it as `source-processing-unsupported`.
+
+ Where sprite-gen gives frames at a higher rate than it was given them:
+
+ | Path | Before | Now |
+ |---|---|---|
+ | `video-loop --gif-fps`, `--n-out` | The GIF and WebP never hold more frames than the cut (a higher request is capped at the cut's frames, never repeated) | The same; `--out-fps` makes the cells themselves at the higher rate |
+ | `video-cycle-align --length` | RIFE's frames between; a frame shown again only with `--between nearest`, or where a frame made is refused and the nearer source frame is taken (named) | Unchanged: it already makes frames between |
+ | `video-loop --out-fps` (new) | None | RIFE's frames between, never a frame shown again |
+ | `scene-render` at a scene rate above an asset's | A cell of the asset shown over several scene frames | Unchanged: give the asset at the scene's rate (`--out-fps`) |
+ | `video-stop --fps` | The rate of the frames given, not an output rate | Unchanged |
+
+ ### What it takes from sprite-gen
+
+ | Part | Taken from | Why a part is its own |
+ |---|---|---|
+ | The thumbnail the steps are read on | `loop._small_features`, the analysis thumbnail the cut is chosen by | |
+ | What a drawing held on threes is | `held.HOLDS` | |
+ | Whether the cut is drawn on twos or threes | `held.measure_cycle` (`cycle_drawings`), `held.measure` (`drawings`) | |
+ | The judgement of a frame made | `align.measure_made`, `interpolation_quality.faults`, `looks` | |
+ | A frame made again at another fraction | `align.RETIME_T`, `align.RETIME_WINDOW_MAX` | |
+ | RIFE located only once a frame is made; no RIFE as a warning | The pattern of `_repair_jumps` and `_bridge_seam` | |
+ | The ghost screen's reading | `interpolation_quality.ghost_screen` | |
+ | Solid pixels | `legs.LOW_ALPHA` | |
+ | The window a tenth of the body high | `rife.GHOST_BAND` | |
+ | The same picture (`same_steps`) | New | A distance over the mass (`nonloop.STABLE_MAX`, `held.measure`'s steps) reads a one-pixel move of a small part as held; `held.measure` reads a rhythm of redrawn drawings, not a frame shown again. |
+ | A part standing still (`still_kept`) | New | `rife.hole` reads a hole through a limb, `inspect-motion` a foot's place in spans a person marks; neither reads whether an in-between keeps what both its frames hold still. |
+ | The times of a higher rate (`times`, `upsample`) | New | `align.resample` resamples a loop as a ring to a length; a cut played once runs from its first frame to its last. |
+
## Related
- [video-pipeline.md](video-pipeline.md) — the pipeline these repairs run inside
diff --cc docs/video-pipeline.md
index 4a80d7a,ded718c..fdf7861
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@@ -682,75 -721,8 +727,82 @@@ place of the body, and a stretched loo
names the strip they were read on — its file's sha256, as cut, before any follow-through (64
lowercase hexadecimal digits; anything else is refused before anything is read):
-- **`no-match`**, refused: neither — another clip, another cut, a strip nothing here was cut or
- aligned from. Locate the regions again on this strip.
+- **`recut`**: the regions were read on another cut of this loop's own source clip, given by
+ `--read-on-cut STRIP`. It pairs the cuts when both records name the same source in `source_cut`
+ (its `source`) and this loop's cut holds the source frame of the cut's cell 0, at its cell j.
+ The report `video-loop` wrote beside a cut is no longer looked for or read for `--read-on-cut`,
+ and need not be beside the strip. Each cut is now read by its record of its cells alone.
+ `video-loop` writes it in the strip's record (`<name>.strip.json`, not the report) under
+ `cell_record`, bound to the strip by `cell_record.strip_sha256`, the sha256 of the strip PNG it
+ describes. `cell_record.cells` holds one entry per cell of the strip, in order: `source_frame`,
+ the source frame the cell is (a whole number); `anchor_move_px`, where the cut's anchor moved
+ that frame before the crop, across and down, in whole px (nothing (`[0, 0]`) at `--anchor none`,
+ round(`wrap_dx_px` x k / L) across at `--anchor body` for frame k of a cut L frames long, and the
+ left and top of `padding_ltrb` plus that frame's entry of `shifts_xy` at `--anchor motion` and
+ `--anchor motion-auto`); `scale`, the factor each step that holds a clip's frames to one size
+ scaled the frame by about its feet before the cut, `size_hold` (the size hold) and `gait_fallback`
+ (the gait fallback), 1 where the step did not hold the clip's frames; and `as_filmed`, true where
+ the cell is that frame as filmed but for its anchor's move. Its pixels at the end of the cut are
+ its pixels anchored, before any repair (the receipt `video-loop` writes in its report,
+ `source_projection.before_repair_pixels_sha256`), and no step held the clip's frames to one size.
+ A cell the jump repair, the seam bridge, the overlapped wrap or the wrap blend made again, gave
- way or redrew is not as filmed by its pixels; no list of those steps is read. `video-loop` now
++ way or redrew is not as filmed by its pixels; no list of those steps is read. In a cut at
++ `--out-fps` (cells each made at a time of their own, more cells than the cut has frames),
++ `cell_record` still holds one entry per cell, and each cell's `source_frame` is the frame the
++ cell is, and for a cell made between two frames the cut's frame at or before its time (the frame
++ the seam reads it as), with that frame's `anchor_move_px` and `scale`. `as_filmed` is true only
++ where the cell's pixels are that frame's pixels anchored before any repair, so a cell that
++ repeats a frame unchanged is as filmed, and a cell made between two frames is not, and
++ `video-sway --read-on-cut` does not pair it. `video-loop` now
+ writes that receipt (`source_projection`) in the report of every cut but `--anchor feet` and a
+ lifetime cut, so also at `--anchor motion` and `motion-auto` (`recipe`
+ `motion-anchor-correction-v1` there). On a loop aligned from its cut (`cycle_align`), the aligned
+ strip is another strip, so `video-cycle-align` does not carry `cell_record` over to it. Its first
+ alignment keeps the cut's own strip record, byte for byte, beside the cut's frames as filmed
+ (`cycle.source/<name>.strip.json`), and later alignments keep it. There the cut's record is read
+ from that file, bound to the strip the alignment's origin names
+ (`cycle_align.origin.strip_sha256`); the regions sit on the aligned cell that is cut cell j and
+ are carried as `transported` carries them. On an unaligned loop they are read on cell j and
+ carried from there. The regions' centres, a `--region-mask` PNG, and a single `--hold-mask` PNG
+ are moved pixel for pixel onto cell j by the whole pixel shift the two crops and cell sizes set
+ that frame apart, each crop taken on the frame as filmed: its `source_rect` less the cell's
+ `anchor_move_px`. A pixel may lie at most `RECUT_DRIFT` (1.0 px) off that shift anywhere in the
+ cell. The pair's policy is now `same-clip/source-frame/whole-px-shift/2`. Then the two cells are
+ compared: the cut's cell 0 laid on this loop's cell j at the shift must be the same pixels (RGBA)
+ wherever they overlap. A record changed to call a cell the frame as filmed is held to that
+ frame's pixels this way. Before crops are read, the run is refused no-match and the loop left as
+ it was, saying which and naming the field: a cut with no `cell_record` (a cut `video-loop` made
+ before it wrote one: every cut made by 3.5.0 or before), on the cut `--read-on-cut` names or on
+ this loop's ("it holds no record of them (cell_record), as a cut video-loop made before it wrote
+ one does"); a record of another strip (`cell_record.strip_sha256` is not the strip's sha256); a
+ record that does not give its cells as `video-loop` writes it, naming the field, for instance
+ `cell_record.cells[2].source_frame` (`cell_record` not an object, `cells` not one entry per cell of
+ the strip, a cell's entry not an object, `source_frame` not a whole number, `anchor_move_px` not
+ two whole px, a `scale` factor missing or not a positive number, `as_filmed` not true or false);
+ a loop aligned from its cut whose cut's record is not kept beside its frames as filmed
+ (`cycle.source/<name>.strip.json`); a record that names no clip it is cut from (`source_cut`),
+ two cuts of different clips, or a source frame this loop's cut does not hold. Every cell's entry
+ is read this way, not only the cell paired. Refusal no-match also occurs if either cell paired was
+ scaled by a hold (its `scale.size_hold` or `scale.gait_fallback` not 1: no whole px shift undoes a
+ scale), or is not as filmed (`as_filmed` false). Only the two cells paired are read for this; a
+ cell elsewhere in either cut that a hold scaled or a repair made leaves the pair as it is.
+ Refusal no-match also occurs if the two cells are not the same pixels where they overlap at the
+ shift, saying how many of how many px differ, or if the strip `--read-on-cut` names is a loop
+ aligned from its cut (`cycle_align`), whose cells are not the cut's frames in order. A run is
+ refused uncertain if a cut records no crop, if crops, scales and anchors set a pixel more than 1 px
+ off one whole shift, or if an aligned loop holds no cell for cut cell j. `STRIP` is that cut's
+ strip PNG, whose bytes must have the sha256 `--read-on` names, with its record beside it as
+ `video-loop` writes one using the same file name ending `.json` instead of `.png`, refusing with
+ "--read-on-cut names the strip --read-on names by its sha256; it needs --read-on" when `--read-on`
+ is not given and "wants the strip's PNG and its record beside it" when either file is missing.
+ Masks are moved by the shift alone with no polygon grown and no scaling, while a mask pixel that
+ would leave the cell refuses the run, and a folder of masks (one per cell) is refused under
+ `--read-on-cut` with "regions read on another cut (--read-on-cut) are drawn on its cell 0 alone:
+ give one PNG". `video-sway` takes `--read-on-cut` on `--loop-dir` only, and `video-sway-inspect`
+ does not take it.
+- **`no-match`**, refused: neither — another clip, another cut no record pairs with this one
+ (`--read-on-cut` names the cut that one does), a strip nothing here was cut or aligned from.
+ Locate the regions again on this strip.
#### A least area each move leaves — `--stretch-floor D`
diff --cc sprite_gen/video/held_fill.py
index 0000000,b81e66f..3d23399
mode 000000,100644..100644
--- a/sprite_gen/video/held_fill.py
+++ b/sprite_gen/video/held_fill.py
@@@ -1,0 -1,332 +1,339 @@@
+ # SPDX-License-Identifier: Apache-2.0
+ """Held cells: neighbour cells of a cut that show the same picture, found, made again as the frames between the poses
+ beside them, and read again (docs/loop-repair.md section 7).
+
+ A clip may show a frame twice or three times in a row: a video model that stalls, a rate carried to another by
+ repeating frames (20 fps in 24 repeats one in six), a cut mapped to a higher rate by taking the nearer frame. Played,
+ the motion stops on that picture and jumps on: one pose, two or three cells. Each cut `video-loop` makes is read for
+ them (`same_steps`, `reading`): the cells, the poses (the cells less the ones that show their neighbour's picture
+ again) and each run of cells showing one picture (`held_runs`, its first cell and how many). The cells are read as
+ filmed, before an anchor moves each frame of a pair apart.
+
+ The same picture is a step at most CHANGED_MAX of whose subject's pixels (premultiplied) change by more than
+ PIXEL_SAME, read twice: on the analysis thumbnail `video-loop` cuts by and on the frames as cut. A textured figure shown
+ three times, encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`, changes no thumbnail pixel of a frame
+ shown again by more than 0.008, 0.020 and 0.051, and 0.012 %, 0.049 % and 0.11 % of its frame's subject pixels by more
+ than PIXEL_SAME. An arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the thumbnail's subject
+ pixels (0.38 % of the frame's); a walker going away in a frame 280 px wide changes 4.9 % of the frame's in a step that
+ moves none of the thumbnail's. A distance over the subject's mass (`nonloop.STABLE_MAX`, which reads a once cut's
+ settled end) does not part them: the arm's pixel reads under it. A small part's move of a fraction of a pixel reads as
+ the same picture, as a hold plays.
+
+ `fill` makes each run's cells again, between the run's first cell and the next pose, at their own times — the cells of a
+ run of three a third and two thirds of the way — so the cut keeps its length, its beat, its first and last cells and
+ its wrap: a made cell stands where a held cell stood. A run is kept as filmed where filling it would change what the
+ cut means: longer than HOLD_MAX cells (a drawing held on threes is three: longer is a hold the motion means), the opening
+ or the closing pose of a cut played once, the last cells of a loop (their next pose is across its wrap). A cut drawn on
+ twos or threes keeps every run (`drawn`): limited animation, each drawing shown as long as the next. It is drawn so where
+ its held-drawings reading (`held.measure_cycle`, which `video-cycle-align` reads) gives a hold of 2 or 3 and every run is
+ that long, but a run cut short at the cut's first or last cell: a clip carried to a higher rate by repeating frames
+ reads a hold too (24 fps carried to 60 shows each frame two or three times), its runs two and three cells by turns, and
+ a clip that stalls now and then reads none. A frame made
+ is judged as the frames the alignment makes are (`align.measure_made`, `faults`), and for a part standing still on
+ both sides of it (`still_kept`: a foot planted, a hand on a ledge), which must stand where it stood; a frame refused is
+ made again at another fraction of RETIME_T within half a cell of its own time, else the run is kept as filmed and says
+ why. A run is made whole or kept whole: half made it would step back.
+
+ `upsample` gives a cut at a rate above its own (`--out-fps`) its frames between, at their own times, never a frame
+ shown again; a cell where both frames beside its time show one picture (a hold kept) is that picture."""
+
+ from __future__ import annotations
+
+ import math
+ from collections.abc import Sequence
+ from typing import Any
+
+ from PIL import Image, ImageFilter
+
+ from sprite_gen._deps import np
+ from sprite_gen.video import held as held_mod
+ from sprite_gen.video import legs as legs_mod
+ from sprite_gen.video import rife as rife_mod
+ from sprite_gen.video.interpolation_quality import faults, ghost_screen, looks
+
+ MODES = ("auto", "off")
+ PIXEL_SAME = 0.1 # a thumbnail pixel (premultiplied, 0..1) that changes by more than this has changed
+ CHANGED_MAX = 0.005 # the same picture: at most this share of the subject's thumbnail pixels changed
+ HOLD_MAX = max(held_mod.HOLDS) # a run of cells longer than a drawing on threes is a hold the motion means: kept
+ # A part standing still on both sides of a frame made (`still_kept`): its outline pixels, solid (legs.LOW_ALPHA) and
+ # within STILL_RGB of each other in both frames, must be solid and within STILL_RGB in the frame made, within a pixel,
+ # for at least STILL_KEPT_MIN of them in every window of rife.GHOST_BAND of the body high holding STILL_MIN_PX or more.
+ STILL_RGB = 24
+ STILL_KEPT_MIN = 0.8
+ STILL_MIN_PX = 12
+ SNAP = 0.03 # a time within this of a frame takes that frame (align.SNAP)
+
+
+ def _thumbs(frames: Sequence[Image.Image]) -> np.ndarray:
+ from sprite_gen.video.loop import _small_features # the thumbnail video-loop cuts by (loop imports this module)
+
+ return np.stack([_small_features(f).reshape(-1, 4) for f in frames])
+
+
+ def _premultiplied(frame: Image.Image) -> np.ndarray:
+ a = np.asarray(frame.convert("RGBA"), dtype=np.float32) / 255.0
+ return np.concatenate([a[..., :3] * a[..., 3:], a[..., 3:]], axis=-1)
+
+
+ def _same(a: np.ndarray, b: np.ndarray) -> bool:
+ """Whether at most CHANGED_MAX of the subject's pixels (alpha over half in either) change by more than PIXEL_SAME:
+ premultiplied RGBA, 0..1, pixels along the last axis."""
+ subject = int((np.maximum(a[..., 3], b[..., 3]) > 0.5).sum())
+ changed = int((np.abs(a - b).max(axis=-1) > PIXEL_SAME).sum())
+ return changed <= CHANGED_MAX * subject
+
+
+ def same_steps(frames: Sequence[Image.Image]) -> list[bool]:
+ """For each step of `frames` (cell k to k + 1), whether the two show the same picture: on the thumbnail and on the
+ frames as cut (see the module)."""
+ t = _thumbs(frames)
+ return [_same(t[k], t[k + 1]) and _same(_premultiplied(frames[k]), _premultiplied(frames[k + 1]))
+ for k in range(len(frames) - 1)]
+
+
+ def runs(same: Sequence[bool]) -> list[dict[str, int]]:
+ """Each run of cells showing one picture: its first cell and how many (two or more). Not read across a wrap."""
+ found, k = [], 0
+ while k < len(same):
+ if not same[k]:
+ k += 1
+ continue
+ start = k
+ while k < len(same) and same[k]:
+ k += 1
+ found.append({"start": start, "length": k - start + 1})
+ return found
+
+
+ def reading(same: Sequence[bool]) -> dict[str, Any]:
+ """The cells, the poses and the held runs of a cut whose steps are `same`."""
+ held = runs(same)
+ cells = len(same) + 1
+ return {"cells": cells, "poses": cells - sum(r["length"] - 1 for r in held), "held_runs": held}
+
+
+ def said(record: dict[str, Any]) -> str:
+ """The poses over the cells, as a person is told them: `poses/cells`."""
+ return f"{record['poses']}/{record['cells']}"
+
+
+ def _edge(solid: np.ndarray) -> np.ndarray:
+ inner = np.asarray(Image.fromarray(np.uint8(solid) * 255).filter(ImageFilter.MinFilter(3))) > 0
+ return solid & ~inner
+
+
+ def still_kept(frame: Image.Image, a: Image.Image, b: Image.Image) -> dict[str, Any]:
+ """Whether a part standing still in `a` and `b` stands where it stood in `frame`, made between them: the outline
+ pixels both draw in one place in one colour (`still`), and the share of them `frame` draws there too, within a
+ pixel (`kept`), the least over windows of rife.GHOST_BAND of the body high that hold STILL_MIN_PX of them (`reads`
+ false where none does)."""
+ A, B, F = (np.asarray(im.convert("RGBA"), dtype=np.int16) for im in (a, b, frame))
+ sa, sb, sf = (x[..., 3] >= legs_mod.LOW_ALPHA for x in (A, B, F))
+ still = _edge(sa) & _edge(sb) & (np.abs(A[..., :3] - B[..., :3]).max(axis=-1) <= STILL_RGB)
+ drawn = sf & (np.abs(F[..., :3] - A[..., :3]).max(axis=-1) <= STILL_RGB)
+ near = np.asarray(Image.fromarray(np.uint8(drawn) * 255).filter(ImageFilter.MaxFilter(3))) > 0
+ rows = np.nonzero((sa | sb).any(axis=1))[0]
+ if not rows.size:
+ return {"reads": False, "still_px": 0}
+ top, bottom = int(rows[0]), int(rows[-1])
+ win = max(8, round((bottom - top + 1) * rife_mod.GHOST_BAND))
+ still_rows, kept_rows = still.sum(axis=1), (still & near).sum(axis=1)
+ least, at = None, None
+ for y in range(top, max(top, bottom - win + 1) + 1, max(1, win // 4)):
+ n = int(still_rows[y:y + win].sum())
+ if n >= STILL_MIN_PX:
+ share = float(kept_rows[y:y + win].sum()) / n
+ if least is None or share < least:
+ least, at = share, y
+ if least is None:
+ return {"reads": False, "still_px": int(still.sum())}
+ return {"reads": True, "still_px": int(still.sum()), "kept": round(least, 4), "at_row": at, "window_px": win}
+
+
+ def judge(frame: Image.Image, a: Image.Image, b: Image.Image, t: float, *, reads: bool) -> tuple[dict[str, Any], list[str]]:
+ """A frame made between `a` and `b` at `t`: the alignment's measure and faults (`align.measure_made`, `faults`),
+ and `contact` where a part standing still on both sides does not stand where it stood (`still_kept`)."""
+ from sprite_gen.video.align import measure_made # align imports loop, which imports this module
+
+ measure = measure_made(frame, a, b, t, reads=reads)
+ contact = still_kept(frame, a, b)
+ wrong = faults(measure) + (["contact"] if contact["reads"] and contact["kept"] < STILL_KEPT_MIN else [])
+ return {**measure, "contact": contact}, wrong
+
+
+ def _made(interpolate: rife_mod.Interpolate, a: Image.Image, b: Image.Image, t: float, window: tuple[float, float], *,
+ reads: bool) -> tuple[Image.Image | None, dict[str, Any]]:
+ """The frame between `a` and `b` at `t`, or at the fraction of RETIME_T nearest it inside `window` that is made
+ with no fault and, made only off its time, with its ghost band under RETIME_WINDOW_MAX in every window (align's
+ bar for a frame made again at another fraction); None and what each try was refused for, where none is."""
+ from sprite_gen.video.align import RETIME_T, RETIME_WINDOW_MAX
+
+ tries = []
+ for at in [t] + sorted((r for r in RETIME_T if window[0] < r < window[1] and abs(r - t) > 1e-3), key=lambda r: (abs(r - t), r)):
+ frame = interpolate(a, b, at)
+ measure, wrong = judge(frame, a, b, at, reads=reads)
+ seen = at != t and (measure.get("ghost_window") or 0.0) >= RETIME_WINDOW_MAX
+ tries.append({"t": round(at, 4), "faults": wrong, **({"window_over": RETIME_WINDOW_MAX} if seen and not wrong else {})})
+ if not wrong and not seen:
+ return frame, {"t": round(at, 4), **({"from_t": round(t, 4)} if at != t else {}),
+ "contact": measure["contact"], "look": looks(measure), "tries": tries}
+ return None, {"t": round(t, 4), "tries": tries}
+
+
+ def drawn(found: Sequence[dict[str, int]], n: int, hold: int | None) -> int | None:
+ """The hold of a cut of `n` cells drawn on twos or threes, or None: the held-drawings reading's `hold` 2 or 3, and
+ every held run `found` that many cells long, but one cut short at the cut's first or last cell (see the module)."""
+ if hold not in held_mod.HOLDS or not found:
+ return None
+ edge = lambda r: r["start"] == 0 or r["start"] + r["length"] == n # noqa: E731
+ return hold if all(r["length"] == hold or (r["length"] < hold and edge(r)) for r in found) else None
+
+
+ def _fillable(run: dict[str, int], n: int, *, ring: bool, on: int | None = None) -> str | None:
+ """Why a held run is kept as filmed, or None where it is made again. `on` is the hold of a cut drawn on twos or
+ threes (`drawn`)."""
+ if on is not None:
+ return (f"the cut is drawn on {'twos' if on == 2 else 'threes'} (its held-drawings reading holds {on}, and so does "
+ "every run): limited animation, kept as filmed")
+ if run["length"] > HOLD_MAX:
+ return (f"held {run['length']} cells, longer than a drawing on threes ({HOLD_MAX}): a hold the motion means, "
+ "kept as filmed")
+ if run["start"] + run["length"] == n:
+ return ("the loop's last cells: their next pose is across its wrap, and the wrap stays as cut" if ring else
+ "the cut's closing pose, kept as filmed")
+ if run["start"] == 0 and not ring:
+ return "the cut's opening pose, kept as filmed"
+ return None
+
+
+ def fill(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool,
+ same: Sequence[bool] | None = None, mode: str = "auto", reads: bool | None = None,
+ hold: int | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`frames` with each held run's cells made again between the run's first cell and the next pose (see the module),
+ and the record: the reading before (`before`, each run `filled` or why not), the cells made (`made`, and how each
+ was, `frames`), the cells left for want of an interpolator (`unmade`, `interpolate` None), the hold of a cut drawn
+ on twos or threes (`drawn`), and the reading of the frames returned (`cells`, `poses`, `held_runs`). `same` is the
+ steps' reading as filmed (`same_steps` of `frames` where None); `reads` whether the ghost screen reads the cut (read
+ on `frames` where None); `hold` the cut's held-drawings reading (`held.measure_cycle`)."""
+ if mode not in MODES:
+ raise ValueError(f"fill mode {mode!r}: one of {', '.join(MODES)}")
+ same = list(same_steps(frames) if same is None else same)
+ n = len(frames)
+ on = drawn(runs(same), n, hold)
+ out = list(frames)
+ before = []
+ made: list[int] = []
+ unmade: list[int] = []
+ rows: list[dict[str, Any]] = []
+ for run in runs(same):
+ row: dict[str, Any] = dict(run)
+ cells = list(range(run["start"] + 1, run["start"] + run["length"]))
+ why = "--fill-held off" if mode == "off" else _fillable(run, n, ring=ring, on=on)
+ if why is None and interpolate is None:
+ unmade += cells
+ why = "no interpolator"
+ if why is not None:
+ before.append({**row, "filled": False, "why": why})
+ continue
+ if reads is None:
+ reads = bool(ghost_screen(frames)["reads"])
+ a, b = run["start"], run["start"] + run["length"]
+ taken, tried = [], []
+ for c in cells:
+ t = (c - a) / (b - a)
+ half = 0.5 / (b - a)
+ frame, how = _made(interpolate, frames[a], frames[b % n], t, (t - half, t + half), reads=reads)
+ tried.append({"cell": c, "between": [a, b % n], **how})
+ if frame is None:
+ break
+ taken.append((c, frame))
+ if len(taken) < len(cells):
+ refused = sorted({f for row_ in tried for t_ in row_["tries"] for f in t_["faults"]})
+ before.append({**row, "filled": False, "faults": refused, "tries": tried,
+ "why": f"a frame between was refused ({', '.join(refused) or 'ghost band over the retime bar'}): kept as filmed"})
+ continue
+ for c, frame in taken:
+ out[c] = frame
+ made += cells
+ rows += tried
+ before.append({**row, "filled": True, "made": cells})
+ record: dict[str, Any] = {
+ "mode": mode, "pixel_same": PIXEL_SAME, "changed_max": CHANGED_MAX, "hold_max": HOLD_MAX,
+ "before": {**reading(same), "held_runs": before},
+ "made": made, "frames": rows,
+ "contact": [{"cell": r["cell"], **r["contact"]} for r in rows if r["contact"]["reads"]],
+ }
+ if on is not None:
+ record["drawn"] = on
+ if unmade:
+ record["unmade"] = {"cells": unmade}
+ record.update(reading(same_steps(out)) if made else reading(same))
+ return out, record
+
+
+ def times(n: int, fps: float, out_fps: float, *, ring: bool) -> list[float]:
+ """The times, in frames of the cut, of the cells of a cut of `n` frames at `fps` given at `out_fps`: a loop's
+ round(n·out_fps/fps) cells over its cycle, a cut played once from its first frame to its last."""
+ if ring:
+ count = round(n * out_fps / fps)
+ return [k * n / count for k in range(count)]
+ count = round((n - 1) * out_fps / fps) + 1
+ return [k * (n - 1) / (count - 1) for k in range(count)]
+
+
+ def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ring: bool, fps: float, out_fps: float,
+ reads: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`frames` given at `out_fps` (`times`): a cell on a frame's time is that frame, one between two frames showing
+ one picture is that picture, any other is made between the two at its own time (`_made`, within half a cell of
- it), and one no frame made is taken for is the nearer frame and named (`shown_again`)."""
++ it), and one no frame made is taken for is the nearer frame and named (`shown_again`). `shows`: the frame each cell
++ is, None where it was made."""
+ n = len(frames)
+ at = times(n, fps, out_fps, ring=ring)
+ same = same_steps(frames + ([frames[0]] if ring else []))
+ if reads is None:
+ reads = bool(ghost_screen(frames)["reads"])
+ spacing = fps / out_fps
+ out: list[Image.Image] = []
+ made: list[dict[str, Any]] = []
+ shown_again: list[int] = []
++ shows: list[int | None] = []
+ for k, tau in enumerate(at):
+ near = round(tau)
+ if abs(tau - near) <= SNAP:
+ out.append(frames[near % n])
++ shows.append(near % n)
+ continue
+ a = math.floor(tau)
+ if same[a]:
+ out.append(frames[a])
++ shows.append(a)
+ continue
+ t = tau - a
+ frame, how = _made(interpolate, frames[a], frames[(a + 1) % n], t, (t - spacing / 2, t + spacing / 2), reads=reads)
+ if frame is None:
+ out.append(frames[near % n])
++ shows.append(near % n)
+ shown_again.append(k)
+ made.append({"cell": k, "between": [a, (a + 1) % n], "taken": near % n, **how})
+ continue
+ out.append(frame)
++ shows.append(None)
+ made.append({"cell": k, "between": [a, (a + 1) % n], **how})
+ return out, {"asked": out_fps, "fps": fps, "applied": True, "cells": len(out), "times": [round(x, 4) for x in at],
- "made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made}
++ "made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made,
++ "shows": shows}
+
+
+ def public(record: dict[str, Any]) -> dict[str, Any]:
+ """The record as the strip metadata carries it: the reading as delivered (`cells`, `poses`, `held_runs`), before
+ (each run `filled` or why not, with its faults), the cells made and left, and the rate asked — not each try."""
+ out: dict[str, Any] = {k: record[k] for k in ("mode", "why", "drawn", "cells", "poses", "held_runs", "made") if k in record}
+ before = record["before"]
+ out["before"] = {"cells": before["cells"], "poses": before["poses"],
+ "held_runs": [{k: v for k, v in r.items() if k != "tries"} for r in before["held_runs"]]}
+ if "unmade" in record:
+ out["unmade"] = {k: record["unmade"][k] for k in ("cells", "why", "install") if k in record["unmade"]}
+ if "out_fps" in record:
+ out["out_fps"] = {k: record["out_fps"][k] for k in ("asked", "fps", "applied", "cells", "made", "shown_again", "why", "install")
+ if k in record["out_fps"]}
+ return out
diff --cc sprite_gen/video/loop.py
index 603990d,5f6191a..159cdcf
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@@ -1746,15 -1817,14 +1834,16 @@@ def _counted(cycle: dict[str, Any], ste
def _motion_auto(frames: list[Image.Image], files: list[Path], D: np.ndarray, trajectory: np.ndarray, analysis: dict[str, Any],
- *, fps: float, window: CutWindow, prof: LoopProfile, steps: int | None, seam_max: float,
+ *, fps: float, window: CutWindow, prof: LoopProfile, state: str, steps: int | None, seam_max: float,
seam_pop_max: float | None, scratch: _Scratch, said: dict[str, Any],
- turn: body_turn_mod.Turn | None = None) -> tuple[dict[str, Any], list[Path], dict[str, Any]]:
+ turn: body_turn_mod.Turn | None = None
+ ) -> tuple[dict[str, Any], list[Path], dict[str, Any], list[float] | None]:
"""`--anchor motion-auto`'s cut of `frames` — the clip after its lead-in, held, `files` written of them and `D`,
`trajectory` and `analysis` read on them (auto_motion.analyse): the search, the gait fallback after a first search
- that finds nothing, then the count, given (`steps`, `_counted`) or the clip's crossings (`_by_steps`). Returns the
+ that finds nothing, then the count, given (`steps`, `_counted`) or the clip's crossings (`_by_steps`) and, for a cut
+ one step long that neither counted, the clip two lengths on (`_two_lengths`). Returns the
- cut, and the files and the analysis it was read on (the gait fallback's, where it scaled the frames back); `said`
+ cut, the files and the analysis it was read on (the gait fallback's, where it scaled the frames back), and the factor
+ the gait fallback scaled each frame by (None where it did not); `said`
takes what the report adds (`automatic_motion_analysis` read again, `gait_fallback`), whether a cut is found or the
search raises. With `turn` (body_turn.Turn), no cut that holds a frame of a body turn is taken."""
lo, hi = window.lo, window.hi
@@@ -1815,7 -1883,10 +1904,10 @@@
else:
cycle = _by_steps(cycle, refused, frames=frames, analysis=analysis, D=D, trajectory=trajectory,
window=window, searched=searched, detect=detect, seam_max=seam_max, cells=cells, turn=turn)
+ # A cut one step long that nothing counted: the clip itself is asked for two (`_two_lengths`).
+ cycle = _two_lengths(cycle, prof=prof, fps=fps, state=state, window=window, D=D, trajectory=trajectory, frames=frames,
+ files=files, moved=moved, detect=detect, cells=cells, seam_max=seam_max, turn=turn)
- return cycle, files, analysis
+ return cycle, files, analysis, undone
def _from_lead_in(record: Any, lead: int) -> Any:
@@@ -1944,29 -2158,6 +2181,37 @@@ def _refuse_overlap(frames_dir: Path, f
refuse_overlap({"--frames-dir": frames_dir, **{f"{f.name} in --frames-dir": f for f in files}}, outputs, verb="video-loop")
+def _cell_record(strip_bytes: bytes, cells: list[Image.Image], *, start: int, length: int, samples: list[int],
+ anchored: list[str], wrap_dx: int, motion: dict[str, Any] | None,
- scales: dict[str, list[float]]) -> dict[str, Any]:
++ scales: dict[str, list[float]], upsampled: dict[str, Any] | None = None) -> dict[str, Any]:
+ """The strip's record of its cells (`CELL_RECORD`), bound to the strip by its PNG's sha256: for each cell, the frame of
+ the cut it shows at the end of the cut (`cells`, frame `samples[c]` of a cut `length` frames long from clip frame
- `start`), the source frame it is, where the anchor moved that frame before the crop (the body anchor's ramp,
- `ramp_offset` of `wrap_dx`; the motion correction's place, `motion_anchor.laid_at`; nothing at --anchor none or feet),
++ `start`; at --out-fps, `upsampled`, the frame cell `samples[c]` is, and one made between two frames reads as the
++ frame at or before its time, as the seam reads it), the source frame it is, where the anchor moved that frame before
++ the crop (the body anchor's ramp, `ramp_offset` of `wrap_dx`; the motion correction's place, `motion_anchor.laid_at`;
++ nothing at --anchor none or feet),
+ the factor each step that held the clip's frames to one size scaled it by (`scales`, per clip frame; 1 where none did),
+ and whether it is that frame as filmed but for the anchor's move: its pixels are its pixels anchored, before any
+ repair (`anchored`, the cut's receipt), and no step held the clip's frames. What made a cell otherwise — a repair, a
- blend at the wrap, a hold — is not listed: the cell's pixels say it."""
++ blend at the wrap, a hold, a frame between at --out-fps — is not listed: the cell's pixels say it."""
+ def moved(k: int) -> list[int]:
+ if motion is not None:
+ return list(motion_anchor.laid_at(motion, k))
+ return [ramp_offset(wrap_dx, k, length), 0]
+
++ def frame(c: int) -> int:
++ if upsampled is None:
++ return c
++ shown = upsampled["shows"][c]
++ return shown if shown is not None else min(length - 1, math.floor(upsampled["times"][c]))
++
+ return {"strip_sha256": evidence_mod.digest(strip_bytes), "cells": [
+ {"source_frame": start + k, "anchor_move_px": moved(k),
+ "scale": {step: scales[step][start + k] if step in scales else 1.0 for step in CELL_SCALE_STEPS},
+ "as_filmed": not scales and evidence_mod.digest(cell.tobytes()) == anchored[k]}
- for k, cell in zip(samples, cells)]}
++ for k, cell in ((frame(c), cell) for c, cell in zip(samples, cells))]}
+
+
def run_loop(frames_dir: Path, out_dir: Path, **options: Any) -> dict[str, Any]:
"""Cut the loop (`_cut_loop`, which takes the options). The frames a size hold or the gait fallback scales back
are written in folders of the run's own (`_Scratch`), removed however the run ends."""
@@@ -2343,15 -2568,34 +2629,37 @@@ def _cut_loop
refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})
raise SystemExit(error) from exc
report_base["motion_anchor"] = motion
- if anchor in ("none", "body") and cycle["kind"] != "lifetime":
+ # Each frame of the cut anchored, before any repair, pixel for pixel: its receipt, and what each cell's record reads
+ # whether it is that frame as filmed (`cell_record`).
+ anchored = [evidence_mod.digest(f.tobytes()) for f in frames]
+ if anchor != "feet" and cycle["kind"] != "lifetime":
from sprite_gen.video.source import RECIPE
report_base["source_projection"] = {
- "recipe": RECIPE, "wrap_dx_px": wrap_dx,
- "before_repair_pixels_sha256": [evidence_mod.digest(f.tobytes()) for f in frames],
+ "recipe": MOTION_RECIPE if motion is not None else RECIPE, "wrap_dx_px": wrap_dx,
+ "before_repair_pixels_sha256": anchored,
}
+ # A loop closes on its first cell again; a cut played once runs from its first to its last.
+ ring = cycle["kind"] not in ("one-shot", "lifetime", *nonloop.KINDS)
+ if cycle["kind"] == "lifetime":
+ report_base["held_fill"] = {"mode": fill_held, "why": "an effect's lifetime is played as filmed", "made": [],
+ "before": held_fill_mod.reading(same), **held_fill_mod.reading(same)}
+ else:
+ # The cells that show the picture before them again, made between the poses beside them (docs/loop-repair.md
+ # section 7), on the cut as anchored, before anything reads its flow or its wrap. A cut drawn on twos or threes
+ # keeps them: its hold as video-cycle-align reads it, over the cut, else over the clip.
+ cut_drawings = report_base["cycle_drawings"]
+ hold = cut_drawings["hold"] if cut_drawings["hold"] is not None else report_base["drawings"]["hold"]
+ try:
+ frames, report_base["held_fill"] = _fill_held(frames, interpolate, ring=ring, same=same, mode=fill_held, hold=hold)
+ except (ValueError, rife_mod.RifeUnavailable) as exc:
+ error = (f"video-loop: {exc}; the cut shows a picture again and the frames between are to be made — fix RIFE, "
+ "or pass --fill-held off to cut it as filmed (docs/loop-repair.md section 7)")
+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})
+ raise SystemExit(error) from exc
+ if report_base["held_fill"]["made"]:
+ report_base["seam_measurement"] = "rendered-cells"
+ for line in _fill_lines(report_base["held_fill"]):
+ print(f"video-loop: warning: {name}: {line}", file=sys.stderr)
if prof.gait:
# The ghost screen of the cut as filmed (docs/loop-repair.md section 4), read before the jump repair: each
# filmed ghost it names is a target of that repair, which gives it way to a clean frame where there is one.
@@@ -2602,11 -2877,7 +2941,12 @@@
n_out = min(n_out, int(strip_meta["frames"]))
strip_path = out_dir / f"{name}.strip.png"
strip.save(strip_path)
- atomic_write_text(out_dir / f"{name}.strip.json", json.dumps(strip_meta, indent=2) + "\n")
+ cell_record = _cell_record(strip_path.read_bytes(), [frames[k] for k in strip_meta["sample_indices"]], start=i,
+ length=L, samples=strip_meta["sample_indices"], anchored=anchored, wrap_dx=wrap_dx,
- motion=motion, scales=clip_scales)
++ motion=motion, scales=clip_scales,
++ upsampled=held_record["out_fps"] if upsampled is not None else None)
+ # The record of its cells is the strip's own: written beside it, not into the report.
+ atomic_write_text(out_dir / f"{name}.strip.json", json.dumps({**strip_meta, CELL_RECORD: cell_record}, indent=2) + "\n")
# resampled GIF/WebP frames: same crop as the strip, n_out evenly across the cycle
single_play = cycle["kind"] in nonloop.KINDS
diff --cc tests/video/test_held_fill.py
index 0000000,ca123f7..1840887
mode 000000,100644..100644
--- a/tests/video/test_held_fill.py
+++ b/tests/video/test_held_fill.py
@@@ -1,0 -1,498 +1,540 @@@
+ # SPDX-License-Identifier: Apache-2.0
+ """Held cells (sprite_gen/video/held_fill.py, docs/loop-repair.md section 7): neighbour cells of a cut that show the
+ same picture are found on every cut `video-loop` makes, recorded (`held_fill`: the held runs, the poses and the cells)
+ and, by default, made again as the frames between the pose before them and the pose after; the cut's first and last
+ cells, its length, its beat and its wrap stay as they were, and a part standing still in both stays where it stood.
+ A clip asked for at a higher rate than it was filmed (`--out-fps`) is given frames between, not frames shown again.
+ With no RIFE the cut is delivered as filmed with a warning naming the motion and the install line; `--fill-held off`
+ cuts it as before. A cut with no held cell comes out byte for byte as before (the six inputs below, their pictures
+ pinned on the engine before the fill).
+
+ The interpolator is a stand-in that draws the synthetic clip again at the time asked for (`Between`), so the tests
+ need no binary and say which frame comes back."""
+
+ from __future__ import annotations
+
+ import hashlib
+ import json
++import math
+ import os
+ from pathlib import Path
+
+ import numpy as np
+ import pytest
+ from PIL import Image
+
+ from sprite_gen.video import held_fill
+ from sprite_gen.video import loop as loop_mod
++from sprite_gen.video import sway
+ from tests.picture_digest import picture_digest
+ from tests.video.held_fill_inputs import (N, Between, hop, planter, save, shown_again, slid, swing, topple, walk,
+ walk_at)
+
+
+ def _no_rife(monkeypatch, tmp_path: Path) -> None:
+ """No RIFE anywhere the engine looks: no SPRITE_GEN_RIFE, no directory on PATH holding one, an empty data
+ directory."""
+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
+ path = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not (Path(d) / "rife-ncnn-vulkan").exists()]
+ monkeypatch.setenv("PATH", os.pathsep.join(path))
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))
+
+
+ def _run(tmp_path: Path, frames: list[Image.Image], name: str = "m", **kw) -> dict:
+ keyed = save(frames, tmp_path / f"{name}-keyed")
+ return loop_mod.run_loop(keyed, tmp_path / f"{name}-out", fps=24.0, min_len=None, max_len=None, n_out=None,
+ seam_max=loop_mod.SEAM_RATIO_MAX, name=name, report_path=None, **kw)
+
+
+ def _sha(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+ def _bytes(out: Path, name: str) -> dict[str, str]:
+ cycle = hashlib.sha256(b"".join(p.read_bytes() for p in sorted((out / "cycle").glob("frame-*.png")))).hexdigest()
+ return {"strip": _sha(out / f"{name}.strip.png"), "gif": _sha(out / f"{name}.gif"), "webp": _sha(out / f"{name}.webp"),
+ "cycle": cycle}
+
+
+ def _pictures(out: Path, name: str) -> dict[str, str]:
+ return {"strip": picture_digest([out / f"{name}.strip.png"]), "gif": picture_digest([out / f"{name}.gif"]),
+ "webp": picture_digest([out / f"{name}.webp"]),
+ "cycle": picture_digest(sorted((out / "cycle").glob("frame-*.png")))}
+
+
+ def _meta(rep: dict) -> dict:
+ return json.loads(Path(rep["strip"]["path"]).with_suffix("").with_suffix(".strip.json").read_text())
+
+
+ def _cycle(rep: dict) -> list[Image.Image]:
+ return [Image.open(p).convert("RGBA") for p in sorted((Path(rep["out_dir"]) / "cycle").glob("frame-*.png"))]
+
+
+ # Pinned on the engine before the fill (886936e): a cut with no held cell is delivered as it was. The pins are the
+ # pictures (`_pictures`, tests/picture_digest.py), not the files: the same pixels are other PNG bytes on Linux than on
+ # macOS, while the engine before the fill and this one write the same files on each.
+ UNHELD = {
+ "walk-fixed": (lambda: walk(), dict(state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off"), {
+ "strip": "1467e5923f24c4830ef24e6525e9e537d73504a0d95badf1ba4cd0ed3288572b",
+ "gif": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
+ "webp": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
+ "cycle": "319c0f8aee34fb537b1702eecc018afc4a03b10dcda1b84c5cb204a14d4ac3fa"}),
+ "walk-auto": (lambda: walk(N * 3 + 4), dict(state="walk", repair="off"), {
+ "strip": "1c3945eadb5095d3b1c929bd2009bd510ebf7760a4f0f92c8e618b04d882b6ca",
+ "gif": "6e9348b6d9ac27dc1868bf8a2b9aae7daee44847274eb65c1b6ce4431c686f06",
+ "webp": "6e9348b6d9ac27dc1868bf8a2b9aae7daee44847274eb65c1b6ce4431c686f06",
+ "cycle": "185053b6a035a9d0b672a1d93d7e378f819189cd3cf144540e9f95a111a0b2b2"}),
+ "hop-one-shot": (lambda: hop(), dict(state="jump", cycle_mode="one-shot"), {
+ "strip": "6442073e3ada3b03e2f7df6c52348fc001fcbdce6c51c8e91ce157e91c313ac7",
+ "gif": "ab58ee8b25599331b7958701d81526b155a05b1cddfa8b9ed823134f9f2e93fb",
+ "webp": "ab58ee8b25599331b7958701d81526b155a05b1cddfa8b9ed823134f9f2e93fb",
+ "cycle": "189484dd441486fe6241534fae7a03ea7afac71ec204b8871e9da938e6e69793"}),
+ "swing-pinned": (lambda: swing(), dict(state="attack", cycle_mode="pinned", anchor="none"), {
+ "strip": "9dd4896eef213ae44b487f92d33ffa1d7e6aea66ac32e9c97773f6c0ed27e3d1",
+ "gif": "75df72100becbdd3b823ae282b2dd28815f6271198dd8562d8d91ee9363d6358",
+ "webp": "75df72100becbdd3b823ae282b2dd28815f6271198dd8562d8d91ee9363d6358",
+ "cycle": "b2a255d5f0018a71225501a86dcfa54915fa9ed4c4d936319fb83c31ab57bf1e"}),
+ "topple-once": (lambda: topple(), dict(state="death", cycle_mode="once"), {
+ "strip": "c9b7900ec1d4523bb34c07eb8077f72352bbc8251fc5caab31647317e0634957",
+ "gif": "285a7352ba6345648cfc48185f9121ce75f37cc63b3b5875dce5b4bed738fc8a",
+ "webp": "285a7352ba6345648cfc48185f9121ce75f37cc63b3b5875dce5b4bed738fc8a",
+ "cycle": "67a1691bc7cb2eabf5a885dd9b993eb8596ea20090594958b7a02afc09948c63"}),
+ "swing-once-return": (lambda: swing(), dict(state="leap", cycle_mode="once-return", anchor="none"), {
+ "strip": "883f7e44cc1f54ec5a1442ed12fe8f608070e12b9795c73d2f871425d76e977f",
+ "gif": "70de98ed5a45f2e9840c6946057a868260cae3588bff9969205e453ef1b024f3",
+ "webp": "70de98ed5a45f2e9840c6946057a868260cae3588bff9969205e453ef1b024f3",
+ "cycle": "4dfe6899ab09db62987b27d0a35ba754a22ca78e02945e731b1025dfe3af90e3"}),
+ }
+
+
+ @pytest.mark.parametrize("case", sorted(UNHELD))
+ def test_a_cut_with_no_held_cell_is_delivered_byte_for_byte_as_before(case, tmp_path, monkeypatch):
+ _no_rife(monkeypatch, tmp_path) # nothing is made, so nothing looks for RIFE
+ frames, kw, pinned = UNHELD[case]
+ rep = _run(tmp_path, frames(), case, **kw)
+ assert _pictures(Path(rep["out_dir"]), case) == pinned
+ record = _meta(rep)["held_fill"]
+ assert record == held_fill.public(rep["held_fill"])
+ assert record["mode"] == "auto" and record["made"] == [] and "unmade" not in record
+ cells = rep["cycle"]["length"]
+ assert record["cells"] == cells
+ if case == "topple-once":
+ # It lies still for its last five cells: the cut's closing pose, kept.
+ assert record["held_runs"] == [{"start": cells - 5, "length": 5}]
+ assert record["before"]["held_runs"][0]["filled"] is False
+ assert record["poses"] == cells - 4
+ else:
+ assert record["held_runs"] == [] and record["poses"] == cells
+
+
+ STALLED = {5: 2, 13: 3} # the walk's frame 5 shown twice, frame 13 three times
+ STALLED_OFF = { # the stalled walk cut on the engine before the fill (886936e)
+ "strip": "32f2c1b7f4f3aedfa3eba4d49b849fd8efea9e011aaf2e035407a97ac6e9430d",
+ "gif": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
+ "webp": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
+ "cycle": "2d74651f64831c9c512f0486e1b03ca3827c4b9d3840bf11f8c67fad221bbfe9",
+ }
+ STALLED_CUT = dict(state="walk", cycle_mode="fixed", start=0, length=N + 3, anchor="none", repair="off")
+
+
+ def test_a_stalled_walk_has_its_held_cells_made_between_the_poses_beside_them(tmp_path):
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, shown_again(walk(), STALLED), interpolate=between, **STALLED_CUT)
+ record = rep["held_fill"]
+ assert record["before"]["cells"] == N + 3 and record["before"]["poses"] == N
+ assert [(r["start"], r["length"], r["filled"]) for r in record["before"]["held_runs"]] == [(5, 2, True), (14, 3, True)]
+ assert record["made"] == [6, 15, 16]
+ # Each made at its own time between the pose before the run and the pose after it: half way, a third and two thirds.
+ assert sorted(between.calls) == [(5.0, 6.0, 0.5), (13.0, 14.0, 0.3333), (13.0, 14.0, 0.6667)]
+ assert (record["cells"], record["poses"], record["held_runs"]) == (N + 3, N + 3, [])
+ cells = _cycle(rep)
+ assert cells[6].tobytes() == walk_at(5.5).tobytes()
+ assert cells[15].tobytes() == walk_at(13 + 1 / 3).tobytes()
+ # Every other cell is the cut's as filmed: the first and the last, the length, the beat.
+ filmed = shown_again(walk(), STALLED)[: N + 3]
+ assert len(cells) == N + 3
+ assert all(cells[k].tobytes() == filmed[k].tobytes() for k in range(N + 3) if k not in (6, 15, 16))
+ assert _meta(rep)["held_fill"] == held_fill.public(record)
+ assert rep["seam_measurement"] == "rendered-cells"
+
+
+ def test_fill_held_off_cuts_the_stalled_walk_as_before_and_still_names_its_runs(tmp_path):
+ rep = _run(tmp_path, shown_again(walk(), STALLED), fill_held="off", **STALLED_CUT)
+ assert _pictures(Path(rep["out_dir"]), "m") == STALLED_OFF
+ record = rep["held_fill"]
+ assert record["mode"] == "off" and record["made"] == []
+ assert [(r["start"], r["length"], r["filled"], r["why"]) for r in record["before"]["held_runs"]] == [
+ (5, 2, False, "--fill-held off"), (14, 3, False, "--fill-held off")]
+ assert (record["cells"], record["poses"]) == (N + 3, N)
+
+
+ def test_no_rife_delivers_the_held_cells_as_filmed_and_says_which_motion(tmp_path, monkeypatch, capsys):
+ _no_rife(monkeypatch, tmp_path)
+ rep = _run(tmp_path, shown_again(walk(), STALLED), name="stalled-walk", **STALLED_CUT)
+ assert rep["status"] == "passed"
+ out = Path(rep["out_dir"])
+ # The images are the cut as filmed: what --fill-held off delivers.
+ off = _run(tmp_path, shown_again(walk(), STALLED), name="off", fill_held="off", **STALLED_CUT)
+ assert {k: v for k, v in _bytes(out, "stalled-walk").items()} == _bytes(Path(off["out_dir"]), "off")
+ record = rep["held_fill"]
+ assert record["made"] == [] and record["unmade"]["cells"] == [6, 15, 16]
+ assert record["unmade"]["install"] == loop_mod.rife_mod.install_command()
+ assert (record["cells"], record["poses"]) == (N + 3, N)
+ err = capsys.readouterr().err
+ assert "stalled-walk" in err and "RIFE is not installed" in err and loop_mod.rife_mod.install_command() in err
+
+
+ def test_a_hold_longer_than_three_cells_is_the_motion_s_own_and_kept(tmp_path):
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, shown_again(walk(), {9: 5}), interpolate=between,
+ **{**STALLED_CUT, "length": N + 4})
+ run = rep["held_fill"]["before"]["held_runs"]
+ assert [(r["start"], r["length"], r["filled"]) for r in run] == [(9, 5, False)]
+ assert "longer than" in run[0]["why"]
+ assert between.calls == [] and rep["held_fill"]["held_runs"] == [{"start": 9, "length": 5}]
+
+
+ @pytest.mark.slow
+ def test_a_walk_drawn_on_twos_is_limited_animation_and_kept(tmp_path):
+ # Each drawing shown twice, as a clip of 12 drawings a second at 24 fps is (sprite_gen/video/held.py).
+ twos = shown_again(walk(), {k: 2 for k in range(N + 6)})
+ cut = {**STALLED_CUT, "length": 2 * N}
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, twos, interpolate=between, **cut)
+ record = rep["held_fill"]
+ assert rep["cycle_drawings"]["hold"] == 2 and record["drawn"] == 2
+ assert between.calls == [] and record["made"] == []
+ assert all(not r["filled"] and "drawn on twos" in r["why"] for r in record["before"]["held_runs"])
+ assert (record["cells"], record["poses"]) == (2 * N, N)
+ off = _run(tmp_path, twos, name="off", fill_held="off", **cut)
+ assert _bytes(Path(rep["out_dir"]), "m") == _bytes(Path(off["out_dir"]), "off")
+
+
+ @pytest.mark.slow
+ def test_a_walk_carried_to_60_fps_by_repeating_frames_reads_a_hold_and_is_filled_to_a_pose_a_cell(tmp_path):
+ # 24 fps carried to 60 by the frame under each time: each frame shown three and two times by turns. Its rhythm
+ # reads a hold of 2, but its runs are not each two cells: the frames between are made.
+ filmed = walk(2 * N + 2)
+ carried = [filmed[k * 24 // 60] for k in range(len(filmed) * 60 // 24)]
+ between = Between(walk_at, range(2 * N + 2), period=N)
+ keyed = save(carried, tmp_path / "carried-keyed")
+ rep = loop_mod.run_loop(keyed, tmp_path / "carried-out", fps=60.0, min_len=None, max_len=None, n_out=None,
+ seam_max=loop_mod.SEAM_RATIO_MAX, name="m", report_path=None, interpolate=between,
+ state="walk", anchor="none", repair="off")
+ record = rep["held_fill"]
+ assert rep["cycle_drawings"]["hold"] == 2 and "drawn" not in record
+ assert {r["length"] for r in record["before"]["held_runs"]} == {2, 3}
+ assert record["before"]["poses"] < record["before"]["cells"] == rep["cycle"]["length"] == 60
+ assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])
+ cells, start = _cycle(rep), rep["cycle"]["start"]
+ assert cells[0].tobytes() == carried[start].tobytes() and cells[-1].tobytes() == carried[start + 59].tobytes()
+
+
+ def test_a_once_cut_and_a_one_shot_have_their_held_cells_made_too(tmp_path):
+ frames = topple()
+ stalled = shown_again(frames, {20: 2})
+ times = {f.tobytes(): float(k) for k, f in enumerate(frames)}
+ between = Between(lambda t: _topple_at(t), [])
+ between.known.update(times)
+ rep = _run(tmp_path, stalled, "fall", interpolate=between, state="death", cycle_mode="once")
+ record = rep["held_fill"]
+ start = rep["cycle"]["start"]
+ assert [(r["start"], r["filled"]) for r in record["before"]["held_runs"] if r["filled"]] == [(20 - start, True)]
+ assert between.calls == [(20.0, 21.0, 0.5)]
+ hopped = shown_again(hop(), {18: 2})
+ rep = _run(tmp_path, hopped, "hop", interpolate=lambda a, b, t: Image.blend(a, b, t), state="jump", cycle_mode="one-shot")
+ assert any(r["start"] + rep["cycle"]["start"] == 18 for r in rep["held_fill"]["before"]["held_runs"])
+
+
+ def _topple_at(time: float) -> Image.Image:
+ """`topple`'s body `time` frames in, between its frames as well."""
+ t = min(1.0, max(0.0, (time - 6) / 30))
+ a = np.zeros((96, 128, 4), dtype=np.uint8)
+ height, width = round(64 - 40 * t), round(16 + 36 * t)
+ a[86 - height:86, 40:40 + width] = (200, 80, 30, 255)
+ return Image.fromarray(a, "RGBA")
+
+
+ # The fill on a cut's frames, as `video-loop` calls it: which runs it makes, which it keeps and why.
+
+
+ def _reach(time: float) -> Image.Image:
+ return planter(4 * time)
+
+
+ def _planted(times: list[float]) -> list[Image.Image]:
+ return [_reach(t) for t in times]
+
+
+ def test_a_part_standing_still_on_both_sides_stays_where_it_stood():
+ frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])
+ out, record = held_fill.fill(frames, Between(_reach, range(7)), ring=False)
+ assert record["made"] == [4]
+ assert out[4].tobytes() == _reach(3.5).tobytes()
+ assert record["before"]["held_runs"][0]["filled"] is True
+ assert record["contact"][0]["kept"] == 1.0
+
+
+ def test_a_frame_between_that_drags_a_planted_foot_is_not_taken():
+ frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])
+ out, record = held_fill.fill(frames, Between(_reach, range(7), after=slid), ring=False)
+ assert record["made"] == []
+ assert out[4].tobytes() == frames[4].tobytes() # the held cell, as filmed
+ run = record["before"]["held_runs"][0]
+ assert run["filled"] is False and "contact" in run["faults"]
+ assert record["held_runs"] == [{"start": 3, "length": 2}]
+
+
+ def test_a_frame_between_that_cross_fades_two_poses_is_not_taken():
+ # Two poses laid over each other at half strength: the double exposure an interpolator gives where it cannot follow.
+ frames = shown_again(walk(), STALLED)[: N + 3]
+ out, record = held_fill.fill(frames, lambda a, b, t: Image.blend(a, b, t), ring=True)
+ assert record["made"] == [] and [o.tobytes() for o in out] == [f.tobytes() for f in frames]
+ assert all(not r["filled"] and "ghost" in r["faults"] for r in record["before"]["held_runs"])
+
+
+ def test_the_opening_and_the_closing_pose_of_a_cut_played_once_are_kept():
+ frames = _planted([0, 0, 1, 2, 3, 4, 4])
+ calls: list = []
+ out, record = held_fill.fill(frames, lambda a, b, t: calls.append(t) or a, ring=False)
+ whys = [r["why"] for r in record["before"]["held_runs"]]
+ assert calls == [] and record["made"] == []
+ assert "opening" in whys[0] and "closing" in whys[1]
+
+
+ def test_a_loop_s_held_cells_at_its_wrap_are_kept_and_at_its_start_made():
+ frames = _planted([0, 0, 1, 2, 3, 4, 5, 5])
+ between = Between(_reach, range(7), period=None)
+ # The wrap closes on cell 0 again: a frame between the last pose and the first is the wrap's, not the hold's.
+ out, record = held_fill.fill(frames, between, ring=True)
+ runs = record["before"]["held_runs"]
+ assert (runs[0]["start"], runs[0]["filled"]) == (0, True)
+ assert (runs[1]["start"], runs[1]["filled"]) == (6, False) and "wrap" in runs[1]["why"]
+ assert record["made"] == [1] and out[0].tobytes() == frames[0].tobytes() and out[7].tobytes() == frames[7].tobytes()
+
+
+ def test_codec_copies_read_as_the_same_picture_and_the_slowest_motion_does_not():
+ still = planter(10)
+ noisy = np.asarray(still).astype(np.int16)
+ noisy[..., :3] += np.random.default_rng(0).integers(-3, 4, size=noisy[..., :3].shape).astype(np.int16)
+ noisy = Image.fromarray(np.clip(noisy, 0, 255).astype(np.uint8), "RGBA")
+ assert held_fill.same_steps([still, noisy, planter(11)]) == [True, False]
+
+
+ def test_a_whole_figure_moving_under_a_thumbnail_pixel_is_not_the_same_picture():
+ # A walker going away, a frame 280 px wide: its steps move a thousand of its pixels, and some move none of the
+ # analysis thumbnail's. The frame as cut is read too: a cut of it shows no held cell.
+ from tests.video.test_gait_fallback import walking_away
+
+ frames = [walking_away(k) for k in range(73)][24:48]
+ thumbs = held_fill._thumbs(frames)
+ assert any(held_fill._same(a, b) for a, b in zip(thumbs, thumbs[1:]))
+ assert held_fill.same_steps(frames) == [False] * 23
+
+
+ # A higher rate than the clip's: frames between, never frames shown again.
+
+
+ @pytest.mark.slow
+ def test_a_walk_asked_for_at_60_fps_is_made_of_frames_between(tmp_path):
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, walk(), "walk60", interpolate=between, out_fps=60.0,
+ state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")
+ meta = _meta(rep)
+ record = rep["held_fill"]
+ assert record["out_fps"]["applied"] is True and record["out_fps"]["cells"] == 60
+ assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])
+ assert meta["frames"] == 60 and meta["cycle_seconds"] == 1.0 and meta["delay_ms"] == pytest.approx(16.67)
+ assert meta["out_fps"] == 60.0
+ cells = _cycle(rep)
+ assert len(cells) == 60
+ assert cells[0].tobytes() == walk_at(0).tobytes() and cells[5].tobytes() == walk_at(2).tobytes()
+ assert cells[1].tobytes() == walk_at(0.4).tobytes()
+ assert len({c.tobytes() for c in cells}) == 60
+
+
++def test_a_cut_at_a_rate_of_its_own_records_each_cell_as_the_frame_it_is_and_a_cell_made_between_as_not_filmed(tmp_path):
++ # The strip's record of its cells (`cell_record`, video-sway --read-on-cut) of a walk that shows frame 9 twice, its
++ # held cells kept, at --out-fps 49: a cell that is a frame (on its time, a hair before it, or between the two frames
++ # of one picture, that picture again; `out_fps.shows`) is that frame as filmed; one made between two frames reads
++ # as the frame before its time, is not as filmed but where its pixels are that frame's, and --read-on-cut does not
++ # pair it.
++ clip, between = shown_again(walk(), {9: 2}), Between(walk_at, range(N + 6), period=N)
++ cut = dict(state="walk", cycle_mode="fixed", length=N, anchor="none", repair="off", fill_held="off")
++ rep = _run(tmp_path, clip, "walk49", interpolate=between, out_fps=49.0, start=0, **cut)
++ record = rep["held_fill"]["out_fps"]
++ assert record["applied"] is True and record["cells"] == 49 and record["shown_again"] == []
++ own = _meta(rep)
++ cells = sway.cell_record(own, _sha(Path(rep["strip"]["path"])))
++ shown = _cycle(rep)
++ kinds = []
++ for c, (cell, times, shows) in enumerate(zip(cells, record["times"], record["shows"])):
++ assert cell["anchor_move_px"] == [0, 0] and cell["scale"] == {"size_hold": 1.0, "gait_fallback": 1.0}
++ frame = clip[cell["source_frame"]].tobytes()
++ if shows is not None:
++ assert cell["source_frame"] == shows and cell["as_filmed"] is True and shown[c].tobytes() == frame
++ kinds.append("on" if abs(times - round(times)) <= held_fill.SNAP else "again")
++ else:
++ # the stand-in draws the walk again at the cell's time: now and then that is a frame's own picture
++ assert cell["source_frame"] == math.floor(times) and cell["as_filmed"] is (shown[c].tobytes() == frame)
++ kinds.append("made")
++ # frame 1 a hair before its time (0.98), frame 9 again between its two cells (9.31, 9.80), the rest made
++ assert record["times"][2] == 0.9796 and cells[2]["source_frame"] == 1 and kinds[2] == "on"
++ assert [cells[c]["source_frame"] for c in (19, 20)] == [9, 9] and kinds[19:21] == ["again", "again"]
++ assert [c for c, kind in enumerate(kinds) if kind != "made"] == [0, 2, 19, 20, 47] and kinds.count("made") == 44
++ assert sum(not cells[c]["as_filmed"] for c, kind in enumerate(kinds) if kind == "made") >= 40
++ # Read on a cut of the same clip from frame 3 (24 fps): this cut's first cell of frame 3 is made between 3 and 4.
++ read = _run(tmp_path, clip, "from3", start=3, **cut)
++ first = [c["source_frame"] for c in cells].index(3)
++ assert cells[first]["as_filmed"] is False and kinds[first] == "made"
++ with pytest.raises(SystemExit, match=rf"cell {first} is not that frame as filmed: video-loop did not cut it as filmed "
++ rf"\(cell_record\.cells\[{first}\]\.as_filmed\)"):
++ sway.recut_pair(own, _meta(read), _sha(Path(read["strip"]["path"])), strip_sha256=_sha(Path(rep["strip"]["path"])))
++
++
+ @pytest.mark.slow
+ def test_a_one_shot_asked_for_at_60_fps_keeps_its_first_and_last_frame(tmp_path):
+ frames = hop()
+ times = {f.tobytes(): float(k) for k, f in enumerate(frames)}
+ made: list = []
+
+ def between(a, b, t):
+ made.append((times[a.tobytes()], times[b.tobytes()], round(t, 4)))
+ return Image.blend(a, b, t)
+
+ rep = _run(tmp_path, frames, "hop60", interpolate=between, out_fps=60.0, state="jump", cycle_mode="one-shot")
+ L = rep["cycle"]["length"]
+ record = rep["held_fill"]
+ cells = _cycle(rep)
+ assert len(cells) == round((L - 1) * 2.5) + 1 == record["cells"]
+ filmed = hop()[rep["cycle"]["start"]: rep["cycle"]["start"] + L]
+ assert cells[0].tobytes() == filmed[0].tobytes() and cells[-1].tobytes() == filmed[-1].tobytes()
+ assert record["out_fps"]["applied"] is True
+
+
+ def test_no_rife_delivers_a_clip_asked_for_at_a_higher_rate_at_its_own(tmp_path, monkeypatch, capsys):
+ _no_rife(monkeypatch, tmp_path)
+ rep = _run(tmp_path, walk(), "walk60", out_fps=60.0, state="walk", cycle_mode="fixed", start=0, length=N,
+ anchor="none", repair="off")
+ assert rep["status"] == "passed" and _meta(rep)["frames"] == N and "out_fps" not in _meta(rep)
+ assert rep["held_fill"]["out_fps"]["applied"] is False
+ err = capsys.readouterr().err
+ assert "walk60" in err and "--out-fps 60" in err and loop_mod.rife_mod.install_command() in err
+
+
+ def test_a_rate_under_the_clip_s_own_is_refused(tmp_path):
+ with pytest.raises(SystemExit, match="--out-fps 12"):
+ _run(tmp_path, walk(), out_fps=12.0, state="walk", cycle_mode="fixed", start=0, length=N, anchor="none")
+
+
+ def test_video_loop_and_video_set_take_the_switches():
+ import argparse
+
+ from sprite_gen.video import batch
+
+ parser = argparse.ArgumentParser()
+ loop_mod.add_arguments(parser)
+ args = parser.parse_args(["--frames-dir", "f", "--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])
+ assert (args.fill_held, args.out_fps) == ("off", 60.0)
+ assert parser.parse_args(["--frames-dir", "f", "--out-dir", "o"]).fill_held == "auto"
+ parser = argparse.ArgumentParser()
+ batch.add_arguments(parser)
+ args = parser.parse_args(["--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])
+ assert (args.fill_held, args.out_fps) == ("off", 60.0)
+ assert parser.parse_args(["--out-dir", "o"]).fill_held == "auto"
+
+
+ def test_video_set_hands_the_switches_to_each_cut(monkeypatch, tmp_path):
+ from sprite_gen.video import batch
+
+ seen: list[dict] = []
+ monkeypatch.setattr(batch.frames_mod, "run_frames", lambda clip, out, **kw: {
+ "fps": 24, "frames": 10, "alpha_zero_pct_min": 50, "alpha_zero_pct_max": 60, "keyed_dir": str(out)})
+
+ def run_loop(*a, **kw):
+ seen.append(kw)
+ return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,
+ "gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"},
+ "held_fill": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2}], "made": [],
+ "before": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2, "filled": False,
+ "why": "--fill-held off"}]}}}
+
+ def video(image, prompt, out, report, **kw):
+ out.write_bytes(b"test-video")
+ report.write_text(json.dumps({"prompt": prompt}))
+ return 0
+
+ monkeypatch.setattr(batch.loop_mod, "run_loop", run_loop)
+ monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
+ still = tmp_path / "front.png"
+ Image.new("RGBA", (64, 64), (200, 80, 30, 255)).save(still)
+ result = batch.run_set(bases={"front": still}, states=["idle"], root=tmp_path / "set", character=None, duration=3,
+ resolution="720p", key="green", concurrency=1, force=False, gap=0, video_runner=video,
+ align_cycles="off", fill_held="off", out_fps=60.0)
+ assert [(kw["fill_held"], kw["out_fps"]) for kw in seen] == [("off", 60.0)]
+ # The set's report says each motion's poses over its cells.
+ assert result["items"][0]["loop"]["poses"] == "9/10"
+
+
+ def test_a_cut_with_cells_made_is_not_restored_from_its_source_frames(tmp_path):
+ """The source frames do not hold a cell made between two of them: restoration (`video-loop-repair`) reads the cut
+ as one it cannot project (`source-processing-unsupported`), as it reads a blended wrap."""
+ import shutil
+ import subprocess
+
+ from sprite_gen.video import source
+ from sprite_gen.video.compare import Loop
+
+ if not shutil.which("ffmpeg") or not loop_mod.img2webp_supports_exact():
+ pytest.skip("ffmpeg and img2webp >=1.5 required")
+ filmed = shown_again(walk(), STALLED)
+ keyed = save(filmed, tmp_path / "keyed")
+ out = tmp_path / "cut"
+ loop_mod.run_loop(keyed, out, fps=24.0, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX,
+ name="walk", report_path=None, interpolate=Between(walk_at, range(N + 6), period=N), **STALLED_CUT)
+ files = sorted(keyed.glob("*.png"))
+ frames_report = tmp_path / "frames.json"
+ frames_report.write_text(json.dumps({"kind": "sprite-gen-video-frames-report", "fps": 24.0, "frames": len(files),
+ "width": filmed[0].width, "height": filmed[0].height, "stream_index": 0,
+ "key": "green"}))
+ clip = tmp_path / "clip.mp4"
+ subprocess.run(["ffmpeg", "-v", "error", "-framerate", "24", "-i", str(keyed / "%04d.png"), "-c:v", "libx264",
+ "-pix_fmt", "yuv420p", str(clip)], check=True)
+ manifest = tmp_path / "source.json"
+ manifest.write_text(json.dumps(source.manifest(clip=clip, canvas=files[0], frames_report=frames_report, files=files,
+ timestamps=source.timestamps(clip, 0))))
+ loop = Loop.read(out / "walk.strip.png", out / "walk.strip.json", out / "walk.loop.report.json")
+ projection, issue = source.project(loop, source.Source.read(
+ source_manifest=manifest, source_frames_dir=keyed, source_clip=clip, source_canvas=files[0],
+ source_frames_report=frames_report))
+ assert (projection, issue) == (None, "source-processing-unsupported")
+
+
+ @pytest.mark.slow
+ def test_the_alignment_and_a_stop_refuse_a_loop_cut_at_a_rate_of_its_own(tmp_path):
+ from sprite_gen.video import align, stop
+
+ rep = _run(tmp_path, walk(), "walk60", interpolate=Between(walk_at, range(N + 6), period=N), out_fps=60.0,
+ state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")
+ out = Path(rep["out_dir"])
+ with pytest.raises(ValueError, match="--out-fps 60"):
+ align._loop_files(out)
+ with pytest.raises(SystemExit, match="--out-fps 60"):
+ stop.read_loop(out / "walk60.strip.json")
+
+
+ def test_the_curation_view_marks_the_cells_made_and_the_cells_still_held(tmp_path):
+ """A loop's `cycle/` imported into the curation view (`unpack-atlas --pngs-dir`): each card of a cell the fill made
+ says `made`, of a cell still showing the picture before it `held`."""
+ from sprite_gen import cli
+
+ rep = _run(tmp_path, shown_again(walk(), {**STALLED, 20: 5}), interpolate=Between(walk_at, range(N + 6), period=N),
+ **{**STALLED_CUT, "length": N + 7})
+ assert rep["held_fill"]["made"] == [6, 15, 16]
+ assert cli.main(["unpack-atlas", "--pngs-dir", str(Path(rep["out_dir"]) / "cycle"), "--out-dir", str(tmp_path / "run")]) == 0
+ rows = json.loads((tmp_path / "run" / "frames" / "frames-manifest.json").read_text())["rows"]
+ labels = rows[0]["labels"]
+ assert [k for k, label in enumerate(labels) if label.endswith(" (made)")] == [6, 15, 16]
+ assert [k for k, label in enumerate(labels) if label.endswith(" (held)")] == [24, 25, 26, 27]
+ assert labels[0] == "frame-000"