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): the body turn is read by each frame's mass and about its head's axis between pixels, so a piece apart from the body moves no turn (torso-side-v2)

Soohong Kime54dc9c88f89
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6f675c4..c9349d3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,11 +6,12 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
**Upgrading from 3.3.0: a clip whose cut held a turn is now cut where a window without the turn holds a cycle, while clips with no turn, clips that are not read, and clips with a turn and no turn-free cycle under `warn` keep every cut and byte.**
-- **New: `video-loop` detects torso turns in walk and run clips and avoids them during the cut search.** A video model asked to walk at the still's angle sometimes turns the body inside the clip: a back-diagonal walk turns to a full back view half way and back. A loop cut across the turn plays the body swinging round. Until now the engine had no reading of this: the cut search could not avoid it, and a clip that held no cycle for it was refused only as `video-loop: no periodic cycle found`, so an app could not name that the body turned as the reason to film it again. The new module `sprite_gen/video/body_turn.py` introduces reading `torso-side-v1` 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.24). Read against the still filmed small, the same synthetic walk (its first 8 frames filmed from 0.6 of its size) reads only nearer 0: +0.41 where it does not turn (+0.86 without the lead-in), and its turn -0.14 (-0.30 without the lead-in), at the same frames. 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. 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)`. Under module constants `SIDE_SHOWN_MIN` = 0.10, `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. 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-v1`), `bounds` (`SIDE_SHOWN_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_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 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 also gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.
-- Python callers: new module `sprite_gen.video.body_turn` provides `read(frames)`, `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`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`, `MODES` (`warn`, `refuse`), `NECK_RANGE` (0.10, 0.55), and `HEAD_REACH` (0.3). 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 6 to 16 and 51 to 61, least -0.21), because the tail swung up into the head's rows and pulled the head's centre aside; the cut search then left those frames out, cut it 17/29 instead of two steps, and the seam gate refused it (2.82). 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 133 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.9 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.
-- **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 at the frames it reads 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 instead, the same walk not turning 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.4. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.30), 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.
+- **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. 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`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_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 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 also gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.
+- Python callers: new module `sprite_gen.video.body_turn` provides `read(frames)`, `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`, `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.
+- 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. A square still that a piece beside its head lays off its nearest mirror is read and can read turns it does not make: the synthetic walker seen square from behind, with a 36 px piece beside its head in the still, lies at most 0.060 off its nearest mirror and is not read; read with `SIDE_SHOWN_MIN` at 0.06, it reads turns over 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.
+- **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 instead, the same walk not turning 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); `GUARD` 2, `STEP` 1 or `SIDE_SHOWN_MIN` 0.06 read that square walker with turns, and `SIDE_SHOWN_MIN` 0.095 leaves the hooded walker unread; `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.
## 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 315aa22..46953e4 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -377,11 +377,13 @@ taken again from them (`--cycle fixed --start`) is the frames they name. A cut t
**The body turn is avoided by 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. Every walk or run with `--anchor motion-auto` reads each frame to find turns. No window whose cut holds a frame of a turn is taken while another window holds a cycle. The search refuses that window with the reason `the body turns (clip frames a-b)`. Two-step cuts by the clip's crossings that hold a turn are left out (`step_count.turned_out` counts them), and so are the held side's windows two lengths long.
-The reading (`torso-side-v1` in `sprite_gen/video/body_turn.py`) reads each frame's torso 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, where the video model reframes 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.24). Read against the still filmed small, the same synthetic walk (its first 8 frames filmed from 0.6 of its size) reads only nearer 0: +0.41 where it does not turn (+0.86 without the lead-in), and its turn -0.14 (-0.30 without the lead-in), at the same frames. 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. The neck is the narrowest row of the first frame between 10 % and 55 % of its height, taking the topmost row on a tie. A body with no neck narrower than its head (a hood widening down to the shoulders) has its narrowest row at the top of that range, so its crop holds the head and the chest, which turn with the body. On a synthetic hooded walker the neck reads at 0.11 of the height (the range's top row) and its turn reads as on a walker with a neck (least -0.28; +0.87 where it does not turn). Every crop is centred on the head's centre: the middle of the solid pixels of the top 15 % of the body. Under the fourth named bound, `HEAD_REACH` = 0.3, that middle is now read again on the pixels within `HEAD_REACH` of the body's height of it, until it settles; where no pixel of those rows lies further out, the middle is the plain mass centre as before. A part swung up beside the head (a tail on a beat of its own, a held prop) pulls a plain mass centre aside on every swing, and the torso then reads as turning with it. The test suite's side walker with a 60 px tail on a 45-frame beat read a turn on every swing (least -0.21) and was then cut across it and refused; with `HEAD_REACH` it reads none (least +0.11) and is cut as before (on it, 0.3 reads no turn and 0.4 a turn every swing). 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: its `side` is null and `body_turn` gains `unread`, a list of `{frames, why}` (each reason with the frames it applies to), while a clip whose first frame is not read records `read: false`, a `why`, and verdict `not-read`, running the cut search once for the same cut and bytes as without the reading. The largest part is not taken for the head because a prop can weigh what the head does: on the test suite's synthetic walker holding a staff beside it (its ornament at the head's height and apart from it, its handle in the hand), the ornament and the head hold the same number of solid pixels in those rows, 513 each, with the middle falling between them and no pixel within 39.9 px of it (0.3 of the 133 px body), and a crop centred on a prop would read turns the body does not make, which the cut search would leave out of the cut, or `--body-turn refuse` would refuse. Every other place where the reading would select nothing is also not read, never read as 0 and never centred on a middle no pixel holds: a first frame whose torso rows hold no solid pixel (a part apart above the body tops its box, so its narrowest row lies in the gap; on a synthetic walker with a pennant 240 px above its head, the neck reads at 0.11 and the rows from there down half the box are empty); a crop of no width (a torso one column wide under the head's centre, or a body one pixel high); a crop with nothing in it, which would have read 0, a torso as near the still as its mirror; and a clip with no frames; and a frame that is not read ends a run of turned frames, as a frame with no body already did.
+The reading (`torso-side-v2` in `sprite_gen/video/body_turn.py`) reads each frame's torso 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, where the video model reframes 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). Turns of 4 frames under 0, drawn from 8 places (the facing over the mirror over frames 8 to 15, 10 to 17, 12 to 19, 14 to 21, 16 to 23, 20 to 27, 24 to 31 and 30 to 37), each read over the same 4 frames with the lead-in as without it (frames 10 to 13 for the turn drawn over frames 8 to 15, and so on); `torso-side-v1` read 7 of the 8, not the one drawn over frames 10 to 17, with the lead-in or without it. 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. In `torso-side-v2`, each frame's box top and the still's torso width are read by mass under the named bound `MASS_SHARE` = 0.01, the same hundredth as the speck bound of `sprite_gen/video/frames.py` (`SPECK_MIN_FRACTION`). The box's top is the row with more than a hundredth of the frame's solid pixels above it, and the still's torso width (the crop's width, held for every frame) 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. Under `torso-side-v1`, the box ran from the frame's topmost solid pixel and the width from the torso rows' outermost columns, so a piece apart from the body moved them: on the synthetic walkers, a 3 px fleck over the head for 10 frames read a turn over those frames, a 6 px fleck near the head read a turn, a 6 px fleck beside the head in the still alone read a turn over the whole clip (frames 1 to 72), an ornament cut loose beside the head hid the turn the walk made, and an antenna cut loose from the head over frames 30 to 39 hid the turn too. `MASS_SHARE` turnovers: at 0.005 the antenna over the head (1 px wide and 31 px tall, 0.008 of the walker's pixels, cut loose from the head over frames 30 to 39) tops the box and the walk reads a turn every stride (frames 14 to 22, 37 to 46 and 62 to 70); at 0.008 and 0.009 no synthetic reading changes; at 0.011 a front walker with a 70 px tail reads one of its turns from a frame earlier; at 0.0125 the 7 px fleck over the head over frames 30 to 39 (49 px) no longer tops the box, and its frames read no turn. Of the test suite's 42 named walkers, `torso-side-v1` reads 8 wrong and `torso-side-v2` none, and across 186 placements of a 3 px fleck anywhere along the canvas's top with an antenna or whisker cut loose over frames 30 to 39, `torso-side-v1` reads a turn at 34 and `torso-side-v2` at none. The box's bottom is the frame's last solid row, as `torso-side-v1` read it: 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; 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. The neck is the narrowest row of the first frame between 10 % and 55 % of its height, taking the topmost row on a tie. A body with no neck narrower than its head (a hood widening down to the shoulders) has its narrowest row at the top of that range, so its crop holds the head and the chest, which turn with the body. On a synthetic hooded walker the neck reads at 0.11 of the height (the range's top row) and its turn reads as on a walker with a neck (least -0.67; +0.91 where it does not turn). Every crop is centred on the head's centre (`HEAD_CORE` = 0.5): the middle of the solid pixels of the top 15 % of the body, now taken only over the columns of those rows holding at least `HEAD_CORE` (0.5, half) of the fullest column's solid pixels, so a 6 px fleck or an ornament cut loose beside the head does not count. At 0.3 the columns of a 6 px fleck beside the head in the still alone count, and the still's centre moves 1.5 px; at 0.35 the columns of the ornament cut loose beside the head count, and it moves 0.9 px. With each frame read against the still at its nearest within `TOL` (described in the next paragraph), the fleck's walk still reads no turn and the ornament walker still reads its turn over frames 32 to 38. No synthetic walker's reading changes with `HEAD_CORE` anywhere from 0 to 0.9 (the suite's 42 named walkers and its 27 other synthetic walkers). Under the named bound `HEAD_REACH` = 0.3, that middle is now read again on the pixels within `HEAD_REACH` of the body's height of it, until it settles; where no pixel of those rows lies further out, the middle is the plain mass centre as before. A part swung up beside the head (a tail on a beat of its own, a held prop) pulls a plain mass centre aside on every swing, and the torso then reads as turning with it. The test suite's side walker with a 60 px tail on a 45-frame beat read a turn on every swing (least -0.19); with `HEAD_REACH` it reads none (least +0.11) and is cut as before (on it, 0.3 reads no turn and 0.35 a turn every swing). 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: its `side` is null and `body_turn` gains `unread`, a list of `{frames, why}` (each reason with the frames it applies to), while a clip whose first frame is not read records `read: false`, a `why`, and verdict `not-read`, running the cut search once for the same cut and bytes as without the reading. The largest part is not taken for the head because a prop can weigh what the head does: on the test suite's synthetic walker holding a staff beside it (its ornament at the head's height and apart from it, its handle in the hand), the ornament and the head hold the same number of solid pixels in those rows, 513 each, with the middle falling between them and no pixel within 39.6 px of it (0.3 of the 132 px body), and a crop centred on a prop would read turns the body does not make, which the cut search would leave out of the cut, or `--body-turn refuse` would refuse. Every other place where the reading would select nothing is also not read, never read as 0 and never centred on a middle no pixel holds: a first frame whose torso rows hold no solid pixel (a part apart above the body tops its box, so its narrowest row lies in the gap; on a synthetic walker with a pennant 240 px above its head, the neck reads at 0.11 and the rows from there down half the box are empty); a crop of no width (a torso one column wide under the head's centre, or a body one pixel high); a crop with nothing in it, which would have read 0, a torso as near the still as its mirror; and a clip with no frames; and a frame that is not read ends a run of turned frames, as a frame with no body already did.
-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). 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. Three named module constants define the report field `bounds`, bounding whether the clip is read and what counts as a turn. `SIDE_SHOWN_MIN` = 0.10 sets how far the still's head and shoulders (the top 45 % of its body) lie off their mirror 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. `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.31 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 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` 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 off its nearest mirror, over `SIDE_SHOWN_MIN`, and is read: the walk reads turns it does not make (frames 15 to 21 and 39 to 43); at every value under 2.0 such a square walker is read and reads turns too. 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 the walk reads turns (frames 3 to 9, 27 to 32 and 51 to 57); at 0.5 and under it is not read. 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.
-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-v1`), `bounds` (the three), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_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 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.
+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. Three 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 square walker with the 3 by 12 px column 6 px right of its head is read and reads turns (frames 15 to 21 and 39 to 43); at 0.095 the hooded walker is not read. `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 three), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_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 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.
What it does not see:
- A square still (a front or back walk) is not read, so a front or back walk that turns to a diagonal is not seen.
@@ -390,6 +392,13 @@ What it does not see:
- 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.
- A body whose only side-to-side difference is its swinging arms, drawn symmetric about the head (the test suite's synthetic side walker, two arms either side of the head's centre, a tone apart), reads its own stride as a turn (least -0.50, every half cycle), because its stride is its own mirror. Every window holds such a turn, so `warn` keeps the cut the search took before, byte for byte, but `refuse` would refuse it.
- A clip whose first frame holds a prop as high as the head and apart from it (or a part apart above the body over its torso rows) is not read at all, so a turn in it is not seen.
+- A piece apart over a hundredth of the body is read as the body's own: a 7 px fleck over the head over frames 30 to 39 (49 px of the 3849 px walker) tops the box and those frames read as a turn, as under `torso-side-v1`.
+- The box's bottom is the last solid row: a piece apart under the feet runs the box down to it. In some frames (3 to 10 px square, 1 to 45 px under the lowest row the feet step on, over frames 30 to 39), the box runs down to it and no turn reads. In the still, far enough under the feet (from about 25 px under, the distance depending on the piece's size, on the synthetic walker), the still's torso reads as its own mirror and the clip is not read (verdict `not-read`, cut as the search alone cuts it), as under `torso-side-v1`.
+- The neck is read on the still's rows 2 % of its height apart: a box a pixel taller or shorter can move the neck a step of that grid, and every frame's torso rows with it.
+- A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: pieces under a hundredth of the body (a column or a row 1 or 3 px wide, a near-square, an L or a diagonal; 12, 24, 36 or 38 px), placed in the head's rows right or left of it (against it or apart), over the head (against it, apart, or at its corner), beside the neck or beside the arm, in the still alone, in every frame but the still, or over frames 30 to 39: 957 placements on each of four walkers that do not turn (the plain walker, the lead-in walker, the hooded walker, and the side walker with a 60 px tail and its arms), each frame's pieces erased first as keying erases them (`frames.drop_specks` with its defaults). Of the pieces under a hundredth of every frame they are drawn on and left by the keying (863, 372, 808 and 148 placements), none reads a turn; 11, 1, 22 and 0 leave the clip unread: each a piece in the still alone, 6 or 20 px right or left of the head (21 of the 34) or beside an arm (13), laying the still's head and shoulders under 0.08 off their nearest mirror.
+- A still seen square that a piece beside its head lays `SIDE_SHOWN_MIN` or more off its nearest mirror is read, and its walk is read against the side the piece shows: a front or back walk with a piece in its still alone can read turns it does not make. The synthetic walker seen square from behind, with a 36 px piece beside its head in the still, lies 0.060 off its nearest mirror at most and is not read; read with `SIDE_SHOWN_MIN` at 0.06, it reads turns (frames 15 to 21 and 39 to 43). `torso-side-v1`, about the centre the column moved, read that still 0.199 off its mirror and the walk turned.
+- `GUARD` and `TOL` are pixels of the frame, not shares of the body. 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 (under a hundredth of the body at every size): the column moves the head's centre 1.8, 2.7 and 4.0 px, and the walk reads no turn, least +0.78, +0.44 and +0.31 (without the column +0.85, +0.92 and +0.94); turning over frames 30 to 40, each reads its turn over frames 32 to 38. A larger body's margin narrows.
+- Over 447 synthetic turns of 6 to 12 frames (from frames 4 to 62; on ones, on twos, and after an 8-frame lead-in), `torso-side-v2` reads every frame `torso-side-v1` reads as turned, over the same frames or more, and 14 turns that `torso-side-v1` does not read; 54 clips read other frames than under `torso-side-v1`, and there is no clip where `torso-side-v1` reads a turn that `torso-side-v2` does not. Each of those 54 clips was cut by `video-loop` under `--body-turn warn` with each reading: 37 avoid their turn under both (verdict `avoided`); 13 where `torso-side-v1` reads no turn avoid the turn `torso-side-v2` reads; 3 are `clear` under both; 1 where `torso-side-v1` reads no turn is `clear` of the turn `torso-side-v2` reads. In none does the cut taken under `torso-side-v2` hold a frame `torso-side-v1` reads as turned that the cut under `torso-side-v1` leaves out, and no clip goes from `avoided` or `clear` to `kept`, `unfound` or `refused`.
Gates, all fail loud: no period (profile flat, below the recorded `periodicity_min`), loop seam ratio above `--seam-max` (2.0), GIF/WebP reopened and checked (frame count, `loop=0`, transparent corners, no RGB under alpha 0 in the WebP). On every walk or run loop that plays round, the step gate reads cells between drawings and refuses the loop when its largest step that is not a pixel's jitter, divided by the mean of the other steps, exceeds `STEP_RATIO_MAX` (2.5); a step is a pixel's jitter when aligning its drawing with the previous drawing takes at most `STEP_JITTER_PX` (1.5) pixels of the frames as filmed, measured by coverage so colour has no effect, and the step with that move taken back is within 2.5 of the mean. A fixed cut of a walk or run reads clip foot crossings to judge the cut, refusing an odd step count that would swap legs at the wrap. Both checks are lifted by `--seam-max` past 2.5; see `docs/loop-repair.md` section 3, "The step gate". Every walk or run loop gated by its seam ratio (not a pinned clip) is also refused when the top of its silhouette (the head, or a part held above it) jumps into the loop's first frame more than `--seam-pop-max` times its median step (default 10; `jolt.seam_pop.pop`, read on the loop as it plays); a top that cannot be read is not refused (`seam_pop_gate` says `unreadable`). `--seam-max` does not lift this gate; `--seam-pop-max off` turns it off, leaving a warning line as before; see `docs/loop-repair.md` section 3, "The seam pop gate".
diff --git a/sprite_gen/video/body_turn.py b/sprite_gen/video/body_turn.py
index d74a55e..c6efa52 100644
--- a/sprite_gen/video/body_turn.py
+++ b/sprite_gen/video/body_turn.py
@@ -4,38 +4,74 @@ docs/video-pipeline.md section 4, "The body turn").
A clip filmed from a still walks at the still's angle, or should: a back-diagonal walk that turns to a full back view
half way and back holds no two steps in one facing, and a cut across the turn plays the body swinging round. The
-reading (`torso-side-v1`) puts each frame's torso between the clip's first frame — the still it was filmed from, a
-standing pose, lead-in or not — and that frame mirrored about its head:
-`side = (v.s - v.m) / (1 - s.m)`, 1 where the torso shows the side the still's does, 0 where it is as near the still as
-its mirror (a body seen square, from behind or in front), under 0 past it. A pose the walk changes moves both
-correlations alike; a turn moves them apart. Each clip is read against its own first frame, never against a kind of
-motion or a direction's name. Not against the first frame after a lead-in (the video model reframing the still to the
-walk's size, which the search leaves out): that frame is a stride's pose, whose mirror the walk draws half a cycle on, so
-a walk that does not turn reads a turn every stride (a synthetic one, least -0.24); the still filmed small reads blurred,
-but only nearer 0 (a synthetic walk filmed from 0.6 of its size for 8 frames: +0.41 where it does not turn, its turn
--0.14).
+reading (`torso-side-v2`) puts each frame's torso between the clip's first frame — the still it was filmed from, a
+standing pose, lead-in or not — and that frame mirrored about its head: `side = (v.s - v.m) / (1 - s.m)`, 1 where the
+torso shows the side the still's does, 0 where it is as near the still as its mirror (a body seen square, from behind or
+in front), under 0 past it. A pose the walk changes moves both correlations alike; a turn moves them apart. Each clip is
+read against its own first frame, never against a kind of motion or a direction's name. Not against the first frame
+after a lead-in (the video model reframing the still to the walk's size, which the search leaves out): that frame is a
+stride's pose, whose mirror the walk draws half a cycle on, so a walk that does not turn reads a turn every stride (a
+synthetic one, least -0.34). The still filmed small reads blurred, but hardly: a synthetic walk filmed from 0.6 of its
+size for 8 frames reads +0.87 at least where it does not turn (+0.92 filmed from its own size), and where it turns,
+the turn over the frames it reads it over filmed from its own size, a turn of 4 frames too (turning over frames 30-40,
+least -0.71 against -0.63).
Three named bounds:
-- SIDE_SHOWN_MIN: how far the still's head and shoulders (the top 45 % of its body) lie off their mirror (1 - s.m) for
- the clip to be read at all. Under it the still is seen square — a front or back walk, whose far step lays the torso
- nearer its mirror each step — and its facing is not read: a square still that turns to a diagonal is not seen.
+- SIDE_SHOWN_MIN: how far the still's head and shoulders (the top 45 % of its body) lie off their nearest mirror
+ (1 - s.m; GUARD, below) for the clip to be read at all. Under it the still is seen square — a front or back walk,
+ whose far step lays the torso nearer its mirror each step — and its facing is not read: a square still that turns to
+ a diagonal is not seen. 0.08 lies between the synthetic walkers seen at an angle, 0.090 off it or more (the hooded
+ one; the plain one 0.102), and the one seen square from behind with a 36 px piece beside its head in the still,
+ 0.060 at most.
- 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
dip is the walk's own.
-Each crop is centred on the head: the middle of the solid pixels of the top 15 % of the body (HEAD_SHARE), read again on
-those within HEAD_REACH of the body's height of it until it settles. A part swung up beside the head (a tail on a beat of
-its own, a held prop) would pull a plain mass centre aside every swing, and the torso would read as turning with it (a
-synthetic side walk with a 60 px tail on a 45-frame beat read a turn every swing, least -0.21); where nothing lies that
-far out, the middle is the mass centre itself. Where nothing lies within HEAD_REACH of the middle — the top's parts lie
-apart either side of it: a prop held as high as the head and apart from it, or a body too small for a pixel to lie that
-near — the top does not tell which part is the head, and the frame is not read (None in `side`, its why in `unread`); a
-still not read so leaves the clip unread, cut as the search alone cuts it. The largest part is not taken for the head: a
-prop can weigh what the head does in those rows (a synthetic staff's ornament beside the head weighs the same), and a
-crop about the prop would read turns the body does not make, which the cut search would leave out, or
-`--body-turn refuse` refuse.
+Each frame is read by its mass (MASS_SHARE, the speck bound of sprite_gen/video/frames.py: a hundredth). Its box tops at
+the row with a hundredth of its solid pixels over it, and the still's torso is held as wide, about the head, as the
+columns of its torso rows with a hundredth of those rows' pixels beside them. A fleck apart from the body, a part of its
+own cut loose (its toes, a tail's tip, an ornament) or a thin part (an antenna, a whisker) is under a hundredth and
+moves neither: `torso-side-v1` read the box from the frame's topmost and outermost solid pixel, and a 3 px fleck over
+the head for 10 frames read a turn over them, while an ornament cut loose beside the head hid the turn the walk made
+(synthetic walkers, tests/video/test_loop_body_turn.py). The box's bottom is its last solid row, as `torso-side-v1`
+read it — the one end the mass does not set: where the legs cross each stride they lay their pixels over each other,
+and a bottom read by mass rises with them (the synthetic lead-in walker's, a row over its last solid row in most
+frames, 3 where they cross), the crop's rows with it; its turns read over the same frames either way.
+
+Each crop is centred on the head: the middle of the top 15 % of the body (HEAD_SHARE), of its columns holding at least
+HEAD_CORE (half) of the fullest one's solid pixels — a fleck or an ornament beside the head, a few rows of each column,
+does not count — read again on those within HEAD_REACH of the body's height of it until it settles. A part swung up
+beside the head (a tail on a beat of its own, a held prop) would pull a plain mass centre aside every swing, and the
+torso would read as turning with it (a synthetic side walk with a 60 px tail on a 45-frame beat read a turn every
+swing, least -0.19); where nothing lies that far out, the middle is the mass centre itself. Where nothing lies within
+HEAD_REACH of the middle — the top's parts lie apart either side of it: a prop held as high as the head and apart from
+it, or a body too small for a pixel to lie that near — the top does not tell which part is the head, and the frame is
+not read (None in `side`, its why in `unread`); a still not read so leaves the clip unread, cut as the search alone cuts
+it. The largest part is not taken for the head: a prop can weigh what the head does in those rows (a synthetic staff's
+ornament beside the head weighs the same), and a crop about the prop would read turns the body does not make, which the
+cut search would leave out, or `--body-turn refuse` refuse.
+
+The crop's axis is the middle of the centre's column (column c spans c to c + 1), and its edges lie where they fall,
+between pixels too, the crop resampled from the frame about them: a body that is its own mirror about its head crops as
+its own mirror wherever its centre falls (`torso-side-v1` rounded each edge to a whole pixel, and the synthetic walker
+drawn in one grey lay 0.050 off its mirror, a side its silhouette does not show). A part holding over HEAD_CORE of the
+fullest column in each of its own columns still moves the centre — a column 3 wide and 12 tall beside a head 19 rows
+tall, 1.4 px — and read about a centre 0.75 px off, `torso-side-v1` read a walk that does not turn as turning every
+stride. So each crop is read about the axes STEP (a quarter of a pixel) apart either side of the centre as well, each
+as wide as the centre's:
+
+- GUARD: the still's head and shoulders lie off their nearest mirror about any axis within 2.5 px of the centre — the
+ side SIDE_SHOWN_MIN bounds. The walker seen square from behind with that column 6 px beside its head in the still
+ lies 0.060 off it; about the axes within 2 px, or a pixel apart, 0.093, and the walk, read, reads turns it does not
+ make.
+- TOL: each frame's torso is read against the still's torso and against its mirror, each at its nearest about any axis
+ within 2 px of the still's centre. The walk with the still's centre read up to a pixel off reads no turn, no frame's
+ side 0.07 from where it reads; the walker filmed small with that column beside its head over frames 30-39 reads no
+ turn there, where read about the still's centre alone (TOL 0) it reads one. Under it, HEAD_CORE moves no synthetic
+ walker's reading anywhere from 0 to 0.9: a fleck beside the head moving the centre 1.5 px (at 0.3), or an ornament
+ 0.9 px (at 0.35), is read within TOL.
A crop reads only what it holds. A still with no solid pixel across its torso's rows (a part apart above the body tops
its box, its narrowest row in the gap between), a crop of no width, or one of a single value throughout (an empty crop)
@@ -44,23 +80,53 @@ mirror.
The torso (`torso_rows`) is the rows from the neck — the narrowest row of the first frame between NECK_RANGE of its
height — down half the body below it. A body with no neck narrower than its head (a hood, a robe) has its narrowest row
-at the range's top, so its crop starts in the head and holds the head and the chest, which turn with it."""
+at the range's top, so its crop starts in the head and holds the head and the chest, which turn with it.
+
+Named limits. A piece apart over a hundredth of the body is the body's own: it tops the box, and the frames it lies in
+read as a turn where it moves the crop far enough (a synthetic 7 px fleck over the head, 49 px of a 3849 px walker,
+reads its frames turned, as `torso-side-v1` did). A piece apart under the feet runs the box down to it (no turn reads
+over the frames it lies in; in the still, far enough down, the still's torso reads its own mirror and the clip is not
+read). The neck is read on the still's rows 2 % of its height apart: a box a pixel taller or shorter can read it a row
+of the grid higher or lower, and every frame's torso rows with it. A piece beside the still's head and shoulders (its
+head or an arm) can lay them under SIDE_SHOWN_MIN off their nearest mirror though the still is seen at an angle, and the
+clip is not read (34 of 2191 synthetic pieces under a hundredth of the body, placed about the heads and torsos of four
+walkers). A still seen square that a piece beside its head lays SIDE_SHOWN_MIN or more off its nearest mirror is read,
+and its walk against the side the piece shows: a front or back walk with a piece in its still alone can read turns it
+does not make (the synthetic walker seen square from behind with a 36 px piece beside its head in the still lies 0.060
+off it at most, and read with SIDE_SHOWN_MIN at 0.06, reads them). 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
from typing import Any
from PIL import Image
from sprite_gen._deps import np
+from sprite_gen.video.frames import SPECK_MIN_FRACTION
-READING = "torso-side-v1"
-SIDE_SHOWN_MIN = 0.10
+READING = "torso-side-v2"
+SIDE_SHOWN_MIN = 0.08
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
+# 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
HEAD_SHARE = 0.15 # the head's centre: the middle of the solid pixels of the top 15 % of the body's box
+HEAD_CORE = 0.5 # ... in the columns holding at least this share of the fullest one
HEAD_REACH = 0.3 # ... of those within this share of the body's height of it, read again until it settles
+# The axes the still is read about besides its head's centre, STEP px apart: its head and shoulders against their
+# nearest mirror about any within GUARD px (the side SIDE_SHOWN_MIN bounds), each frame against its torso and its
+# torso's mirror, each at its best, about any within TOL px.
+GUARD = 2.5
+TOL = 2.0
+STEP = 0.25
+PAD = 4 # px of the frame either side of a crop's box, read by the resampling filter
UPPER = (0.0, 0.45) # the still's head and shoulders, read for SIDE_SHOWN_MIN
NECK_RANGE = (0.10, 0.55) # where the neck is looked for, in shares of the body's height from its top
ROWS = np.arange(0.01, 1.0, 0.02) # the rows the profile is read at, each 2 % of the height tall
@@ -68,16 +134,25 @@ CROP = (48, 64) # every crop is read at this size
LUMA = np.array([0.299, 0.587, 0.114])
+def _ends(mass: np.ndarray, cut: float) -> tuple[int, int]:
+ """The first and the last index of `mass` with more than `cut` of it before (after) them."""
+ first = int(np.searchsorted(np.cumsum(mass), cut, side="right"))
+ return first, len(mass) - 1 - int(np.searchsorted(np.cumsum(mass[::-1]), cut, side="right"))
+
+
def _body(frame: Image.Image) -> tuple[np.ndarray, int, int, float] | str:
- """The frame's solid pixels, its box's top row and height, and its head's centre column (HEAD_SHARE, HEAD_REACH);
- where they are not read, why, said of the frame: no solid pixel, or no head to centre on — the top's parts lie
- apart either side of their middle, none within HEAD_REACH of it."""
+ """The frame's solid pixels, its box's top row and height, and its head's centre column (HEAD_SHARE, HEAD_CORE,
+ HEAD_REACH); where they are not read, why, said of the frame: no solid pixel, or no head to centre on — the top's
+ parts lie apart either side of their middle, none within HEAD_REACH of it."""
solid = np.asarray(frame.getchannel("A")) >= SOLID
- rows = np.nonzero(solid.any(axis=1))[0]
+ mass = solid.sum(axis=1)
+ rows = np.nonzero(mass)[0]
if not len(rows):
return "has no solid body to read"
- top, height = int(rows[0]), int(rows[-1]) - int(rows[0]) + 1
+ top = _ends(mass, MASS_SHARE * float(mass.sum()))[0]
+ height = int(rows[-1]) - top + 1
mass = solid[top:top + max(2, int(HEAD_SHARE * height))].sum(axis=0).astype(np.float64)
+ mass[mass < HEAD_CORE * mass.max()] = 0.0
cols = np.arange(len(mass))
centre = float((mass * cols).sum() / mass.sum())
for _ in range(20):
@@ -105,23 +180,32 @@ def _crop(frame: Image.Image, body: tuple[np.ndarray, int, int, float], rows: tu
held: float | None = None) -> tuple[np.ndarray, np.ndarray, float] | str:
"""The crop of `rows` (shares of the body's height from its top) about the head's centre, `held` wide (a share of
the height; where None, the frame's own extent across those rows, about the head), read at CROP: unit vectors of
- its luma times alpha and its alpha, of the same mirrored about the head's centre, and the width held. Where it
- holds nothing to read, why, said of the frame — no solid pixel across those rows (the width the frame's own), a
- crop of no width, or one of a single value throughout (an empty crop's 0): not read as a torso at 0."""
+ its luma times alpha and its alpha, of the same mirrored about the head's centre, and the width held. The axis is
+ the middle of the centre's column (column c spans c to c + 1), and the box's edges lie where they fall, between
+ pixels too, the crop resampled from the frame about them: a body that is its own mirror about its head crops as its
+ own mirror, wherever its centre falls. Where it holds nothing to read, why, said of the frame — no solid pixel
+ across those rows (the width the frame's own), a crop of no width (a torso of one column, nothing beside the axis
+ to mirror, or a box under a pixel wide), or one of a single value throughout (an empty crop's 0): not read as a
+ torso at 0."""
solid, top, height, centre = body
r0 = top + int(rows[0] * height)
r1 = max(r0 + 2, top + int(rows[1] * height))
span = f"rows {rows[0]:.2f}-{rows[1]:.2f} of its height"
+ axis = centre + 0.5
if held is None:
- cols = np.nonzero(solid[r0:r1].any(axis=0))[0]
- if not len(cols):
+ mass = solid[r0:r1].sum(axis=0)
+ if not mass.any():
return f"has no solid pixel in its {span}"
- held = 2 * max(centre - cols.min(), cols.max() - centre) / height
- half = held * height / 2
- box = (int(round(centre - half)), r0, int(round(centre + half)), r1)
- if box[2] <= box[0]:
+ lo, hi = _ends(mass, MASS_SHARE * float(mass.sum()))
+ if hi <= lo:
+ return f"has a crop of no width over its {span}"
+ held = 2 * max(axis - lo, hi + 1 - axis) / height
+ x0, x1 = axis - held * height / 2, axis + held * height / 2
+ if x1 - x0 < 1:
return f"has a crop of no width over its {span}"
- y = np.asarray(frame.crop(box).resize(CROP, Image.Resampling.LANCZOS), dtype=np.float64) / 255.0
+ left = math.floor(x0) - PAD
+ y = np.asarray(frame.crop((left, r0, math.ceil(x1) + PAD, r1)).resize(
+ CROP, Image.Resampling.LANCZOS, box=(x0 - left, 0.0, x1 - left, float(r1 - r0))), dtype=np.float64) / 255.0
luma, alpha = (y[..., :3] @ LUMA) * y[..., 3], y[..., 3]
v = _unit(luma, alpha)
if not v.any():
@@ -129,6 +213,24 @@ def _crop(frame: Image.Image, body: tuple[np.ndarray, int, int, float], rows: tu
return v, _unit(luma[:, ::-1], alpha[:, ::-1]), held
+def _windows(frame: Image.Image, body: tuple[np.ndarray, int, int, float], rows: tuple[float, float],
+ reach: float) -> tuple[np.ndarray, np.ndarray, float] | str:
+ """The crops of `rows` about the head's centre and about every axis within `reach` px of it, STEP apart, each as
+ wide as the centre's own (`_crop`): their unit vectors and their mirrors', stacked in the order of the axes (the
+ centre's in the middle), and the width held; where one holds nothing to read, why."""
+ centred = _crop(frame, body, rows)
+ if isinstance(centred, str):
+ return centred
+ solid, top, height, centre = body
+ n = round(reach / STEP)
+ crops = [_crop(frame, (solid, top, height, centre + j * STEP), rows, centred[2]) if j else centred
+ for j in range(-n, n + 1)]
+ for crop in crops:
+ if isinstance(crop, str):
+ return crop
+ return np.stack([crop[0] for crop in crops]), np.stack([crop[1] for crop in crops]), centred[2]
+
+
def neck(body: tuple[np.ndarray, int, int, float]) -> float:
"""The neck: of the rows in NECK_RANGE, the narrowest (the span holding the middle 96 % of the row's solid pixels,
over the height), the topmost on a tie — a share of the body's height."""
@@ -179,11 +281,11 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
still = _body(first)
if isinstance(still, str):
return {**out, "read": False, "still_side": None, "why": f"the clip's first frame {still}"}
- upper = _crop(first, still, UPPER)
+ upper = _windows(first, still, UPPER, GUARD)
if isinstance(upper, str):
return {**out, "read": False, "still_side": None, "why": f"the clip's first frame {upper}"}
- s, m, _ = upper
- out["still_side"] = round(1 - float(s @ m), 4)
+ crops, mirrors, _ = upper
+ out["still_side"] = round(1 - float((mirrors @ crops[len(crops) // 2]).max()), 4)
if out["still_side"] < SIDE_SHOWN_MIN:
return {**out, "read": False,
"why": f"the still is seen square: its head and shoulders lie {out['still_side']:.2f} off their mirror, under "
@@ -191,11 +293,11 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
at = neck(still)
out["neck"] = round(at, 2)
rows = torso_rows(at)
- torso = _crop(first, still, rows)
+ torso = _windows(first, still, rows, TOL)
if isinstance(torso, str):
return {**out, "read": False, "why": f"the clip's first frame {torso}, its torso's from the neck down"}
- s, m, held = torso
- shown = 1 - float(s @ m)
+ crops, mirrors, held = torso
+ shown = 1 - float((mirrors @ crops[len(crops) // 2]).max())
out["torso_still_side"] = round(shown, 4)
if shown <= 1e-6:
return {**out, "read": False, "why": "the still's torso is its own mirror: no side to read it by"}
@@ -209,7 +311,7 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
unread.setdefault(crop, []).append(k)
continue
v, _, _ = crop
- side.append(round((float(v @ s) - float(v @ m)) / shown, 4))
+ side.append(round((float((crops @ v).max()) - float((mirrors @ v).max())) / shown, 4))
out = {**out, "read": True, "side": side, "turns": turns(side)}
if unread:
out["unread"] = [{"frames": ks, "why": why} for why, ks in unread.items()]
diff --git a/tests/video/test_loop_body_turn.py b/tests/video/test_loop_body_turn.py
index 1781621..41fee86 100644
--- a/tests/video/test_loop_body_turn.py
+++ b/tests/video/test_loop_body_turn.py
@@ -1,9 +1,16 @@
# SPDX-License-Identifier: Apache-2.0
"""A walk whose body turns inside its clip (docs/video-pipeline.md section 4, "The body turn";
sprite_gen/video/body_turn.py): each frame's torso is read between the clip's first frame and that frame mirrored
-(`torso-side-v1`), a turn is the torso under TURN_SIDE_MAX for TURN_RUN_MIN frames or more, and `video-loop --anchor
-motion-auto` takes no cut that holds a frame of one while another holds a cycle. Where none does, `--body-turn warn` (the
-default) takes the cut it took before and says so; `--body-turn refuse` refuses the clip in a line of its own.
+(`torso-side-v2`), a turn is the torso under TURN_SIDE_MAX for TURN_RUN_MIN frames or more, and `video-loop --anchor
+motion-auto` takes no cut that holds a frame of one while another holds a cycle. Where none does, `--body-turn warn`
+(the default) takes the cut it took before and says so; `--body-turn refuse` refuses the clip in a line of its own. Each
+frame is read by its mass: its box tops at the row with a hundredth of its solid pixels over it (MASS_SHARE), its head's
+centre is read on the head's fullest columns (HEAD_CORE), and the still's torso is held as wide as the columns with a
+hundredth of its torso rows' pixels beside them — a fleck or a thin part apart from the body moves none of them. Each
+crop is cut about the middle of the head's centre column, its edges where they fall, between pixels too, and each frame
+is read against the still and against its mirror, each at its best about any axis within TOL px of the still's head's
+centre (the still's own side about any within GUARD px): a body that is its own mirror crops as its own mirror, and a
+piece beside the head that moves a centre a pixel or two moves no turn.
The walker is a back diagonal 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 on the head
@@ -31,6 +38,9 @@ W, H = 300, 240
TURN = (30, 40) # the frames the turning walker turns over, the still's mirror reached at their middle
LOW = -0.6 # the facing the turn reaches
APART = 240 # how much lower the walker is drawn, on a canvas as much taller, where a part is apart above it
+SPECK = (179, 0) # a fleck's top left on the canvas: over the head (its top row 37-43) and right of it, apart
+NEAR = (26, -18) # ... or from the head's top middle: 6 px square, 13 px above and right of its corner
+BESIDE = (20, 2) # ... or 6 px square, 6 px right of the head's edge and 2 under its top: in its rows, not over them
def _facing(turns, t: float, low: float = LOW, edge: int = 3) -> float:
@@ -43,13 +53,22 @@ def _facing(turns, t: float, low: float = LOW, edge: int = 3) -> float:
def _walker(k: int, *, turns=(), every: tuple[int, int] | None = None, hold: int = 1, square: bool = False,
- hood: bool = False, lead: int = 0, staff=(), apart=None) -> Image.Image:
- """The walker's frame `k`: turning over `turns`, or `every` (at, span) frames of each cycle; drawn on `hold`s; square
- from behind (`square`); hooded, its head and shoulders one shape that widens downward with no neck (`hood`); filmed
- smaller over its first `lead` frames, from 0.6 of its size, about its feet (a lead-in); over the frames in `staff`,
- holding a staff beside it that bobs with it, its ornament as high as the head and apart from it, the handle in its
- hand; where `apart` is given, drawn APART px lower on a canvas as much taller, a pennant apart above it at the top
- over the frames in `apart`."""
+ hood: bool = False, lead: int = 0, staff=(), apart=None, speck=(), speck_side: int = 3,
+ speck_at: tuple[int, int] | None = None, speck_xy: tuple[int, int] | None = None, loose: str | None = None,
+ joined=(), part: str | None = None, cut=(), droop: int = 0) -> Image.Image:
+ """The walker's frame `k`: turning over `turns`, or `every` (at, span) frames of each cycle; drawn on `hold`s;
+ square from behind (`square`); hooded, its head and shoulders one shape that widens downward with no neck (`hood`);
+ filmed smaller over its first `lead` frames, from 0.6 of its size, about its feet (a lead-in); over the frames in
+ `staff`, holding a staff beside it that bobs with it, its ornament as high as the head and apart from it, the handle
+ in its hand; where `apart` is given, drawn APART px lower on a canvas as much taller, a pennant apart above it at
+ the top over the frames in `apart`; over the frames in `speck`, a fleck `speck_side` px square apart from it, its
+ top left at SPECK on the canvas, at `speck_xy` on it, or `speck_at` (dx, dy) from the head's top middle; where
+ `loose` is given, a part of it cut loose a transparent row or column from it: its feet's last two rows (`toes`), a
+ tail's tip beside its legs (`tail`), or an ornament beside its head (`ornament`, joined to it by a pixel over the
+ frames in `joined`); where `part` is given, a thin part of its own joined to its head and cut loose over the frames
+ in `cut` (its joining pixel transparent): an antenna over the head's right (`antenna`, a pixel wide, 31 px tall), or
+ a whisker right of it (`whisker`, a pixel tall, 30 px from the head joined, 29 px from the pixel after cut loose,
+ `droop` rows lower then)."""
t = k - k % hold
ph = 2 * math.pi * t / CYCLE
if square:
@@ -85,6 +104,25 @@ def _walker(k: int, *, turns=(), every: tuple[int, int] | None = None, hold: int
d.rectangle((267, y, 293, y + 28), fill=(90, 60, 40, 255))
d.rectangle((278, y + 28, 282, y + 90), fill=(140, 90, 40, 255))
d.rectangle((170, y + 70, 282, y + 74), fill=(140, 90, 40, 255))
+ if k in speck:
+ sx, sy = speck_xy or (SPECK if speck_at is None else (x + speck_at[0], y + speck_at[1]))
+ d.rectangle((sx, sy, sx + speck_side - 1, sy + speck_side - 1), fill=(250, 220, 90, 255))
+ if loose == "toes":
+ d.rectangle((0, y + 130, W - 1, y + 130), fill=(0, 0, 0, 0))
+ elif loose == "tail":
+ d.rectangle((170, y + 94, 171, y + 105), fill=(90, 60, 40, 255))
+ elif loose == "ornament":
+ d.rectangle((165, y + 2, 168, y + 8), fill=(250, 220, 90, 255))
+ if k in joined:
+ d.point((x + 14, y + 5), fill=(250, 220, 90, 255))
+ if part == "antenna":
+ d.line((x + 12, y - 31, x + 12, y - 1), fill=(250, 220, 90, 255))
+ if k in cut:
+ d.point((x + 12, y - 1), fill=(0, 0, 0, 0))
+ elif part == "whisker" and k in cut:
+ d.line((x + 15, y + 5 + droop, x + 43, y + 5 + droop), fill=(250, 220, 90, 255))
+ elif part == "whisker":
+ d.line((x + 14, y + 5, x + 43, y + 5), fill=(250, 220, 90, 255))
if k < lead:
s = 0.6 + 0.4 * k / lead
small = im.resize((round(W * s), round(H * s)), Image.Resampling.LANCZOS)
@@ -232,9 +270,9 @@ def test_a_turn_is_counted_in_frames_however_the_walk_is_held():
@pytest.mark.slow
def test_a_lead_in_is_read_against_the_still(tmp_path):
"""The reference is the clip's first frame, the still, lead-in or not (the first 8 frames filmed from 0.6 of the
- size, which the search leaves out): the turn reads where it reads without the lead-in, and the walk where it does
- not turn stays clear of 0. Read from the first frame after the lead-in — a stride's pose, whose mirror the walk
- draws half a cycle on — a walk that does not turn reads a turn every stride."""
+ size, which the search leaves out): the turn reads over the frames it reads over without the lead-in, and the walk
+ where it does not turn stays clear of 0. Read from the first frame after the lead-in — a stride's pose, whose mirror
+ the walk draws half a cycle on — a walk that does not turn reads a turn every stride."""
from sprite_gen.video import body_turn
report = _cut(tmp_path / "out", _keyed(tmp_path, turns=[TURN], lead=8))
@@ -252,7 +290,7 @@ def test_a_lead_in_is_read_against_the_still(tmp_path):
def test_a_part_swung_up_beside_the_head_does_not_pull_its_centre(monkeypatch):
"""HEAD_REACH: the side walker with a 60 px tail on a 45-frame beat (tests/video/test_walk_steps.py, the half step),
its tail swung up into the head's rows every swing. The head's centre read within 0.3 of the body's height of it,
- the walker reads no turn; within 0.4 the tail pulls the centre aside and the torso reads a turn every swing (the
+ the walker reads no turn; within 0.35 the tail pulls the centre aside and the torso reads a turn every swing (the
search then took a cut that does not close)."""
from sprite_gen.video import body_turn
from tests.video.test_walk_steps import _side
@@ -261,7 +299,7 @@ def test_a_part_swung_up_beside_the_head_does_not_pull_its_centre(monkeypatch):
assert body_turn.HEAD_REACH == 0.3
read = body_turn.read(frames)
assert read["read"] and read["turns"] == [] and min(read["side"]) > 0
- monkeypatch.setattr(body_turn, "HEAD_REACH", 0.4)
+ monkeypatch.setattr(body_turn, "HEAD_REACH", 0.35)
assert len(body_turn.read(frames)["turns"]) == 2
@@ -276,6 +314,334 @@ def test_a_body_with_no_neck_reads_its_head_and_chest():
assert body_turn.read(_frames(hood=True))["turns"] == []
+# --- a piece apart from the body, read by its mass -----------------------------------------------------------------
+
+
+def _flag(far: bool = False) -> list[Image.Image]:
+ """The antenna cut loose over frames 30-39, and a 25 px square flag apart from the walker low on the left over those
+ frames and on the right in the still (`far`: at the canvas's edges): over a hundredth of the body, read as its
+ own."""
+ frames = _frames(part="antenna", cut=range(30, 40))
+ for k in [0, *range(30, 40)]:
+ y = 40 + round(3 * math.cos(4 * math.pi * k / CYCLE))
+ x = (275 if far else 260) if k == 0 else (0 if far else 15)
+ ImageDraw.Draw(frames[k]).rectangle((x, y + 100, x + 24, y + 124), fill=(60, 120, 60, 255))
+ return frames
+
+
+def _tail() -> list[Image.Image]:
+ from tests.video.test_walk_steps import _side
+
+ return [_side(k, cycle=29, tail_cycle=45, tail=60, arms=False) for k in range(FRAMES)]
+
+
+SHORT = (33, 40)
+WHISKER = dict(part="whisker", cut=range(30, 40))
+NAMED = [ # (id, read as, the frames a turn lies inside, the clip): a fleck, a part cut loose, a thin part of its own
+ ("plain-steady", "none", None, lambda: _frames()),
+ ("plain-turning-30-40", "turn", TURN, lambda: _frames(turns=[TURN])),
+ ("plain-short-33-40", "turn", SHORT, lambda: _frames(turns=[SHORT])),
+ ("hold2-turning", "turn", TURN, lambda: _frames(turns=[TURN], hold=2)),
+ ("dip-3-frames", "none", None, lambda: _frames(turns=[(12, 18)])),
+ ("dip-4-frames", "turn", (12, 19), lambda: _frames(turns=[(12, 19)])),
+ ("hood-steady", "none", None, lambda: _frames(hood=True)),
+ ("hood-turning", "turn", TURN, lambda: _frames(turns=[TURN], hood=True)),
+ ("square", "unread", None, lambda: _frames(square=True)),
+ ("staff-all", "unread", None, lambda: _frames(staff=range(FRAMES))),
+ ("pennant-all", "unread", None, lambda: _frames(apart=range(FRAMES))),
+ ("side-tail-60-beat45", "none", None, _tail),
+ ("fleck3-over-head-30-39", "none", None, lambda: _frames(speck=range(30, 40))),
+ ("fleck3-over-head-10-19", "none", None, lambda: _frames(speck=range(10, 20))),
+ ("fleck6-near-30-39", "none", None, lambda: _frames(speck=range(30, 40), speck_at=NEAR, speck_side=6)),
+ ("fleck6-beside-head-still", "none", None, lambda: _frames(speck=(0,), speck_at=BESIDE, speck_side=6)),
+ ("fleck6-beside-head-still-turning", "turn", TURN,
+ lambda: _frames(speck=(0,), speck_at=BESIDE, speck_side=6, turns=[TURN])),
+ ("fleck3-over-head-30-39-turning", "turn", TURN, lambda: _frames(speck=range(30, 40), turns=[TURN])),
+ ("fleck3-where-head-bobs-still", "none", None, lambda: _frames(speck=(0,), speck_xy=(148, 37))),
+ ("fleck6-where-head-bobs-10-14", "none", None,
+ lambda: _frames(speck=range(10, 15), speck_side=6, speck_xy=(148, 35))),
+ ("toes-loose-short-33-40", "turn", SHORT, lambda: _frames(turns=[SHORT], loose="toes")),
+ ("tail-loose-turning", "turn", TURN, lambda: _frames(turns=[TURN], loose="tail")),
+ ("antenna-cut-30-39", "none", None, lambda: _frames(part="antenna", cut=range(30, 40))),
+ ("antenna-cut-30-39+flag25", "none", None, _flag),
+ ("antenna-cut-30-39+flag25-farther", "none", None, lambda: _flag(far=True)),
+ ("antenna-cut-still", "none", None, lambda: _frames(part="antenna", cut=(0,))),
+ ("antenna-cut-0-39", "none", None, lambda: _frames(part="antenna", cut=range(40))),
+ ("antenna-joined-still-alone", "none", None, lambda: _frames(part="antenna", cut=range(1, FRAMES))),
+ ("antenna-cut-30-39-turning", "turn", TURN, lambda: _frames(part="antenna", cut=range(30, 40), turns=[TURN])),
+ ("whisker-cut-30-39", "none", None, lambda: _frames(**WHISKER)),
+ ("whisker-joined-still-alone", "none", None, lambda: _frames(part="whisker", cut=range(1, FRAMES))),
+ ("whisker-cut-30-39-droop2", "none", None, lambda: _frames(**WHISKER, droop=2)),
+ ("ornament-joined-still-alone", "none", None, lambda: _frames(loose="ornament", joined=(0,))),
+ ("ornament-cut-30-39", "none", None,
+ lambda: _frames(loose="ornament", joined=[k for k in range(FRAMES) if not 30 <= k < 40])),
+ ("ornament-loose-steady", "none", None, lambda: _frames(loose="ornament")),
+ ("ornament-loose-turning", "turn", TURN, lambda: _frames(loose="ornament", turns=[TURN])),
+ ("fleck7-over-head-30-39", "turn", (30, 39), lambda: _frames(speck=range(30, 40), speck_side=7)),
+ ("lead8-plain", "none", None, lambda: _frames(lead=8)),
+ ("lead8-turning", "turn", TURN, lambda: _frames(lead=8, turns=[TURN])),
+ ("lead8-ornament-joined-still", "none", None, lambda: _frames(loose="ornament", joined=(0,), lead=8)),
+ ("lead8-ornament-joined-still-turning", "turn", TURN,
+ lambda: _frames(loose="ornament", joined=(0,), lead=8, turns=[TURN])),
+ ("lead8-antenna-cut-30-39", "none", None, lambda: _frames(lead=8, part="antenna", cut=range(30, 40))),
+]
+
+
+def _outcome(read: dict) -> str:
+ return "unread" if not read["read"] else "turn" if read["turns"] else "none"
+
+
[email protected]("expect, inside, clip", [case[1:] for case in NAMED], ids=[case[0] for case in NAMED])
+def test_a_piece_apart_from_the_body_moves_no_turn(expect, inside, clip):
+ """Each walker reads as drawn: a turn where it turns, inside the frames it turns over, and none where it does not. A
+ fleck under a hundredth of the body over the head, near it or beside it, a part of its own cut loose (its toes, a
+ tail's tip, an ornament), or a thin part joined to the head and cut loose (an antenna, a whisker) — in some frames,
+ in the still alone or in every frame but the still — moves neither the box's top nor the head's centre nor the
+ still's torso width, where torso-side-v1, reading the box from its topmost and outermost pixel, read turns the body
+ does not make (a 3 px fleck over the head over 10 frames, those frames) or none where it does (an ornament cut loose
+ beside the head). A piece apart over a hundredth of the body (a 7 px fleck over the head, 49 px) is the body's own:
+ its frames read turned, as torso-side-v1 read them — a limit of the reading, named in docs/video-pipeline.md."""
+ from sprite_gen.video import body_turn
+
+ read = body_turn.read(clip())
+ assert _outcome(read) == expect, read.get("turns") or read.get("why")
+ if expect == "turn":
+ assert body_turn.turned(read) <= set(range(inside[0], inside[1] + 1))
+
+
[email protected]("part", ["antenna", "whisker"])
+def test_a_fleck_and_a_thin_part_cut_loose_over_the_same_frames_read_no_turn(part):
+ """The antenna or the whisker cut loose over frames 30-39 and a 3 px fleck over the same frames anywhere along the
+ canvas's top (x 119-239 every 4 px, y 0, 2 or 4): no turn at any — each is under a hundredth of the body, and the
+ two together too (torso-side-v1, its box topped by whichever is higher, read a turn at 34 of the 186)."""
+ from sprite_gen.video import body_turn
+
+ for dy in (0, 2, 4):
+ for dx in range(-60, 61, 4):
+ read = body_turn.read(_frames(part=part, cut=range(30, 40), speck=range(30, 40), speck_xy=(179 + dx, dy)))
+ assert read["read"] and read["turns"] == [], (179 + dx, dy)
+
+
+FEET = (182, 176) # under the feet: 13 px right of the farthest a foot swings (x 169), under its lowest row (175)
+
+
[email protected]("side", [3, 6, 7, 10])
+def test_a_piece_apart_under_the_feet_in_some_frames_reads_no_turn(side):
+ """The box's bottom is its last solid row, not a hundredth of the body up (the one end the mass does not set: the
+ legs crossing each stride lay their pixels over each other, and a bottom read by mass rises with them, the crop's
+ rows with it). A piece apart under the feet over frames 30-39 — 3 to 10 px square, 1 to 45 px under the lowest the
+ feet step — runs the box down to it in those frames: no turn reads, under a hundredth of the body or over it."""
+ from sprite_gen.video import body_turn
+
+ for gap in (0, 5, 11, 12, 19, 29, 44):
+ read = body_turn.read(_frames(speck=range(30, 40), speck_side=side, speck_xy=(FEET[0], FEET[1] + gap)))
+ assert read["read"] and read["turns"] == [], gap
+
+
+def test_the_box_tops_at_a_hundredth_of_the_body(monkeypatch):
+ """MASS_SHARE, the speck bound of sprite_gen/video/frames.py (SPECK_MIN_FRACTION): the box tops at the row with a
+ hundredth of the frame's solid pixels over it. A 6 px fleck over the head over frames 30-39 (36 px, under a
+ hundredth of the walker) does not top the box there, and no turn reads; a 7 px one (49 px, over it) tops it, its
+ frames read turned. Under the bound (0.005) the antenna over the head (31 px, 0.008 of the walker) tops the box 12
+ rows over the head and the walk reads a turn every stride; over it (0.0125) the 7 px fleck is under it, and its
+ frames read no turn."""
+ from sprite_gen.video import body_turn
+ from sprite_gen.video.frames import SPECK_MIN_FRACTION
+
+ assert body_turn.MASS_SHARE == SPECK_MIN_FRACTION == 0.01
+ six, seven = _frames(speck=range(30, 40), speck_side=6), _frames(speck=range(30, 40), speck_side=7)
+ antenna = _frames(part="antenna", cut=range(30, 40))
+ walker = sum(_frames()[0].getchannel("A").histogram()[body_turn.SOLID:])
+ assert 36 < body_turn.MASS_SHARE * walker < 49
+ assert body_turn.read(six)["turns"] == [] and body_turn.read(antenna)["turns"] == []
+ assert [(t["from"], t["to"]) for t in body_turn.read(seven)["turns"]] == [(30, 39)]
+ monkeypatch.setattr(body_turn, "MASS_SHARE", 0.005)
+ assert len(body_turn.read(antenna)["turns"]) == 3
+ monkeypatch.setattr(body_turn, "MASS_SHARE", 0.0125)
+ assert body_turn.read(seven)["turns"] == []
+
+
+def test_the_heads_centre_is_read_on_its_fullest_columns(monkeypatch):
+ """HEAD_CORE: the head's centre is the middle of the head band's columns holding at least half the fullest one's
+ pixels. Of the head band's 19 rows, a 6 px fleck beside the head in the still alone (in the head's rows, not over
+ them) holds 6 in each of its columns and an ornament cut loose beside it 7: under half a head column, they move no
+ centre. Read on columns of 0.3 of the fullest, the fleck's count, and the still's centre moves 1.5 px; on 0.35, the
+ ornament's, 0.9 px. Under TOL either way, the walk reads as it reads (no turn; the ornament's turn): each frame is
+ read against the still at its best within TOL px of its centre."""
+ from sprite_gen.video import body_turn
+
+ assert body_turn.HEAD_CORE == 0.5
+ centre = body_turn._body(_walker(0))[3]
+ fleck = _frames(speck=(0,), speck_at=BESIDE, speck_side=6)
+ ornament = _frames(loose="ornament", turns=[TURN])
+ assert body_turn._body(fleck[0])[3] == centre == body_turn._body(ornament[0])[3]
+ assert body_turn.read(fleck)["turns"] == [] and len(body_turn.read(ornament)["turns"]) == 1
+ monkeypatch.setattr(body_turn, "HEAD_CORE", 0.3)
+ assert body_turn.read(fleck)["turns"] == [] and 1 < body_turn._body(fleck[0])[3] - centre < body_turn.TOL
+ monkeypatch.setattr(body_turn, "HEAD_CORE", 0.35)
+ assert len(body_turn.read(ornament)["turns"]) == 1 and 0 < body_turn._body(ornament[0])[3] - centre < body_turn.TOL
+
+
+# --- the crop about the head's axis, the still at its best about it ------------------------------------------------
+
+
+def _grey(frame: Image.Image) -> Image.Image:
+ """The frame's silhouette alone: every pixel one grey, its alpha kept."""
+ grey = Image.new("RGBA", frame.size, (128, 128, 128, 0))
+ grey.putalpha(frame.getchannel("A"))
+ return grey
+
+
+def _beside(frames: list[Image.Image], at, size: tuple[int, int], gap: int = 6) -> list[Image.Image]:
+ """A piece `size` (w, h) px right of the head, `gap` px from its edge (x 163) and 2 rows under its top, in the
+ frames `at` — 6 px apart, BESIDE's place."""
+ for k in at:
+ top = 40 + round(3 * math.cos(4 * math.pi * k / CYCLE))
+ x, y = 164 + gap, top + BESIDE[1]
+ ImageDraw.Draw(frames[k]).rectangle((x, y, x + size[0] - 1, y + size[1] - 1), fill=(250, 220, 90, 255))
+ return frames
+
+
+def _moved(monkeypatch, frames: list[Image.Image], still: float = 0.0, rest: float = 0.0) -> None:
+ """The still's head centre read `still` px right of where it is read, every other frame's `rest` px."""
+ from sprite_gen.video import body_turn
+
+ real = body_turn._body
+
+ def moved(frame):
+ body = real(frame)
+ return (*body[:3], body[3] + (still if frame is frames[0] else rest))
+
+ monkeypatch.setattr(body_turn, "_body", moved)
+
+
+def test_a_body_that_is_its_own_mirror_crops_as_its_own_mirror():
+ """The walker's silhouette is its own mirror about the middle of its head's centre column (the head x 137-163, the
+ column 150), its side drawn in tone alone. Cropped about that axis, the box's edges where they fall, the still's
+ head and shoulders and its torso, every pixel one grey, are their own 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: one
+ grey, the head and shoulders lay 0.050 off their mirror and the torso 0.028, a side the still does not show (in its
+ own tones, the still read 0.146 off its mirror, 0.102 about the axis)."""
+ from sprite_gen.video import body_turn
+
+ still = _grey(_walker(0))
+ body = body_turn._body(still)
+ assert body[3] == 150.0
+ for rows in (body_turn.UPPER, body_turn.torso_rows(body_turn.neck(body))):
+ v, m, _ = body_turn._crop(still, body, rows)
+ assert 1 - float(v @ m) < 1e-6, rows
+ assert 0.1 < body_turn.read(_frames())["still_side"] < 0.11
+
+
+def test_a_still_read_off_its_heads_centre_reads_the_walk_as_it_is(monkeypatch):
+ """TOL and STEP: each frame is read against the still and against the still's mirror, each at its best of the crops
+ about every axis within 2 px of the still's head's centre, a quarter of a pixel apart. The walker with its still's
+ centre read up to a pixel either way of where it is (as a piece beside the head moves it) reads no turn, no frame's
+ side 0.07 from where it reads with the still read at its centre. torso-side-v1, reading about the centre alone, its
+ box's edges whole pixels, read the walk turned every stride with the still's centre 0.75 px right (least -0.06)."""
+ from sprite_gen.video import body_turn
+
+ frames = _frames()
+ plain = body_turn.read(frames)["side"]
+ for dc in (-1.0, -0.75, -0.5, -0.25, 0.25, 0.5, 0.75, 1.0):
+ with monkeypatch.context() as m:
+ _moved(m, frames, still=dc)
+ read = body_turn.read(frames)
+ assert read["read"] and read["turns"] == [], dc
+ assert max(abs(a - b) for a, b in zip(read["side"], plain)) < 0.07, dc
+
+
[email protected]("drawn, at, size",
+ [({}, (0,), (6, 6)), ({}, (0,), (3, 12)), ({"lead": 8}, range(30, 40), (3, 12))],
+ ids=["6x6-in-the-still", "3x12-in-the-still", "3x12-over-30-39-lead-in"])
+def test_a_piece_beside_the_head_that_moves_its_centre_moves_no_turn(drawn, at, size):
+ """36 px BESIDE the head, 6 px right of it and 2 rows under its top — a 6x6 near-square, or a column 3 wide and 12
+ tall — in the still alone, or over frames 30-39 of the walker filmed from 0.6 of its size for 8 frames: under a
+ hundredth of the walker. Each of the column's columns holds 12 of the head band's 19 rows, over HEAD_CORE's half,
+ and moves the head's centre 1.4 px right; read at its best within TOL px, the walk reads no turn, and the walker
+ turning over frames 30-40 reads its turn there. torso-side-v1, reading about the centre alone, read the walk with
+ either piece in the still turned over frames 1-72 (least -0.14), and with the column over frames 30-39 of the
+ lead-in walker turned there (least -0.18)."""
+ from sprite_gen.video import body_turn
+
+ read = body_turn.read(_beside(_frames(**drawn), at, size))
+ assert read["read"] and read["turns"] == []
+ (turn,) = body_turn.read(_beside(_frames(turns=[TURN], **drawn), at, size))["turns"]
+ assert TURN[0] <= turn["from"] and turn["to"] <= TURN[1]
+
+
+def test_a_still_is_read_where_its_head_and_shoulders_lie_0_08_off_their_mirror():
+ """SIDE_SHOWN_MIN 0.08, between the stills the synthetic walkers are read by and those seen square: the hooded
+ walker's head and shoulders lie 0.090 off their mirror at their best within GUARD px of the head's centre, the
+ walker filmed from 0.6 of its size for 8 frames 0.098, the plain walker 0.102; the walker seen square from behind
+ 0.0002, and with a 36 px piece beside its head in the still alone (a column 3 or 2 wide, a 6x6 near-square, against
+ the head or 6 px from it) 0.060 at most — not read, where a front or back walk with a piece beside the head in its
+ still, read, reads its walk against the side the piece shows."""
+ from sprite_gen.video import body_turn
+
+ for drawn in ({"hood": True}, {"lead": 8}, {}):
+ read = body_turn.read(_frames(**drawn))
+ assert read["read"] and 0.08 < read["still_side"] < 0.11, drawn
+ assert body_turn.SIDE_SHOWN_MIN == 0.08
+ sides = []
+ for size in ((3, 12), (2, 18), (6, 6)):
+ for gap in (0, 6):
+ read = body_turn.read(_beside(_frames(square=True), (0,), size, gap))
+ assert read["read"] is False and "square" in read["why"], (size, gap)
+ sides.append(read["still_side"])
+ assert 0.05 < max(sides) < 0.07
+
+
+def test_the_stills_side_is_read_about_its_nearest_mirror(monkeypatch):
+ """GUARD and STEP: the still's head and shoulders are read against their mirror about every axis within 2.5 px of
+ the head's centre, a quarter of a pixel apart, and their side is the least of them. The column 3 wide and 12 tall
+ 6 px right of the head in the still of the walker seen square moves its centre 1.4 px; about its nearest mirror the
+ still lies 0.060 off it, under SIDE_SHOWN_MIN, and the walk is not read (torso-side-v1, about the centre the column
+ moved, read it 0.199 off its mirror, and turns). About the axes within 2 px (GUARD 2), or a pixel apart (STEP 1), it
+ lies 0.093 off its mirror, and the walk, read, reads turns it does not make; with SIDE_SHOWN_MIN under its 0.060
+ (0.06), too. Over the hooded walker's 0.090 (0.095), the hooded walker is not read."""
+ from sprite_gen.video import body_turn
+
+ square = _beside(_frames(square=True), (0,), (3, 12))
+ read = body_turn.read(square)
+ assert read["read"] is False and 0.055 < read["still_side"] < body_turn.SIDE_SHOWN_MIN
+ assert (body_turn.GUARD, body_turn.STEP) == (2.5, 0.25)
+ for bound, value in (("GUARD", 2.0), ("STEP", 1.0), ("SIDE_SHOWN_MIN", 0.06)):
+ with monkeypatch.context() as m:
+ m.setattr(body_turn, bound, value)
+ read = body_turn.read(square)
+ assert read["read"] and read["turns"], bound
+ monkeypatch.setattr(body_turn, "SIDE_SHOWN_MIN", 0.095)
+ assert body_turn.read(_frames(hood=True))["read"] is False
+
+
+def test_each_frame_is_read_at_its_best_within_tol(monkeypatch):
+ """TOL: each frame is read against the still and its mirror at their best within 2 px of the still's head's centre.
+ The column 3 wide and 12 tall beside the head over frames 30-39 of the walker filmed from 0.6 of its size for 8
+ frames moves those frames' centres 1.4 px: read about the still's centre alone (TOL 0), they read turned. The side
+ walker with the 60 px tail (tests/video/test_walk_steps.py, the half step), its arms drawn: a 36 px column against
+ its head moves its centre 2.3 px. With every frame's centre read 3 px left of its own, the walk reads no turn; read
+ within 1 px of the still's centre, it reads a turn with them 2.25 px off."""
+ from sprite_gen.video import body_turn
+ from tests.video.test_walk_steps import _side
+
+ lead = _beside(_frames(lead=8), range(30, 40), (3, 12))
+ assert body_turn.read(lead)["turns"] == []
+ assert body_turn.TOL == 2.0
+ with monkeypatch.context() as m:
+ m.setattr(body_turn, "TOL", 0.0)
+ assert [(t["from"], t["to"]) for t in body_turn.read(lead)["turns"]] == [(30, 39)]
+ arms = [_side(k, cycle=29, tail_cycle=45, tail=60) for k in range(FRAMES)]
+ with monkeypatch.context() as m:
+ _moved(m, arms, rest=-3.0)
+ assert body_turn.read(arms)["turns"] == []
+ with monkeypatch.context() as m:
+ _moved(m, arms, rest=-2.25)
+ m.setattr(body_turn, "TOL", 1.0)
+ assert body_turn.read(arms)["turns"]
+
+
# --- what the reading cannot read ----------------------------------------------------------------------------------