Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(video): the loop repair notes and the changelog read a walk's steps on the order its feet are drawn in where the clip shows its two sides of feet are its two legs, never from the side or on a cut the search kept where no two-step cut closes, say video-cycle-align run on its own stops on a loop whose report holds its cut, name the diagonal walk whose feet pass each other on the screen as not told apart, and describe the tests; text by the writing hand-off
Soohong Kim1ef27ccce7b7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fdff2b9..1ea4be0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,7 +2,7 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.-## Unreleased - A walk whose feet meet once a cycle is cut one cycle long only where its body witnesses it, a walk that starts or stops in its take is named to film again, and video-set cuts a searched walk or run with motion-auto by default+## Unreleased - A walk whose feet meet once a cycle is cut one cycle long only where its body or the order the feet are drawn in witnesses it, a walk that starts or stops in its take is named to film again, and video-set cuts a searched walk or run with motion-auto by default**Upgrading from 3.5.0: `video-set` now cuts searched walk and run loops with `--anchor motion-auto` and their view by default, and `video-loop --anchor motion-auto` recognises crossings that mark cycles where feet hide or step apart instead of cutting two cycles.** Every walk or run item whose loop is searched is now cut with `motion-auto` and its view, producing a different cut and different bytes; `--anchor none` gives the old cut, its pictures and reports byte for byte apart from the engine hash (`producer.implementation_sha256`). Idle, attack, once-hold, lifetime, and once-return items are cut as before. In `video-loop --anchor motion-auto` without `--view`, a walk whose feet are seen together over half the interval at a pass (`crossings.HIDE_SHARE`, 0.5) and whose picture repeats each interval is now counted on cycles only where the body's top line, read less the picture's own flow, rises and falls twice an interval, and that rise and fall must be the body's own, read against its lowest row and its upper body, so the picture moved or zoomed with it witnesses nothing: where the parent engine cut two cycles, the loop is now one cycle with new bytes; where the parent engine kept the search's cut with no `steps`, the cut is the same and the strip and report now record `steps: 2`; where nothing witnesses, its crossings stay on steps with a warning (`cycle-unwitnessed`). A walk whose crossings mark steps (brief passes, or from the side) is cut to the same bytes. With `--view` (or through `video-set`), a front, back, or diagonal walk is evaluated even with brief passes: such a walk is counted on cycles with the same witness, the view's foot cue only refusing where it turns over one interval on; where nothing witnesses, its crossings stay on steps with a warning, and `video-set` leaves a `cycle-unwitnessed` loop out of the cycle alignment. Every report whose clip stands still gains `stands` and `run_limit`, and reports where cycle reading is asked gain `cycles`, with `bob` where the picture passes and `cue` only where a view is given.@@ -13,9 +13,11 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- **Changed: cycle alignment leaves out start-stop retake, cycle-unwitnessed and cycle-four-steps loops (`batch.align_gaits`, `video-set --align-cycles auto`, `local_cycle.four_steps`).** Takes flagged with `start-stop` retakes loop no two steps, loops whose cut nothing witnesses whole cycles (`cycle-unwitnessed`: crossings left on steps unwitnessed, or a cut the cut witness held) may hold half a cycle or two, and the warning says so, and loops whose cut witness says four steps (`cycle-four-steps`) hold two cycles where their strip counts two steps (`steps: 2`, which `video-cycle-align` reads as one cycle) and would play twice as fast if aligned as one cycle; all are excluded from gait cycle alignment, keeping their loops as cut while aligning the remaining directions. Excluded items are recorded under `left_out` (`{item: reasons}`, listing `["start-stop"]`, `["cycle-unwitnessed"]`, `["cycle-four-steps"]`, or `["start-stop", "cycle-unwitnessed"]`) with a stderr warning and a set warning; if fewer than two directions remain, alignment is skipped (`applied: false`, `why: "fewer than two directions left to align"`). A left-out loop whose step screen suspects one step is told in its warning what settles it (`video-loop --steps 1`), as `video-cycle-align` says when it stops on such a loop, and `batch.left_out_why` takes `one_step`.- **New: a walk's cut is held to its body's word before it is cut (`loop._witnessed`, `local_cycle.cut_word`, `local_cycle.unwitnessed`, `local_cycle.held_verdict`).** In `video-loop --anchor motion-auto` (`--cycle auto` or `periodic`), after `loop._by_steps` chooses the cut and before frames are cut, `loop._witnessed(cycle, frames=...)` holds the cut s/L to `local_cycle.cut_word(signals, length)`, which reads `local_cycle.bob_word` on two lines, `local_cycle.CUT_LINES` (`'screen'` on the screen, less its flow, and `'feet'` over its feet with `local_cycle.over_feet`, `feet=True`), at length L, L/2 and 2L (a picture swaying up and down once a cut or slower hides the body's rise and fall twice the cut on the screen, where the line over the feet reads it; a walk whose lean changes slowly on its feet tilts the ground under them, so the line over the feet takes in the two feet's heights by turns and reads no rise and fall, where the line on the screen reads it) and says the first either line says in `local_cycle.CUT_WORDS`: `"two steps"` (a cycle), `"four steps"` (two cycles), `"one step"` (once in the cut), or null. On two steps or four steps the cut stands (`{cut: [s, L], ...cut_word's record}`; where the cut stands and its lowest row rises and falls twice the cut more than its top line on the screen, the record carries `mark`; it holds nothing), and a cut of four steps (two cycles), its strip still counting two steps, makes `local_cycle.four_steps(cycle)` true, and `video-set` leaves the item out of cycle alignment (`left_out` `["cycle-four-steps"]`); anything else is held exactly as chosen (two clip crossing intervals where counted, else the search's cut), setting `cut_witness.held` to `"unwitnessed"`, warning `cycle-unwitnessed` (`local_cycle.held_verdict(cycle)` via `local_cycle.step_verdict`), and marking `local_cycle.unwitnessed(cycle)` true so `video-set` leaves the item out of cycle alignment (`left_out` `["cycle-unwitnessed"]`), while cuts the step count already held record `held: "step count"`. A reading of `"one step"` is held and never cut again two long because a body rising and falling once in the cut cannot be distinguished between half a cycle of legs drawn alike and a full cycle of a limp or bouncing legless body without reading legs, and the witness never lengthens or shortens a cut; walks whose body rises once a cycle, legless bodies bouncing once in the cut, and walks carried whole with no rise of their own are held and named even where a cut is a whole cycle.- **Changed: the body's own rise and fall is read against the lowest opaque row as well (`legs.body_signals` `sole`, `legs.OPAQUE`, `local_cycle.own_beat`).** `legs.body_signals(frames)` now returns `sole` per frame, taking the lowest row with an alpha of `legs.OPAQUE` (255) or the lowest solid row where none is opaque. `local_cycle.own_beat(signals, interval)` reads `sole` with `twice_an_interval` and takes `less_lowest` as the top line's rise and fall less the lowest solid row's or less the lowest opaque row's, whichever leaves less, returning `sole` as rows up and down. This prevents a translucent shadow drawn fixed on the screen under the feet from acting as the lowest solid row and registering picture shake twice an interval as the body's own rise against it, since opaque feet move with the picture.+- **New: the order the feet are drawn in witnesses a walk's steps (`legs.feet_order`, `legs.CONTACT`, `local_cycle.order_word`, `ORDER_ROWS`, `ORDER_TRAVEL`, `ORDER_SWAY`, `ORDER_REACH`, `ORDER_SLACK`, `ORDER_WORDS`).** `legs.feet_order` tracks which foot is drawn lower in each frame, and `local_cycle.order_word` gates side changes to witness one, two, or four steps across a span from non-side views. From the front, the back, or a diagonal, the foot nearer the viewer is drawn lower, and the nearer foot changes sides once a step, twice a cycle. The view's label is not taken for it, because a generated walk's label may be wrong: the clip must show that its two sides of feet are its two legs, or nothing is witnessed. `read_cycles` and `cut_word` read the foot drawing order when body cues do not witness crossings or cuts, and search cuts that failed to close are held unwitnessed rather than stood by foot order. A diagonal walk whose feet pass each other on the screen, one foot always drawn lower and the other passing it on either side, shows the same changes a side walk does, and the order does not witness it; a side walk is never read on the order.+- **Changed: standalone `video-cycle-align` stops on held or four-step cuts (`align.held_cut`).** `video-cycle-align` run on its own reads the cut report beside each loop through `align.held_cut(loop_dir, meta_path, meta)`. Where nothing witnessed the cut whole cycles (`cycle-unwitnessed`) or the cut spans four steps (`cycle-four-steps`), the loop is named under `held` and the aligner stops under `--multi-cycle fail` before rewriting any files, adding "and nothing witnessed some of the cuts whole cycles". Under `--multi-cycle warn` it aligns the loop with a warning, matching `video-set` instead of aligning held loops as one cycle without a word.- CLI: `video-loop --view front|back|side|front_diagonal|back_diagonal` (default none) sets the clip view for cycle detection and foot cue selection.-- Report fields: `cycle.step_count.cycles` (`{asked, interval, overlap, half, one, two, slack, cue, bob, cycles, unwitnessed, why}`, where `cue` and `bob` are recorded only where the picture passes, `cue: {range, floor, swapped, one, says, why}` only with a view, `one` absent where `says` is `"alike"`, `bob: {swing, rows, floor, twice, half, quarter, edge, body: {beat, lowest, sole, less_lowest, less_bands, still_bands, own, bands: {rows, width, zoom, beat, reads, less}, share, scale, least, scale_least, band_floor}, says, why}`, `half`, `quarter`, `edge` and `body` absent under the floors, `body` absent where under 8 frames are left, and `why` absent where it says `"cycles"`, and `unwitnessed` true only where nothing witnessed); the loop's warnings (`jolt.warnings`); `step_count.stands` and `step_count.run_limit`; `loop.retake` (`{reason: "start-stop", reasons, start_stop: {stands, run_limit, crossings, cut, verdict, code, why}, remedy: "retake"}`); the set report's item `loop.retake` (`{reason, reasons, remedy}`) and item `loop["cycle-unwitnessed"]` (`true`), and its state's `cycle_align.<state>.left_out` (`{item: reasons}`); the loop report's `cycle.cut_witness` (`{cut, says, by, lines, on, why, held, mark}`, `lines` (`{screen, feet}`, each `{says, bob, on, why}`), the feet line's `bob` and `on` with `over`, `by` only where it says a word, `on` with its `line` and `interval` only for four steps or one step, `why` only where `says` is null, `held` only where held, and `mark` only where marked); the printed summary's `cycle.cut_witness` (`{cut, says, by, held, mark}`, each where present).-- Python callers: new `local_cycle.read_cycles(reading, distances, view=None, cue=None, cue_step=None, signals=None)`, `local_cycle.bob_word(signals, interval, feet=False)`, `local_cycle.twice_an_interval(values, interval)`, `local_cycle.own_beat(signals, interval)`, `local_cycle.cut_word(signals, length)`, `local_cycle.over_feet(signals, interval)`, `local_cycle.unwitnessed(cycle)`, `local_cycle.four_steps(cycle)`, `local_cycle.held_verdict(cycle)` (refuses with a `ValueError` a cut held on one step whose record names no line it was read on (no `by` or `lines`)), `legs.OPAQUE`, `local_cycle.BOB_OWN`, `local_cycle.BOB_SCALE`, `local_cycle.BEAT_FRAMES`, `legs.body_signals(frames)`, `legs.BANDS`, `legs.band_rows(median)`, `legs.band_widths(alpha, rows)`, `legs.zoomed(alpha, scale)`, `local_cycle.BAND_FLOOR`, `local_cycle.off_flow(values, interval)`, `local_cycle.cue_word(cue, interval, step=None)`, `local_cycle.BOB_TWICE`, `local_cycle.BOB_FLOOR`, `local_cycle.BOB_ROWS`, `local_cycle.CUT_LINES`, `local_cycle.CUT_WORDS`, `local_cycle.UNWITNESSED`, `local_cycle.FOUR_STEPS`, `local_cycle.CUE_FLOOR`, `legs.TONE`, `local_cycle.repeat_at(distances, span)`, `batch.anchor_for(state, cut, anchor)`, `batch.left_out_why(reasons, stands=False, one_step=False)`, `loop.stand_retake(cycle)`, `loop.retakes(*records)`, `loop.STAND_REASON`; `crossings._alternation` is now public `crossings.correlation_on(values, span)`; `align._feet`, `align._depth_cue`, `align._shade_cue`, and `align.SHADE_BAND` are moved to `legs.feet_halves`, `legs.depth_cue`, `legs.shade_cue`, and `legs.SHADE_BAND` (`align` keeps `_depth_cue` and `_shade_cue` aliases); `crossings.Reading` gains `interval`, `per`, `cycles`, `hides`, and `mark_cycles(said)`.+- Report fields: `cycle.step_count.cycles` (`{asked, interval, overlap, half, one, two, slack, cue, bob, cycles, unwitnessed, why}`, where `cue` and `bob` are recorded only where the picture passes, `cue: {range, floor, swapped, one, says, why}` only with a view, `one` absent where `says` is `"alike"`, `bob: {swing, rows, floor, twice, half, quarter, edge, body: {beat, lowest, sole, less_lowest, less_bands, still_bands, own, bands: {rows, width, zoom, beat, reads, less}, share, scale, least, scale_least, band_floor}, says, why}`, `half`, `quarter`, `edge` and `body` absent under the floors, `body` absent where under 8 frames are left, and `why` absent where it says `"cycles"`, and `unwitnessed` true only where nothing witnessed); the loop's warnings (`jolt.warnings`); `step_count.stands` and `step_count.run_limit`; `loop.retake` (`{reason: "start-stop", reasons, start_stop: {stands, run_limit, crossings, cut, verdict, code, why}, remedy: "retake"}`); the set report's item `loop.retake` (`{reason, reasons, remedy}`) and item `loop["cycle-unwitnessed"]` (`true`), and its state's `cycle_align.<state>.left_out` (`{item: reasons}`); the loop report's `cycle.cut_witness` (`{cut, says, by, lines, on, why, held, mark}`, `lines` (`{screen, feet}`, each `{says, bob, on, why}`), the feet line's `bob` and `on` with `over`, `by` only where it says a word, `on` with its `line` and `interval` only for four steps or one step, `why` only where `says` is null, `held` only where held, and `mark` only where marked); the printed summary's `cycle.cut_witness` (`{cut, says, by, held, mark}`, each where present). `cycle.step_count.cycles.order` and `cut_witness.order` record foot-order metrics (`apart`, `swing`, `floor`, `changes`, `slides`, `spacing`, `travel`, `sway`, `tilt`, `per`, `says`, `why`), and `video-cycle-align` reports held suspect loops under `held` with `{reason, report}`.+- Python callers: new `local_cycle.read_cycles(reading, distances, view=None, cue=None, cue_step=None, signals=None)`, `local_cycle.bob_word(signals, interval, feet=False)`, `local_cycle.twice_an_interval(values, interval)`, `local_cycle.own_beat(signals, interval)`, `local_cycle.cut_word(signals, length)`, `local_cycle.over_feet(signals, interval)`, `local_cycle.unwitnessed(cycle)`, `local_cycle.four_steps(cycle)`, `local_cycle.held_verdict(cycle)` (refuses with a `ValueError` a cut held on one step whose record names no line it was read on (no `by` or `lines`)), `legs.OPAQUE`, `local_cycle.BOB_OWN`, `local_cycle.BOB_SCALE`, `local_cycle.BEAT_FRAMES`, `legs.body_signals(frames)`, `legs.BANDS`, `legs.band_rows(median)`, `legs.band_widths(alpha, rows)`, `legs.zoomed(alpha, scale)`, `local_cycle.BAND_FLOOR`, `local_cycle.off_flow(values, interval)`, `local_cycle.cue_word(cue, interval, step=None)`, `local_cycle.BOB_TWICE`, `local_cycle.BOB_FLOOR`, `local_cycle.BOB_ROWS`, `local_cycle.CUT_LINES`, `local_cycle.CUT_WORDS`, `local_cycle.UNWITNESSED`, `local_cycle.FOUR_STEPS`, `local_cycle.CUE_FLOOR`, `legs.TONE`, `local_cycle.repeat_at(distances, span)`, `batch.anchor_for(state, cut, anchor)`, `batch.left_out_why(reasons, stands=False, one_step=False)`, `loop.stand_retake(cycle)`, `loop.retakes(*records)`, `loop.STAND_REASON`; `crossings._alternation` is now public `crossings.correlation_on(values, span)`; `align._feet`, `align._depth_cue`, `align._shade_cue`, and `align.SHADE_BAND` are moved to `legs.feet_halves`, `legs.depth_cue`, `legs.shade_cue`, and `legs.SHADE_BAND` (`align` keeps `_depth_cue` and `_shade_cue` aliases); `crossings.Reading` gains `interval`, `per`, `cycles`, `hides`, and `mark_cycles(said)`. `local_cycle.read_cycles` and `local_cycle.cut_word` take `order`, `cut_word` takes `declined`, and `align.held_cut` checks loop cut reports.- **Tests**: `tests/video/test_walk_steps.py` covers these synthetic walker cases (the walkers' bodies rise and fall on legs whose soles stay on the ground unless held still or drawn carried whole; the walkers whose body is witnessed (and those the cut's witness reads one step of) swing their arms within the body's sides, 8 px either way of its middle (`ARMS_IN`), the body's sides 28 px apart; the other walkers seen from the side, from behind or on a front diagonal swing them 16 px either way of the body's middle, past its sides; the walker seen from the front swings its arms up and down beside its body, and some walkers have no arms):- a walker seen from behind whose far foot hides behind the near one (feet together over half the interval) across cycles of 20 frames on twos, 24 on threes, and 17.5 and 18.5 on ones: its top line rises and falls twice an interval, cutting one cycle within a frame with `cycles` true, `steps: 2`, and no cue read with no view, its bob's `body.share` at least `0.3`, `body.scale` at least `0.6`, `edge` 0, every band seen holds still on the beat (`still_bands` equals the bands seen), and its `why` naming the body's own; the same walker with its far leg drawn as the near one (legs alike), with no view and with `--view back_diagonal`, is still cut to one cycle because the view's cue says `"alike"` (which no longer refuses) and the bob witnesses;- a front-diagonal walker whose near foot steps out toward the camera and passes the far one apart (feet together under half the interval, cycle 16 and 18): with `--view front_diagonal` cut to one cycle because its foot cue moves over the floor and does not turn over one interval on (`says` null) and its top line rises and falls twice an interval; without a view it is not asked and is cut to two cycles (32, 36 frames); its cut witness says `"four steps"`, its strip says `steps: 2`, and `local_cycle.four_steps` is true;@@ -59,11 +61,16 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- the walker whose far foot passes hidden behind the near one, its legs drawn alike, its feet meeting once a cycle (17.5 frames), rising and falling on its legs once a step, turned 15 degrees about its feet over the clip (k/72 of it in frame k, on a canvas 60 px taller above and below: a lean changing slowly on its feet), swinging its arms within its sides: it cuts one cycle (within 1 frame of 17.5), the count reading its crossings as cycles (`cycles` true, `steps: 2`); on the screen the top line, less its flow, rises and falls of its own twice the cut, every band of its upper body seen holding still on the beat: the cut's witness says "two steps", the screen among the lines that say it (`by`), not held, no warning; read off its frames on a cut of 18, the line over its feet says null: it does not rise and fall twice an interval (the lean tilts the ground under the feet, and the line over them takes in the two feet's heights by turns), where the line on the screen says "two steps" (`by` the screen alone).- a side walker whose legs four tones apart tell its steps apart on a 30-frame cycle, swinging its arms within its sides, filmed 100 frames, with its body sinking 3 px once a cycle and not at each step (a limp) is cut 30 frames by the search, two steps by the crossings, returning "one step", held and named, and is never cut 60 frames long.- the legless body bouncing every 16 frames: the search cuts one bounce (16 frames, within 1) and the cut stands as cut, never cut again two long; it squashes as it bounces, so its upper body's widths, read on rows below its top, change with it on that beat: nothing witnesses the cut (`says` null), and it is held and named; read on twice its cut, its top line rises and falls twice that interval and the word says null, its why naming the upper body's width.+ - the walker seen from the front whose feet stay apart (stepping foot drawn up to 3 px under the ground, the other as far over it; right foot swinging in to meet the left only while it is drawn higher, the other foot drawn lower and nearer the viewer, and back out before it is drawn lower; no foot standing on the ground sliding along it; arms swinging within the body's sides; body not rising and falling), 20-frame and 24-frame cycles, `--view front`: cut one cycle, `steps` 2, `cycles.order.says` "two steps", zero slides, travel under `ORDER_TRAVEL` of spacing, body word null, `cut_witness` "two steps" by `["order"]`; with `--view side`: cut two intervals, `cut_witness.held` "unwitnessed", no order read (previously cut two intervals with a warning).+ - the walker from the side with legs drawn alike (46 frames, swinging leg lifted 6 px at pass) with no view and with `--view` front, front_diagonal, back, and back_diagonal: cut 46 frames, `steps` 2; crossing check has `cycles` false, `order.why` value stating a foot passes under the body; cut never stands on order.+ - the walker whose feet stay apart (cycle 30) tested across spans in `local_cycle.order_word`: spans of 30, 60, and 15 frames, `says` value "two steps", "four steps", and "one step", span 22 none, also checking that no foot slides and that the upper body's sway stays under `ORDER_SWAY` of the tilt; picture rocked 10 degrees either way about feet once a cycle, feet drawn level and still, `says` null, `why` value stating it may rock on its feet; the same walker drawn with its right foot sliding along the ground, planted, to meet the left as both stand level and back out, `says` null, `why` value stating a foot slides (the order is not read where a foot on the ground passes under the body toward the other side); lifted-foot side walker with legs 5 and 10 px either side of line, `says` null, `why` value stating a foot passes under the body; rear walker with soles on one row, `says` null, `why` value stating feet are drawn level.+ - the walker whose feet stay apart cut 20 frames, `--view front`, under `loop._witnessed`: cut stands on order, `by` `["order"]`; with step count `declined` record set: cut held, `cut_witness.held` "unwitnessed", `order.read` "two steps", `order.why` value stating order does not stand a length the closing refused.- **Tests**: `tests/video/test_gait_guard_anchor_wide.py` and `tests/video/test_cycle_align.py` cover batch anchoring and cycle alignment:- `batch.anchor_for` assigns `motion-auto` to walk and run loops while assigning `none` to cheer, walk with `--anchor none`, and pinned idle items, propagating loop retakes to item records, warnings, and markdown tables;- `batch.align_gaits` excludes loops with a `start-stop` retake, a loop with `cycle-unwitnessed`, or a loop with both, names its reasons under `left_out` (`["start-stop"]`, `["cycle-unwitnessed"]`, `["start-stop", "cycle-unwitnessed"]`) and in the stderr warning, aligns remaining directions, and leaves the state unaligned when fewer than two directions remain.- `batch.align_gaits` with three directions, two loops of one cycle (20 and 24 frames) and one loop of two cycles (40 frames) whose strip says `steps: 2` and whose cut witness says four steps: the two-cycle loop is left out under `left_out` (`["cycle-four-steps"]`) and named in the warning, its loop and strip kept as cut (40 frames, `steps: 2`), and the other two are aligned to their median length.-- **Tests**: `tests/video/test_one_step_cut.py`: a side walker whose cycle (42 frames) the walk window cannot hold is cut one step long (21 frames) by the pixel search, its feet read as unseen, and the step screen names it; before, the test said nothing else speaks (no `steps` and no warning about steps), whereas now there are still no `steps`, the walker is carried whole on its legs, so its cut witness holds the cut (`cut_witness.held` is `"unwitnessed"`, `local_cycle.unwitnessed` is true), and the one warning that speaks of steps is the witness's (`local_cycle.held_verdict`), naming `cycle-unwitnessed`. In a set of two items, the same walker on a 25-frame cycle (front, cut a whole cycle) and the one-step side walk, their rows now carry the marks `run_set` records (`cycle-unwitnessed` from `local_cycle.unwitnessed`, and `step_screen`) instead of rows built without them; both are left out of the alignment (`left_out` `["cycle-unwitnessed"]` each, `why: "fewer than two directions left to align"`), each warning says nothing witnesses its cut whole cycles and it may hold half a cycle or two, only the side walk's warning adds that it may be one step (cut it again with `video-loop --steps 1` if it is), `video-cycle-align` run on the items' loops reads the step screen in the report beside the side walk's loop and stops on it (`one_step`), naming `--steps 1`, and the set table still marks the side walk's cycle `(one step?)`.+ - three walker loops with reports beside them, the third loop marked held (`cut_witness.held` "unwitnessed") or four steps (`cut_witness.says` "four steps", strip `steps: 2`, walker two cycles long): standalone `video-cycle-align` stops with one suspect, `held` value `{reason, report}`, `settle` value `=1` and `=2`, nothing rewritten; `--multi-cycle warn` aligns and names reason; `--cycles` 1 or 2 aligns it, suspect `status` "counted" (previously aligned as one cycle without a word).+- **Tests**: `tests/video/test_one_step_cut.py`: a side walker whose cycle (42 frames) the walk window cannot hold is cut one step long (21 frames) by the pixel search, its feet read as unseen, and the step screen names it; before, the test said nothing else speaks (no `steps` and no warning about steps), whereas now there are still no `steps`, the walker is carried whole on its legs, so its cut witness holds the cut (`cut_witness.held` is `"unwitnessed"`, `local_cycle.unwitnessed` is true), and the one warning that speaks of steps is the witness's (`local_cycle.held_verdict`), naming `cycle-unwitnessed`. In a set of two items, the same walker on a 25-frame cycle (front, cut a whole cycle) and the one-step side walk, their rows now carry the marks `run_set` records (`cycle-unwitnessed` from `local_cycle.unwitnessed`, and `step_screen`) instead of rows built without them; both are left out of the alignment (`left_out` `["cycle-unwitnessed"]` each, `why: "fewer than two directions left to align"`), each warning says nothing witnesses its cut whole cycles and it may hold half a cycle or two, only the side walk's warning adds that it may be one step (cut it again with `video-loop --steps 1` if it is), `video-cycle-align` run on the items' loops reads the step screen in the report beside the side walk's loop and stops on it (`one_step`), naming `--steps 1`, and the set table still marks the side walk's cycle `(one step?)`. The walker carried whole on its legs across the two set tests: `video-cycle-align` now stops on both loops, each named `held`, `reason` "cycle-unwitnessed", the side loop also suspected one step; a count of one cycle for each settles it.## 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 nothingdiff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex d7170e8..b73c790 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -1577,6 +1577,46 @@ each sole up to 6, 12 or 24 px lower the further back its foot is, the foot movi(the lowest row is the planted foot, sliding down the screen through its step); still, or on a picturemoved 3, 6 (four phases) or 12 px either way every d/2 frames, or 6 px every d: never witnessed.+**The order the feet are drawn in.** `legs.feet_order(frame)` reads the order a frame draws its two feet in.+`ground` records the first and last column of each run of solid pixels within `legs.CONTACT` (0.005 of the body's+height, at least one row) of the frame's lowest row, and `height` records the body height. The feet are seen+`apart` when the foot band (the lowest `legs.FOOT_BAND`, 0.08, of the height) parts at its widest empty run, and+that run spans at least `legs.FEET_APART` (0.02) of the height. Where they are apart, `depth` measures how many+rows lower the right foot's lowest solid row is drawn than the left's, `left` and `right` record each foot's+contact columns within `CONTACT` of its own lowest row, and `sway` records how far right of the middle of that+empty run the mean column of the upper half of the body lies. From the front, the back, or a diagonal, the foot+nearer the viewer is drawn lower, and the nearer foot changes sides once a step, twice a cycle. Counted over a+crossing interval or a cut, those changes say how many steps it holds. The view's label is not taken for it,+because a generated walk's label may be wrong: the clip must show that its two sides of feet are its two legs, or+nothing is witnessed. `local_cycle.order_word(order, span)` tests the frames across a span through a sequence of+gates in order: the feet must be seen apart in at least `legs.FEET_APART_SHARE` (20 %) of the frames; the depth's+swing (10th to 90th percentile) must reach at least `ORDER_ROWS` (2) rows and `legs.REACH_MIN` (0.015) of the+height, or the feet are drawn level; each frame's lower side is read where one foot is at least an eighth of the+swing (at least one row) lower; no change of side may have the lower foot's contact before it and the other+side's contact after it share or touch a column, which marks one foot sliding under the body from one side to the+other as seen from the side; nothing standing on the lowest row may slide along it `ORDER_TRAVEL` (0.8) of the+feet's median distance apart or more (`_travel` follows each run frame to frame while it touches exactly one run+of the next frame, starting afresh where runs meet or part); and the upper body's sway (10th to 90th percentile)+must stay under `ORDER_SWAY` (0.5) of what a tilt about the feet would need to draw one foot that much lower (the+swing times `ORDER_REACH`, 0.75, of the height, over the feet's distance apart), because a picture rocking on its+feet draws one foot lower and then the other. Then at least three changes are required, and their rate over the+span (the span over the mean distance between changes) must fall within `ORDER_SLACK` (0.2) of two, four, or one,+with no two changes more than twice their mean apart (`ORDER_WORDS`), giving `"two steps"`, `"four steps"`, or+`"one step"`, or null with `why`. The record keeps `apart`, `swing`, `floor`, `changes`, `slides`, `spacing`,+`travel`, `sway`, `tilt`, `per`, `says`, and `why`. It is not read from the side (`--view side`,+`local_cycle.SIDE_VIEW`), where the two sides of the feet are the front foot and the back foot rather than two+legs. In `local_cycle.read_cycles(..., order=None)`, `video-loop` passes `order=[legs.feet_order(f) for f in+frames]`. After the foot cue's refusal and the body's word, where the body does not witness two steps an interval+and the order says `"two steps"` over the crossing interval, the crossings mark cycles: `cycles` is true, and+`why` records that the foot drawn nearer changes sides `<per>` times an interval, the clip's two sides of feet+its two legs (none slides from one to the other, the upper body sways `<sway>` px of the `<tilt>` a tilt would+need): two steps an interval, the feet meet once a cycle. The record is kept as `cycle.step_count.cycles.order`.+Where nothing witnesses, `why` adds the order's own reason ("the order of the feet is not read from the side"+from the side). A diagonal walk whose feet pass each other on the screen, one foot always drawn lower and the+other passing it on either side, shows the same changes a side walk does (a planted foot sliding under the body+past the other), and the order does not witness it: its crossings stay on steps or its cut is held, named. A side+walk is never read on the order, and reading which foot passes in front of which on the screen is not done here.+**Choosing the cut.**- The clip does not show its steps (no feet seen, a legless body, a lean that does not turn over, under@@ -1672,10 +1712,28 @@ places. The line over the feet is then the feet's as much as the body's: a footso once a cycle, and a cut of two cycles could be stood on it as one. A mark holds nothing: the cut stands as itsword says, and nothing is warned or left out for it. Two steps or four steps: the cut stands, and`cycle.cut_witness` records `{cut: [s, L], ...cut_word's record}`.+`local_cycle.cut_word(signals, length, order=None, declined=None)` reads the order on the cut: `loop._witnessed`+passes it the order (none from the side, none where the frames give no top line) and the step count's `declined`+record. Where neither line says two steps or four steps, the order is read on the cut: if it says two steps or+four steps, the cut stands, `by` records `["order"]`, and the record is placed under `order`. Otherwise the+lines' word stands, the order's record is kept under `order`, and its reason is joined to the cut's why. A cut of+four steps read on the order is two cycles exactly as one read by the body: `local_cycle.four_steps` is true,+`video-set` leaves it out (`cycle-four-steps`), and the `video-set` warning reads "its body rises and falls, or+its foot drawn nearer changes sides, four times in its cut (cycle-four-steps)". Because the order counts the+changes in a cut rather than whether the cut's length closes them, a cut a sixth short of a cycle still reads two+steps. Where the cut is the search's, kept because none of the clip's two-step cuts closes (`declined`, the step+count's record of the best of them), the order does not stand a length the closing refused: `order.says` is null,+`order.read` keeps the word it read, its why says the order "counts its steps, not whether its length closes, and+does not stand a length the closing refused", and the cut is held (`cut_witness.held` "unwitnessed",+`cycle-unwitnessed`). The body's word on such a cut is unchanged.A cut of four steps (two cycles) still has its strip counting two steps (`steps: 2`), which `video-cycle-align`reads as one cycle; so `local_cycle.four_steps(cycle)` is true and `video-set` leaves the item out of its state's-cycle alignment (`left_out` `["cycle-four-steps"]`, `local_cycle.FOUR_STEPS`), its loop as cut. `video-cycle-align`-run on its own does not read the witness.+cycle alignment (`left_out` `["cycle-four-steps"]`, `local_cycle.FOUR_STEPS`), its loop as cut.+`video-cycle-align` run on its own reads the cut report beside each loop through `align.held_cut(loop_dir,+meta_path, meta)`. Where nothing witnessed the cut whole cycles (`cycle-unwitnessed`) or the cut spans four steps+(`cycle-four-steps`), the loop is named under `held` and the aligner stops under `--multi-cycle fail` before+rewriting any files, adding "and nothing witnessed some of the cuts whole cycles". Under `--multi-cycle warn` it+aligns the loop with a warning, matching `video-set` instead of aligning held loops as one cycle without a word.Anything else: the cut is held: kept exactly as it was chosen (two of the clip's crossing intervals where thestep count counted them, else the search's cut), `cut_witness.held` is `"unwitnessed"`, a warning line names`cycle-unwitnessed` (`local_cycle.held_verdict(cycle)`, said through `local_cycle.step_verdict`), and@@ -1862,6 +1920,19 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-In `video-set`, a walk whose cut its cut witness held is left out of the alignment(`cycle-unwitnessed`) before it is screened, and where its step screen suspects one step, itswarning gives the same advice (cut it again with `video-loop --steps 1` if it is one).+ `video-cycle-align` run on its own reads the cut report beside each loop through+ `align.held_cut(loop_dir, meta_path, meta)` (using `align.cut_report` in the loop's directory or+ the directory above it, matching the strip metadata). When nothing witnessed the cut whole cycles+ (`local_cycle.unwitnessed`, reason `cycle-unwitnessed`) or a loop with two strip steps was cut two+ cycles long (`local_cycle.four_steps`, reason `cycle-four-steps`), `held` records `{reason,+ report}`. Under `--multi-cycle fail` (the default), the command stops before anything is rewritten,+ adding "and nothing witnessed some of the cuts whole cycles". A loop counted two steps whose cut is+ held receives no `steps` status and its return half way is not read as its second step; `settle`+ offers `--cycles <loop>=1` to align it as one cycle and `--cycles <loop>=2` to take one cycle out+ of two, and a held loop that may be one step is cut again with `video-loop ... --steps 1`. Under+ `--multi-cycle warn`, it is aligned and warned that "at the set's length it plays half or twice as+ fast as the rest, if it is not one cycle" where no return was found, bringing standalone alignment+ into agreement with `video-set` instead of aligning held loops as one cycle without a word.- **Two cycles in one loop are stopped, and counted by whoever looks**: one length for the set isone beat only if every loop holds one cycle. A loop that holds two strides, resampled to theset's length, walks twice as fast as the rest, arms and legs alike — and pixels cannot tell it