Skip to content

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

fix(video-loop): a walk that reads square against a still that shows a side is not read, and a warning line says so (WALK_SIDE_MIN)

Soohong Kim96fb505ad2d5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c9349d3..b9ef6b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,12 +6,13 @@ 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-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"`).
+- **New: `video-loop` detects torso turns in walk and run clips and avoids them during the cut search.** A video model asked to walk at the still's angle sometimes turns the body inside the clip: a back-diagonal walk turns to a full back view half way and back. A loop cut across the turn plays the body swinging round. Until now the engine had no reading of this: the cut search could not avoid it, and a clip that held no cycle for it was refused only as `video-loop: no periodic cycle found`, so an app could not name that the body turned as the reason to film it again. The new module `sprite_gen/video/body_turn.py` introduces reading `torso-side-v2` on every walk or run under `--anchor motion-auto`, reading each frame's torso crop against the clip's first frame, the still the clip was filmed from, a standing pose. It does so whether or not the clip opens on a lead-in (the video model reframing the still to the walk's size over the first frames, which the cut search leaves out). It does not read against the first frame after the lead-in: that frame is a stride's pose, and a walk draws the mirror of a stride's pose half a cycle later, so a synthetic walk that does not turn, read against it, read a turn every stride (least -0.34). Read against the still filmed small, the same synthetic walk (its first 8 frames filmed from 0.6 of its size) reads +0.87 at least where it does not turn (+0.92 without the lead-in); turning over frames 30 to 40, its turn over frames 32 to 38, the same frames as without the lead-in, least -0.71 (-0.63 without the lead-in). The torso crop runs from the neck down half the body below it, centred on the head's centre, as wide as the first frame's torso. Each crop is cut about the head's axis between pixels, and the still and every frame are read at their nearest about the axes within `GUARD` (2.5 px) and `TOL` (2 px), `STEP` (0.25 px) apart, so a piece beside the head that moves its centre 1.4 px moves no turn. Under the module constant `MASS_SHARE` = 0.01, the box's top is read as the row with more than a hundredth of the frame's solid pixels above it, and the still's torso width is read about the head's centre from the columns of the still's torso rows with more than a hundredth of those rows' solid pixels beside them. Reading them by mass prevents a piece apart from the body from moving the box or the torso width. The box's bottom is the frame's last solid row, the one end of the box not read by mass: where the legs cross each stride they lay their pixels over each other, and a bottom read by mass (the row with a hundredth of the frame's solid pixels under it, as the top is read) rises with them (on the lead-in walker, a row over its last solid row in most frames and 3 rows over where the legs cross, moving the crop's rows with it), though read either way, the walkers turning over frames 30 to 40 and the 4-frame turns drawn from 8 places, with the lead-in and without it, read their turns over the same frames. Under `HEAD_CORE` = 0.5, the head's centre is read as the middle of the head band's columns that hold at least half the solid pixels of the band's fullest column, before being read again within `HEAD_REACH` as before. This stops a fleck or a cut-loose ornament beside the head from shifting the head's centre and falsely reading a turn across the clip or hiding the walk's turn. The neck is the narrowest row of the first frame between 10 % and 55 % of its height (the topmost on a tie, or row 0.11 on a hooded walker). Each frame's `side` correlation is `(v.s - v.m) / (1 - s.m)`, where each correlation is taken at its nearest about the axes within `TOL`. Under module constants `SIDE_SHOWN_MIN` = 0.08, `TURN_SIDE_MAX` = 0, and `TURN_RUN_MIN` = 4 consecutive frames, candidate windows whose cut holds a frame of a turn are refused with `the body turns (clip frames a-b)`, two-step cuts holding one are left out (`step_count.turned_out`), and held-side windows two lengths long are excluded. A new bound, `HEAD_REACH` = 0.3, re-reads the head's centre (the middle of the solid pixels of the top 15 % of the body) on the pixels within `HEAD_REACH` of the body's height of it until it settles, leaving the plain mass centre as before where no pixel of those rows lies further out. Clips without turns (or unread) are searched once as before with the same cut and bytes. A walk that reads square against a still that shows a side is not read either and is cut the same way, with a warning line (`WALK_SIDE_MIN`). Where no window without the turn holds a cycle, `--body-turn warn` (the default) reruns the cut search as before and keeps the cut with a warning line naming the turn, or refuses as before (`video-loop: no periodic cycle found`) after a warning line if no cut holds a cycle; while `--body-turn refuse` (requiring `--anchor motion-auto`) prints `video-loop: the body turns in the walk` as its first line, prescribes filming it again with the torso and hips kept at the still's angle, hands over nothing, and sets `status: failed`, supporting app retake rules such as `loop-body-turned`.
+- Report fields (`<name>.loop.report.json`): every walk or run report under `--anchor motion-auto` adds the `body_turn` object containing `reading` (`torso-side-v2`), `bounds` (`SIDE_SHOWN_MIN`, `WALK_SIDE_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_side`, `walk_side`, `read` (true or false), `why` (where not read), `neck`, `torso_still_side`, `side` (each frame's reading), `turns` (each `{from, to, least, at}`), `mode` (`warn` or `refuse`), `verdict`, `refused` (how many windows were refused for it), `cut` (`frames`, the cut's first and last clip frame, and `holds`, the turned frames it holds), `avoiding` (the search's refusal where the search that avoided the turn found nothing), and `unread` (a list of `{frames, why}`, each reason with the frames it applies to, appearing only where at least one frame was not read). The `verdict` field records one of `none` (read, no turn), `not-read` (a square still, a walk seen square, a first frame with no body, or a first frame the reading cannot read (no head to centre on, no solid pixel across its torso rows, or a crop of no width or with nothing in it)), `clear` (a turn, and the cut holds none of it without refusing anything), `avoided` (windows were refused for the turn and the cut leaves it out), `kept` (no cut without the turn holds a cycle; the cut taken before is kept, warned), `unfound` (no cycle with the turn or without it; refused as before, warned), or `refused` (`--body-turn refuse`). Where the still passes `SIDE_SHOWN_MIN` and the walk is seen square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing`. The command's JSON summary also gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.
+- Python callers: new module `sprite_gen.video.body_turn` provides `read(frames)`, `square(reading)`, `turns(side)`, `turned(reading)`, `neck(body)`, `torso_rows(at)`, class `Turn(reading, skip=0)` (callable as `(start, length)`, returning the refusal reason or None, `held(start, length)`, counter `refused`), `refusal(...)`, `kept(...)`, `unfound(...)`, constants `READING`, `SIDE_SHOWN_MIN`, `WALK_SIDE_MIN`, `TURN_SIDE_MAX`, `TURN_RUN_MIN`, `MODES` (`warn`, `refuse`), `NECK_RANGE` (0.10, 0.55), `HEAD_REACH` (0.3), `MASS_SHARE` (0.01, the same value as `frames.SPECK_MIN_FRACTION`), `HEAD_CORE` (0.5), `GUARD` (2.5), `TOL` (2.0) and `STEP` (0.25). Functions `local_cycle.detect`, `local_cycle.by_steps` and `local_cycle.counted` take a new keyword argument `turn` (a `Turn`, default None: as before). Function `loop.run_loop` takes `body_turn` (default `"warn"`).
- Output changes: a new named bound of the reading, `HEAD_REACH` = 0.3, re-reads the head's centre on the pixels within 0.3 of the body's height of it. The full test suite caught why it is needed: its side walker with a 60 px tail on a 45-frame beat (`tests/video/test_walk_steps.py`, the half-step case) read a turn on every swing (frames 8 to 15 and 53 to 60, least -0.19), because the tail swung up into the head's rows and pulled the head's centre aside. With `HEAD_REACH` it reads no turn (least +0.11) and is cut as before. Where no solid pixel of those rows lies within `HEAD_REACH` of their middle, the top's parts lie apart on either side of the middle (a prop held as high as the head and apart from it, or a body too small for any pixel to lie that near), and the top does not tell which part is the head, so the frame is not read instead of taking the largest part and centring on a prop that can weigh what the head does (on the test suite's 132 px synthetic staff walker, the ornament and the head hold the same number of solid pixels in those rows, 513 each, with no pixel within 39.6 px of the middle) and reading turns the body does not make. Where that frame is the first frame, the clip is not read and the cut search runs once as on any unread clip; cut by `video-loop` under default `--body-turn warn`, that synthetic staff walker is not read and is cut 11/24 (start 11, 24 frames), every byte as 3.3.0 cuts it.
-- 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.
+- Output changes: a new named bound of the reading, `WALK_SIDE_MIN` = 0.045, and report field `walk_side` in `body_turn` keep front and back walks whose still shows a side (from arm swings or pieces beside the head) from reading turns every stride. For each frame after the still, its head and shoulders (top 45 % of body) cropped about its head are compared with the still's head and shoulders and their mirror within `GUARD` (2.5 px); `walk_side` is the median of frame nearness to the still minus nearness to the mirror (v.s - v.m). Where the still passes `SIDE_SHOWN_MIN` and `walk_side` lies between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read`, `why` starts "the walk is seen square", and cuts match search alone. Angled walks lie 0.061 or more (the 447 synthetic turn windows 0.090 or more), whereas square walks lie 0.000 to 0.013. When square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side`, giving the still's side and `walk_side` in that parenthesis, naming a front or back walk or a body that turned for much of the walk to face the camera or to its mirror, saying its facing is not read, and ending `check the loop's facing`. Reading `walk_side` costs one more crop per frame.
+- Named limits: a piece apart from the body over a hundredth of body pixels is read as body: on synthetic walkers (3849 solid pixels), a 7 px fleck over frames 30 to 39 (49 px) tops the box, reading a turn. The box bottom is the last solid row: pieces under the feet (3 to 10 px square, 1 to 45 px under, across frames 30 to 39) stop turn reads, or return a verdict of `not-read` from about 25 px under in the still. Neck rows spaced 2 % of height apart shift grid steps on 1 px box changes. A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: of 863, 372, 808 and 148 placements of a piece under a hundredth of the body about the heads and torsos of four walkers that do not turn (in the still alone, in every frame but the still, or over frames 30 to 39), 11, 1, 22 and 0 leave the clip unread, each a piece in the still alone (21 of 34 right or left of the head at 6 or 20 px, 13 beside an arm) laying the still's head and shoulders under 0.08 off their nearest mirror. The piece-in-the-still case is now closed by `WALK_SIDE_MIN`: that square walker's still is read when `SIDE_SHOWN_MIN` is lowered to 0.06 (or `GUARD` set to 2, or `STEP` to 1), but its walk is not (`walk_side` 0.000); only with `WALK_SIDE_MIN` also at 0 does it read turns (frames 15 to 21 and 39 to 43). `GUARD` and `TOL` are pixels of the frame, so a larger body's margin narrows: the plain walker drawn 1.5, 2 and 3 times as large, with the 3 by 12 px column drawn as many times as large beside its head in the still moving the centre 1.8, 2.7 and 4.0 px, the walk reads least +0.78, +0.44 and +0.31 without turning. (a) A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn. (b) A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read. (c) A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006.
+- **Tests**: synthetic tests in new test file `tests/video/test_loop_body_turn.py` verify a 73-frame, 24-frame cycle back-diagonal walker seen from behind (legs side by side swinging half a cycle apart, arms either side swinging opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek toward the facing) whose turn moves its facing over to the still's mirror and back. Tests verify boundary turnovers: a torso reading of exactly 0 is not turned and one just under it is; three turned frames in a row are not a turn and four are; a frame not read ends a run; and `SIDE_SHOWN_MIN` set to the walker's own still side reads the clip and set just above it does not. The walker that turns reads one turn inside the frames it turns over and none elsewhere; the same walker not turning reads none; drawn square from behind it is not read. The same turn drawn on twos reads the same frames as on ones (within a frame), in fewer drawings. On a lead-in where the first 8 frames are filmed from 0.6 of the size (which the search leaves out), the report's `body_turn.reference` is 0, the turn reads over the frames it reads over without the lead-in (under -0.1), and the walk where it does not turn stays over +0.1; read from the first frame after the lead-in, the walk that does not turn is not read, and with `WALK_SIDE_MIN` at 0 it reads a turn every stride. A hooded walker with no neck reads its neck at the top row of the range (0.11) and finds the turn too, and finds none where it does not turn. The walker facing past its mirror 3 frames in a row reads no turn (however deep); 4 frames in a row read one turn of 4 frames. The suite's half-step side walker with a 60 px tail reads no turn at `HEAD_REACH` 0.3 and a turn every swing at 0.35. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.63), 3.3.0 cuts 22/24 (frames 22 to 45) across the turn, while this version refuses the windows that hold it and cuts 41/24 (frames 41 to 64); and turning over frames 14 to 24 and 24 to 34 where 3.3.0 cut 11/24 and 17/24 across the turn, this version cuts 35/24 and 41/24. When a walker turns in every cycle, `warn` keeps the cut the search took before, byte for byte, with the warning line, while `refuse` refuses it with `video-loop: the body turns in the walk` as the first line and hands nothing over. Walkers that do not turn and walkers drawn square are cut byte for byte as the search alone cuts them. The walker that turns (over frames 30 to 40) is cut with the cycle search replaced by one that finds no cycle in any window (as on a clip that holds no repeat), and its feet are not read; `warn` refuses it in the words it was refused in before (`video-loop: no periodic cycle found`), after the warning line naming the turn; `refuse` refuses it with `video-loop: the body turns in the walk`. Passing `--body-turn refuse` without `--anchor motion-auto` is refused. New synthetic tests in `tests/video/test_loop_body_turn.py` verify that the staff walker's still is not read; the staff over frames 20 to 29 and a 2 pixel sliver at frame 40 leave those frames null with their reason, every other frame reading as it reads without them; a pennant apart above the walker leaves the still's torso rows empty and the still unread; the pennant over frames 20 to 29 only leaves those frames' torso crops empty, so they are null, not 0; a head on a pole (one column under the head's centre) gives a crop of no width and the still is not read, and a frame of one solid pixel is null; a clip with no frames is not read; and under the default `warn`, the staff walker and the walker with the pennant in its first frame alone are cut byte for byte as the search alone cuts them, and the report says why they were not read. For `torso-side-v2`, new synthetic tests in `tests/video/test_loop_body_turn.py` verify that the 42 named walkers each read as drawn (a turn inside the frames it turns over, none where it does not, unread where the still cannot be read), the 7 px fleck reading its frames turned as the named limit; the antenna or whisker cut loose with a 3 px fleck at 186 placements reading no turn (marked slow); a piece apart under the feet over frames 30 to 39 (3, 6, 7 and 10 px; 1 to 45 px under) reading no turn; `MASS_SHARE` on both sides (the 6 px fleck and the antenna cut loose read no turn at 0.01, the 7 px fleck reads its frames turned at 0.01, the antenna tops the box and the walk reads three turns at 0.005, the 7 px fleck reads no turn at 0.0125, and the walker's 3849 px put a hundredth between 36 and 49); `HEAD_CORE` on both sides (at 0.5 neither the fleck beside the head in the still nor the ornament moves the still's centre, the fleck's walk reads no turn and the ornament walker reads its turn; at 0.3 the fleck moves the still's centre more than 1 px and less than `TOL` and the walk still reads no turn; at 0.35 the ornament moves it less than `TOL` and the turn still reads). The walker drawn in one grey crops as its own mirror about its head's axis (head and shoulders and torso under 1e-6 off it), and in its own tones its still lies 0.10 to 0.11 off its mirror; with the still's centre read 0.25 to 1 px off either way the walk reads no turn and no frame's side moves 0.07; a 6 by 6 px square or a 3 by 12 px column 6 px right of the head in the still, or the column over frames 30 to 39 of the lead-in walker, reads no turn, and the same walkers turning read their turn inside frames 30 to 40; the hooded, lead-in and plain stills lie between 0.08 and 0.11 off their nearest mirror, and the walker seen square with a 3 by 12 or 2 by 18 px column or a 6 by 6 px square against its head or 6 px from it in the still is not read (its side between 0.05 and 0.07); with `GUARD` 2, `STEP` 1 or `SIDE_SHOWN_MIN` 0.06 the square walker with the 3 by 12 px column has its still read but its walk not ("the walk is seen square"), and with `WALK_SIDE_MIN` at 0 as well it reads turns; `TOL` 0 reads the lead-in walker with the column over frames 30 to 39 turned there; and the side walker with a 60 px tail and its arms reads no turn with every frame's centre read 3 px left, where at `TOL` 1 it reads a turn with them 2.25 px left. The square walker taken 6, 3 or 9 frames into its stride, or 1, 2 or 11 frames with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still, has its still over `SIDE_SHOWN_MIN`, `walk_side` under 0.005, and is not read, while with `WALK_SIDE_MIN` at 0 it reads three turns. `walk_side` lies between 0.08 and 0.11 for the plain, hooded, lead-in, turning, hooded turning, turning-every-cycle and on-twos walkers, between 0.07 and 0.075 for the side walker with a 60 px tail on a 45-frame beat, and under 0.005 for the square walker taken 3, 6 or 9 frames on, and `WALK_SIDE_MIN` is 0.045. The walker turned to its mirror over frames 18 to 53 (36 of 73) is read with its turn over frames 20 to 51 and no warning, over 16 to 55 (40) is not read (`walk_side` under 0.005) and gets the warning (naming the turn to its mirror), as does the walker turned over 15 frames of each 24-frame cycle, and over 14 to 57 (44) is read with its turn over frames 16 to 55, `walk_side` under 0 and no warning. Cut by `video-loop`, the walker turned square at frame 24 and held to the end is not read (`verdict` `not-read`, `walk_side` under 0.01), prints exactly one warning line beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing` that gives the still's side and `walk_side` and names the turn to face the camera or to its mirror, and is cut every byte as the search alone cuts it, while the diagonal walker that does not turn and the walker drawn square print no such line.
## v3.3.0 - PyTorch RIFE backend for CUDA and CPU, executor for a GPU on another machine, and Linux CPU and cloud T4 release lanes
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 46953e4..84c9056 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -379,14 +379,17 @@ taken again from them (`--cycle fixed --start`) is the frames they name. A cut t
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 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.
+Each crop's axis is the middle of the head's centre column (the column c spans c to c + 1). The crop's edges lie where they fall, between pixels too: the crop is resampled from the frame about them, and mirrored about the axis. A body that is its own mirror about its head crops as its own mirror wherever its centre falls: the walker drawn all in one grey (its silhouette alone, its own mirror about the middle of column 150) reads its head and shoulders and its torso 0.000000 off their mirror. `torso-side-v1` rounded each edge of the box to a whole pixel and mirrored the crop about the box's middle, the column's edge, half a pixel off the axis: in one grey, the head and shoulders lay 0.050 off their mirror and the torso 0.028, a side the silhouette does not show. In its own tones the still reads 0.102 off its mirror (`torso-side-v1`: 0.146). The still and every frame are also read about the axes either side of the head's axis because a piece beside the head whose columns each hold over half the fullest column's pixels moves the head's centre: a column 3 px wide and 12 px tall, 6 px right of the head and 2 rows under its top (36 px, under a hundredth of the walker; each of its columns holds 12 of the head band's 19 rows), moves it 1.4 px. Read about the centre alone, `torso-side-v1` read the walk with that column in the still turned over frames 1 to 72 (least -0.14), and with the column over frames 30 to 39 of the lead-in walker turned there (least -0.18). `torso-side-v2` reads both with no turn (least +0.64 and +0.83), and the same walkers turning over frames 30 to 40 read their turn over frames 32 to 38. A 6 px square in the same place in the still holds 6 rows of each column, under `HEAD_CORE`, and moves no centre; `torso-side-v1`, which read the head's centre as the plain mass centre, read the walk with it turned over frames 1 to 72 (least -0.14). With the still's centre read 0.25 to 1 px off either way, the walk reads no turn and no frame's side moves 0.07 (at most 0.062, at 0.5 px); `torso-side-v1` read the walk turned every stride from 0.75 px right (least -0.06). Besides the crop about the head's axis, each crop is cut about the axes `STEP` (0.25 px) apart either side of it, each as wide as the crop about the axis. `GUARD` = 2.5 px: the still's head and shoulders, cropped about the axis, are read against their mirrors about every axis within 2.5 px of it; their side (`still_side`, the side `SIDE_SHOWN_MIN` bounds) is 1 minus the largest of those correlations, how far they lie off their nearest mirror. `TOL` = 2 px: the still's torso is cropped about every axis within 2 px of its head's axis, and mirrored about each. Each frame's torso, cropped about its own head's axis, is read against the still's torso and against its mirror at their nearest: in `side` = (v.s - v.m) / (1 - s.m), v.s is the largest of its correlations with those crops and v.m the largest with those mirrors, and s.m is the largest of the still's torso crop about its own axis with those mirrors (1 - s.m is the report's `torso_still_side`). At `GUARD` from 0 to 2.0, the walker seen square from behind with the 3 by 12 px column 6 px right of its head in the still alone lies 0.093 (at 2.0) to 0.256 (at 0) off its nearest mirror, over `SIDE_SHOWN_MIN`, so the still is read, but its walk lies 0.000 at the median (`walk_side`), under `WALK_SIDE_MIN`, so the clip is not read; with `WALK_SIDE_MIN` set to 0 as well, it reads turns it does not make (frames 15 to 21 and 39 to 43) at every one of those values; at 2.25 the still lies 0.075 off its nearest mirror and is not read. At 2.5 it lies 0.060 off it, at 3 and 4 0.053, and is not read. At `STEP` 1 px the same still lies 0.093 off its nearest mirror and is read, but its walk lies 0.000 and the clip is not read; with `WALK_SIDE_MIN` at 0 as well it reads turns (frames 3 to 9, 27 to 32 and 51 to 57); at 0.75 the still lies 0.075 off it and is not read; at 0.5 and under it is not read either. At `TOL` 0, the lead-in walker with a 3 by 12 or a 2 by 18 px column beside its head over frames 30 to 39 reads a turn over frames 30 to 39 (least -0.26 with the 3 by 12 px column, -0.25 with the 2 by 18); from 0.5 to 4 it reads none. Margins at `TOL` 2: with every frame's head centre but the still's read the same distance off, the lead-in walker first reads a turn 3.75 px right (frames 1 to 4), and the side walker with a 60 px tail and its arms 3.25 px left; at `TOL` 1, at 2.5 and 2.25 px. With the still's centre alone read off, no synthetic walker reads a turn within 4 px either way.
-Each frame's `side` = (v.s - v.m) / (1 - s.m), where v is the frame's crop, s the first frame's and m the first frame's mirrored about the head's centre (each a unit vector of luma times alpha and alpha); v.s and v.m are each taken at their largest over the first frame's torso crops and mirrors about the axes within `TOL` of its head's axis, and s.m at the largest of the first frame's own crop with those mirrors. A value of 1 means the torso shows the side the still shows; 0 means it is as near the still as its mirror (a body seen square from behind or in front); under 0 means it faces nearer the still's mirror. A pose the walk changes moves both correlations alike; a turn moves them apart. Each clip is read only against its own first frame, never against a named motion or direction. 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.
+Each frame's `side` = (v.s - v.m) / (1 - s.m), where v is the frame's crop, s the first frame's and m the first frame's mirrored about the head's centre (each a unit vector of luma times alpha and alpha); v.s and v.m are each taken at their largest over the first frame's torso crops and mirrors about the axes within `TOL` of its head's axis, and s.m at the largest of the first frame's own crop with those mirrors. A value of 1 means the torso shows the side the still shows; 0 means it is as near the still as its mirror (a body seen square from behind or in front); under 0 means it faces nearer the still's mirror. A pose the walk changes moves both correlations alike; a turn moves them apart. Each clip is read only against its own first frame, never against a named motion or direction. Four named module constants define the report field `bounds`, bounding whether the clip is read and what counts as a turn. `SIDE_SHOWN_MIN` = 0.08 sets how far the still's head and shoulders (the top 45 % of its body) lie off their nearest mirror about the axes within `GUARD` for the clip to be read at all. Under it the still is seen square (a front or back walk) and the facing is not read, because a back walk's far step lays its torso nearer its mirror each step. About their nearest mirror, the synthetic walkers seen at an angle lie 0.090 or more off it (the hooded walker 0.090, the lead-in walker 0.098, the plain walker 0.102, the side walker with a 60 px tail 0.397); the walker seen square from behind lies 0.0002 off it, and with a 36 px piece beside its head in the still alone (a 3 by 12 or 2 by 18 px column, or a 6 by 6 px square, against the head or 6 px from it, on either side) 0.049 to 0.060. At 0.06, the still of the square walker with the 3 by 12 px column 6 px right of its head is read, but its walk is not; at 0.095 the hooded walker is not read. The report field `walk_side` in `body_turn` and bound `WALK_SIDE_MIN` (0.045) gate front or back walks whose still alone shows a side. For each frame after the still, its head and shoulders (the top 45 % of the body, cropped about its head as wide as the still's crop) are compared with the still and its mirror within `GUARD` (2.5 px) of the still's head centre, giving nearness to the still minus nearness to the mirror (v.s - v.m); `walk_side` is the median across read frames. Where the still passes `SIDE_SHOWN_MIN` and `walk_side` falls between -0.045 and +0.045, the walk is seen square: `read` is false, `verdict` is `not-read` (`why` starting "the walk is seen square"), and the loop is cut as search alone cuts it. Under `--body-turn warn` and `refuse`, `video-loop` prints one warning line beginning "video-loop: warning: the walk reads square against a still that shows a side (still_side", giving the still's side and `walk_side`, naming what it can be (a front or back walk, or a body that turned for much of the walk, to face the camera or to its mirror), stating its facing is not read, and ending "check the loop's facing"; `body_turn.square(reading)` returns this text or None. `TURN_SIDE_MAX` = 0 marks any frame reading under 0 as turned. `TURN_RUN_MIN` = 4 requires 4 turned frames in a row or more to count as a turn. Turns are counted in frames, the time the clip plays them, not in drawings: a walk held on twos holds a turn as long as one drawn on ones, in half the drawings. A shorter dip is the walk's own. A synthetic walker facing past its mirror 3 frames in a row reads no turn even 0.61 under 0; 4 frames in a row read one. A clip with no turn (or one not read) is searched once, exactly as before: the same cut, the same bytes.
-Where no window without the turn holds a cycle, the flag `--body-turn` decides the outcome. Under `warn` (the default), the search runs again as before, and the cut it took before is kept with a warning line naming the turned frames, the least reading and its frame, the bound, the cut and the frames of the turn it holds. Where no cut holds a cycle at all, the clip is refused in the words it was refused in before (`video-loop: no periodic cycle found`), after a warning line naming the turn. An app that matches the old refusal lines keeps matching them. Under `refuse` (which needs `--anchor motion-auto`), the clip is refused in a line of its own, the first line the run prints: `video-loop: the body turns in the walk`. That line names the turned frames, the least reading and its frame, the bound, that no cut that leaves those frames out holds two steps that repeat (or, where a cut was found that holds the turn, which cut and which frames), and the prescription to film it again with the torso and hips kept at the still's angle. Nothing is handed over; the report is written with `status: failed`. App builders can attach a retake rule, such as `loop-body-turned`, to this refusal line. Every report on a walk or run under `--anchor motion-auto` includes the `body_turn` field: `reading` (`torso-side-v2`), `bounds` (the 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.
+Where no window without the turn holds a cycle, the flag `--body-turn` decides the outcome. Under `warn` (the default), the search runs again as before, and the cut it took before is kept with a warning line naming the turned frames, the least reading and its frame, the bound, the cut and the frames of the turn it holds. Where no cut holds a cycle at all, the clip is refused in the words it was refused in before (`video-loop: no periodic cycle found`), after a warning line naming the turn. An app that matches the old refusal lines keeps matching them. Under `refuse` (which needs `--anchor motion-auto`), the clip is refused in a line of its own, the first line the run prints: `video-loop: the body turns in the walk`. That line names the turned frames, the least reading and its frame, the bound, that no cut that leaves those frames out holds two steps that repeat (or, where a cut was found that holds the turn, which cut and which frames), and the prescription to film it again with the torso and hips kept at the still's angle. Nothing is handed over; the report is written with `status: failed`. App builders can attach a retake rule, such as `loop-body-turned`, to this refusal line. Every report on a walk or run under `--anchor motion-auto` includes the `body_turn` field: `reading` (`torso-side-v2`), `bounds` (the four), `reference` (0: the frame read against, the clip's first, lead-in or not), `still_side`, `walk_side`, `read` (true or false), `why` (where not read), `neck`, `torso_still_side`, `side` (each frame's reading), `turns` (each `{from, to, least, at}`), `mode` (`warn` or `refuse`), `verdict`, `refused` (how many windows were refused for it), `cut` (`frames`, the cut's first and last clip frame, and `holds`, the turned frames it holds), `avoiding` (the search's refusal where the search that avoided the turn found nothing), and `unread` (a list of `{frames, why}`, each reason with the frames it applies to, appearing only where at least one frame was not read). The `verdict` is one of `none` (read, no turn), `not-read` (a square still, a walk that reads square against a still that shows a side, a first frame with no body, or a first frame the reading cannot read (no head to centre on, no solid pixel across its torso rows, or a crop of no width or with nothing in it)), `clear` (a turn, and the cut holds none of it without refusing anything), `avoided` (windows were refused for the turn and the cut leaves it out), `kept` (no cut without the turn holds a cycle; the cut taken before is kept, warned), `unfound` (no cycle with the turn or without it; refused as before, warned), or `refused` (`--body-turn refuse`). The command's JSON summary gains `body_turn` (`verdict`, `turns`, `cut`) where a turn was read.
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.
+- A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn.
+- A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read.
+- A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006.
- A shallow turn: a three-quarter walk that turns to the side each stride reads shallow, and a dip under 4 frames, or one that does not go under 0, is the walk's own.
- It does not make a walk where there is none: where the frames before the turn do not repeat either, avoiding the turn finds no cycle; the reading changes the reason given, not the result.
- A body whose narrowest row in 10 % to 55 % of its height is its waist (no neck and a head narrower than its waist) has its crop start at the waist; no such body has been measured.
@@ -396,7 +399,7 @@ What it does not see:
- 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.
+- A front or back walk whose still shows a side because of a piece beside its head is now not read. This case is closed by `WALK_SIDE_MIN`: that square walker's still is read when `SIDE_SHOWN_MIN` is lowered to 0.06 (or `GUARD` set to 2, or `STEP` to 1), but its walk is not (`walk_side` 0.000); only with `WALK_SIDE_MIN` also at 0 does it read turns (frames 15 to 21 and 39 to 43). Where the still passes `SIDE_SHOWN_MIN` and the walk is seen square, `video-loop` prints one warning line under `--body-turn warn` and `refuse` alike, beginning "video-loop: warning: the walk reads square against a still that shows a side (still_side" and ending "check the loop's facing", giving the still's side and `walk_side`, naming what it can be (a front or back walk, or a body that turned for much of the walk, to face the camera or to its mirror), and stating that its facing is not read, while the cut and its bytes remain what the search alone makes.
- `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`.
diff --git a/sprite_gen/video/body_turn.py b/sprite_gen/video/body_turn.py
index c6efa52..7b1e2c9 100644
--- a/sprite_gen/video/body_turn.py
+++ b/sprite_gen/video/body_turn.py
@@ -16,7 +16,7 @@ size for 8 frames reads +0.87 at least where it does not turn (+0.92 filmed from
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:
+Four named bounds:
- 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,
@@ -24,6 +24,23 @@ Three named bounds:
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.
+- WALK_SIDE_MIN: how much nearer the still's head and shoulders than their mirror the walk's lie at the median, or
+ nearer the mirror's, for the clip to be read (`walk_side`: each frame after the still, its top 45 % cropped about its
+ own head as wide as the still's, against the still's and against its mirror, each at its nearest about the axes
+ within GUARD px of the still's centre, v.s - v.m). Under it either way the walk is seen square: a front or back walk
+ whose still shows a side its walk does not — a piece beside the head in the still alone, or the still taken where
+ the arms swing apart — lies as near the still's mirror as the still, each frame's mirror a frame of the walk half a
+ stride on, and read against the still it reads a turn every stride (the synthetic walker seen square from behind,
+ taken 6 frames into its stride, its still 0.148 off its mirror: turns over frames 7-17, 31-41 and 55-65; its walk
+ 0.000 at the median). A walk seen at an angle lies nearer the still's side (the plain walker 0.101, the hooded one
+ 0.090); one turned past the still's mirror over most of its frames lies nearer the mirror's, under 0, and is read with
+ its turn. 0.045 lies between the synthetic walkers seen at an angle, 0.061 at least (the side walker of
+ tests/video/test_walk_steps.py with a 60 px tail on a beat of its own), and those seen square: 0.000 with a piece
+ beside the head or the arms swung apart in the still, 0.013 the front walker of tests/video/test_walk_steps.py with a
+ 70 px tail. The frames alone do not tell a front or back walk whose still shows a side from a body that turned for
+ much of its walk, to face the camera or to its mirror (its frames square at the median, its still at an angle; the
+ named limits below): each is left unread, and `video-loop` says so in a warning line (`square`), the cut as the search
+ alone cuts it.
- TURN_SIDE_MAX: a frame whose torso reads under it is turned.
- TURN_RUN_MIN: a turn is that many turned frames in a row or more, counted in frames — the time the clip plays them —
not in drawings: a walk held on twos holds a turn as long as one drawn on ones does, in half the drawings. A shorter
@@ -63,9 +80,10 @@ stride. So each crop is read about the axes STEP (a quarter of a pixel) apart ei
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.
+ side SIDE_SHOWN_MIN bounds — and each frame's lie nearer them or their mirror, each at its nearest (WALK_SIDE_MIN).
+ 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 its walk, 0.000 at the median, is not read either way: read with
+ WALK_SIDE_MIN at 0, it 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
@@ -90,10 +108,12 @@ read). The neck is read on the still's rows 2 % of its height apart: a box a pix
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
+walkers). A walk turned over about half its frames lies as near the still's mirror as the still at the median, as a
+square walk does, and is not read: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their
+middle (38 to 41 hooded), or over 14 to 16 frames of each 24-frame cycle; over 38 or fewer (37 hooded), or 42 or more,
+it is read and its turn with it. One turned to square — a back-diagonal walk turned to a full back view — and held there
+over 41 of its 73 frames or more (40 hooded) is a square walk by its frames, and is not read either. Each of the three
+is left unread with the warning line (`square`), not in silence. 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
@@ -110,6 +130,7 @@ from sprite_gen.video.frames import SPECK_MIN_FRACTION
READING = "torso-side-v2"
SIDE_SHOWN_MIN = 0.08
+WALK_SIDE_MIN = 0.045
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
@@ -121,13 +142,14 @@ HEAD_SHARE = 0.15 # the head's centre: the middle of the solid pixels of the to
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.
+# nearest mirror about any within GUARD px (the side SIDE_SHOWN_MIN bounds), and each frame's against them and their
+# mirror (the walk's side, WALK_SIDE_MIN); 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
+UPPER = (0.0, 0.45) # the head and shoulders, read for SIDE_SHOWN_MIN and WALK_SIDE_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
CROP = (48, 64) # every crop is read at this size
@@ -270,10 +292,11 @@ def turns(side: list[float | None]) -> list[dict[str, Any]]:
def read(frames: list[Image.Image]) -> dict[str, Any]:
"""The clip's facing against its first frame (`frames`, the clip as keyed, RGBA): the record the loop report keeps
(`body_turn`) — the reading, its bounds, the frame read against (`reference`), the still's own side (`still_side`),
- whether it was read (`why` where not), the neck, each frame's `side` and the `turns`. A frame not read is None in
- `side`, and `unread` says why, each why with its frames (where any is)."""
- out: dict[str, Any] = {"reading": READING, "bounds": {"SIDE_SHOWN_MIN": SIDE_SHOWN_MIN, "TURN_SIDE_MAX": TURN_SIDE_MAX,
- "TURN_RUN_MIN": TURN_RUN_MIN},
+ whether it was read (`why` where not), the neck, the walk's side (`walk_side`: the median of the frames after the
+ still, where any is read), each frame's `side` and the `turns`. A frame not read is None in `side`, and `unread`
+ says why, each why with its frames (where any is)."""
+ out: dict[str, Any] = {"reading": READING, "bounds": {"SIDE_SHOWN_MIN": SIDE_SHOWN_MIN, "WALK_SIDE_MIN": WALK_SIDE_MIN,
+ "TURN_SIDE_MAX": TURN_SIDE_MAX, "TURN_RUN_MIN": TURN_RUN_MIN},
"reference": 0, "turns": []}
if not frames:
return {**out, "read": False, "still_side": None, "why": "the clip has no frames"}
@@ -284,8 +307,8 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
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}"}
- crops, mirrors, _ = upper
- out["still_side"] = round(1 - float((mirrors @ crops[len(crops) // 2]).max()), 4)
+ uppers, umirrors, uheld = upper
+ out["still_side"] = round(1 - float((umirrors @ uppers[len(uppers) // 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 "
@@ -302,6 +325,7 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
if shown <= 1e-6:
return {**out, "read": False, "why": "the still's torso is its own mirror: no side to read it by"}
side: list[float | None] = []
+ walk: list[float] = []
unread: dict[str, list[int]] = {}
for k, frame in enumerate(frames):
body = _body(frame)
@@ -312,6 +336,17 @@ def read(frames: list[Image.Image]) -> dict[str, Any]:
continue
v, _, _ = crop
side.append(round((float((crops @ v).max()) - float((mirrors @ v).max())) / shown, 4))
+ top = _crop(frame, body, UPPER, uheld) if k else None
+ if top is not None and not isinstance(top, str):
+ walk.append(float((uppers @ top[0]).max()) - float((umirrors @ top[0]).max()))
+ if walk:
+ out["walk_side"] = round(float(np.median(walk)), 4)
+ if abs(out["walk_side"]) < WALK_SIDE_MIN:
+ return {**out, "read": False,
+ "why": f"the walk is seen square: its frames' head and shoulders lie {out['walk_side']:+.3f} "
+ f"nearer the still's than their mirror at the median, under {WALK_SIDE_MIN:g} either way (a "
+ "front or back walk, or a body that turned for much of the walk), and its facing is not "
+ "read"}
out = {**out, "read": True, "side": side, "turns": turns(side)}
if unread:
out["unread"] = [{"frames": ks, "why": why} for why, ks in unread.items()]
@@ -364,6 +399,20 @@ def _over(reading: dict[str, Any]) -> str:
"frames or more)")
+def square(reading: dict[str, Any]) -> str | None:
+ """The warning of `video-loop` where the still is read and its walk reads square (WALK_SIDE_MIN): a front or back
+ walk whose still shows a side, or a body that turned for much of the walk — to face the camera (or away from it),
+ or to its mirror over about half of it — the frames alone not telling which; the clip not read, cut as the search
+ alone cuts it. None where it was not left unread so."""
+ side = reading.get("walk_side")
+ bound = reading["bounds"].get("WALK_SIDE_MIN", WALK_SIDE_MIN)
+ if reading.get("read") is not False or side is None or abs(side) >= bound:
+ return None
+ return (f"the walk reads square against a still that shows a side (still_side {reading['still_side']:.3f}, "
+ f"walk_side {side:+.3f}, under {bound:g} either way): a front or back walk, or a body that turned for much "
+ "of the walk — to face the camera, or to its mirror; its facing is not read; check the loop's facing")
+
+
def refusal(reading: dict[str, Any], *, cut: tuple[int, int] | None = None, held: list[int] | None = None) -> str:
"""The refusal of `--body-turn refuse`, after `video-loop: `: the turn, and that no cut without it holds two steps
that repeat — or, where a cut was found that holds it (`cut`, in the clip's frames, and its turned frames `held`),
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 4cf2190..563d9df 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -2021,12 +2021,15 @@ def _cut_loop(
# The body's turn (sprite_gen/video/body_turn.py), read on the clip as keyed against its first frame, the still,
# lead-in or not: a cut that holds a frame of one is not taken while another holds a cycle. Where none does,
# --body-turn warn takes the cut the search takes with the turn in, and says so; refuse refuses the clip in a line
- # of its own. A clip that turns nowhere is searched once, as before.
+ # of its own. A clip that turns nowhere is searched once, as before; one whose walk reads square against a
+ # still that shows a side is not read either, and a warning line says so.
turning = {**body_turn_mod.read(gait_frames), "mode": body_turn}
report_base["body_turn"] = turning
turn = body_turn_mod.Turn(turning, skip) if turning["turns"] else None
if turn is None:
turning["verdict"] = "none" if turning["read"] else "not-read"
+ if seen := body_turn_mod.square(turning):
+ print(f"video-loop: warning: {seen}", file=sys.stderr)
said: dict[str, Any] = {}
found = avoided = None
if turn is not None:
diff --git a/tests/video/test_loop_body_turn.py b/tests/video/test_loop_body_turn.py
index 41fee86..a268c02 100644
--- a/tests/video/test_loop_body_turn.py
+++ b/tests/video/test_loop_body_turn.py
@@ -16,9 +16,12 @@ The walker is a back diagonal seen from behind: legs side by side swinging half
opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek on the head
toward the facing. Over a turn the facing goes over to the still's mirror and back (`facing` 1 the still's three-quarter
view, 0 square from behind, under 0 past it), the arms' tones crossing. A walker drawn square from behind (`square`) is
-the back walk whose still shows no side. A frame the reading cannot read — no head to centre on, no solid pixel across
-the still's torso rows, a crop of no width or with nothing in it, no frames — is not read, never read as 0 or as a
-middle no pixel holds. Synthetic frames only."""
+the back walk whose still shows no side; taken into its stride, or with a piece beside its head in the still, its still
+shows one its walk does not, each frame's mirror a frame of the walk half a stride on, and the walk, as near the still's
+mirror as the still at the median (WALK_SIDE_MIN), is not read — as a walk that turned to square and stayed is not: the
+frames alone do not tell the two apart, and a warning line says so. A frame the reading cannot read — no head to centre
+on, no solid pixel across the still's torso rows, a crop of no width or with nothing in it, no frames — is not read,
+never read as 0 or as a middle no pixel holds. Synthetic frames only."""
from __future__ import annotations
@@ -52,10 +55,10 @@ def _facing(turns, t: float, low: float = LOW, edge: int = 3) -> float:
return f
-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, 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:
+def _walker(k: int, *, turns=(), every: tuple[int, int] | None = None, low: float = LOW, hold: int = 1,
+ square: bool = False, 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
@@ -68,15 +71,16 @@ def _walker(k: int, *, turns=(), every: tuple[int, int] | None = None, hold: int
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)."""
+ `droop` rows lower then). A turn goes over to `low`: LOW, past the still's mirror, or 0, square from behind."""
t = k - k % hold
ph = 2 * math.pi * t / CYCLE
if square:
f = 0.0
elif every is not None:
- f = _facing([(every[0] + c * CYCLE, every[0] + c * CYCLE + every[1]) for c in range(-1, FRAMES // CYCLE + 2)], t)
+ spans = [(every[0] + c * CYCLE, every[0] + c * CYCLE + every[1]) for c in range(-1, FRAMES // CYCLE + 2)]
+ f = _facing(spans, t, low)
else:
- f = _facing(turns, t)
+ f = _facing(turns, t, low)
im = Image.new("RGBA", (W, H))
d = ImageDraw.Draw(im)
x, y = 150, 40 + round(3 * math.cos(2 * ph))
@@ -268,11 +272,13 @@ 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):
+def test_a_lead_in_is_read_against_the_still(tmp_path, monkeypatch):
"""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 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."""
+ the walk draws half a cycle on — a walk that does not turn reads a turn every stride with WALK_SIDE_MIN at 0 (as
+ e54dc9c read it); its walk lies as near that frame's mirror as the frame at the median, as a square walk's does, and
+ it is not read."""
from sprite_gen.video import body_turn
report = _cut(tmp_path / "out", _keyed(tmp_path, turns=[TURN], lead=8))
@@ -284,6 +290,9 @@ def test_a_lead_in_is_read_against_the_still(tmp_path):
assert min(v for k, v in enumerate(turn["side"]) if k >= skip and not led["from"] - 2 <= k <= led["to"] + 2) > 0.1
steady = _frames(lead=8)
assert body_turn.read(steady)["turns"] == []
+ after = body_turn.read(steady[skip:])
+ assert after["read"] is False and abs(after["walk_side"]) < body_turn.WALK_SIDE_MIN
+ monkeypatch.setattr(body_turn, "WALK_SIDE_MIN", 0.0)
assert len(body_turn.read(steady[skip:])["turns"]) >= 2
@@ -599,8 +608,10 @@ def test_the_stills_side_is_read_about_its_nearest_mirror(monkeypatch):
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."""
+ lies 0.093 off its mirror; with SIDE_SHOWN_MIN under its 0.060 (0.06), the still is read too. Its walk lies as near
+ the still's mirror as the still (0.000 at the median), under WALK_SIDE_MIN, and is not read; with WALK_SIDE_MIN at
+ 0 as well, read, it reads turns it does not make. 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))
@@ -611,11 +622,81 @@ def test_the_stills_side_is_read_about_its_nearest_mirror(monkeypatch):
with monkeypatch.context() as m:
m.setattr(body_turn, bound, value)
read = body_turn.read(square)
+ assert read["read"] is False and read["still_side"] >= body_turn.SIDE_SHOWN_MIN, bound
+ assert abs(read["walk_side"]) < 0.005 and read["why"].startswith("the walk is seen square"), bound
+ m.setattr(body_turn, "WALK_SIDE_MIN", 0.0)
+ 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
[email protected]("taken, piece", [(6, None), (3, None), (9, None), (1, (6, 6)), (2, (3, 12)), (11, (2, 18))],
+ ids=["half-a-stride-on", "3-frames-on", "9-frames-on", "1-frame-on-6x6-beside",
+ "2-frames-on-3x12-beside", "11-frames-on-2x18-beside"])
+def test_a_square_walk_whose_still_shows_a_side_is_not_read(monkeypatch, taken, piece):
+ """WALK_SIDE_MIN: the walker seen square from behind, its still taken `taken` frames into its stride (half a stride
+ on, the arms swung furthest apart), alone or with a 36 px piece beside its head in the still: its still lies 0.096
+ to 0.148 off its mirror, over SIDE_SHOWN_MIN, and read against it the walk reads a turn every stride, each frame's
+ mirror a frame of the walk half a stride on (e54dc9c read the walker taken 6 frames on turned over frames 7-17,
+ 31-41 and 55-65). Its walk's head and shoulders lie as near the still's mirror as the still, 0.000 at the median,
+ under WALK_SIDE_MIN: not read, and cut as the search alone cuts it."""
+ from sprite_gen.video import body_turn
+
+ frames = [_walker(k + taken, square=True) for k in range(FRAMES)]
+ if piece:
+ frames = _beside(frames, (0,), piece)
+ read = body_turn.read(frames)
+ assert read["still_side"] >= body_turn.SIDE_SHOWN_MIN
+ assert read["read"] is False and read["turns"] == [] and abs(read["walk_side"]) < 0.005
+ assert read["why"].startswith("the walk is seen square: its frames' head and shoulders lie ")
+ monkeypatch.setattr(body_turn, "WALK_SIDE_MIN", 0.0)
+ assert len(body_turn.read(frames)["turns"]) == 3
+
+
+def test_a_walk_is_read_where_its_head_and_shoulders_lie_0_045_nearer_either_side():
+ """WALK_SIDE_MIN 0.045, between the synthetic walks seen at an angle, their frames' head and shoulders 0.07 nearer
+ the still's than their mirror at the median or more (the side walker with a 60 px tail on a beat of its own 0.072;
+ the hooded walker turning over frames 30-40 0.086, the plain walker 0.101), and those seen square whose still shows
+ a side, 0.000."""
+ from sprite_gen.video import body_turn
+
+ assert body_turn.WALK_SIDE_MIN == 0.045
+ for drawn in ({}, {"hood": True}, {"lead": 8}, {"turns": [TURN]}, {"turns": [TURN], "hood": True},
+ {"every": (6, 8)}, {"turns": [TURN], "hold": 2}):
+ read = body_turn.read(_frames(**drawn))
+ assert read["read"] and 0.08 < read["walk_side"] < 0.11, drawn
+ read = body_turn.read(_tail())
+ assert read["read"] and 0.07 < read["walk_side"] < 0.075
+ for taken in (3, 6, 9):
+ read = body_turn.read([_walker(k + taken, square=True) for k in range(FRAMES)])
+ assert read["read"] is False and abs(read["walk_side"]) < 0.005, taken
+
+
[email protected]("turns, walk, turned", [((18, 53), "read", (20, 51)), ((16, 55), "not read", None),
+ ((14, 57), "read", (16, 55))],
+ ids=["36-of-73", "40-of-73", "44-of-73"])
+def test_a_walk_turned_over_about_half_its_frames_is_not_read(turns, walk, turned):
+ """The walker turned to its mirror over 36 of its 73 frames lies nearer the still's side at the median, over 44
+ past its mirror's (walk_side under 0): each is read, its turn with it, and no warning. Over 40, half its frames on
+ either side, it lies as near the still's mirror as the still, as a square walk does, and is not read — a limit of
+ the reading, named in docs/video-pipeline.md (e54dc9c read its turn over frames 18-53) — with the warning line
+ (`square`), as the walker turned over 15 frames of each 24-frame cycle is."""
+ from sprite_gen.video import body_turn
+
+ read = body_turn.read(_frames(turns=[turns]))
+ if walk == "read":
+ assert read["read"] and abs(read["walk_side"]) >= body_turn.WALK_SIDE_MIN
+ assert [(t["from"], t["to"]) for t in read["turns"]] == [turned]
+ assert (read["walk_side"] < 0) == (turns[1] - turns[0] + 1 > FRAMES / 2)
+ assert body_turn.square(read) is None
+ else:
+ assert read["read"] is False and abs(read["walk_side"]) < 0.005 and read["turns"] == []
+ assert "or to its mirror" in body_turn.square(read)
+ every = body_turn.read(_frames(every=(8, 15)))
+ assert every["read"] is False and abs(every["walk_side"]) < 0.005 and body_turn.square(every)
+
+
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
@@ -774,11 +855,38 @@ def test_a_turn_every_cycle_keeps_the_cut_with_a_warning_or_is_refused(tmp_path,
@pytest.mark.slow
@pytest.mark.parametrize("drawn", [{}, {"square": True}], ids=["diagonal", "square"])
-def test_a_walk_that_does_not_turn_is_cut_as_before(tmp_path, monkeypatch, drawn):
- """No turn — read and none found, or a square still not read — and the cut is every byte the search alone made."""
+def test_a_walk_that_does_not_turn_is_cut_as_before(tmp_path, monkeypatch, capsys, drawn):
+ """No turn — read and none found, or a square still not read — and the cut is every byte the search alone made;
+ no warning line on either (the square still, showing no side, is left unread before its walk is read)."""
keyed = _keyed(tmp_path, **drawn)
+ capsys.readouterr()
report = _cut(tmp_path / "read", keyed)
assert report["body_turn"]["verdict"] == ("none" if not drawn else "not-read")
+ assert "the walk reads square" not in capsys.readouterr().err
+ with monkeypatch.context() as m:
+ _unread(m)
+ _cut(tmp_path / "unread", keyed)
+ _same_cut(tmp_path / "read", tmp_path / "unread")
+
+
+def test_a_walk_turned_to_face_the_camera_and_held_is_cut_as_before_with_a_warning(tmp_path, monkeypatch, capsys):
+ """The walker turned to square at frame 24 and held there to the end (49 of its 73 frames, as a side walk that turns
+ to face the camera and walks on toward it): its frames lie as near the still's mirror as the still at the median
+ (0.006), as a front walk's do with a piece beside the head in its still — the frames alone do not tell the two
+ apart, and e54dc9c read this one turned at every stride after frame 27. Not read, it is cut every byte as the search
+ alone cuts it, and a warning line says the walk reads square against a still that shows a side, with both
+ readings."""
+ keyed = _keyed(tmp_path, turns=[(24, 200)], low=0.0)
+ capsys.readouterr()
+ report = _cut(tmp_path / "read", keyed)
+ turn = report["body_turn"]
+ assert turn["read"] is False and turn["verdict"] == "not-read" and abs(turn["walk_side"]) < 0.01
+ assert turn["why"].startswith("the walk is seen square")
+ (line,) = [x for x in capsys.readouterr().err.splitlines() if "the walk reads square" in x]
+ assert line.startswith("video-loop: warning: the walk reads square against a still that shows a side (still_side ")
+ assert f"still_side {turn['still_side']:.3f}, walk_side {turn['walk_side']:+.3f}," in line
+ assert "to face the camera, or to its mirror" in line and line.endswith("check the loop's facing")
with monkeypatch.context() as m:
_unread(m)
_cut(tmp_path / "unread", keyed)