Skip to content

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

fix(video-loop): a frame holds the drawing last counted where under 0.5 % of that drawing's solid pixels flip, so a walk whose every frame flips less than that from the frame before is still counted as it moves (HELD_MAX)

Soohong Kimdc41d0ceb3ab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ffee97a..a6b2223 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,9 +10,9 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- Report fields (`<name>.loop.report.json`): every walk or run report under `--anchor motion-auto` adds the `body_turn` object containing `reading` (`torso-side-v2`), `bounds` (`SIDE_SHOWN_MIN`, `WALK_SIDE_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_side`, `walk_side`, `read` (true or false), `why` (where not read), `neck`, `torso_still_side`, `side` (each frame's reading), `turns` (each `{from, to, least, at}`), `mode` (`warn` or `refuse`), `verdict`, `refused` (how many windows were refused for it), `cut` (`frames`, the cut's first and last clip frame, and `holds`, the turned frames it holds), `avoiding` (the search's refusal where the search that avoided the turn found nothing), and `unread` (a list of `{frames, why}`, each reason with the frames it applies to, appearing only where at least one frame was not read). The `verdict` field records one of `none` (read, no turn), `not-read` (a square still, a walk seen square, a first frame with no body, or a first frame the reading cannot read (no head to centre on, no solid pixel across its torso rows, or a crop of no width or with nothing in it)), `clear` (a turn, and the cut holds none of it without refusing anything), `avoided` (windows were refused for the turn and the cut leaves it out), `kept` (no cut without the turn holds a cycle; the cut taken before is kept, warned), `unfound` (no cycle with the turn or without it; refused as before, warned), or `refused` (`--body-turn refuse`). Where the still passes `SIDE_SHOWN_MIN` and the walk is seen square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing`. The command's JSON summary also gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.
- Python callers: new module `sprite_gen.video.body_turn` provides `read(frames)`, `square(reading)`, `turns(side)`, `turned(reading)`, `neck(body)`, `torso_rows(at)`, class `Turn(reading, skip=0)` (callable as `(start, length)`, returning the refusal reason or None, `held(start, length)`, counter `refused`), `refusal(...)`, `kept(...)`, `unfound(...)`, constants `READING`, `SIDE_SHOWN_MIN`, `WALK_SIDE_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`, `MODES` (`warn`, `refuse`), `NECK_RANGE` (0.10, 0.55), `HEAD_REACH` (0.3), `MASS_SHARE` (0.01, the same value as `frames.SPECK_MIN_FRACTION`), `HEAD_CORE` (0.5), `GUARD` (2.5), `TOL` (2.0) and `STEP` (0.25). Functions `local_cycle.detect`, `local_cycle.by_steps` and `local_cycle.counted` take a new keyword argument `turn` (a `Turn`, default None: as before). Function `loop.run_loop` takes `body_turn` (default `"warn"`).
- Output changes: a new named bound of the reading, `HEAD_REACH` = 0.3, re-reads the head's centre on the pixels within 0.3 of the body's height of it. The full test suite caught why it is needed: its side walker with a 60 px tail on a 45-frame beat (`tests/video/test_walk_steps.py`, the half-step case) read a turn on every swing (frames 8 to 15 and 53 to 60, least -0.19), because the tail swung up into the head's rows and pulled the head's centre aside. With `HEAD_REACH` it reads no turn (least +0.11) and is cut as before. Where no solid pixel of those rows lies within `HEAD_REACH` of their middle, the top's parts lie apart on either side of the middle (a prop held as high as the head and apart from it, or a body too small for any pixel to lie that near), and the top does not tell which part is the head, so the frame is not read instead of taking the largest part and centring on a prop that can weigh what the head does (on the test suite's 132 px synthetic staff walker, the ornament and the head hold the same number of solid pixels in those rows, 513 each, with no pixel within 39.6 px of the middle) and reading turns the body does not make. Where that frame is the first frame, the clip is not read and the cut search runs once as on any unread clip; cut by `video-loop` under default `--body-turn warn`, that synthetic staff walker is not read and is cut 11/24 (start 11, 24 frames), every byte as 3.3.0 cuts it.
-- Output changes: a new named bound of the reading, `WALK_SIDE_MIN` = 0.045, and report field `walk_side` in `body_turn` keep front and back walks whose still shows a side (from arm swings or pieces beside the head) from reading turns every stride. For each frame after the still, its head and shoulders (top 45 % of body) cropped about its head are compared with the still's head and shoulders and their mirror within `GUARD` (2.5 px); `walk_side` is the median of frame nearness to the still minus nearness to the mirror (v.s - v.m), where a frame that flips under `HELD_MAX` (0.5 %) of the frame before's solid pixels (alpha 128 or more) is not counted, so each drawing counts once and `walk_side` is the median of the walk's drawings, not of the time the clip gives each drawing; a clip in which every frame flips 0.5 % or more of the frame before's solid pixels reads exactly as before. The synthetic walker seen square from behind (the walker's still was taken 6 frames into its stride and the clip is 147 frames), each drawing of the first half of each stride held 3 frames and the second half 1 frame, previously lay 0.075 and read turns over frames 19 to 29, 67 to 77 and 115 to 125 that it does not make, but counting each drawing once it now lies 0.000 and is not read, with the warning line. Through the codec and keying (libx264 and `video-frames`), at most 2 of its 74 held frames came back the same pixels as the frame before, so it previously lay 0.076 to 0.083 and read turns that it does not make, but counted once under `HELD_MAX` it lies 0.002 to 0.013 and is not read. Where the still passes `SIDE_SHOWN_MIN` and `walk_side` lies between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read`, `why` starts "the walk is seen square", and cuts match search alone. Angled walks lie 0.061 or more (the 447 synthetic turn windows 0.090 or more), whereas square walks now all lie at 0.000 (the front walker with a 70 px tail moved from 0.013 to 0.000). When square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side`, giving the still's side and `walk_side` in that parenthesis, naming a front or back walk or a body that turned for much of the walk to face the camera or to its mirror, saying its facing is not read, and ending `check the loop's facing`. Reading `walk_side` costs one more crop per frame.
-- Named limits: a piece apart from the body over a hundredth of body pixels is read as body: on synthetic walkers (3849 solid pixels), a 7 px fleck over frames 30 to 39 (49 px) tops the box, reading a turn. The box bottom is the last solid row: pieces under the feet (3 to 10 px square, 1 to 45 px under, across frames 30 to 39) stop turn reads, or return a verdict of `not-read` from about 25 px under in the still. Neck rows spaced 2 % of height apart shift grid steps on 1 px box changes. A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: of 863, 372, 808 and 148 placements of a piece under a hundredth of the body about the heads and torsos of four walkers that do not turn (in the still alone, in every frame but the still, or over frames 30 to 39), 11, 1, 22 and 0 leave the clip unread, each a piece in the still alone (21 of 34 right or left of the head at 6 or 20 px, 13 beside an arm) laying the still's head and shoulders under 0.08 off their nearest mirror. The piece-in-the-still case is now closed by `WALK_SIDE_MIN`: that square walker's still is read when `SIDE_SHOWN_MIN` is lowered to 0.06 (or `GUARD` set to 2, or `STEP` to 1), but its walk is not (`walk_side` 0.000); only with `WALK_SIDE_MIN` also at 0 does it read turns (frames 15 to 21 and 39 to 43). `GUARD` and `TOL` are pixels of the frame, so a larger body's margin narrows: the plain walker drawn 1.5, 2 and 3 times as large, with the 3 by 12 px column drawn as many times as large beside its head in the still moving the centre 1.8, 2.7 and 4.0 px, the walk reads least +0.78, +0.44 and +0.31 without turning. (a) A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn. (b) A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read. (c) A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006. (d) A frame is counted once only where under `HELD_MAX` of the frame before's solid pixels flip: a part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise over `HELD_MAX` (at crf 28, some of the synthetic walker's held frames, up to 0.9 %), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; over `WALK_SIDE_MIN` it is read and reads turns it does not make. And a drawing that flips under `HELD_MAX` of the previous drawing (a large or slow walker where its stride turns) is taken for that drawing held and is not counted.
-- **Tests**: synthetic tests in new test file `tests/video/test_loop_body_turn.py` verify a 73-frame, 24-frame cycle back-diagonal walker seen from behind (legs side by side swinging half a cycle apart, arms either side swinging opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek toward the facing) whose turn moves its facing over to the still's mirror and back. Tests verify boundary turnovers: a torso reading of exactly 0 is not turned and one just under it is; three turned frames in a row are not a turn and four are; a frame not read ends a run; and `SIDE_SHOWN_MIN` set to the walker's own still side reads the clip and set just above it does not. The walker that turns reads one turn inside the frames it turns over and none elsewhere; the same walker not turning reads none; drawn square from behind it is not read. The same turn drawn on twos reads the same frames as on ones (within a frame), in fewer drawings. On a lead-in where the first 8 frames are filmed from 0.6 of the size (which the search leaves out), the report's `body_turn.reference` is 0, the turn reads over the frames it reads over without the lead-in (under -0.1), and the walk where it does not turn stays over +0.1; read from the first frame after the lead-in, the walk that does not turn is not read, and with `WALK_SIDE_MIN` at 0 it reads a turn every stride. A hooded walker with no neck reads its neck at the top row of the range (0.11) and finds the turn too, and finds none where it does not turn. The walker facing past its mirror 3 frames in a row reads no turn (however deep); 4 frames in a row read one turn of 4 frames. The suite's half-step side walker with a 60 px tail reads no turn at `HEAD_REACH` 0.3 and a turn every swing at 0.35. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.63), 3.3.0 cuts 22/24 (frames 22 to 45) across the turn, while this version refuses the windows that hold it and cuts 41/24 (frames 41 to 64); and turning over frames 14 to 24 and 24 to 34 where 3.3.0 cut 11/24 and 17/24 across the turn, this version cuts 35/24 and 41/24. When a walker turns in every cycle, `warn` keeps the cut the search took before, byte for byte, with the warning line, while `refuse` refuses it with `video-loop: the body turns in the walk` as the first line and hands nothing over. Walkers that do not turn and walkers drawn square are cut byte for byte as the search alone cuts them. The walker that turns (over frames 30 to 40) is cut with the cycle search replaced by one that finds no cycle in any window (as on a clip that holds no repeat), and its feet are not read; `warn` refuses it in the words it was refused in before (`video-loop: no periodic cycle found`), after the warning line naming the turn; `refuse` refuses it with `video-loop: the body turns in the walk`. Passing `--body-turn refuse` without `--anchor motion-auto` is refused. New synthetic tests in `tests/video/test_loop_body_turn.py` verify that the staff walker's still is not read; the staff over frames 20 to 29 and a 2 pixel sliver at frame 40 leave those frames null with their reason, every other frame reading as it reads without them; a pennant apart above the walker leaves the still's torso rows empty and the still unread; the pennant over frames 20 to 29 only leaves those frames' torso crops empty, so they are null, not 0; a head on a pole (one column under the head's centre) gives a crop of no width and the still is not read, and a frame of one solid pixel is null; a clip with no frames is not read; and under the default `warn`, the staff walker and the walker with the pennant in its first frame alone are cut byte for byte as the search alone cuts them, and the report says why they were not read. For `torso-side-v2`, new synthetic tests in `tests/video/test_loop_body_turn.py` verify that the 42 named walkers each read as drawn (a turn inside the frames it turns over, none where it does not, unread where the still cannot be read), the 7 px fleck reading its frames turned as the named limit; the antenna or whisker cut loose with a 3 px fleck at 186 placements reading no turn (marked slow); a piece apart under the feet over frames 30 to 39 (3, 6, 7 and 10 px; 1 to 45 px under) reading no turn; `MASS_SHARE` on both sides (the 6 px fleck and the antenna cut loose read no turn at 0.01, the 7 px fleck reads its frames turned at 0.01, the antenna tops the box and the walk reads three turns at 0.005, the 7 px fleck reads no turn at 0.0125, and the walker's 3849 px put a hundredth between 36 and 49); `HEAD_CORE` on both sides (at 0.5 neither the fleck beside the head in the still nor the ornament moves the still's centre, the fleck's walk reads no turn and the ornament walker reads its turn; at 0.3 the fleck moves the still's centre more than 1 px and less than `TOL` and the walk still reads no turn; at 0.35 the ornament moves it less than `TOL` and the turn still reads). The walker drawn in one grey crops as its own mirror about its head's axis (head and shoulders and torso under 1e-6 off it), and in its own tones its still lies 0.10 to 0.11 off its mirror; with the still's centre read 0.25 to 1 px off either way the walk reads no turn and no frame's side moves 0.07; a 6 by 6 px square or a 3 by 12 px column 6 px right of the head in the still, or the column over frames 30 to 39 of the lead-in walker, reads no turn, and the same walkers turning read their turn inside frames 30 to 40; the hooded, lead-in and plain stills lie between 0.08 and 0.11 off their nearest mirror, and the walker seen square with a 3 by 12 or 2 by 18 px column or a 6 by 6 px square against its head or 6 px from it in the still is not read (its side between 0.05 and 0.07); with `GUARD` 2, `STEP` 1 or `SIDE_SHOWN_MIN` 0.06 the square walker with the 3 by 12 px column has its still read but its walk not ("the walk is seen square"), and with `WALK_SIDE_MIN` at 0 as well it reads turns; `TOL` 0 reads the lead-in walker with the column over frames 30 to 39 turned there; and the side walker with a 60 px tail and its arms reads no turn with every frame's centre read 3 px left, where at `TOL` 1 it reads a turn with them 2.25 px left. The square walker taken 6, 3 or 9 frames into its stride, or 1, 2 or 11 frames with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still, has its still over `SIDE_SHOWN_MIN`, `walk_side` under 0.005, and is not read, while with `WALK_SIDE_MIN` at 0 it reads three turns. The walker seen square from behind whose still shows a side, each drawing of one half of its stride held 2, 3 or 4 frames and each of the other half 1 frame (taken 2, 3, 6, 9 or 11 frames into its stride; alone, or with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still), is not read, with the warning line, and its `walk_side` is the same as drawn on ones (within 0.002 with a piece); with `WALK_SIDE_MIN` at 0 it reads turns. The plain, hooded, turning and hooded turning walkers held the same way have the same `walk_side` as on ones, read their turn over the frames that hold the drawings they turn over (drawings 30 to 40), and read none where they do not turn. The square walker held 3 and 1 frames over the two halves of its stride (taken 6 frames into its stride, alone or with a 6 by 6 px piece beside its head in the still), each held frame with 6 of its edge pixels cleared (under 0.2 % of its solid pixels), has the same `walk_side` as without the noise and is not read (with `HELD_MAX` at 0 it is read, with turns), while the turning walker held the same way with the same noise has the same `walk_side` as without it and reads its turn over the frames that hold drawings 30 to 40. Through libx264 (its default crf 23) and `video-frames`' keying (a slow test, skipped without ffmpeg), the square walker held 3 and 1 lies under 0.02 and is not read, and the turning walker held the same way reads its turn over the frames that hold drawings 30 to 40. `walk_side` lies between 0.08 and 0.11 for the plain, hooded, lead-in, turning, hooded turning, turning-every-cycle and on-twos walkers, between 0.07 and 0.075 for the side walker with a 60 px tail on a 45-frame beat, and under 0.005 for the square walker taken 3, 6 or 9 frames on, and `WALK_SIDE_MIN` is 0.045. The walker turned to its mirror over frames 18 to 53 (36 of 73) is read with its turn over frames 20 to 51 and no warning, over 16 to 55 (40) is not read (`walk_side` under 0.005) and gets the warning (naming the turn to its mirror), as does the walker turned over 15 frames of each 24-frame cycle, and over 14 to 57 (44) is read with its turn over frames 16 to 55, `walk_side` under 0 and no warning. Cut by `video-loop`, the walker turned square at frame 24 and held to the end is not read (`verdict` `not-read`, `walk_side` under 0.01), prints exactly one warning line beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing` that gives the still's side and `walk_side` and names the turn to face the camera or to its mirror, and is cut every byte as the search alone cuts it, while the diagonal walker that does not turn and the walker drawn square print no such line.
+- Output changes: a new named bound of the reading, `WALK_SIDE_MIN` = 0.045, and report field `walk_side` in `body_turn` keep front and back walks whose still shows a side (from arm swings or pieces beside the head) from reading turns every stride. For each frame after the still, its head and shoulders (top 45 % of body) cropped about its head are compared with the still's head and shoulders and their mirror within `GUARD` (2.5 px); `walk_side` is the median of frame nearness to the still minus nearness to the mirror (v.s - v.m), where a frame that flips under `HELD_MAX` (0.5 %) of the drawing last counted's solid pixels (alpha 128 or more) is not counted, so each drawing counts once and `walk_side` is the median of the walk's drawings, not of the time the clip gives each drawing; a clip in which every frame flips 0.5 % or more of the frame before's solid pixels reads exactly as before. The synthetic walker seen square from behind (the walker's still was taken 6 frames into its stride and the clip is 147 frames), each drawing of the first half of each stride held 3 frames and the second half 1 frame, previously lay 0.075 and read turns over frames 19 to 29, 67 to 77 and 115 to 125 that it does not make, but counting each drawing once it now lies 0.000 and is not read, with the warning line. Through the codec and keying (libx264 and `video-frames`), at most 2 of its 74 held frames came back the same pixels as the frame before, so it previously lay 0.076 to 0.083 and read turns that it does not make, but counted once under `HELD_MAX` it lies at most 0.013 and is not read. Held against the drawing last counted, a large or slow body is counted each time it has moved `HELD_MAX` from the drawing last counted; the synthetic walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels: seen square from behind (its still taken 6 frames into its stride) its `walk_side` lies under `WALK_SIDE_MIN` and it is not read; seen at an angle its `walk_side` lies over `WALK_SIDE_MIN` and it is read. Where the still passes `SIDE_SHOWN_MIN` and `walk_side` lies between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read`, `why` starts "the walk is seen square", and cuts match search alone. Angled walks lie 0.061 or more (the 447 synthetic turn windows 0.090 or more), whereas square walks now all lie at 0.000 (the front walker with a 70 px tail moved from 0.013 to 0.000). When square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side`, giving the still's side and `walk_side` in that parenthesis, naming a front or back walk or a body that turned for much of the walk to face the camera or to its mirror, saying its facing is not read, and ending `check the loop's facing`. Reading `walk_side` costs one more crop per frame.
+- Named limits: a piece apart from the body over a hundredth of body pixels is read as body: on synthetic walkers (3849 solid pixels), a 7 px fleck over frames 30 to 39 (49 px) tops the box, reading a turn. The box bottom is the last solid row: pieces under the feet (3 to 10 px square, 1 to 45 px under, across frames 30 to 39) stop turn reads, or return a verdict of `not-read` from about 25 px under in the still. Neck rows spaced 2 % of height apart shift grid steps on 1 px box changes. A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: of 863, 372, 808 and 148 placements of a piece under a hundredth of the body about the heads and torsos of four walkers that do not turn (in the still alone, in every frame but the still, or over frames 30 to 39), 11, 1, 22 and 0 leave the clip unread, each a piece in the still alone (21 of 34 right or left of the head at 6 or 20 px, 13 beside an arm) laying the still's head and shoulders under 0.08 off their nearest mirror. The piece-in-the-still case is now closed by `WALK_SIDE_MIN`: that square walker's still is read when `SIDE_SHOWN_MIN` is lowered to 0.06 (or `GUARD` set to 2, or `STEP` to 1), but its walk is not (`walk_side` 0.000); only with `WALK_SIDE_MIN` also at 0 does it read turns (frames 15 to 21 and 39 to 43). `GUARD` and `TOL` are pixels of the frame, so a larger body's margin narrows: the plain walker drawn 1.5, 2 and 3 times as large, with the 3 by 12 px column drawn as many times as large beside its head in the still moving the centre 1.8, 2.7 and 4.0 px, the walk reads least +0.78, +0.44 and +0.31 without turning. (a) A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn. (b) A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read. (c) A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006. (d) A frame is counted once only where under `HELD_MAX` of the drawing last counted's solid pixels flip: a part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise over `HELD_MAX` (at crf 28, some of the synthetic walker's held frames), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; over `WALK_SIDE_MIN` it is read and reads turns it does not make. And a drawing that flips under `HELD_MAX` of the drawing last counted (a large or slow walker where its stride turns) is taken for that drawing held and is not counted.
+- **Tests**: synthetic tests in new test file `tests/video/test_loop_body_turn.py` verify a 73-frame, 24-frame cycle back-diagonal walker seen from behind (legs side by side swinging half a cycle apart, arms either side swinging opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek toward the facing) whose turn moves its facing over to the still's mirror and back. Tests verify boundary turnovers: a torso reading of exactly 0 is not turned and one just under it is; three turned frames in a row are not a turn and four are; a frame not read ends a run; and `SIDE_SHOWN_MIN` set to the walker's own still side reads the clip and set just above it does not. The walker that turns reads one turn inside the frames it turns over and none elsewhere; the same walker not turning reads none; drawn square from behind it is not read. The same turn drawn on twos reads the same frames as on ones (within a frame), in fewer drawings. On a lead-in where the first 8 frames are filmed from 0.6 of the size (which the search leaves out), the report's `body_turn.reference` is 0, the turn reads over the frames it reads over without the lead-in (under -0.1), and the walk where it does not turn stays over +0.1; read from the first frame after the lead-in, the walk that does not turn is not read, and with `WALK_SIDE_MIN` at 0 it reads a turn every stride. A hooded walker with no neck reads its neck at the top row of the range (0.11) and finds the turn too, and finds none where it does not turn. The walker facing past its mirror 3 frames in a row reads no turn (however deep); 4 frames in a row read one turn of 4 frames. The suite's half-step side walker with a 60 px tail reads no turn at `HEAD_REACH` 0.3 and a turn every swing at 0.35. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.63), 3.3.0 cuts 22/24 (frames 22 to 45) across the turn, while this version refuses the windows that hold it and cuts 41/24 (frames 41 to 64); and turning over frames 14 to 24 and 24 to 34 where 3.3.0 cut 11/24 and 17/24 across the turn, this version cuts 35/24 and 41/24. When a walker turns in every cycle, `warn` keeps the cut the search took before, byte for byte, with the warning line, while `refuse` refuses it with `video-loop: the body turns in the walk` as the first line and hands nothing over. Walkers that do not turn and walkers drawn square are cut byte for byte as the search alone cuts them. The walker that turns (over frames 30 to 40) is cut with the cycle search replaced by one that finds no cycle in any window (as on a clip that holds no repeat), and its feet are not read; `warn` refuses it in the words it was refused in before (`video-loop: no periodic cycle found`), after the warning line naming the turn; `refuse` refuses it with `video-loop: the body turns in the walk`. Passing `--body-turn refuse` without `--anchor motion-auto` is refused. New synthetic tests in `tests/video/test_loop_body_turn.py` verify that the staff walker's still is not read; the staff over frames 20 to 29 and a 2 pixel sliver at frame 40 leave those frames null with their reason, every other frame reading as it reads without them; a pennant apart above the walker leaves the still's torso rows empty and the still unread; the pennant over frames 20 to 29 only leaves those frames' torso crops empty, so they are null, not 0; a head on a pole (one column under the head's centre) gives a crop of no width and the still is not read, and a frame of one solid pixel is null; a clip with no frames is not read; and under the default `warn`, the staff walker and the walker with the pennant in its first frame alone are cut byte for byte as the search alone cuts them, and the report says why they were not read. For `torso-side-v2`, new synthetic tests in `tests/video/test_loop_body_turn.py` verify that the 42 named walkers each read as drawn (a turn inside the frames it turns over, none where it does not, unread where the still cannot be read), the 7 px fleck reading its frames turned as the named limit; the antenna or whisker cut loose with a 3 px fleck at 186 placements reading no turn (marked slow); a piece apart under the feet over frames 30 to 39 (3, 6, 7 and 10 px; 1 to 45 px under) reading no turn; `MASS_SHARE` on both sides (the 6 px fleck and the antenna cut loose read no turn at 0.01, the 7 px fleck reads its frames turned at 0.01, the antenna tops the box and the walk reads three turns at 0.005, the 7 px fleck reads no turn at 0.0125, and the walker's 3849 px put a hundredth between 36 and 49); `HEAD_CORE` on both sides (at 0.5 neither the fleck beside the head in the still nor the ornament moves the still's centre, the fleck's walk reads no turn and the ornament walker reads its turn; at 0.3 the fleck moves the still's centre more than 1 px and less than `TOL` and the walk still reads no turn; at 0.35 the ornament moves it less than `TOL` and the turn still reads). The walker drawn in one grey crops as its own mirror about its head's axis (head and shoulders and torso under 1e-6 off it), and in its own tones its still lies 0.10 to 0.11 off its mirror; with the still's centre read 0.25 to 1 px off either way the walk reads no turn and no frame's side moves 0.07; a 6 by 6 px square or a 3 by 12 px column 6 px right of the head in the still, or the column over frames 30 to 39 of the lead-in walker, reads no turn, and the same walkers turning read their turn inside frames 30 to 40; the hooded, lead-in and plain stills lie between 0.08 and 0.11 off their nearest mirror, and the walker seen square with a 3 by 12 or 2 by 18 px column or a 6 by 6 px square against its head or 6 px from it in the still is not read (its side between 0.05 and 0.07); with `GUARD` 2, `STEP` 1 or `SIDE_SHOWN_MIN` 0.06 the square walker with the 3 by 12 px column has its still read but its walk not ("the walk is seen square"), and with `WALK_SIDE_MIN` at 0 as well it reads turns; `TOL` 0 reads the lead-in walker with the column over frames 30 to 39 turned there; and the side walker with a 60 px tail and its arms reads no turn with every frame's centre read 3 px left, where at `TOL` 1 it reads a turn with them 2.25 px left. The square walker taken 6, 3 or 9 frames into its stride, or 1, 2 or 11 frames with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still, has its still over `SIDE_SHOWN_MIN`, `walk_side` under 0.005, and is not read, while with `WALK_SIDE_MIN` at 0 it reads three turns. The walker seen square from behind whose still shows a side, each drawing of one half of its stride held 2, 3 or 4 frames and each of the other half 1 frame (taken 2, 3, 6, 9 or 11 frames into its stride; alone, or with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still), is not read, with the warning line, and its `walk_side` is the same as drawn on ones (within 0.002 with a piece); with `WALK_SIDE_MIN` at 0 it reads turns. The plain, hooded, turning and hooded turning walkers held the same way have the same `walk_side` as on ones, read their turn over the frames that hold the drawings they turn over (drawings 30 to 40), and read none where they do not turn. The square walker held 3 and 1 frames over the two halves of its stride (taken 6 frames into its stride, alone or with a 6 by 6 px piece beside its head in the still), each held frame with 6 of its edge pixels cleared (under 0.2 % of its solid pixels), has the same `walk_side` as without the noise and is not read (with `HELD_MAX` at 0 it is read, with turns), while the turning walker held the same way with the same noise has the same `walk_side` as without it and reads its turn over the frames that hold drawings 30 to 40. Through libx264 (its default crf 23) and `video-frames`' keying (a slow test, skipped without ffmpeg), the square walker held 3 and 1 lies under 0.02 and is not read, and the turning walker held the same way reads its turn over the frames that hold drawings 30 to 40. The walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels, seen square from behind (taken 6 frames into its stride) is not read (`walk_side` under `WALK_SIDE_MIN`), and seen at an angle is read (`walk_side` over `WALK_SIDE_MIN`). `walk_side` lies between 0.08 and 0.11 for the plain, hooded, lead-in, turning, hooded turning, turning-every-cycle and on-twos walkers, between 0.07 and 0.075 for the side walker with a 60 px tail on a 45-frame beat, and under 0.005 for the square walker taken 3, 6 or 9 frames on, and `WALK_SIDE_MIN` is 0.045. The walker turned to its mirror over frames 18 to 53 (36 of 73) is read with its turn over frames 20 to 51 and no warning, over 16 to 55 (40) is not read (`walk_side` under 0.005) and gets the warning (naming the turn to its mirror), as does the walker turned over 15 frames of each 24-frame cycle, and over 14 to 57 (44) is read with its turn over frames 16 to 55, `walk_side` under 0 and no warning. Cut by `video-loop`, the walker turned square at frame 24 and held to the end is not read (`verdict` `not-read`, `walk_side` under 0.01), prints exactly one warning line beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing` that gives the still's side and `walk_side` and names the turn to face the camera or to its mirror, and is cut every byte as the search alone cuts it, while the diagonal walker that does not turn and the walker drawn square print no such line.
## v3.3.0 - PyTorch RIFE backend for CUDA and CPU, executor for a GPU on another machine, and Linux CPU and cloud T4 release lanes
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 0ea1edb..d4d1e7e 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -381,7 +381,7 @@ The reading (`torso-side-v2` in `sprite_gen/video/body_turn.py`) reads each fram
Each crop's axis is the middle of the head's centre column (the column c spans c to c + 1). The crop's edges lie where they fall, between pixels too: the crop is resampled from the frame about them, and mirrored about the axis. A body that is its own mirror about its head crops as its own mirror wherever its centre falls: the walker drawn all in one grey (its silhouette alone, its own mirror about the middle of column 150) reads its head and shoulders and its torso 0.000000 off their mirror. `torso-side-v1` rounded each edge of the box to a whole pixel and mirrored the crop about the box's middle, the column's edge, half a pixel off the axis: in one grey, the head and shoulders lay 0.050 off their mirror and the torso 0.028, a side the silhouette does not show. In its own tones the still reads 0.102 off its mirror (`torso-side-v1`: 0.146). The still and every frame are also read about the axes either side of the head's axis because a piece beside the head whose columns each hold over half the fullest column's pixels moves the head's centre: a column 3 px wide and 12 px tall, 6 px right of the head and 2 rows under its top (36 px, under a hundredth of the walker; each of its columns holds 12 of the head band's 19 rows), moves it 1.4 px. Read about the centre alone, `torso-side-v1` read the walk with that column in the still turned over frames 1 to 72 (least -0.14), and with the column over frames 30 to 39 of the lead-in walker turned there (least -0.18). `torso-side-v2` reads both with no turn (least +0.64 and +0.83), and the same walkers turning over frames 30 to 40 read their turn over frames 32 to 38. A 6 px square in the same place in the still holds 6 rows of each column, under `HEAD_CORE`, and moves no centre; `torso-side-v1`, which read the head's centre as the plain mass centre, read the walk with it turned over frames 1 to 72 (least -0.14). With the still's centre read 0.25 to 1 px off either way, the walk reads no turn and no frame's side moves 0.07 (at most 0.062, at 0.5 px); `torso-side-v1` read the walk turned every stride from 0.75 px right (least -0.06). Besides the crop about the head's axis, each crop is cut about the axes `STEP` (0.25 px) apart either side of it, each as wide as the crop about the axis. `GUARD` = 2.5 px: the still's head and shoulders, cropped about the axis, are read against their mirrors about every axis within 2.5 px of it; their side (`still_side`, the side `SIDE_SHOWN_MIN` bounds) is 1 minus the largest of those correlations, how far they lie off their nearest mirror. `TOL` = 2 px: the still's torso is cropped about every axis within 2 px of its head's axis, and mirrored about each. Each frame's torso, cropped about its own head's axis, is read against the still's torso and against its mirror at their nearest: in `side` = (v.s - v.m) / (1 - s.m), v.s is the largest of its correlations with those crops and v.m the largest with those mirrors, and s.m is the largest of the still's torso crop about its own axis with those mirrors (1 - s.m is the report's `torso_still_side`). At `GUARD` from 0 to 2.0, the walker seen square from behind with the 3 by 12 px column 6 px right of its head in the still alone lies 0.093 (at 2.0) to 0.256 (at 0) off its nearest mirror, over `SIDE_SHOWN_MIN`, so the still is read, but its walk lies 0.000 at the median (`walk_side`), under `WALK_SIDE_MIN`, so the clip is not read; with `WALK_SIDE_MIN` set to 0 as well, it reads turns it does not make (frames 15 to 21 and 39 to 43) at every one of those values; at 2.25 the still lies 0.075 off its nearest mirror and is not read. At 2.5 it lies 0.060 off it, at 3 and 4 0.053, and is not read. At `STEP` 1 px the same still lies 0.093 off its nearest mirror and is read, but its walk lies 0.000 and the clip is not read; with `WALK_SIDE_MIN` at 0 as well it reads turns (frames 3 to 9, 27 to 32 and 51 to 57); at 0.75 the still lies 0.075 off it and is not read; at 0.5 and under it is not read either. At `TOL` 0, the lead-in walker with a 3 by 12 or a 2 by 18 px column beside its head over frames 30 to 39 reads a turn over frames 30 to 39 (least -0.26 with the 3 by 12 px column, -0.25 with the 2 by 18); from 0.5 to 4 it reads none. Margins at `TOL` 2: with every frame's head centre but the still's read the same distance off, the lead-in walker first reads a turn 3.75 px right (frames 1 to 4), and the side walker with a 60 px tail and its arms 3.25 px left; at `TOL` 1, at 2.5 and 2.25 px. With the still's centre alone read off, no synthetic walker reads a turn within 4 px either way.
-Each frame's `side` = (v.s - v.m) / (1 - s.m), where v is the frame's crop, s the first frame's and m the first frame's mirrored about the head's centre (each a unit vector of luma times alpha and alpha); v.s and v.m are each taken at their largest over the first frame's torso crops and mirrors about the axes within `TOL` of its head's axis, and s.m at the largest of the first frame's own crop with those mirrors. A value of 1 means the torso shows the side the still shows; 0 means it is as near the still as its mirror (a body seen square from behind or in front); under 0 means it faces nearer the still's mirror. A pose the walk changes moves both correlations alike; a turn moves them apart. Each clip is read only against its own first frame, never against a named motion or direction. Four named module constants define the report field `bounds`, bounding whether the clip is read and what counts as a turn. `SIDE_SHOWN_MIN` = 0.08 sets how far the still's head and shoulders (the top 45 % of its body) lie off their nearest mirror about the axes within `GUARD` for the clip to be read at all. Under it the still is seen square (a front or back walk) and the facing is not read, because a back walk's far step lays its torso nearer its mirror each step. About their nearest mirror, the synthetic walkers seen at an angle lie 0.090 or more off it (the hooded walker 0.090, the lead-in walker 0.098, the plain walker 0.102, the side walker with a 60 px tail 0.397); the walker seen square from behind lies 0.0002 off it, and with a 36 px piece beside its head in the still alone (a 3 by 12 or 2 by 18 px column, or a 6 by 6 px square, against the head or 6 px from it, on either side) 0.049 to 0.060. At 0.06, the still of the square walker with the 3 by 12 px column 6 px right of its head is read, but its walk is not; at 0.095 the hooded walker is not read. The report field `walk_side` in `body_turn` and bound `WALK_SIDE_MIN` (0.045) gate front or back walks whose still alone shows a side. For each frame after the still, its head and shoulders (the top 45 % of the body, cropped about its head as wide as the still's crop) are compared with the still and its mirror within `GUARD` (2.5 px) of the still's head centre, giving nearness to the still minus nearness to the mirror (v.s - v.m); `walk_side` is the median across the read frames after the still of each frame's v.s - v.m, not counting any frame that flips under `HELD_MAX` (0.5 %) of the frame before's solid pixels so each drawing counts once. Each frame of a square walk lies as near the still's mirror as its frame half a stride on lies near the still, so the median of every frame leans toward a half of the stride that the clip holds longer than the other: for the synthetic walker seen square from behind, its still taken 6 frames into its stride (the still 0.148 off its nearest mirror), each drawing of the first half of each stride held 3 frames and each drawing of the second half 1 frame (147 frames), the median of every frame lay 0.075 (0.074 with a 36 px piece beside its head in the still), over `WALK_SIDE_MIN`, and the clip was read, with turns over frames 19 to 29, 67 to 77 and 115 to 125 that it does not make, and no warning line, whereas counting each drawing once, its walk lies 0.000, as drawn on ones, and it is not read, with the warning line. A clip comes to the reading through a codec and the keying, which leave hardly a held frame as it was: when the same walker (still taken 6 frames into its stride, each drawing of the first half of each stride held 3 frames and each of the second half 1 frame, 147 frames) was put through libx264 at crf 0, 18, 23 and 28 and through `video-frames`' keying, at most 2 of its 74 held frames came back the same pixels as the frame before, and the rest with up to 0.9 % of their solid pixels flipped (under 0.5 % in 99 of 100 at crf 23, libx264's default). Counted again wherever not the same pixels, its walk lay 0.076 to 0.083 and it read turns that it does not make, whereas counted once under `HELD_MAX` it lies 0.002 to 0.013 and is not read. A drawing of the synthetic walkers flips 1.9 % or more of the previous drawing's solid pixels, except the front walker with a 70 px tail (0.44 % at one drawing, none at another), which reads square either way; its `walk_side` moved from 0.013 to 0.000, so the synthetic square walks now all lie at 0.000. Where the still passes `SIDE_SHOWN_MIN` and `walk_side` falls between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read` (`why` starting "the walk is seen square"), and the loop is cut as search alone cuts it. Under `--body-turn warn` and `refuse`, `video-loop` prints one warning line beginning "video-loop: warning: the walk reads square against a still that shows a side (still_side", giving the still's side and `walk_side`, naming what it can be (a front or back walk, or a body that turned for much of the walk, to face the camera or to its mirror), stating its facing is not read, and ending "check the loop's facing"; `body_turn.square(reading)` returns this text or None. `TURN_SIDE_MAX` = 0 marks any frame reading under 0 as turned. `TURN_RUN_MIN` = 4 requires 4 turned frames in a row or more to count as a turn. Turns are counted in frames, the time the clip plays them, not in drawings: a walk held on twos holds a turn as long as one drawn on ones, in half the drawings. A shorter dip is the walk's own. A synthetic walker facing past its mirror 3 frames in a row reads no turn even 0.61 under 0; 4 frames in a row read one. A clip with no turn (or one not read) is searched once, exactly as before: the same cut, the same bytes.
+Each frame's `side` = (v.s - v.m) / (1 - s.m), where v is the frame's crop, s the first frame's and m the first frame's mirrored about the head's centre (each a unit vector of luma times alpha and alpha); v.s and v.m are each taken at their largest over the first frame's torso crops and mirrors about the axes within `TOL` of its head's axis, and s.m at the largest of the first frame's own crop with those mirrors. A value of 1 means the torso shows the side the still shows; 0 means it is as near the still as its mirror (a body seen square from behind or in front); under 0 means it faces nearer the still's mirror. A pose the walk changes moves both correlations alike; a turn moves them apart. Each clip is read only against its own first frame, never against a named motion or direction. Four named module constants define the report field `bounds`, bounding whether the clip is read and what counts as a turn. `SIDE_SHOWN_MIN` = 0.08 sets how far the still's head and shoulders (the top 45 % of its body) lie off their nearest mirror about the axes within `GUARD` for the clip to be read at all. Under it the still is seen square (a front or back walk) and the facing is not read, because a back walk's far step lays its torso nearer its mirror each step. About their nearest mirror, the synthetic walkers seen at an angle lie 0.090 or more off it (the hooded walker 0.090, the lead-in walker 0.098, the plain walker 0.102, the side walker with a 60 px tail 0.397); the walker seen square from behind lies 0.0002 off it, and with a 36 px piece beside its head in the still alone (a 3 by 12 or 2 by 18 px column, or a 6 by 6 px square, against the head or 6 px from it, on either side) 0.049 to 0.060. At 0.06, the still of the square walker with the 3 by 12 px column 6 px right of its head is read, but its walk is not; at 0.095 the hooded walker is not read. The report field `walk_side` in `body_turn` and bound `WALK_SIDE_MIN` (0.045) gate front or back walks whose still alone shows a side. For each frame after the still, its head and shoulders (the top 45 % of the body, cropped about its head as wide as the still's crop) are compared with the still and its mirror within `GUARD` (2.5 px) of the still's head centre, giving nearness to the still minus nearness to the mirror (v.s - v.m); `walk_side` is the median across the read frames after the still of each frame's v.s - v.m, not counting any frame that flips under `HELD_MAX` (0.5 %) of the drawing last counted's solid pixels so each drawing counts once. Each frame of a square walk lies as near the still's mirror as its frame half a stride on lies near the still, so the median of every frame leans toward a half of the stride that the clip holds longer than the other: for the synthetic walker seen square from behind, its still taken 6 frames into its stride (the still 0.148 off its nearest mirror), each drawing of the first half of each stride held 3 frames and each drawing of the second half 1 frame (147 frames), the median of every frame lay 0.075 (0.074 with a 36 px piece beside its head in the still), over `WALK_SIDE_MIN`, and the clip was read, with turns over frames 19 to 29, 67 to 77 and 115 to 125 that it does not make, and no warning line, whereas counting each drawing once, its walk lies 0.000, as drawn on ones, and it is not read, with the warning line. A clip comes to the reading through a codec and the keying, which leave hardly a held frame as it was: when the same walker (still taken 6 frames into its stride, each drawing of the first half of each stride held 3 frames and each of the second half 1 frame, 147 frames) was put through libx264 at crf 0, 18, 23 and 28 and through `video-frames`' keying, at most 2 of its 74 held frames came back the same pixels as the frame before, and the rest with up to 0.9 % of their solid pixels flipped (under 0.5 % in 99 of 100 at crf 23, libx264's default). Counted again wherever not the same pixels, its walk lay 0.076 to 0.083 and it read turns that it does not make, whereas counted once under `HELD_MAX` it lies at most 0.013 and is not read. Held against the drawing last counted, a large or slow body is counted each time it has moved `HELD_MAX` from the drawing last counted. The synthetic walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels: seen square from behind (its still taken 6 frames into its stride) its `walk_side` lies under `WALK_SIDE_MIN` and it is not read; seen at an angle its `walk_side` lies over `WALK_SIDE_MIN` and it is read. A drawing of the synthetic walkers flips 1.9 % or more of the previous drawing's solid pixels, except the front walker with a 70 px tail (0.44 % at one drawing, none at another), which reads square either way; its `walk_side` moved from 0.013 to 0.000, so the synthetic square walks now all lie at 0.000. Where the still passes `SIDE_SHOWN_MIN` and `walk_side` falls between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read` (`why` starting "the walk is seen square"), and the loop is cut as search alone cuts it. Under `--body-turn warn` and `refuse`, `video-loop` prints one warning line beginning "video-loop: warning: the walk reads square against a still that shows a side (still_side", giving the still's side and `walk_side`, naming what it can be (a front or back walk, or a body that turned for much of the walk, to face the camera or to its mirror), stating its facing is not read, and ending "check the loop's facing"; `body_turn.square(reading)` returns this text or None. `TURN_SIDE_MAX` = 0 marks any frame reading under 0 as turned. `TURN_RUN_MIN` = 4 requires 4 turned frames in a row or more to count as a turn. Turns are counted in frames, the time the clip plays them, not in drawings: a walk held on twos holds a turn as long as one drawn on ones, in half the drawings. A shorter dip is the walk's own. A synthetic walker facing past its mirror 3 frames in a row reads no turn even 0.61 under 0; 4 frames in a row read one. A clip with no turn (or one not read) is searched once, exactly as before: the same cut, the same bytes.
Where no window without the turn holds a cycle, the flag `--body-turn` decides the outcome. Under `warn` (the default), the search runs again as before, and the cut it took before is kept with a warning line naming the turned frames, the least reading and its frame, the bound, the cut and the frames of the turn it holds. Where no cut holds a cycle at all, the clip is refused in the words it was refused in before (`video-loop: no periodic cycle found`), after a warning line naming the turn. An app that matches the old refusal lines keeps matching them. Under `refuse` (which needs `--anchor motion-auto`), the clip is refused in a line of its own, the first line the run prints: `video-loop: the body turns in the walk`. That line names the turned frames, the least reading and its frame, the bound, that no cut that leaves those frames out holds two steps that repeat (or, where a cut was found that holds the turn, which cut and which frames), and the prescription to film it again with the torso and hips kept at the still's angle. Nothing is handed over; the report is written with `status: failed`. App builders can attach a retake rule, such as `loop-body-turned`, to this refusal line. Every report on a walk or run under `--anchor motion-auto` includes the `body_turn` field: `reading` (`torso-side-v2`), `bounds` (the four), `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` is one of `none` (read, no turn), `not-read` (a square still, a walk that reads square against a still that shows a side, 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`). The command's JSON summary gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.
@@ -390,7 +390,7 @@ What it does not see:
- A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn.
- A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read.
- A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006.
-- A frame is counted once only where under `HELD_MAX` of the frame before's solid pixels flip. A part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise over `HELD_MAX` (at crf 28, some of the synthetic walker's held frames, up to 0.9 %), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; over `WALK_SIDE_MIN` it is read and reads turns it does not make. And a drawing that flips under `HELD_MAX` of the previous drawing (a large or slow walker where its stride turns) is taken for that drawing held and is not counted.
+- A frame is counted once only where under `HELD_MAX` of the drawing last counted's solid pixels flip. A part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise over `HELD_MAX` (at crf 28, some of the synthetic walker's held frames), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; over `WALK_SIDE_MIN` it is read and reads turns it does not make. And a drawing that flips under `HELD_MAX` of the drawing last counted (a large or slow walker where its stride turns) is taken for that drawing held and is not counted.
- A shallow turn: a three-quarter walk that turns to the side each stride reads shallow, and a dip under 4 frames, or one that does not go under 0, is the walk's own.
- It does not make a walk where there is none: where the frames before the turn do not repeat either, avoiding the turn finds no cycle; the reading changes the reason given, not the result.
- A body whose narrowest row in 10 % to 55 % of its height is its waist (no neck and a head narrower than its waist) has its crop start at the waist; no such body has been measured.
diff --git a/sprite_gen/video/body_turn.py b/sprite_gen/video/body_turn.py
index c843879..31d559d 100644
--- a/sprite_gen/video/body_turn.py
+++ b/sprite_gen/video/body_turn.py
@@ -33,26 +33,30 @@ Four named bounds:
stride on, and read against the still it reads a turn every stride (the synthetic walker seen square from behind,
taken 6 frames into its stride, its still 0.148 off its mirror: turns over frames 7-17, 31-41 and 55-65; its walk
0.000 at the median). The median is of the walk's drawings, not of the time the clip gives each: a frame that holds
- the frame before it (the still the frame before the first) is not counted again. Each frame of a square walk lies as
- near the still's mirror as its frame half a stride on lies near the still, and a clip that holds one half of the
- stride longer than the other lay toward the half held longer at the median of its frames: the same walker, each
- drawing of the first half of each stride held 3 frames and each of the second 1 (147 frames), 0.075, and it read
- turns over frames 19-29, 67-77 and 115-125; each drawing counted once, 0.000, as on ones. A held frame is the frame
- before with under HELD_MAX (0.5 %) of its solid pixels flipped, not the same pixels: the codec and the key leave
- hardly a held frame of a clip as it was. Through libx264 at crf 0 to 28 and `video-frames`' key, at most 2 of that
- clip's 74 held frames came back the frame before's pixels, and the rest with up to 0.9 % of their solid pixels
+ the drawing last counted (the still the first) is not counted again. Each frame of a square walk lies as near the
+ still's mirror as its frame half a stride on lies near the still, and a clip that holds one half of the stride longer
+ than the other lay toward the half held longer at the median of its frames: the same walker, each drawing of the first
+ half of each stride held 3 frames and each of the second 1 (147 frames), 0.075, and it read turns over frames 19-29,
+ 67-77 and 115-125; each drawing counted once, 0.000, as on ones. A frame holds the drawing last counted where under
+ HELD_MAX (0.5 %) of that drawing's solid pixels flip in it, not only where it is the same pixels: the codec and the
+ key leave hardly a held frame of a clip as it was. Through libx264 at crf 0 to 28 and `video-frames`' key, at most 2
+ of that clip's 74 held frames came back the frame before's pixels, and the rest with up to 0.9 % of their solid pixels
flipped (under 0.5 % in 99 of 100 at crf 23, the default): counted again wherever not the same pixels, the walk lay
- 0.076 to 0.083 off and read the turns; counted once under HELD_MAX, 0.002 to 0.013. A drawing of the synthetic
- walkers flips 1.9 % of the one before's solid pixels at least, but the front walker of tests/video/test_walk_steps.py
- with a 70 px tail: 0.44 % at one drawing and none at another, square either way. A walk seen at an angle lies nearer
- the still's side (the plain walker 0.101, the hooded one 0.090); one turned past the still's mirror over most of its
- frames lies nearer the mirror's, under 0, and is read with its turn. 0.045 lies between the synthetic walkers seen at
- an angle, 0.061 at least (the side walker of tests/video/test_walk_steps.py with a 60 px tail on a beat of its own),
- and those seen square: 0.000 with a piece beside the head or the arms swung apart in the still, or the front walker
- of tests/video/test_walk_steps.py with a 70 px tail. The frames alone do not tell a front or back walk whose still
- shows a side from a body that turned for much of its walk, to face the camera or to its mirror (its frames square at
- the median, its still at an angle; the named limits below): each is left unread, and `video-loop` says so in a
- warning line (`square`), the cut as the search alone cuts it.
+ 0.076 to 0.083 off and read the turns; counted once under HELD_MAX, 0.013 at most, and not read. Against the drawing
+ last counted, not the frame before: a walk whose every frame flips under HELD_MAX of the one before (a large or slow
+ body; the synthetic square walker stepped from each drawing to the next over such frames) is counted each time it has
+ moved HELD_MAX from the drawing last counted, and its walk lies under WALK_SIDE_MIN, as its drawings' does; held
+ against the frame before, no frame of it was counted, and it was read with no walk's side to hold it. A drawing of the
+ synthetic walkers flips 1.9 % of the one before's solid pixels at least, but the front walker of
+ tests/video/test_walk_steps.py with a 70 px tail: 0.44 % at one drawing and none at another, square either way. A walk
+ seen at an angle lies nearer the still's side (the plain walker 0.101, the hooded one 0.090); one turned past the
+ still's mirror over most of its frames lies nearer the mirror's, under 0, and is read with its turn. 0.045 lies
+ between the synthetic walkers seen at an angle, 0.061 at least (the side walker of tests/video/test_walk_steps.py with
+ a 60 px tail on a beat of its own), and those seen square: 0.000 with a piece beside the head or the arms swung apart
+ in the still, or the front walker of tests/video/test_walk_steps.py with a 70 px tail. The frames alone do not tell a
+ front or back walk whose still shows a side from a body that turned for much of its walk, to face the camera or to its
+ mirror (its frames square at the median, its still at an angle; the named limits below): each is left unread, and
+ `video-loop` says so in a warning line (`square`), the cut as the search alone cuts it.
- TURN_SIDE_MAX: a frame whose torso reads under it is turned.
- TURN_RUN_MIN: a turn is that many turned frames in a row or more, counted in frames — the time the clip plays them —
not in drawings: a walk held on twos holds a turn as long as one drawn on ones does, in half the drawings. A shorter
@@ -126,15 +130,15 @@ middle (38 to 41 hooded), or over 14 to 16 frames of each 24-frame cycle; over 3
it is read and its turn with it. One turned to square — a back-diagonal walk turned to a full back view — and held there
over 41 of its 73 frames or more (40 hooded) is a square walk by its frames, and is not read either. Each of the three
is left unread with the warning line (`square`), not in silence. A frame is counted once only where it flips under
-HELD_MAX of the frame before's solid pixels: a part of the stride a clip plays slower in drawings of its own, or a held
-frame under noise over HELD_MAX (at crf 28, some of the synthetic walker's, up to 0.9 %), counts frame by frame, and a
-square walk so played lies off the still's mirror at the median toward that part, and over WALK_SIDE_MIN it is read,
-and reads turns it does not make; a drawing that flips under HELD_MAX of the one before (a large or slow walker where
-its stride turns) is taken for that one held, and not counted. GUARD and TOL are pixels of the frame, not shares of
-the body: a piece beside the head that moves the centre further than TOL is read about axes that do not reach the
-head's, and a larger body's margin is narrower (the plain walker drawn three times as large, the column beside its head
-in the still three times as large, under a hundredth: the centre moves 4.0 px, and the walk reads no turn, least +0.31
-against +0.94 without the column)."""
+HELD_MAX of the drawing last counted's solid pixels: a part of the stride a clip plays slower in drawings of its own, or
+a held frame under noise over HELD_MAX (at crf 28, some of the synthetic walker's), counts frame by frame, and a square
+walk so played lies off the still's mirror at the median toward that part, and over WALK_SIDE_MIN it is read, and reads
+turns it does not make; a drawing under HELD_MAX of the drawing last counted (a large or slow walker where its stride
+turns) is taken for it held, and not counted. GUARD and TOL are pixels of the frame, not shares of the body: a piece
+beside the head that moves the centre further than TOL is read about axes that do not reach the head's, and a larger
+body's margin is narrower (the plain walker drawn three times as large, the column beside its head in the still three
+times as large, under a hundredth: the centre moves 4.0 px, and the walk reads no turn, least +0.31 against +0.94
+without the column)."""
from __future__ import annotations
import math
@@ -152,7 +156,7 @@ TURN_SIDE_MAX = 0.0
TURN_RUN_MIN = 4
MODES = ("warn", "refuse") # --body-turn: a cut that holds a turn, where none without it holds a cycle, warned of or refused
SOLID = 128 # an alpha at least this is the body
-HELD_MAX = 0.005 # a frame that flips under this share of the frame before's solid pixels holds it (WALK_SIDE_MIN)
+HELD_MAX = 0.005 # a frame that flips under this share of the drawing last counted's solid pixels holds it (WALK_SIDE_MIN)
# The box's top, and the still's torso width: the row (the columns) with more than this share of the solid pixels over
# (beside) it — frames.py's speck bound, a fleck or a thin part apart from the body under it.
MASS_SHARE = SPECK_MIN_FRACTION
@@ -311,8 +315,8 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
"""The clip's facing against its first frame (`frames`, the clip as keyed, RGBA): the record the loop report keeps
(`body_turn`) — the reading, its bounds, the frame read against (`reference`), the still's own side (`still_side`),
whether it was read (`why` where not), the neck, the walk's side (`walk_side`: the median of the frames after the
- still, a frame the clip holds from the frame before it, under HELD_MAX of its solid pixels flipped, counted once,
- where any is read), each frame's `side` and the `turns`. A frame not read is None in `side`, and `unread` says why,
+ still, a frame that holds the drawing last counted, under HELD_MAX of its solid pixels flipped, not counted, where
+ any is read), each frame's `side` and the `turns`. A frame not read is None in `side`, and `unread` says why,
each why with its frames (where any is)."""
out: dict[str, Any] = {"reading": READING, "bounds": {"SIDE_SHOWN_MIN": SIDE_SHOWN_MIN, "WALK_SIDE_MIN": WALK_SIDE_MIN,
"TURN_SIDE_MAX": TURN_SIDE_MAX, "TURN_RUN_MIN": TURN_RUN_MIN},
@@ -346,12 +350,13 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
side: list[float | None] = []
walk: list[float] = []
unread: dict[str, list[int]] = {}
- before = None # the frame before's solid pixels
+ counted = None # the solid pixels of the drawing last counted (the still the first)
for k, frame in enumerate(frames):
solid = np.asarray(frame.getchannel("A")) >= SOLID
- drawn = (before is None or before.shape != solid.shape
- or float((solid ^ before).sum()) / max(1, int(before.sum())) >= HELD_MAX)
- before = solid
+ drawn = (counted is None or counted.shape != solid.shape
+ or float((solid ^ counted).sum()) / max(1, int(counted.sum())) >= HELD_MAX)
+ if drawn:
+ counted = solid
body = _body(frame)
crop = body if isinstance(body, str) else _crop(frame, body, rows, held)
if isinstance(crop, str):
diff --git a/tests/video/test_loop_body_turn.py b/tests/video/test_loop_body_turn.py
index 784b0f2..668391d 100644
--- a/tests/video/test_loop_body_turn.py
+++ b/tests/video/test_loop_body_turn.py
@@ -210,6 +210,25 @@ def _coded(frames: list[Image.Image], root: Path) -> list[Image.Image]:
return [Image.open(p).convert("RGBA") for p in sorted((root / "keyed").glob("*.png"))]
+def _stepped(frames: list[Image.Image], most: float = 0.004) -> list[Image.Image]:
+ """`frames` with each drawing reached from the one before over frames of its own, each turning the next share of
+ the solid pixels that come and go between the two, under `most` of the fewer solid pixels of the two: a walk whose
+ every frame flips under HELD_MAX of the frame before, as a large or slow body's does."""
+ out = [frames[0]]
+ for a, b in zip(frames, frames[1:]):
+ pa, pb = np.asarray(a), np.asarray(b)
+ sa, sb = pa[..., 3] >= 128, pb[..., 3] >= 128
+ coming, going = np.argwhere(sb & ~sa), np.argwhere(sa & ~sb)
+ n = max(1, math.ceil((len(coming) + len(going)) / (most * min(int(sa.sum()), int(sb.sum())))))
+ f = pa.copy()
+ for c, g in zip(np.array_split(coming, n), np.array_split(going, n)):
+ f[c[:, 0], c[:, 1]] = pb[c[:, 0], c[:, 1]]
+ f[g[:, 0], g[:, 1]] = pb[g[:, 0], g[:, 1]]
+ out.append(Image.fromarray(f.copy()))
+ out[-1] = b
+ return out
+
+
def _cut(out: Path, keyed: Path, *extra: str) -> dict:
assert loop.main(["--frames-dir", str(keyed), "--out-dir", str(out), "--state", "walk", "--anchor", "motion-auto",
"--repair", "off", *extra]) == 0
@@ -759,15 +778,15 @@ def test_a_walk_seen_at_an_angle_held_longer_over_half_its_stride_reads_as_on_on
@pytest.mark.parametrize("piece", [None, (6, 6)], ids=["alone", "6x6-beside"])
-def test_a_held_frame_with_noise_over_it_holds_the_frame_before(monkeypatch, piece):
- """HELD_MAX: a frame holds the frame before it where under 0.5 % of the frame before's solid pixels flip in it, not
- only where it is the same pixels, for a clip comes to the reading through a codec and the key, which leave hardly a
- held frame as it was. The square walker taken half a stride on, each drawing of the first half of its stride held 3
- frames and each of the second 1, alone or with a 36 px piece beside its head in the still, each held frame with 6 of
- its edge pixels cleared (under 0.2 % of its solid pixels, two such frames in a row under 0.4 % apart): each drawing
- counted once, its walk lies where it lies held without the noise, as on ones, and it is not read. Counted wherever
- not the same pixels (HELD_MAX at 0: every frame, as the clip plays it), the walk lies 0.075 off and the clip is
- read, with the turns it does not make."""
+def test_a_held_frame_with_noise_over_it_holds_the_drawing_last_counted(monkeypatch, piece):
+ """HELD_MAX: a frame holds the drawing last counted where under 0.5 % of that drawing's solid pixels flip in it,
+ not only where it is the same pixels, for a clip comes to the reading through a codec and the key, which leave
+ hardly a held frame as it was. The square walker taken half a stride on, each drawing of the first half of its
+ stride held 3 frames and each of the second 1, alone or with a 36 px piece beside its head in the still, each held
+ frame with 6 of its edge pixels cleared (under 0.2 % of its solid pixels): each drawing counted once, its walk lies
+ where it lies held without the noise, as on ones, and it is not read. Counted wherever not the same pixels
+ (HELD_MAX at 0: every frame, as the clip plays it), the walk lies 0.075 off and the clip is read, with the turns it
+ does not make."""
from sprite_gen.video import body_turn
def drawn():
@@ -799,6 +818,30 @@ def test_a_walk_seen_at_an_angle_held_with_noise_over_its_held_frames_reads_its_
assert TURN[0] <= drawing[turn["from"]] and drawing[turn["to"]] <= TURN[1]
[email protected]("square", [True, False], ids=["square", "plain"])
+def test_a_walk_whose_every_frame_flips_under_held_max_of_the_one_before_is_read_by_its_drawings(square):
+ """HELD_MAX is held against the drawing last counted, not the frame before: a large or slow body can flip under
+ 0.5 % of its solid pixels from each frame to the next, and held against the frame before, no frame of its walk was
+ counted, and it was read with no walk's side to hold it. The walker over one stride, each drawing reached from the
+ one before over frames that each flip under 0.4 % of the frame before's solid pixels, is counted each time it has
+ moved HELD_MAX from the drawing last counted: seen square from behind, taken 6 frames into its stride (its still a
+ side its walk does not show), its walk lies under WALK_SIDE_MIN and it is not read; seen at an angle, its walk lies
+ over WALK_SIDE_MIN and it is read."""
+ from sprite_gen.video import body_turn
+
+ taken = 6 if square else 0
+ frames = _stepped([_walker(k, square=square) for k in range(taken, taken + CYCLE + 1)])
+ solid = [np.asarray(f.getchannel("A")) >= body_turn.SOLID for f in frames]
+ assert all((a ^ b).sum() < body_turn.HELD_MAX * a.sum() for a, b in zip(solid, solid[1:]))
+ read = body_turn.read(frames)
+ if square:
+ assert read["still_side"] >= body_turn.SIDE_SHOWN_MIN
+ assert read["read"] is False and read["turns"] == [] and abs(read["walk_side"]) < body_turn.WALK_SIDE_MIN
+ assert read["why"].startswith("the walk is seen square")
+ else:
+ assert read["read"] and read["walk_side"] >= body_turn.WALK_SIDE_MIN
+
+
@pytest.mark.slow
def test_a_held_walk_through_the_codec_and_the_key_reads_as_drawn(tmp_path):
"""The held walkers through the path a clip takes (`_coded`: libx264 at its own crf 23 and `video-frames`' key),