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(loop-repair): `lines.*.says` is the body's word, the cut's only where the body says it

Soohong Kima6f02017946b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95ffa7e..80e6394 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,7 +13,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- **Changed: the body's word is one line in both places (`local_cycle.body_word`, `local_cycle.TOP_LINES`, `local_cycle.bob_word(..., line=)`, `local_cycle.read_cycles`, `local_cycle.cut_word`).** `local_cycle.body_word(signals, interval)` reads each line of `local_cycle.TOP_LINES` (`{'top': 'its top line', 'first_row': 'its first solid row'}`), in that order, with `local_cycle.bob_word(signals, interval, feet=False, line='top')` in both places of `local_cycle.CUT_LINES`, and says `"cycles"` where one line says so on the screen and over its feet, the same line in both, never one line on the screen and the other over the feet. `read_cycles` reads it on the crossing interval, and `cut_word` reads it on the cut L, L/2 and 2L through `local_cycle._cut_lines`, saying `"two steps"`, `"four steps"` or `"one step"` only where the same line says so in both places. On the screen alone a head rising twice in one step reads as two steps, and the feet leave no such rise and fall over them; over the feet alone the two feet's heights, taken in by turns, read as the body's, and the screen line has none of them. Two lines are read because `top` passes over what is narrower than half the frame's widest row, so a tail or a cape lifted over the head takes it off the head where the first solid row stays on the body's top, and the first solid row takes an ear's or a hat's tip in; neither is the better line. The price is the design's: a walk whose rise and fall shows in one place only is not witnessed. `why` strings that said "its top line" now say the line's name, and the cut's `why` where nothing says is each place's why, repeated ones once, joined by "; ".
- **New: the rows down the middle of the body (`legs.body_signals` `first_row`, `strips`, `legs.STRIP`, `legs.DEEP`, `local_cycle.body_depth`, `BOB_RIGID`, `STRIP_FLOOR`, `STRIP_SHIFT`, `STRIP_SHIFT_MIN`).** `legs.body_signals(frames)` also returns `first_row` (per frame, the first solid row) and `strips` (per frame, the rows down the middle of the body: `legs.DEEP` = 0.7 of its median height from the first solid row, `legs.STRIP` = 0.12 of that height either side of the mean column of the solid pixels among them, each row's mean premultiplied colour and mean cover, shape frames by rows by 4, values 0..1); neither is recorded in any report, and `legs.strike_signals` and `gait.silhouette.signals` are unchanged. `local_cycle.body_depth(signals, interval)` reads the strip at the top of the rise against the bottom: the frames where the rise and fall twice an interval of the line over its lowest row stands a half or more of the way to the top and to the bottom, each set's strips in a median, each fit moved as it fits best, in steps of a twelfth of the most and at least half a row, at most `STRIP_SHIFT` (0.03) of the body's height either way and at least `STRIP_SHIFT_MIN` (3) rows. It returns `need`, `risen`, `rigid`, `zoom`, `ratio` (`zoom` of `rigid`), `moved` and `frames`, or None where no strip is read, the rise and fall is none, a set holds under two frames or the frames at the top are not the taller. `local_cycle.own_beat` reads the body's own on `less_lowest` alone where `ratio` is `BOB_RIGID` (1.0) or more, holds where it is under, and leaves the bands to decide where it is not read: no `depth`, or `moved` under `STRIP_FLOOR` (`CUE_FLOOR` * `legs.TONE`, half the step the colours are drawn in, about 0.00196: under it the strip is as good as plain to that zoom). A body rising whole carries those rows as they are; a zoom as far as the rise draws them longer; arms swinging across the bands hardly touch them. So a walk whose arms swing past its sides on the beat is witnessed where the rows down its middle read a body rising whole, and the bands no longer hold it there. A body one flat colour down its middle has no strip to read, and the bands decide as they did. A picture zoomed on the beat with every band seen drawn against the zoom and a strip as plain is still read as the body's own.
- **New: a line must be at least `BOB_OWN` of what is left against the lowest row on the screen (`local_cycle.bob_word`).** After the `less_lowest` gate and before the bands, where `beat` is under `BOB_OWN` (0.3) times `less_lowest`, nothing is witnessed, and `why` says "its lowest row does the rising and falling: {name} does so twice an interval {beat} rows on the screen, {percent} of the {less_lowest} left against its lowest row (at least 30%), and the body's own is not told from it". Read every four frames, a line on a beat of twelve leaves nothing of it twice an interval of 24, and still correlates there; what is left against the lowest row is then all the lowest row's.
-- **Changed: report fields.** `cycle.step_count.cycles.bob` gains `top_line`, the line that said so, where it says `"cycles"`, and `feet`, the record over the feet, its `says` and `top_line` the same. `body` in `bob`, `lines.*.bob` and `lines.*.on` gains `depth`: null or `{need, risen, rigid, zoom, moved, ratio, frames}` (`need`, `rigid`, `zoom` and `moved` rounded to 5 places, `risen` to 2, `ratio` to 3), a measure recorded as the other measures are, not a verdict. `cycle.cut_witness.by` is `["screen", "feet"]` or `["order"]`, never one place; `cut_witness.lines.screen.says` and `lines.feet.says` are always the cut's word; `lines.*.bob`, `lines.*.on` and `on` carry `top_line`. No report key tells a right hold from a false one. `why` strings changed as `docs/loop-repair.md` says: the line's name in place of "its top line", "on the screen and over its feet" in the crossings' why, the new gate's why, the strip's why, the band gate's why extended with what the rows down the middle tell, and `mark` read of the line that stood.
+- **Changed: report fields.** `cycle.step_count.cycles.bob` gains `top_line`, the line that said so, where it says `"cycles"`, and `feet`, the record over the feet, its `says` and `top_line` the same. `body` in `bob`, `lines.*.bob` and `lines.*.on` gains `depth`: null or `{need, risen, rigid, zoom, moved, ratio, frames}` (`need`, `rigid`, `zoom` and `moved` rounded to 5 places, `risen` to 2, `ratio` to 3), a measure recorded as the other measures are, not a verdict. `cycle.cut_witness.by` is `["screen", "feet"]` or `["order"]`, never one place; `cut_witness.lines.screen.says` and `lines.feet.says` are the body's word, the same in both, the cut's word where `by` is `["screen", "feet"]` and the body's reading as it stood where it is `["order"]`; `lines.*.bob`, `lines.*.on` and `on` carry `top_line`. No report key tells a right hold from a false one. `why` strings changed as `docs/loop-repair.md` says: the line's name in place of "its top line", "on the screen and over its feet" in the crossings' why, the new gate's why, the strip's why, the band gate's why extended with what the rows down the middle tell, and `mark` read of the line that stood.
- **Changed: Python callers.** New `local_cycle.body_word`, `local_cycle.body_depth` and `local_cycle.TOP_LINES`; `local_cycle.bob_word` takes `line`, a `TOP_LINES` key; `local_cycle._cut_line` and `local_cycle.CUT_WORDS` are gone.
- **Tests (`tests/video/test_walk_steps.py`, `tests/video/test_cycle_align.py`, `tests/video/test_loop_silent_pass.py`).** Renamed `test_a_walk_rising_on_its_legs_on_a_picture_swaying_once_a_cycle_or_slower_is_held_as_cut_named` (was `..._is_witnessed_one_cycle`), `test_a_walk_whose_feet_meet_once_a_cycle_its_arms_swinging_past_its_sides_is_cut_one_cycle` (was `..._is_cut_two_intervals_with_a_warning`) and `test_a_walk_whose_arms_swing_past_its_sides_reads_as_one_whose_arms_swing_within_them` (was `test_a_walk_whose_arms_swing_past_its_sides_is_never_witnessed_its_crossings_left_on_steps_or_its_cut_held`). `test_a_fixed_cut_of_one_cycle_whose_crossings_mark_cycles_is_counted_two_steps` now says a walk seen from behind on twos, its arms swinging past its sides, is counted two steps, the same as one whose arms swing within its sides, because the rows down the middle of the body read a body rising whole (it used to say its crossings were left on steps, its fixed cut counted one step, and failed). New tests for a top line on a quick beat of its own over feet rising twice an interval, a head rising twice in one step, a cape taking the top line off the head, a line on the screen and another over the feet, the rows down the middle of a body, a reason both lines of a body give (naming neither) said once, on a crossing interval and on a cut, and `video-cycle-align` on its own stopping on a walk its body reads four steps. Synthetic frames only.
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index a29d28f..2584ced 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -1770,7 +1770,8 @@ and the cut's word is the first it rises and falls twice on, the same line in bo
L (the cut is a cycle); `"four steps"` on L/2 (two cycles); `"one step"` on 2L (once in the cut); null where
none. It returns `{says, by, lines, on, why, mark}`: `by`, `["screen", "feet"]` where the body said the
word and `["order"]` where the order did, never one place, only where it says one; `lines`, each place's
-record, `{screen: {...}, feet: {...}}`, each `{says, bob, on, why}` (`says` in both places the cut's word,
+record, `{screen: {...}, feet: {...}}`, each `{says, bob, on, why}` (`says` in both places the body's word,
+the same in both, the cut's word where the body said it, the body's reading as it stood where the order did,
`bob` that place's reading on the cut, `on` its reading at L/2 or 2L that said four steps or one step, with
its `interval`, only for four steps or one step, `why` only where `says` is null; the record over the feet's
`bob` and `on` record `over`, the row it was read over, `reach` or `sole`); `on`, for four steps or one step,
@@ -1832,9 +1833,11 @@ written. The loop report's `cycle.cut_witness` records `{cut, says, by, lines, o
only where it says a word, `on` only for four steps or one step, `why` only where `says` is null, `held`
only where held, `mark` only where marked); the printed summary's `cycle.cut_witness` records
`{cut, says, by, held, mark}` (each where present). `by` is `["screen", "feet"]` or `["order"]`, never one
-place; `lines.screen.says` and `lines.feet.says` are the cut's word; `lines.*.bob`, `lines.*.on` and `on`
-carry `top_line`, the line that stood. The record over the feet's `bob` and `on` record `over`, the row it
-was read over (`reach` or `sole`). No key in the record tells a right hold from a false one.
+place; `lines.screen.says` and `lines.feet.says` are the body's word, the same in both, the cut's word where
+`by` is `["screen", "feet"]`, the body's reading as it stood where it is `["order"]`; `lines.*.bob`,
+`lines.*.on` and `on` carry `top_line`, the line that stood. The record over the feet's `bob` and `on`
+record `over`, the row it was read over (`reach` or `sole`). No key in the record tells a right hold from a
+false one.
**What crossings cannot see**: a hold the step range absorbs (a 13-frame step held to 17), a still run of
the feet together inside the clip as long as a pass, and a wobble that reaches the reading's sides at a