Skip to content

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

docs(video-sway): laying a region over the figure under it and the rim widened for the shear, in docs/video-pipeline.md section 6 and the CHANGELOG's Unreleased

Soohong Kim87d3b849daea
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09b4af1..3d43129 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,13 +21,15 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- Named limits: a piece apart from the body over a hundredth of body pixels is read as body: on synthetic walkers (3849 solid pixels), a 7 px fleck over frames 30 to 39 (49 px) tops the box, reading a turn. The box bottom is the last solid row: pieces under the feet (3 to 10 px square, 1 to 45 px under, across frames 30 to 39) stop turn reads, or return a verdict of `not-read` from about 25 px under in the still. Neck rows spaced 2 % of height apart shift grid steps on 1 px box changes. A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: of 863, 372, 808 and 148 placements of a piece under a hundredth of the body about the heads and torsos of four walkers that do not turn (in the still alone, in every frame but the still, or over frames 30 to 39), 11, 1, 22 and 0 leave the clip unread, each a piece in the still alone (21 of 34 right or left of the head at 6 or 20 px, 13 beside an arm) laying the still's head and shoulders under 0.08 off their nearest mirror. The piece-in-the-still case is now closed by `WALK_SIDE_MIN`: that square walker's still is read when `SIDE_SHOWN_MIN` is lowered to 0.06 (or `GUARD` set to 2, or `STEP` to 1), but its walk is not (`walk_side` 0.000); only with `WALK_SIDE_MIN` also at 0 does it read turns (frames 15 to 21 and 39 to 43). `GUARD` and `TOL` are pixels of the frame, so a larger body's margin narrows: the plain walker drawn 1.5, 2 and 3 times as large, with the 3 by 12 px column drawn as many times as large beside its head in the still moving the centre 1.8, 2.7 and 4.0 px, the walk reads least +0.78, +0.44 and +0.31 without turning. (a) A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn. (b) A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read. (c) A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006. (d) A frame is counted once only where under `HELD_MAX` of the drawing last counted's solid pixels flip: a part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise over `HELD_MAX` (at crf 28, some of the synthetic walker's held frames), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; over `WALK_SIDE_MIN` it is read and reads turns it does not make. And a drawing that flips under `HELD_MAX` of the drawing last counted (a large or slow walker where its stride turns) is taken for that drawing held and is not counted.
- **Tests**: synthetic tests in new test file `tests/video/test_loop_body_turn.py` verify a 73-frame, 24-frame cycle back-diagonal walker seen from behind (legs side by side swinging half a cycle apart, arms either side swinging opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek toward the facing) whose turn moves its facing over to the still's mirror and back. Tests verify boundary turnovers: a torso reading of exactly 0 is not turned and one just under it is; three turned frames in a row are not a turn and four are; a frame not read ends a run; and `SIDE_SHOWN_MIN` set to the walker's own still side reads the clip and set just above it does not. The walker that turns reads one turn inside the frames it turns over and none elsewhere; the same walker not turning reads none; drawn square from behind it is not read. The same turn drawn on twos reads the same frames as on ones (within a frame), in fewer drawings. On a lead-in where the first 8 frames are filmed from 0.6 of the size (which the search leaves out), the report's `body_turn.reference` is 0, the turn reads over the frames it reads over without the lead-in (under -0.1), and the walk where it does not turn stays over +0.1; read from the first frame after the lead-in, the walk that does not turn is not read, and with `WALK_SIDE_MIN` at 0 it reads a turn every stride. A hooded walker with no neck reads its neck at the top row of the range (0.11) and finds the turn too, and finds none where it does not turn. The walker facing past its mirror 3 frames in a row reads no turn (however deep); 4 frames in a row read one turn of 4 frames. The suite's half-step side walker with a 60 px tail reads no turn at `HEAD_REACH` 0.3 and a turn every swing at 0.35. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.63), 3.3.0 cuts 22/24 (frames 22 to 45) across the turn, while this version refuses the windows that hold it and cuts 41/24 (frames 41 to 64); and turning over frames 14 to 24 and 24 to 34 where 3.3.0 cut 11/24 and 17/24 across the turn, this version cuts 35/24 and 41/24. When a walker turns in every cycle, `warn` keeps the cut the search took before, byte for byte, with the warning line, while `refuse` refuses it with `video-loop: the body turns in the walk` as the first line and hands nothing over. Walkers that do not turn and walkers drawn square are cut byte for byte as the search alone cuts them. The walker that turns (over frames 30 to 40) is cut with the cycle search replaced by one that finds no cycle in any window (as on a clip that holds no repeat), and its feet are not read; `warn` refuses it in the words it was refused in before (`video-loop: no periodic cycle found`), after the warning line naming the turn; `refuse` refuses it with `video-loop: the body turns in the walk`. Passing `--body-turn refuse` without `--anchor motion-auto` is refused. New synthetic tests in `tests/video/test_loop_body_turn.py` verify that the staff walker's still is not read; the staff over frames 20 to 29 and a 2 pixel sliver at frame 40 leave those frames null with their reason, every other frame reading as it reads without them; a pennant apart above the walker leaves the still's torso rows empty and the still unread; the pennant over frames 20 to 29 only leaves those frames' torso crops empty, so they are null, not 0; a head on a pole (one column under the head's centre) gives a crop of no width and the still is not read, and a frame of one solid pixel is null; a clip with no frames is not read; and under the default `warn`, the staff walker and the walker with the pennant in its first frame alone are cut byte for byte as the search alone cuts them, and the report says why they were not read. For `torso-side-v2`, new synthetic tests in `tests/video/test_loop_body_turn.py` verify that the 42 named walkers each read as drawn (a turn inside the frames it turns over, none where it does not, unread where the still cannot be read), the 7 px fleck reading its frames turned as the named limit; the antenna or whisker cut loose with a 3 px fleck at 186 placements reading no turn (marked slow); a piece apart under the feet over frames 30 to 39 (3, 6, 7 and 10 px; 1 to 45 px under) reading no turn; `MASS_SHARE` on both sides (the 6 px fleck and the antenna cut loose read no turn at 0.01, the 7 px fleck reads its frames turned at 0.01, the antenna tops the box and the walk reads three turns at 0.005, the 7 px fleck reads no turn at 0.0125, and the walker's 3849 px put a hundredth between 36 and 49); `HEAD_CORE` on both sides (at 0.5 neither the fleck beside the head in the still nor the ornament moves the still's centre, the fleck's walk reads no turn and the ornament walker reads its turn; at 0.3 the fleck moves the still's centre more than 1 px and less than `TOL` and the walk still reads no turn; at 0.35 the ornament moves it less than `TOL` and the turn still reads). The walker drawn in one grey crops as its own mirror about its head's axis (head and shoulders and torso under 1e-6 off it), and in its own tones its still lies 0.10 to 0.11 off its mirror; with the still's centre read 0.25 to 1 px off either way the walk reads no turn and no frame's side moves 0.07; a 6 by 6 px square or a 3 by 12 px column 6 px right of the head in the still, or the column over frames 30 to 39 of the lead-in walker, reads no turn, and the same walkers turning read their turn inside frames 30 to 40; the hooded, lead-in and plain stills lie between 0.08 and 0.11 off their nearest mirror, and the walker seen square with a 3 by 12 or 2 by 18 px column or a 6 by 6 px square against its head or 6 px from it in the still is not read (its side between 0.05 and 0.07); with `GUARD` 2, `STEP` 1 or `SIDE_SHOWN_MIN` 0.06 the square walker with the 3 by 12 px column has its still read but its walk not ("the walk is seen square"), and with `WALK_SIDE_MIN` at 0 as well it reads turns; `TOL` 0 reads the lead-in walker with the column over frames 30 to 39 turned there; and the side walker with a 60 px tail and its arms reads no turn with every frame's centre read 3 px left, where at `TOL` 1 it reads a turn with them 2.25 px left. The square walker taken 6, 3 or 9 frames into its stride, or 1, 2 or 11 frames with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still, has its still over `SIDE_SHOWN_MIN`, `walk_side` under 0.005, and is not read, while with `WALK_SIDE_MIN` at 0 it reads three turns. The walker seen square from behind whose still shows a side, each drawing of one half of its stride held 2, 3 or 4 frames and each of the other half 1 frame (taken 2, 3, 6, 9 or 11 frames into its stride; alone, or with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still), is not read, with the warning line, and its `walk_side` is the same as drawn on ones (within 0.002 with a piece); with `WALK_SIDE_MIN` at 0 it reads turns. The plain, hooded, turning and hooded turning walkers held the same way have the same `walk_side` as on ones, read their turn over the frames that hold the drawings they turn over (drawings 30 to 40), and read none where they do not turn. The square walker held 3 and 1 frames over the two halves of its stride (taken 6 frames into its stride, alone or with a 6 by 6 px piece beside its head in the still), each held frame with 6 of its edge pixels cleared (under 0.2 % of its solid pixels), has the same `walk_side` as without the noise and is not read (with `HELD_MAX` at 0 it is read, with turns), while the turning walker held the same way with the same noise has the same `walk_side` as without it and reads its turn over the frames that hold drawings 30 to 40. Through libx264 (its default crf 23) and `video-frames`' keying (a slow test, skipped without ffmpeg), the square walker held 3 and 1 lies under 0.02 and is not read, and the turning walker held the same way reads its turn over the frames that hold drawings 30 to 40. The walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels, seen square from behind (taken 6 frames into its stride) is not read (`walk_side` under `WALK_SIDE_MIN`), and seen at an angle is read (`walk_side` over `WALK_SIDE_MIN`). `walk_side` lies between 0.08 and 0.11 for the plain, hooded, lead-in, turning, hooded turning, turning-every-cycle and on-twos walkers, between 0.07 and 0.075 for the side walker with a 60 px tail on a 45-frame beat, and under 0.005 for the square walker taken 3, 6 or 9 frames on, and `WALK_SIDE_MIN` is 0.045. The walker turned to its mirror over frames 18 to 53 (36 of 73) is read with its turn over frames 20 to 51 and no warning, over 16 to 55 (40) is not read (`walk_side` under 0.005) and gets the warning (naming the turn to its mirror), as does the walker turned over 15 frames of each 24-frame cycle, and over 14 to 57 (44) is read with its turn over frames 16 to 55, `walk_side` under 0 and no warning. Cut by `video-loop`, the walker turned square at frame 24 and held to the end is not read (`verdict` `not-read`, `walk_side` under 0.01), prints exactly one warning line beginning `video-loop: warning: the walk reads square against a still that shows a side (still_side` and ending `check the loop's facing` that gives the still's side and `walk_side` and names the turn to face the camera or to its mirror, and is cut every byte as the search alone cuts it, while the diagonal walker that does not turn and the walker drawn square print no such line.
-**Upgrading from 3.5.0: `video-sway` can move each region as one mass with `--band`.** When `--band` is left out, strips, frames, and records remain byte for byte what they were. Passing `--band PX|auto` moves each region's ellipse and an outer margin at full weight, with the weight falling to 0 by cos² over a band of pixels around it, while carrying the region by its own pixels rather than the body's outline lay. The fifth region number `flat` and `--stretch-floor` are refused when `--band` is specified. In the strip's metadata, `follow` gains `band` (and `sway.json` gains `band` for `--frames`), while stdout JSON gains `band` with `band_px`, `margin_px`, and `lay_cells`. The legacy command name `video-follow` accepts the same flags. `video-sway --band` can now hold pixels with `--hold-mask`, leaving them as they are while regions move round them. It is off by default, and when not given, strips, frames, and records remain byte for byte as before. `video-sway` can now move a region's own pixels with `--region-mask`, holding every visible pixel outside it and its soft edge while the weight falls over an inner rim read off the move. It is off by default, and when not given, strips, frames, and records remain byte for byte what they were (with `--band`, with `--band` and `--hold-mask`, and with neither).
+**Upgrading from 3.5.0: `video-sway` can move each region as one mass with `--band`.** When `--band` is left out, strips, frames, and records remain byte for byte what they were. Passing `--band PX|auto` moves each region's ellipse and an outer margin at full weight, with the weight falling to 0 by cos² over a band of pixels around it, while carrying the region by its own pixels rather than the body's outline lay. The fifth region number `flat` and `--stretch-floor` are refused when `--band` is specified. In the strip's metadata, `follow` gains `band` (and `sway.json` gains `band` for `--frames`), while stdout JSON gains `band` with `band_px`, `margin_px`, and `lay_cells`. The legacy command name `video-follow` accepts the same flags. `video-sway --band` can now hold pixels with `--hold-mask`, leaving them as they are while regions move round them. It is off by default, and when not given, strips, frames, and records remain byte for byte as before. `video-sway` can now move a region's own pixels with `--region-mask`, holding every visible pixel outside it and its soft edge while the weight falls over an inner rim read off the move. It is off by default, and when not given, strips, frames, and records remain byte for byte what they were (with `--band`, with `--band` and `--hold-mask`, and with neither). New options `--region-over` and `--region-shear` shape the region mask and its rim; both are off by default, and when not given, strips, frames, and records remain byte for byte what they were. Runs with `--region-crease` now leave the crease edge where it is after wear, changing their output, while runs without `--region-crease` are byte for byte as before.
- **New: banded sway moving regions as one mass (`--band`, `--band-margin`, `--band-up`).** `--band PX|auto` keeps the weight at 1 over each region's ellipse expanded by the margin in every direction (the flat part), falling from 1 to 0 by cos² over a band of `PX` px past it, leaving pixels outside the band unchanged byte for byte. `--band-margin PX|auto` (default `auto`, `ceil(reach) + 1`) sets how far past the ellipse the weight stays 1. `--band auto` sets the band to `ceil(reach x pi / 2) + 1`, the narrowest band that does not fold. Reach is evaluated first at the requested `--gain`, after which band and margin are determined in two stages. The fold rule reads the narrowest band instead of radius, refusing moves where `reach x pi / (2 x band) >= 1` or lowering gain under `--on-fold lower`. `--band-up FLAT[,PX|auto]` shapes the area above the centre separately, stopping the flat part `FLAT` of the vertical radius above the centre and falling over `PX` px (defaulting to the band or `HANG_PAST` of 3 px above the top, whichever is further) so upper regions yield while the rest moves whole. Where the flat ellipse and the outer one differ in shape (above the centre under `--band-up`, where the flat part is short and the band long), the band measured across its ring is narrower than its px, so the weight falls steeper than the fold rule reads. After the fold rule, each region's steepest slope along the move is read over every pixel of every cell (`band_steepest`: per unit of gain, the most of the move at gain 1 dotted with the weight's gradient, the gradient read between each pixel's neighbours, and the cell where it is). A pixel moved by gain `g` keeps `1 - g x steepest` of its area, so a region folds where `g x steepest >= 1`. Then `--on-fold refuse` refuses, saying that `--band`'s weight falls steeper than its px where the band is narrower across its ring, in which cell and what area a pixel keeps at the gain asked, and to lower `--gain` or give a wider `--band` (or `--band-up`, when it was given); `--on-fold lower` lowers that region's gain to the largest whole number of `0.01` steps, no more than the gain it had, whose steepest slope stays under 1 (`steepest_gain`); a region that would have to go under gain 1 is held, and the run is refused only when every region is held, as the fold rule does. Each region is carried across cells in the loop's order from the cell the region was read on by its own solid pixels under the ellipse within `CARRY_SEARCH` (9) px of where the cell before had the region's pixels (around the cell's own body lay only where the cell before was carried by the lay, or is the cell the region was read on; or, with `--reference`, for the first cell) using least squared difference of premultiplied colour and subpixel parabolic fitting; uncertain matches revert to the outline lay and warn on stderr. See [video-pipeline](docs/video-pipeline.md) section 6.
- **New: holding pixels through banded sway (`--hold-mask`).** `--hold-mask MASK.png|DIR` leaves pixels as they are while a band moves its regions round them, requiring `--band` and off by default, byte for byte as before when not given. The mask is a PNG drawn on the cell the regions were read on (holding pixels where alpha is 128 or more; where the PNG has no alpha, grey 128 or more) or a folder of PNGs giving one mask per cell in file-name order. One mask is split into 8-connected pieces, each carried into every cell by its own solid pixels within `CARRY_SEARCH` (9) px by least squared difference of premultiplied colour and parabolic fitting (reverting to body lay with a warning on stderr when uncertain or covering no solid pixel), then grown by `HOLD_GROW` (3) px. Each cell keeps byte for byte the mask pixels, soft edges, and air within `ceil(reach) + HOLD_EDGE` (2) px. Other pixels are read short of kept pixels along the move direction by `f = min(s, h)` px, where `h` is `HOLD_SLOPE` (0.5) times free distance to kept or margin pixels (`HOLD_MARGIN` of 1 px), bounded to rise by at most `HOLD_SLOPE` per pixel (`read_share`). Reads touching forbidden pixels are renormalised or walked back by 1/`HOLD_STEPS` (1/16) of their move. Metadata gains `follow.hold` (and `sway.json` gains `hold` for `--frames`), while stdout JSON gains `hold` with `pieces`, `lay_cells`, and `read_folded_px_max`.
-- **New: a region given as a mask (`--region-mask`, `--region-rim`, `--region-shrink`, `--region-crease`).** `--region-mask MASK.png|DIR` gives the region as a mask of the part's own pixels instead of the ellipse's weight, moving the part while holding every visible pixel outside it and its soft edge in every cell, off by default and byte for byte as before when not given. The mask is a PNG drawn on the cell the regions were read on (alpha 128 or more, or grey 128 or more where it has no alpha) or a folder of PNGs giving one mask per cell in file-name order. When requested, `--region-crease` aligns the mask's lower edge to the median darkest row from `CREASE_UP` (5) rows above to `CREASE_DOWN` (3) rows below over `CREASE_SPAN` (2) columns either way, and `--region-shrink PX` (default `SHRINK_DEFAULT`, 2) wears the mask in by 4-neighbour steps. One mask is carried into each cell by its own solid pixels within `CARRY_SEARCH` (9) px by least squared difference of premultiplied colour, searching round the cell before and the body's lay, keeping the carry of the cell before when neither settles. The region and its soft edge (pixels not opaque within `REGION_SOFT`, 2, px of the region, not beside another solid pixel) move, and the air (clear pixels within `ceil(reach) + REGION_AIR`, 2, px of the region) is where they may move into; every other visible pixel is held. Inside the region, its soft edge and the air, weight rises by `sin²(pi/2 x d)` from 0 at held pixels to 1 across a rim scaled by `--region-rim SCALE` (default `RIM_DEFAULT`, 1.0) and widened until slope is at most `RIM_SLOPE` (0.9), preventing folding. With `--band-up`, weight is the lesser of the rim and the upper yield. Strip metadata gains `follow.region_mask` (and `sway.json` gains `region_mask` for `--frames`), while stdout JSON gains `region_mask` with `kept_cells`, `rim_px`, `move_most_px`, and `walked_px_max`. See [video-pipeline](docs/video-pipeline.md) section 6.
+- **New: a region given as a mask (`--region-mask`, `--region-rim`, `--region-shrink`, `--region-crease`).** `--region-mask MASK.png|DIR` gives the region as a mask of the part's own pixels instead of the ellipse's weight, moving the part while holding every visible pixel outside it and its soft edge in every cell, off by default and byte for byte as before when not given. The mask is a PNG drawn on the cell the regions were read on (alpha 128 or more, or grey 128 or more where it has no alpha) or a folder of PNGs giving one mask per cell in file-name order. When requested, `--region-crease` aligns the mask's lower edge to the median darkest row from `CREASE_UP` (5) rows above to `CREASE_DOWN` (3) rows below over `CREASE_SPAN` (2) columns either way, and `--region-shrink PX` (default `SHRINK_DEFAULT`, 2) wears the mask in by 4-neighbour steps. With `--region-crease`, after the mask is worn in, each column the crease ended where the worn mask still holds a pixel is filled back down to the crease row with the mask's pixels before wear (`crease_kept`), leaving the crease edge where it is while wearing in the rest of the mask; the record's `mask.box` now ends on the crease row. One mask is carried into each cell by its own solid pixels within `CARRY_SEARCH` (9) px by least squared difference of premultiplied colour, searching round the cell before and the body's lay, keeping the carry of the cell before when neither settles. The region and its soft edge (pixels not opaque within `REGION_SOFT`, 2, px of the region, not beside another solid pixel) move, and the air (clear pixels within `ceil(reach) + REGION_AIR`, 2, px of the region) is where they may move into; every other visible pixel is held. Inside the region, its soft edge and the air, weight rises by `sin²(pi/2 x d)` from 0 at held pixels to 1 across a rim scaled by `--region-rim SCALE` (default `RIM_DEFAULT`, 1.0) and widened until slope is at most `RIM_SLOPE` (0.9), preventing folding. With `--band-up`, weight is the lesser of the rim and the upper yield. Strip metadata gains `follow.region_mask` (and `sway.json` gains `region_mask` for `--frames`), while stdout JSON gains `region_mask` with `kept_cells`, `rim_px`, `move_most_px`, and `walked_px_max`. See [video-pipeline](docs/video-pipeline.md) section 6.
+- **New: laying a region over the figure and widening the rim for shear (`--region-over`, `--region-shear`).** `--region-over` lays the region over the figure under it instead of pinning its lower edge, freeing held pixels under the edge (solid or not), moving the band within reach, drawing the layer over band and air pixels by alpha, and showing the figure under the region in its own column where it lifts. Its soft edge moves with the region (except under the lower edge where touching a solid pixel outside keeps it in the band), its solid outline against air goes with the layer, and `--hold-mask` leaves pixels out of the layer and band. `--region-shear S` widens the rim across and down so a move one way rises across the rim the other way by at most S px per px (`shear_floor`), preventing tears along the sides. With either option, the ledger records move steps between neighbouring pixels, still strips left standing, and tip outline shapes, and `--region-over` records `lifted_px`. Both require `--region-mask`, are off by default, and leave strips, frames, and records byte for byte what they were when not given. See [video-pipeline](docs/video-pipeline.md) section 6.
- Python callers: `sway_loop`, `sway_frames`, `read_request`, and `read_ask` accept `band`, `band_margin`, and `band_up` (`band_up` as `(flat, px_or_"auto")` or command-line string). New in `sprite_gen.video.sway`: `band_weight`, `band_shapes`, `carry_match`, `carry_own`, `band_steepest`, `steepest_gain`, `band_ledger`, `band_notes`, and `jacobian` (moved from `sway_inspect`, which retains it under the same name); constants `BAND_POLICY`, `CARRY_BASIS_BAND`, `CARRY_SEARCH`, `HANG_PAST`, `PRESSED`, `STRETCHED`, `MOVED_PX`, and `AUTO`; and methods `Answer.band_field(k, xx, yy)` and `Answer.band_record()`. `sway_loop`, `sway_frames`, `read_request`, and `read_ask` accept `hold_mask` (a Path to a PNG or folder; None: off); new in `sprite_gen.video.sway`: `Hold`, `read_hold`, `Held`, `hold_sets`, `free_back`, `read_share`, `draw_held`, `hold_ledger`, `hold_notes`, and `carry_mask`; constants `HOLD_POLICY`, `HOLD_GROW`, `HOLD_EDGE`, `HOLD_MARGIN`, `HOLD_SLOPE`, `HOLD_ROUND`, and `HOLD_STEPS`; `Ask.hold`, `Answer.hold`, `Answer.held_cell(k)`, and `Answer.hold_record()`; and `carry_own` now calls `carry_mask` (same behaviour).
- Python callers: `sway_loop`, `sway_frames`, `read_request`, and `read_ask` accept `region_mask` (a Path to a PNG or a folder; None: off), `region_rim` (float; None: 1.0), `region_shrink` (int; None: 2), and `region_crease` (bool); new in `sprite_gen.video.sway`: `RegionMask`, `Masked`, `crease_of`, `carry_region`, `rim_bands`, `rim_distance`, `region_sets`, `region_ledger`, and `region_notes`; constants `REGION_POLICY`, `RIM_SLOPE`, `RIM_DEFAULT`, `SHRINK_DEFAULT`, `REGION_SOFT`, `REGION_AIR`, `CREASE_UP`, `CREASE_DOWN`, and `CREASE_SPAN`; `Ask.mask`, `Answer.mask`, `Answer.mask_field(k, xx, yy)`, `Answer.masked_cell(k)`, and `Answer.mask_record()`; and `draw_held` gains `short` (default true; false reads every pixel at its whole move).
+- Python callers: `sway_loop`, `sway_frames`, `read_request` and `read_ask` accept `region_over` (bool; default False) and `region_shear` (float; None: off). New in `sprite_gen.video.sway`: `crease_kept`, `shear_floor`, `layer_sets`, `lay_over`, `cover_depth`, `still_strip`, `tip_shape` and `move_steps`; constants `OVER_POLICY`, `TIP_COLS`, `TIP_AIR`, `TIP_RING`, `TIP_OFF` and `TIP_SEARCH`; `RegionMask` gains `over`, `shear`, `hold` and `edges()`; `Masked` gains `sheared`, `left_out` and `left_out_in(k)`; `rim_bands` gains `floor` (None: as before).
- Record fields: `follow.band` in strip metadata and `band` in `sway.json` record `policy` (`own-pixels/margin-band-cos2/1`), `asked` (`{band, margin, up}`), `reach_px`, `band_px`, and `margin_px`. They record per-region `flat_px` and `band_px` (across, above, below); per region in `follow.band.regions[i]`, `steepest`: `per_gain` (the slope per unit of gain), `cell`, and `ratio` (the region's gain times `per_gain`, under 1 on any written strip); `carry` with `search_px` (9) and per-cell, per-region `px`, `from` (`base`, `pixels`, or `lay`), `why` for lay, `least`, and `curvature`; `lay` entries for cells carried by lay; and `ledger` lists per cell (with `<key>_max` values) for `band_on_regions_px`, `pressed_px`, `stretched_px`, `pressed_box`, `stretched_box`, `area_least`, `area_most`, `outside_moved_px`, and `jacobian_min`. Only the four counts warn: `band_on_regions_px`, `pressed_px`, `stretched_px`, and `outside_moved_px`. For each that is not 0 in some cell, one warning line on stderr says in how many cells, up to how many px and in which cell (for `pressed_px` and `stretched_px` also the least or the most area and where), and ends with the record key: `follow.band.ledger.<key>` on `--loop-dir`, `sway.json band.ledger.<key>` on `--frames`. The lay warning names its record key the same way: `follow.band.lay` on `--loop-dir`, `sway.json band.lay` on `--frames`. `jacobian_min` (the least area of the source any pixel of a moved cell takes, per cell) gives no warning: it is recorded, and 0 or under in any cell refuses the run as the last check, named the engine's fault, nothing written. Command stdout JSON gains `band` containing `band_px`, `margin_px`, and `lay_cells`.
- Record fields: `follow.hold` in strip metadata and `hold` in `sway.json` record `policy` (`own-pixels-grown/kept-edge-air/read-short-sloped/1`), `asked` (`per_cell`, and `sha256`: the file's, or a list per file for a folder), `grow_px` (3; null for a folder), `edge_px`, `margin_px` (1), `slope` (0.5), `round_px` (1), and `steps` (16). They record `pieces` with each piece's `px` and `box` (`x0`, `y0`, `x1`, `y1`) on the cell it was drawn on (empty for a folder); `carry` with `search_px` (9) and per-cell, per-piece `px`, `from` (`base`, `pixels`, or `lay`), `why` for lay, `least`, and `curvature` (null for a folder); `lay` entries (`{cell, piece, why}`) for pieces carried by lay; and `ledger` lists per cell (with `<key>_max` values) for `held_px`, `soft_px`, `air_px`, `short_px`, `renormalised_px`, `walked_px`, `read_folded_px`, `read_folded_edge_px`, `read_least`, `read_turn_folded_px`, and `read_turn_least`. Warning lines on stderr report a piece carried by the lay (in how many cells and why), ending with the record key: `follow.hold.lay` on `--loop-dir`, `sway.json hold.lay` on `--frames`. For `renormalised_px`, `walked_px`, and `read_folded_px`, when not 0 in some cell, one warning line on stderr says in how many cells, up to how many px and in which cell, ending with the record key: `follow.hold.ledger.<key>` on `--loop-dir`, `sway.json hold.ledger.<key>` on `--frames`. Command stdout JSON gains `hold` containing `pieces`, `lay_cells`, and `read_folded_px_max`.
- Record fields: `follow.region_mask` in strip metadata and `region_mask` in `sway.json` record `policy` (`own-pixels-mask/held-outside/rim-sin2/1`), `asked` (`per_cell`, `sha256`: the file's, or a list per file for a folder, `rim`: the scale, `shrink_px`, `crease`: true/false, and `up`: `{flat, band}` or null), `soft_px` (2), and `air_px` (`ceil(reach) + 2`). They record `rim` (`across_px` for Lx, `down_px` for Ly, `least_px`: the two bands it started at, `slope`: the steepest `(pi/2) x sqrt(...)` over the cells, and `slope_bound`: 0.9); `mask` (`px`: its pixel count as worn in, `box`, and `carried_by_px`: the solid pixels it was carried by; null for a folder); `crease` (per mask, `rows`: each column's row, keyed by column, and `free_columns`; null when not asked); `carry` (`search_px` of 9 and `cells`: per cell `px`, `from`: `base`, `pixels` or `before`, `guess`: `before` or `lay` where carried by its pixels, `why` where it kept the cell before's carry, `least`, and `curvature`; null for a folder); `kept` entries (`{cell, why}`) for cells keeping the carry of the cell before; `up` containing the upper yield's shape as a band's record (`reach_px`, `band_px`, `margin_px`, per region `flat_px`, `band_px` and `steepest`, its `carry` and `lay`; null without `--band-up`); and `ledger` lists per cell (with `<key>_max` values) for `region_px`, `soft_px`, `air_px`, `held_px`, `held_changed_px` (0), `move_most` ([px, x, y] of the region pixel that moves most; null where none moves) with `move_most_max`, `pressed_px`, `pressed_box`, `area_least`, `stretched_px`, `stretched_box`, `area_most`, `folded_px`, `jacobian_min`, `read_held_weight` ([weight, x, y]; null where none), `read_held_half_px`, `renormalised_px`, and `walked_px`. Warning lines on stderr report cells that kept the carry of the cell before (ending `follow.region_mask.kept`), a region whose `--band-up` yield was carried by the lay (ending `follow.region_mask.up.lay`), and for `held_changed_px`, `pressed_px`, `stretched_px`, `read_held_half_px`, `renormalised_px` and `walked_px` when not 0 in some cell, one line reports in how many cells and up to how many px (with area and location for pressed and stretched), ending with `follow.region_mask.ledger.<key>` on `--loop-dir` or `sway.json region_mask.ledger.<key>` on `--frames`. Command stdout JSON gains `region_mask` containing `kept_cells`, `rim_px` ([Lx, Ly]), `move_most_px`, and `walked_px_max`.
@@ -77,6 +79,22 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- each refusal leaves the loop as it was;
- the ledger counts each cell, and the warning lines and the stdout JSON say what is in it.
`tests/video/test_follow_inspect.py` now names `--region-mask`, `--region-rim`, `--region-shrink` and `--region-crease` among the arguments `video-sway` takes and `video-sway-inspect` does not.
+- **Tests**: new file `tests/video/test_sway_region_over.py` covers these cases on synthetic figures (the region test's body and its striped part over the torso's right side and past it over the air, with a dark crease under it on the torso; an arm block beside the part's lower left; a dark outline row under the part where it hangs over the air). Each case first reads what a sway writes with the new options (its cells, its record), so on a release without them the same input fails on what comes out:
+ - without the new options nothing of them is read or written (cells and record as before, from Python with them passed off);
+ - with `--region-crease` the wear leaves the lower edge on the crease and wears in the rest, and nothing under the crease moves;
+ - laid over the figure under it, the lower edge moves as much as the part above it does (at gain 2.5 and 1.25), while without `--region-over` the crease pins it;
+ - the layer draws the band and the air where it lands, no read of the move taken there, and they keep their bytes elsewhere; nothing outside the region, its soft edge, the air and the band changes; the layer covers no deeper than the band; nothing folds;
+ - where the part lifts it shows the figure under it, with no hole;
+ - where the part lifts, the torso's soft side under it keeps its alpha in the rows the part leaves (no notch), and what the lift uncovers is read in its own column;
+ - its outline against the air goes with it and leaves the air behind, and its outline against the figure (the crease) keeps its bytes;
+ - `--hold-mask` leaves the arm out of the region and the band (one PNG carried, and a folder per cell), the arm keeping its bytes in every cell; without it the arm's rows the mask covers move;
+ - `--region-shear` 0.5 and 0.25 widen the rim to the least it asks, so the drawn move's step across the rim stays within the bound, and less than without it;
+ - the still strip is read from the region to its side (beside the arm, the px the mask left short; over the air, 0);
+ - the tip is read on the side over the air; a tip moved whole is 0 px off its own shape, its shift found;
+ - `move_steps` reads the most step both ways where both pixels are shown;
+ - `--frames` gives the strip's cells and the same record;
+ - each refusal leaves the loop as it was.
+ `tests/video/test_sway_region.py`'s crease case now reads the worn mask's box ending on the crease row. `tests/video/test_follow_inspect.py` now names `--region-over` and `--region-shear` among the arguments `video-sway` takes and `video-sway-inspect` does not.
## v3.5.0 - Widened square canvas framing for side walk and run stride and trailing parts, measured background matte cutout for flat backgrounds of any colour, and failure when a cutout removes nothing
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index fa6913a..c6a781c 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -631,11 +631,13 @@ sprite-gen video-sway --loop-dir set/front-walk/loop --region 136,164,60,50 [--r
[--gain 2.5] [--on-fold refuse|lower] [--freq 2.4] [--zeta 0.6] [--board follow.png] \
[--read-on <sha256>] [--stretch-floor D] [--gain-across G] \
[--band PX|auto] [--band-margin PX|auto] [--band-up FLAT[,PX|auto]] [--hold-mask MASK.png|DIR] \
- [--region-mask MASK.png|DIR [--region-rim SCALE] [--region-shrink PX] [--region-crease]]
+ [--region-mask MASK.png|DIR [--region-rim SCALE] [--region-shrink PX] [--region-crease] \
+ [--region-over [--hold-mask MASK.png|DIR]] [--region-shear S]]
sprite-gen video-sway --frames set/front-idle/loop/cycle --out swayed --region cx,cy,rx,ry[,flat] [--fps F] \
[--breathe breathed/breathe.json [--lag 0.15]] [--reference FRAME.png] [--gain G] [--gain-across G] [--on-fold ...] [--stretch-floor D] \
[--band PX|auto] [--band-margin PX|auto] [--band-up FLAT[,PX|auto]] [--hold-mask MASK.png|DIR] \
- [--region-mask MASK.png|DIR [--region-rim SCALE] [--region-shrink PX] [--region-crease]]
+ [--region-mask MASK.png|DIR [--region-rim SCALE] [--region-shrink PX] [--region-crease] \
+ [--region-over [--hold-mask MASK.png|DIR]] [--region-shear S]]
```
- **The region** is an ellipse over the part in the strip's first cell, in cell pixels
@@ -743,7 +745,7 @@ Combining `--band` with a region's fifth number `flat` (other than 0, which coun
#### Pixels a band leaves as they are: `--hold-mask`
-`--hold-mask MASK.png|DIR` sets pixels that the band moves round and leaves as they are, whatever part of the figure they belong to, such as an arm that hangs over a moving chest, or a belt or a dress below it. The band's move field itself is not changed. It works only with `--band`; without `--band`, it is refused with the message "--hold-mask keeps pixels as they are while a band moves its regions round them; it needs --band" (a non-zero exit, writing nothing, the loop left as it was). It is off by default; when it is not given, nothing of it is read or written, and strips, frames, and records remain byte for byte as with `--band` alone (and as before without `--band`).
+`--hold-mask MASK.png|DIR` sets pixels that the band moves round and leaves as they are, whatever part of the figure they belong to, such as an arm that hangs over a moving chest, or a belt or a dress below it. The band's move field itself is not changed. It works only with `--band`, or with `--region-mask` and `--region-over`, where it names the pixels the layer leaves out; without `--band` and without `--region-over`, it is refused with the message "--hold-mask keeps pixels as they are while a band moves its regions round them; it needs --band" (a non-zero exit, writing nothing, the loop left as it was). It is off by default; when it is not given, nothing of it is read or written, and strips, frames, and records remain byte for byte as with `--band` alone (and as before without `--band`).
The mask is a PNG drawn on the cell the regions were read on (the first cell; the reference frame with `--reference`; or under `--read-on`, the cut's first cell where the loop holds it), pixel for pixel the cell's size. A pixel is held where the PNG's alpha is 128 (`ALPHA_SOLID`) or more; where the PNG has no alpha, where its grey value is 128 or more. When given as one mask, it is split into its 8-connected pieces. Each piece is carried into every cell by its own solid pixels (alpha 128 or more under it), using the same search a band uses to carry a region (`carry_mask`, built out of the band's `carry_own`): in the loop's order from the cell it was drawn on, within `CARRY_SEARCH` (9) px of where the cell before had it, by the least squared difference of premultiplied colour, with a parabola for the subpixel position. Where that is uncertain (such as unpatterned cloth) or the piece covers no solid pixel, that piece is carried by the body's lay in that cell, and a warning line names it. The carried pieces are then grown by `HOLD_GROW` (3) px in 4-neighbour steps, what a carry may be off by where the part held changes its shape. Alternatively, `--hold-mask` takes a folder of PNGs, one per cell, in file-name order; each is held as given in its cell (no carry, no growth).
@@ -759,9 +761,9 @@ A run is refused with a non-zero exit, writing nothing and leaving the loop as i
With `--region` alone a region is an ellipse whose weight falls from its centre, and with `--band` an ellipse grown by a margin moves whole over a band of pixels outside it, so either way pixels near the part move with it: the belly or waist under a chest, an arm beside it. `--region-mask MASK.png|DIR` gives the region as a mask of the part's own pixels instead of the ellipse's weight: the part moves, and every visible pixel outside it and its soft edge keeps its bytes in every cell, at any gain. The ellipses (`--region`) are still required: they still say each region's gain (the fold rule's and `--on-fold`'s) and where `--band-up`'s shape sits. It is off by default; when it is not given nothing of it is read or written, and strips, frames and records are byte for byte what they were (with `--band`, with `--band` and `--hold-mask`, and with neither).
-The mask is a PNG drawn on the cell the regions were read on (the first cell; the reference frame with `--reference`; or under `--read-on`, the cut's first cell where the loop holds it), pixel for pixel the cell's size. A pixel is in the mask where the PNG's alpha is 128 (`ALPHA_SOLID`) or more; where the PNG has no alpha, where its grey value is 128 or more (read exactly as `--hold-mask` reads its PNG). Alternatively, it takes a folder of PNGs, one per cell, in file-name order, where each is the region in its own cell as given (no carry). When `--region-crease` is passed (off by default), before it is worn in, the mask's lower edge is moved to the crease under it (`crease_of`): in each column of the mask's solid pixels whose lowest pixel has a solid pixel under it (the part lies on more of the figure there), the darkest solid pixel by luma (0.299 R + 0.587 G + 0.114 B) from `CREASE_UP` (5) rows above that lowest pixel to `CREASE_DOWN` (3) rows below it is found; the rows are then taken as the median over `CREASE_SPAN` (2) columns either way (5 columns), rounded down; the mask is cut under that row and filled down to it with the column's solid pixels, while a column whose lowest pixel has a clear pixel under it (the part's free edge, over the air) is left as it is. Under `--region-shrink PX` (default `SHRINK_DEFAULT`, 2; 0 keeps the mask as given; a whole number, 0 or more), the mask is worn in by PX 4-neighbour steps (a pixel stays where it and its 4 neighbours are all in the mask; past the cell's edge none is), so that a mask drawn a little large holds what lies just outside the part. Crease runs first, then shrink. One mask is carried into every cell by its own pixels (`carry_region`): the solid pixels (alpha 128 or more) of the mask as trimmed (before it is worn in) on the cell it was drawn on, matched by the band's search (`carry_match`: least squared difference of premultiplied colour within `CARRY_SEARCH`, 9 px, with a parabola for the subpixel position), in the loop's order from the cell it was drawn on. In each cell two guesses are searched round: first where the cell before had the region (from the cell it was drawn on, for the first one), second round the cell's own body lay (the outline's motion); of the guesses that settle (a sure match) the one with the lesser difference is taken (the cell before's on a tie), and the record says which ("before" or "lay"). Where neither settles (cloth with no pattern, the least on the search's edge), the cell keeps the carry of the cell before, never the lay alone, and the record and a warning line say which cell and why (for each guess, why it did not settle), because a part moves little from one cell to the next, and the lay can lie far off it where the outline changes. The worn-in mask is moved by that carry (read bilinear, the pixels it covers half or more of), and in each cell the region is those pixels that are solid in that cell.
+The mask is a PNG drawn on the cell the regions were read on (the first cell; the reference frame with `--reference`; or under `--read-on`, the cut's first cell where the loop holds it), pixel for pixel the cell's size. A pixel is in the mask where the PNG's alpha is 128 (`ALPHA_SOLID`) or more; where the PNG has no alpha, where its grey value is 128 or more (read exactly as `--hold-mask` reads its PNG). Alternatively, it takes a folder of PNGs, one per cell, in file-name order, where each is the region in its own cell as given (no carry). When `--region-crease` is passed (off by default), before it is worn in, the mask's lower edge is moved to the crease under it (`crease_of`): in each column of the mask's solid pixels whose lowest pixel has a solid pixel under it (the part lies on more of the figure there), the darkest solid pixel by luma (0.299 R + 0.587 G + 0.114 B) from `CREASE_UP` (5) rows above that lowest pixel to `CREASE_DOWN` (3) rows below it is found; the rows are then taken as the median over `CREASE_SPAN` (2) columns either way (5 columns), rounded down; the mask is cut under that row and filled down to it with the column's solid pixels, while a column whose lowest pixel has a clear pixel under it (the part's free edge, over the air) is left as it is. Under `--region-shrink PX` (default `SHRINK_DEFAULT`, 2; 0 keeps the mask as given; a whole number, 0 or more), the mask is worn in by PX 4-neighbour steps (a pixel stays where it and its 4 neighbours are all in the mask; past the cell's edge none is), so that a mask drawn a little large holds what lies just outside the part. Crease runs first, then shrink. With `--region-crease`, after the mask is worn in, each column the crease ended (the columns in the record's `crease.rows`) is filled back from the worn mask's lowest pixel down to the crease row with the pixels of the mask as trimmed to the crease (before wear) (`crease_kept`). Only columns where the worn mask still holds a pixel are filled back. The crease is the picture's own edge, not one drawn a little large, so the wear leaves it where it is; the wear still wears the mask in everywhere else (its sides, its top, and the columns over the air, which the crease leaves as they are). The record's `mask.box` now ends on the crease row. One mask is carried into every cell by its own pixels (`carry_region`): the solid pixels (alpha 128 or more) of the mask as trimmed (before it is worn in) on the cell it was drawn on, matched by the band's search (`carry_match`: least squared difference of premultiplied colour within `CARRY_SEARCH`, 9 px, with a parabola for the subpixel position), in the loop's order from the cell it was drawn on. In each cell two guesses are searched round: first where the cell before had the region (from the cell it was drawn on, for the first one), second round the cell's own body lay (the outline's motion); of the guesses that settle (a sure match) the one with the lesser difference is taken (the cell before's on a tie), and the record says which ("before" or "lay"). Where neither settles (cloth with no pattern, the least on the search's edge), the cell keeps the carry of the cell before, never the lay alone, and the record and a warning line say which cell and why (for each guess, why it did not settle), because a part moves little from one cell to the next, and the lay can lie far off it where the outline changes. The worn-in mask is moved by that carry (read bilinear, the pixels it covers half or more of), and in each cell the region is those pixels that are solid in that cell.
-In each cell, the pixels are partitioned into sets (`region_sets`). The region is the mask's pixels in that cell, as above. Its soft edge is every pixel not opaque (alpha over 0 and under 128) within `REGION_SOFT` (2) 4-neighbour steps of the region, not in it, and not beside (1 step) another solid pixel outside the region; it moves with the region. Held pixels are every other visible pixel (alpha over 0), and each keeps its bytes in every cell. The air is every clear pixel (alpha 0) within `ceil(reach) + REGION_AIR` (2 px) 8-neighbour steps of the region, where reach is the move's reach at the gain the regions move by; the region moves into it, while clear pixels further away stay clear.
+In each cell, the pixels are partitioned into sets (`region_sets`). The region is the mask's pixels in that cell, as above. Its soft edge is every pixel not opaque (alpha over 0 and under 128) within `REGION_SOFT` (2) 4-neighbour steps of the region, not in it, and not beside (1 step) another solid pixel outside the region; it moves with the region. Held pixels are every other visible pixel (alpha over 0), and each keeps its bytes in every cell. The air is every clear pixel (alpha 0) within `ceil(reach) + REGION_AIR` (2 px) 8-neighbour steps of the region, where reach is the move's reach at the gain the regions move by; the region moves into it, while clear pixels further away stay clear. `--region-over` changes the soft edge and the held pixels as its section below says.
Over the region, its soft edge and the air the weight is `sin²(pi/2 x d)`, where `d` is the distance to the nearest held pixel in rim units: an ellipse `Lx` px across and `Ly` px down, `d = min over held pixels q of sqrt(((x - qx)/Lx)² + ((y - qy)/Ly)²)`, and 1 where no held pixel is nearer (computed exactly, the least along each row then down each column, via `rim_distance`). Elsewhere the weight is 0. So the weight is 0 at the held pixels and rises to 1 (the whole move) inside the region, at least `Lx` across and `Ly` down from every held pixel. `Lx` and `Ly` are read off the move: each starts at the fold rule's least band for the largest move that way over the cells, `ceil(most x pi / 2) + 1`, times `--region-rim SCALE` (default `RIM_DEFAULT`, 1.0; 1 or more), rounded up; then both are widened together, a px at a time, until `(pi/2) x sqrt((dx/Lx)² + (dy/Ly)²)` is at most `RIM_SLOPE` (0.9) in every cell, where dx and dy are the cell's move across and down at the gain the regions move by (`rim_bands`). The move does not fold because `sin²(pi/2 x d)` rises at most `pi/2` per unit of `d`, and `d` rises at most `1/Lx` per px across and `1/Ly` per px down, so along the move a pixel keeps at least `1 - RIM_SLOPE` (0.1) of its area, and a move goes less far than the held pixels lie, so no read lands on a held pixel with half its weight. A wider `--region-rim` (1.5, say) makes a gentler rim: less of the part moves whole. Without `--band-up`, the fold rule reads no radius under `--region-mask` (the rim is read off the move instead), and no gain is lowered by it: in the record each region's fold entry has `radius_px` null, `ratio` 0 and `gain_limit` null. `--gain` sets how far the part moves, as before, and the ledger records the most any region pixel moves per cell.
@@ -769,13 +771,40 @@ With `--band-up FLAT[,PX|auto]`, the weight is the lesser of the rim's and the u
Every pixel of the region, its soft edge and the air is read at its whole move using premultiplied bilinear sampling (the band's sampling, `draw_held` with no short read). A read whose four pixels take a held pixel is read from the other three where they carry half its weight or more ("renormalised"), else walked back by 1/`HOLD_STEPS` (1/16) of its move at a time until they do ("walked"); the rim keeps reads from putting half their weight on held pixels, so the walked count is 0.
-In strip metadata under `follow.region_mask` (and `region_mask` in `sway.json` on `--frames`), the record stores `policy` (`own-pixels-mask/held-outside/rim-sin2/1`), `asked` (`per_cell`, `sha256`: the file's, or a list per file for a folder, `rim`: the scale, `shrink_px`, `crease`: true/false, and `up`: `{flat, band}` or null), `soft_px` (2), and `air_px` (`ceil(reach) + 2`). It records `rim` (`across_px` for Lx, `down_px` for Ly, `least_px`: the two bands it started at, `slope`: the steepest `(pi/2) x sqrt(...)` over the cells, and `slope_bound`: 0.9); `mask` (`px`: its pixel count as worn in, `box`, and `carried_by_px`: the solid pixels it was carried by; null for a folder); `crease` (per mask, `rows`: each column's row, keyed by column, and `free_columns`; null when not asked); `carry` (`search_px` of 9 and `cells`: per cell `px`, `from`: `base`, `pixels` or `before`, `guess`: `before` or `lay` where carried by its pixels, `why` where it kept the cell before's carry, `least`, and `curvature`; null for a folder); `kept` (`{cell, why}` for each cell that kept the carry of the cell before); and `up` (the upper yield's shape as a band's record: `reach_px`, `band_px`, `margin_px`, per region `flat_px`, `band_px` and `steepest`, its `carry` and `lay`; null without `--band-up`). The strip's `carry_basis` is the band's (`CARRY_BASIS_BAND`).
+In strip metadata under `follow.region_mask` (and `region_mask` in `sway.json` on `--frames`), the record stores `policy` (`own-pixels-mask/held-outside/rim-sin2/1`), `asked` (`per_cell`, `sha256`: the file's, or a list per file for a folder, `rim`: the scale, `shrink_px`, `crease`: true/false, `up`: `{flat, band}` or null, and when given, `over: true`, `hold` (the hold mask's `{per_cell, sha256}`, or null), and `shear: S`), `soft_px` (2), and `air_px` (`ceil(reach) + 2`). It records `rim` (`across_px` for Lx, `down_px` for Ly, `least_px`: the two bands it started at, `slope`: the steepest `(pi/2) x sqrt(...)` over the cells, `slope_bound`: 0.9, and when given, `shear_px` ([across, down]: the least rim the shear asks)); `mask` (`px`: its pixel count as worn in, `box`, and `carried_by_px`: the solid pixels it was carried by; null for a folder); `crease` (per mask, `rows`: each column's row, keyed by column, and `free_columns`; null when not asked); `carry` (`search_px` of 9 and `cells`: per cell `px`, `from`: `base`, `pixels` or `before`, `guess`: `before` or `lay` where carried by its pixels, `why` where it kept the cell before's carry, `least`, and `curvature`; null for a folder); `kept` (`{cell, why}` for each cell that kept the carry of the cell before); and `up` (the upper yield's shape as a band's record: `reach_px`, `band_px`, `margin_px`, per region `flat_px`, `band_px` and `steepest`, its `carry` and `lay`; null without `--band-up`). The strip's `carry_basis` is the band's (`CARRY_BASIS_BAND`).
The record's `ledger` lists per cell, with `<key>_max` beside each count: `region_px`, `soft_px`, `air_px`, `held_px`, `held_changed_px` (held pixels the drawn cell does not keep byte for byte; 0), `move_most` ([px, x, y] of the region pixel that moves most; null where none moves) with `move_most_max`, `pressed_px`, `pressed_box`, `area_least`, `stretched_px`, `stretched_box`, `area_most` (as the band's ledger counts them: solid moved pixels left under `PRESSED` 0.85 or over `STRETCHED` 1.15 of their area), `folded_px` (moved pixels whose move takes 0 or less of the source's area), `jacobian_min` (the least area any moved pixel takes; the move and the read are one field), `read_held_weight` ([weight, x, y]: the most weight a read's four pixels put on held pixels; null where none), `read_held_half_px` (reads that put half or more on them), `renormalised_px`, and `walked_px`. Warning lines on stderr, one each, report the cells that kept the carry of the cell before ("--region-mask keeps the carry of the cell before in N cells, its own pixels found surely neither round where that cell had them nor round the lay (cell k: why; ...)", ending `follow.region_mask.kept`); a region whose `--band-up` yield was carried by the lay (ending `follow.region_mask.up.lay`); and for `held_changed_px`, `pressed_px`, `stretched_px`, `read_held_half_px`, `renormalised_px` and `walked_px` when not 0 in some cell: "--region-mask: <what> in X of N cells, up to M px (cell k)" (for pressed and stretched also the least or the most area and where), ending `follow.region_mask.ledger.<key>` on `--loop-dir` and `sway.json region_mask.ledger.<key>` on `--frames`. Command stdout JSON gains `region_mask` with `kept_cells`, `rim_px` ([Lx, Ly]), `move_most_px` and `walked_px_max`.
-As the last check, a run is refused, named the engine's fault, with nothing written if `jacobian_min` is 0 or under in any cell: "--region-mask's rim (Lx px across, Ly down) keeps a move of R px taking at most 0.9 of a pixel's area, and cell k's move folds the picture all the same (...); this is the engine's fault - nothing was written". A run is also refused with a non-zero exit, writing nothing and leaving the loop as it was: with `--band` ("--region-mask moves the region's own pixels and holds every visible pixel round it, the weight falling over a rim inside it; --band moves an ellipse over a band outside it: give one of them"); with `--band-margin` ("--band-margin shapes a band; with --region-mask the rim is read off the move (--region-rim)"); with a region's fifth number `flat` ("--region-mask gives the region as a mask, and a region's fifth number (flat, ...) shapes the ellipse's weight: give the region as cx,cy,rx,ry with --region-mask"); with `--stretch-floor` ("--stretch-floor reads the weight that falls from a region's centre; with --region-mask the rim is widened with the move"); with `--hold-mask` ("--region-mask holds every visible pixel outside the region already; --hold-mask is a band's"); when `--region-rim` is under 1 or not finite, such as `nan` ("--region-rim is how many times the fold rule's least band the rim starts at, 1 or more; got X"); when `--region-shrink` is negative, and, for Python callers, also for a `region_shrink` that is not a whole number ("--region-shrink is the px the mask is worn in by, a whole number, 0 or more; got X"); when `--region-rim`, `--region-shrink` or `--region-crease` is given without `--region-mask` ("--region-rim, --region-shrink and --region-crease shape a region mask; they need --region-mask"); when a mask is of another size than the cells ("--region-mask is WxH, the cells are WxH: a mask is drawn on a cell, pixel for pixel"); when a folder holds a count of PNGs that is not the cell count ("--region-mask holds N masks and there are M cells: a folder gives one mask per cell, in name order"); when a mask covers no solid pixel of the cell it was drawn on ("--region-mask holds no solid pixel of the cell it was drawn on: nothing of the region to carry"); when a shrink leaves nothing ("--region-shrink N wears the region mask away: no pixel of it is left to move"); and as `--hold-mask`'s PNG reading refuses: when a file is not read, when a mask holds no pixel, or when a folder has no PNG.
+As the last check, a run is refused, named the engine's fault, with nothing written if `jacobian_min` is 0 or under in any cell: "--region-mask's rim (Lx px across, Ly down) keeps a move of R px taking at most 0.9 of a pixel's area, and cell k's move folds the picture all the same (...); this is the engine's fault - nothing was written". A run is also refused with a non-zero exit, writing nothing and leaving the loop as it was: with `--band` ("--region-mask moves the region's own pixels and holds every visible pixel round it, the weight falling over a rim inside it; --band moves an ellipse over a band outside it: give one of them"); with `--band-margin` ("--band-margin shapes a band; with --region-mask the rim is read off the move (--region-rim)"); with a region's fifth number `flat` ("--region-mask gives the region as a mask, and a region's fifth number (flat, ...) shapes the ellipse's weight: give the region as cx,cy,rx,ry with --region-mask"); with `--stretch-floor` ("--stretch-floor reads the weight that falls from a region's centre; with --region-mask the rim is widened with the move"); with `--hold-mask` without `--region-over` ("--region-mask holds every visible pixel outside the region already; --hold-mask is a band's, or with --region-over the pixels its layer leaves out"); under `--region-over`, `--hold-mask` is refused as a band's `--hold-mask` PNG reading refuses (size, no pixel, not read, folder count, no PNG); when `--region-rim` is under 1 or not finite, such as `nan` ("--region-rim is how many times the fold rule's least band the rim starts at, 1 or more; got X"); when `--region-shrink` is negative, and, for Python callers, also for a `region_shrink` that is not a whole number ("--region-shrink is the px the mask is worn in by, a whole number, 0 or more; got X"); when `--region-rim`, `--region-shrink` or `--region-crease` is given without `--region-mask` ("--region-rim, --region-shrink and --region-crease shape a region mask; they need --region-mask"); when `--region-over` or `--region-shear` is given without `--region-mask` ("--region-over and --region-shear shape a region mask; they need --region-mask"); when `--region-shear` is 0 or under, or not finite ("--region-shear is the most a move one way may rise across the rim the other way, px a px, over 0; got X"; for Python callers, a value that is not a number gives "--region-shear is px a px, over 0; got X"); when a mask is of another size than the cells ("--region-mask is WxH, the cells are WxH: a mask is drawn on a cell, pixel for pixel"); when a folder holds a count of PNGs that is not the cell count ("--region-mask holds N masks and there are M cells: a folder gives one mask per cell, in name order"); when a mask covers no solid pixel of the cell it was drawn on ("--region-mask holds no solid pixel of the cell it was drawn on: nothing of the region to carry"); when a shrink leaves nothing ("--region-shrink N wears the region mask away: no pixel of it is left to move"); and as `--hold-mask`'s PNG reading refuses: when a file is not read, when a mask holds no pixel, or when a folder has no PNG.
-The option works on `--loop-dir` and on `--frames ... --out ...` alike (the frames get the strip's cells and the same record), with `--reference`, and under `--read-on`, where a turned loop carried from its cut is moved cell for cell as the cut is. The alias `video-follow` takes the same flags. `video-sway-inspect` does not take them.
+The options (`--region-mask`, `--region-over` and `--region-shear`) work on `--loop-dir` and on `--frames ... --out ...` alike (the frames get the strip's cells and the same record), with `--reference`, and under `--read-on`, where a turned loop carried from its cut is moved cell for cell as the cut is. The alias `video-follow` takes the same flags. `video-sway-inspect` does not take them.
+
+#### A region laid over the figure under it: `--region-over`
+
+With `--region-mask` alone, every visible pixel outside the region is held and is an anchor of the rim (the weight is 0 at held pixels and rises by `sin²(pi/2 x d)` over the rim). Where the region lies on more of the figure (a part resting on the body under it), the held pixels right under its lower edge pin that edge: the lower edge barely moves while the rest of the part does. `--region-over` lays the region over the figure under it instead. It is off by default; when it is not given, nothing of it is read or written, and strips, frames and records are byte for byte what they were.
+
+Per cell (`layer_sets`, then `lay_over`), under the region's lower edge (per column: the rows from the first row under the region's lowest pixel in that column; for a column past the region's sides, under the lowest pixel of the region's nearest column, the leftmost on a tie; in the region's columns and `air` px past them on each side; `air` = `ceil(reach) + REGION_AIR`, the same reach as the air the region moves into), every held pixel, solid or not, is no anchor of the rim (none of the pixels `--hold-mask` leaves out). So the lower edge moves with the rest of the region. The band is those pixels (solid or not) within `air` 8-neighbour steps of the region and its soft edge. They move too, and the layer is drawn over them. The layer is the region's own pixels (the region, its soft edge, and its outline against the air, premultiplied) read at the move. Where the layer lands on a band pixel (alpha over 0), that pixel is the layer laid by its own alpha over the band pixel's own colour. Where it does not land, the band pixel keeps its bytes. The air the region moves into is drawn the same way: where the layer lands on an air pixel (a drawn alpha of 1 or more), that pixel is the layer alone; where it does not land, the air pixel keeps its bytes. So the air shows the region moved into it, never the figure beside it. Where the region lifts off the figure under it, the region's pixels (and its soft edge's) that the lift uncovers (`uncovered`: those whose own column, read as far under them as the move, reaches past the region's last row into the rows under its lower edge) show the layer laid over the figure under the region as it lies in the pixel's own column, read down as far as the move: the rows under the lower edge drawn up, never moved sideways. So the figure's side under the region stays where it is as the region lifts and moves sideways, with no notch. The band, the air and what a lift uncovers are drawn by the layer (`lay_over`); `draw_held` draws only the rest of the region and its soft edge, so its counts (`renormalised_px`, `walked_px`, `read_held_weight`) read only those. The ledger records `lifted_px`: region pixels the lift uncovers under which the figure shows half or more where the layer does not.
+
+Under `--region-over`, the region's soft edge is every pixel not opaque (alpha over 0, under 128) within `REGION_SOFT` (2) 4-neighbour steps of the region, beside another solid pixel or not, none left out; it moves with the region. (Without `--region-over`, a soft pixel beside another solid pixel outside the region is held.) Left beside the figure under it, it would stay behind as a ghost of the region's outline. Under the region's lower edge, only such a pixel that touches no solid pixel outside the region (8-neighbour) is the soft edge; one that does is the figure's own soft side, which stays where it is (it is in the band). A solid band pixel that is the region's own outline against the air (beside a pixel that is neither solid nor left out, within 2 px of the region and its soft edge, and touching no other solid pixel outside the region by 4-neighbour) goes with the layer and leaves the air behind it. An outline pixel that touches the figure under it or a pixel left out keeps its bytes as the band does.
+
+With `--region-over`, `--hold-mask MASK.png|DIR` names pixels the layer leaves out, such as an arm resting on the part. They are never the region's (taken out of the mask in each cell), never in the band, never drawn over, never in the soft edge, and they stay anchors of the rim. The mask is read and carried exactly as a band's `--hold-mask` (one PNG drawn on the cell the regions were read on, split into 8-connected pieces, each carried by its own solid pixels and grown by `HOLD_GROW` (3) px, with the same warning when a piece is carried by the lay; or a folder of one PNG per cell in name order, held as given). The held pixels the record and the ledger count are then those the drawn cell keeps: every held pixel but the band pixels the layer lands on.
+
+In the record, `asked` gains `over: true` and `hold` (the hold mask's `{per_cell, sha256}`, or null) only when `--region-over` is given. The record gains `over`: `policy` (`under-edge-free/band-and-air-laid-by-alpha/air-outline-with/1`), `band_px` (the band's reach, `ceil(reach) + 2`), and `left_out` (null without `--hold-mask`; else `grow_px` (3, or null for a folder), `pieces` (`{px, box}` per piece; none for a folder), `carry` (`search_px` 9 and per cell the carry of each piece, as a hold's; null for a folder), and `lay` (`{cell, piece, why}` for each piece carried by the lay)). A warning line on stderr names the cells where a left-out piece was carried by the lay: "--hold-mask (what --region-over leaves out) is carried by the body's lay in N cells, its own pixels not found surely (cell k, piece i: why; ...)", ending `follow.region_mask.over.left_out.lay` (or `sway.json region_mask.over.left_out.lay` on `--frames`).
+
+Per cell, only with `--region-over`, the ledger lists each count with its `<key>_max`: `band_px`, `over_px` (band pixels the layer covers half or more, its outline not counted), `edge_px` (the outline that goes with the layer), `lifted_px` (region pixels that show the figure under it where it lifts), `left_out_px` (mask pixels `--hold-mask` leaves out), `cover_depth_px` (how deep the layer covers the band: the straight-line distance from the region and its soft edge to the farthest pixel it covers; at most the band's reach), and `edge_folded_px` (folds within 1 px, by 4-neighbour, of a held pixel: where the layer stops and the band keeps its bytes the move steps from the move to 0, which is the layer's edge, not a fold of the move; these are counted apart, and `folded_px`, `jacobian_min` and the last check's refusal read every other moved pixel as before). `read_held_weight` reads the weight a read puts on held pixels other than the band (the region reads the band where it lifts).
+
+#### The rim widened for the shear: `--region-shear S`
+
+The rim's width each way (`Lx` across, `Ly` down) is read off the move along that way alone (`rim_bands`). A part that moves mostly down gets a narrow rim across, so its move down rises from 0 to the whole move across only a few px: a step across the rim of up to `pi/2 x (most move down) / Lx` px per px, which shows as a tear along the part's side.
+
+`--region-shear S` (px per px, over 0) widens the rim so that a move one way rises across the rim the other way by at most S px per px: `Lx` at least `ceil(pi/2 x (most move down) / S)` and `Ly` at least `ceil(pi/2 x (most move across) / S)`, the most over the cells at the gain the regions move by (`shear_floor`). Each is taken as the larger of that and the rim `rim_bands` reads (after its widening to `RIM_SLOPE`), so it only lowers the slope. `--region-rim` still scales the rim it starts at. Without it the rim is read as before. Unlike widening `--region-rim`, which widens both ways by the move along each way, `--region-shear` widens each way by the move the other way.
+
+In the record, `asked` gains `shear: S` only when given, and `rim` gains `shear_px` ([across, down]: the least rim the shear asks) only when given.
+
+With `--region-over` or `--region-shear`, the ledger also reads the region's edges per cell:
+- `step_across_most` and `step_down_most`: the most the drawn move steps between two pixels side by side and between two one over the other, both visible in the cell as cut, `|m(p) - m(q)|` px per px, and where (`[step, x, y]`, x and y the left or upper pixel of the two; null where no two are) (`move_steps`); under `--region-over` the band's pixels are not read (the layer slides over them). Over the cells, their largest are recorded as `step_across_max` and `step_down_max`.
+- `still_strip`: the strip a region drawn short of its side leaves standing (`still_strip`): per row of the region, at each end of each run of it, how many solid pixels lie outward before the figure's side there (a pixel not solid, or a pixel `--hold-mask` leaves out), none of them the region's (0: the region reaches its side). An end whose way out meets the region again, or the cell's edge, is not read. It records per cell `{median, most, ends, covered}`: the median and the most width, how many ends were read, and how many are no wider than the rim across (`Lx`); null where no end is read.
+- `tip`: the region's tip (`tip_shape`): the side (right or left) of its `TIP_COLS` (10) outermost columns, with its soft edge, more of whose pixels touch the air (the right on a tie); a window of those columns and their rows with `TIP_AIR` (8) px of air round them (`box`); a ring of pixels within `TIP_RING` (3) px of the source's outline against the air in the window, leaving out pixels within `TIP_OFF` (2) px of another solid pixel (`ring_px`); `shape_px`: how far the drawn outline is from the source's outline moved by the shift that fits it best, the sum of `|alpha drawn - alpha source moved|` over the ring at its least over the shift (whole px within `TIP_SEARCH` (6) px, then a quarter and a twentieth of a px round the best) over the sum of the source alpha's gradient on the ring: the mean px the tip's outline is off its own shape once its move is taken away (0: the tip moved whole); `shift`: that shift; and `move_mean`: the mean move of the tip's own solid pixels in the window, from the move field (a shift fits a straight outline anywhere along it, so the shift is no measure of the move). It is recorded per cell, or null where the region has no pixel. Over the cells, `tip_shape_max` and `tip_move_max` record `[value, cell]`.
### Inspecting a sway — `video-sway-inspect`