Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(video-loop): a part that rushes on its way is eased over the frames either side, the body's own steps kept
Soohong Kim790a17fd1732
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c76cecb..6cd37b4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased+- **New: `video-loop --repair auto` (and `on`) eases a part that rushes on its way — the frames either side of the rush are made again at times that spread it, the body's own steps kept.** A part can keep its way and still jump: a tail that runs short of the cycle rushes on at the wrap, covering in one step what it covers in eight elsewhere, and each frame there lies near enough the line between its neighbours that the flow reading lets it pass, or takes the frame at the wrap out and leaves the rush over two steps. `repair.surges` reads the speed on the flow reading's own path and windows: a run of one or two steps whose mean step is at least 3.0 usual steps and 3.0 times the mean of the three steps either side, the part going on the way it came through it (a step that turns back is a frame flung, the flow repair's). After the flow groups, the worst rush is eased over three or four drawings either side, made from the frames as filmed (a frame the flow made inside is made again, `supersedes`) and kept between two frames as filmed: `repair.ease_times` gives every frame a time, on a grid of a twentieth of a step, where the part's step changes from one step to the next as little as it can — from the speed it came in with to the speed it goes on with — while the foot line's centre and the body's mass (`loop.foot_centre`, `loop.body_centre`) and the lowest solid row move in a step no further than the stretch's largest step as it played and half a pixel, and every other window of the flow reading no further than its own largest step there; within 2 % of that, the timing nearest the frames' own. How far the part has gone is the path of its coverage's centre in the windows that read the rush, which grows as far as the part moves where a blurred distance stops growing. RIFE makes each drawing between the frames as filmed either side of its time, one call a drawing, at most nine, outside the three of the flow groups; the stretch is taken only where no frame made has an interpolation fault, no body measure moves a pixel past the stretch's largest step, the part's largest step falls, no frame is left further off the flow and over its limit, and no new rush appears in the rest of the body (`rejected_for`). On the synthetic walker the tail a tenth of a cycle short — under the flow reading's limit — goes from 5.8 usual steps into the wrap to at most 2.7; a quarter short, after the flow repair, from 7.2 to 5.0 and still read a rush, as far as the legs allow; ordinary walks and a flung frame read no rush. A loop with no rush costs one more reading and no call. `jump_repair` carries `surge`, `surge_after`, `ease_skipped`, `ease_calls` and the round `why: ease`, `replaced` its frames, and the summary `eased`; without RIFE the rush is cut as filmed with a warning line, and `--repair on` refuses ([loop-repair](docs/loop-repair.md) section 2, "The eased retime").+- **Tests** — `tests/video/test_loop_ease.py` (a tail that rushes on at the wrap after the flow repair is eased over three or four drawings either side, in play order, made only from frames as filmed — the flow's frame at the wrap made again — every frame outside as it was, the part's largest step down by a quarter or more and the body's feet, mass and ground within the stretch's own steps and a pixel; a rush under the flow reading's limit eased, none left; ordinary walks, drawn every frame and on twos, have no rush and nothing is made; a frame flung against the way is not a rush; on twos each drawing made once and shown on both its frames; a made frame pushed sideways refuses the stretch for drift, and one with its outline melted for a fault, the loop left as the flow left it; without an interpolator the rush named and nothing made; the same frames whichever way the body faces; the search keeps every frame at its own time where the part moves evenly, and spreads a rush as far as the body's bound lets it; `video-loop` playing the frames made in a loop as long, a rush without RIFE cut as filmed with a warning line, `--repair on` without RIFE refused), and `tests/video/test_loop_flow.py`'s walker draws its dark parts whole on asking (`dark_whole`), so that a frame drawn between two phases has no more dark pixels than they have.- **Behavior change: a frame the jump repair or the cycle alignment makes between outlined drawings loses its outline only where it is lighter than its neighbours' edge rank by rank, too.** The fault `outline` read the made frame's edge against one dark line (a solid pixel under 70/255 within 2 px, `outline_loss` over 5 %), so art outlined in a mid tone — a brown or a painted line whose tone lies about 70/255 — had its line on the near side of the line in the drawings and on the far side wherever the flow softened it by a few tones: every frame made between two such drawings read as melted, and the repair and `--between auto` refused it. `rife.outline_shift(made, a, b)` reads the same edge, each pixel by how dark the darkest solid pixel within 2 px of it is, in order, against the lighter neighbour's edge at the same rank, and counts it where it is lighter by more than 50/255 (`rife.OUTLINE_SHIFT`). The fault `outline` now needs both over 5 %: a softened line is lighter by less at every rank and is kept, whatever tone the art outlines in; a line gone to the fill beside it is lighter by its whole contrast and is lost. Art outlined near-black reads the same on both, and art outlined lighter than 70/255 is still not judged by the outline. On the two-tone walker of the tests, the drawing between with its line 20 to 45 tones lighter reads `outline_loss` 57 % and `outline_shift` 0 (refused before, kept now); with its legs' line turned to fill, 24 % and 48 % (refused). A line less than 50/255 darker than the fill it melts into is not read as lost. The rank reading is read only between outlined drawings: `rife.outlined(frame)` is the share of a frame's edge whose line, the darkest solid pixel within 2 px, is darker than its fill, its colour from twice the bleed's depth inside (`rife.LINE_DEPTH`), by more than 50/255, and both neighbours must read at least 75 % (`rife.OUTLINED`); elsewhere `outline_shift` is `null` and the dark line judges alone, as before. Art painted without a line has no line to lose, and a part the flow melts there — a boot washed pale — can come out lighter by less than 50/255 at every rank: read rank by rank it would be kept and delivered, where refused it is replaced by the nearer filmed frame. On the walker of the tests painted without a line (outlined on 4 % of its edge), the drawing between with its near boot washed 40 tones lighter reads `outline_loss` 7.8 % and, rank by rank, 0: refused. The 75 % is set on frames made between drawn walks and judged by eye so that no frame seen as broken that the dark line alone refused is kept. The jump repair's proposals and the alignment's `smear` rows carry `outline_shift`, and the alignment's warning line names it where it was read; `video-loop-compare` and `video-loop-repair` keep their versioned measures, `rife.smear` alone, and judge the outline on the dark line as before ([loop-repair](docs/loop-repair.md) section 4).- **Tests** — `tests/video/test_outline_shift.py` (a mid-tone line drawn lighter is kept and one gone to fill is lost; the versioned measures judge on the dark line alone, and so does a measure whose rank reading was not read; art outlined near-black reads the same on both; a frame with no edge reads 0 and neighbours with none are not read; the jump repair takes a lighter line and refuses one gone to fill; the alignment keeps the one and takes the nearer frame for the other; on the walker painted without a line, a boot washed 40 tones lighter is refused by the jump repair and replaced by the alignment, and the two-tone and black walkers read outlined on all their edge; through RIFE, a short step of two-tone legs keeps its outline and legs crossing far lose it on both).- **Behavior change: every RIFE call runs the binary's test-time augmentation, `-x -z` (`rife.TTA`).** `-x` runs the pair as its eight flips and transposes and `-z` both ways in time, and the results are averaged, so a frame made from a to b is the one made from b to a. Neither rife-ncnn-vulkan nor Practical-RIFE has released a model since 2024; the model stays `rife-v4.6`. On the synthetic pairs of `tests/video/test_rife.py`, `-x -z` is the one setting of the four (none, `-x`, `-z`, both) that makes legs crossing far the same both ways with no ghost, and it keeps the most of a short step's outline. On the Mac's GPU it adds a tenth to half a second a frame; on Modal's CPU it costs 15 to 19 times a plain call's CPU — 12 to 30 s a 280 × 520 frame on two cores, 44 to 61 s a 960 × 960 frame. `SPRITE_GEN_RIFE_TTA` names another (`-x`, `-z`, both, or empty for none; anything else is refused before a frame is asked for), for a CPU-only machine that aligns sets. The interpolator a report names (`jump_repair.interpolator`, the alignment's `interpolator`) carries `tta`. A call past 600 s (120 s before) is stopped and reported as a RIFE that failed, where it used to end in Python's own timeout ([loop-repair](docs/loop-repair.md) section 1, "Which setting").diff --git a/SKILL.md b/SKILL.mdindex efcebe8..1312073 100644--- a/SKILL.md+++ b/SKILL.md@@ -144,7 +144,7 @@ Scene creation consumes finished assets and remains optional. Asset metadata own## RIFE for walk and run loops-`video-loop` repairs a walk's or run's jump frames and gives its filmed ghosts way (a half-drawn frame the video model left, `ghost_given_way`), and `video-set` gives a direction set one cycle length, both with RIFE in-betweens. Install it once per machine: `$SPRITE_GEN_ROOT/.venv/bin/sprite-gen rife install` (pinned rife-ncnn-vulkan 20221029 and model rife-v4.6, SHA-256 checked, into the user data directory, ending with a check frame; Linux without a GPU first needs `libvulkan1 mesa-vulkan-drivers`). Every call runs the binary's test-time augmentation `-x -z`; on a CPU it costs 15 to 19 times a plain call, so a CPU-only machine aligning a set may set `SPRITE_GEN_RIFE_TTA=` (none) or `-z`. Without it every loop is still cut — a jump as filmed, each filmed ghost given way to the clean frame beside it — and what was left unrepaired says so: a `warning:` line on stderr and `jump_repair.rife` with `jump_repair.unmade` (the jump left as filmed) in the loop report (`applied` alone is not the sign: a ghost given way reads true), `cycle_align.<state>.applied: false` and `warnings` in `set.report.json`. When that happens, tell the user which loops went unrepaired and offer the install; after it, cut those loops again and run `video-cycle-align`. `video-loop --repair on` and `video-cycle-align` fail without RIFE instead. [loop-repair](docs/loop-repair.md).+`video-loop` repairs a walk's or run's jump frames, eases a part that rushes on its way at the wrap and gives its filmed ghosts way (a half-drawn frame the video model left, `ghost_given_way`), and `video-set` gives a direction set one cycle length, both with RIFE in-betweens. Install it once per machine: `$SPRITE_GEN_ROOT/.venv/bin/sprite-gen rife install` (pinned rife-ncnn-vulkan 20221029 and model rife-v4.6, SHA-256 checked, into the user data directory, ending with a check frame; Linux without a GPU first needs `libvulkan1 mesa-vulkan-drivers`). Every call runs the binary's test-time augmentation `-x -z`; on a CPU it costs 15 to 19 times a plain call, so a CPU-only machine aligning a set may set `SPRITE_GEN_RIFE_TTA=` (none) or `-z`. Without it every loop is still cut — a jump or a rush as filmed, each filmed ghost given way to the clean frame beside it — and what was left unrepaired says so: a `warning:` line on stderr and `jump_repair.rife` with `jump_repair.unmade` (the jump left as filmed) or `jump_repair.ease_skipped` (the rush) in the loop report (`applied` alone is not the sign: a ghost given way reads true), `cycle_align.<state>.applied: false` and `warnings` in `set.report.json`. When that happens, tell the user which loops went unrepaired and offer the install; after it, cut those loops again and run `video-cycle-align`. `video-loop --repair on` and `video-cycle-align` fail without RIFE instead. [loop-repair](docs/loop-repair.md).## Contracts and advanced toolsdiff --git a/docs/README.md b/docs/README.mdindex 97a1c8e..18d442e 100644--- a/docs/README.md+++ b/docs/README.md@@ -85,7 +85,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.| [video.md](video.md) | `sprite-gen video` / `video-extend` / `video-edit` / `video-resume`: stills and clips to mp4 through Grok Imagine (image-to-video, last-frame pin, references, extension, editing, asking again for an unfinished generation) with the user's own credential || [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch, a set's directions on one sheet || [loop-review.md](loop-review.md) | Automatic loop decisions, ambiguous gait review, visual evidence and explicit cut/alignment overrides |-| [loop-repair.md](loop-repair.md) | RIFE (where it runs, cost, licences, `sprite-gen rife install`, what runs without it), jump-frame repair, the flow reading (frames off a walk's way), the jolt index and its gate, one cycle length per direction set |+| [loop-repair.md](loop-repair.md) | RIFE (where it runs, cost, licences, `sprite-gen rife install`, what runs without it), jump-frame repair, the flow reading (frames off a walk's way), the eased retime (a part that rushes on its way), the jolt index and its gate, one cycle length per direction set || [frame-interpolation.md](frame-interpolation.md) | Generative in-betweens for sprite frames, recorded as a take || [seamless-video-loop.md](seamless-video-loop.md) | Making a non-looping ambient clip loop forever (RIFE seam bridge) — a different job from pipeline B |diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex 3a7edbb..75b0142 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -1,6 +1,6 @@# Loop repair — RIFE in-betweens for jump frames, the jolt index, one cycle per set-> Owns: Where RIFE runs and what it costs, which model and augmentation it runs with, how it is installed and what runs without it, jump-frame repair in `video-loop`, the flow reading (frames off a walk's way), the jolt index and its gate, cycle alignment across a direction set · Index: [docs/README.md](README.md)+> Owns: Where RIFE runs and what it costs, which model and augmentation it runs with, how it is installed and what runs without it, jump-frame repair in `video-loop`, the flow reading (frames off a walk's way), the eased retime (a part that rushes on its way), the jolt index and its gate, cycle alignment across a direction set · Index: [docs/README.md](README.md)A walk loop cut from a generated clip can look right in every still and still hitch when itplays: the video model redraws thin hair a little differently every frame, and now and then@@ -220,7 +220,10 @@ cyclic, the last frame followed by the first, inside the union box of the body o(the strip cells' own crop). The frames that leave the loop's flow — one or two drawings in a rowthat lie far off the line between the frames either side of them, by direction and speed, not byhow much a step changes ([the flow reading](#the-flow-reading--a-frame-off-the-walks-way-not-a-large-step)-below) — are taken out and made again by RIFE between the frames either side.+below) — are taken out and made again by RIFE between the frames either side. Where a part keeps its way+and rushes — a tail that runs short of the cycle, rushing on at the wrap — the frames either side of+the rush are then made again at times that spread it, the body's own steps kept ([the eased+retime](#the-eased-retime--a-part-that-rushes-on-its-way) below).| Rule | Value | Why ||---|---|---|@@ -434,6 +437,107 @@ of the same blurred path, over the same usual step unless said otherwise.| Frame deletion and insertion by optical-flow consistency | Chao, Jiang and Sun, IWDW 2012 | not run | no: the same question for edited video, answered on flow (above) || Outermost points (each row's outermost column) fitted on a periodic curve | — | not run on these loops | no: the outermost point of a row switches from one part to another (a foot leaving the row), a jump on an ordinary step |+### The eased retime — a part that rushes on its way++The flow reading names a frame that leaves the way a part is going. A part can keep its way and+still jump: a tail that runs short of the cycle — swinging on a beat of its own, as a generated+clip's tail can — rushes on at the wrap, covering in one step what it covers in eight elsewhere.+Each frame there lies near enough the line between its neighbours that the flow reading lets it+pass, or takes the frame at the wrap out and leaves the rush over two steps, half as fast and still+far faster than the steps around it. `repair.surges` reads the speed itself, and a stage after the+flow groups makes the frames either side of the rush again, at times that spread it.++**The rush.** On the flow reading's own path, windows and usual steps, on the loop as the ghost and+flow rounds left it: a run of one or two steps (`SURGE_SPAN`) whose mean step in a window is at+least **3.0** usual steps (`SURGE_LIMIT`) and **3.0** times the mean of the three steps either side+of it (`SURGE_RATIO`, `SURGE_AROUND`), and through which the part goes on the way it came — no+drawing from the run's first to its last turns back (the flow reading's `turn` at least 0; a step+that turns back is a frame flung, the flow repair's). Rushes are taken worst first by that ratio,+none sharing a step. On the synthetic walker of the tests (measured 2026-10-17):++| Loop | Largest step, usual steps | Largest run over 2 against the steps either side | Read |+|---|---|---|---|+| ordinary — drawn every frame, at 24 frames, on twos | 2.1 to 2.4 | 1.9 to 2.2 | no rush |+| a frame flung 5 % of the body height against the sway | 5.0 | 3.9 | not a rush: it turns back (the flow repair takes it) |+| the tail 5 % of a cycle short | 3.8 at the wrap | 3.2 | a rush |+| 8 % short | 4.9 | 4.4 | a rush |+| a tenth short — the flow reading's 2.6, under its limit | 5.8 | 5.8 | a rush |+| a quarter short — the flow repair makes a frame at the wrap, and two steps of 5.8 are left | 10.6 (7.2 after the flow repair) | 13.2 (6.6) | a rush |++**The stretch.** Three or four drawings either side of the rush (`EASE_WIDTHS`), between the two+drawings at its ends, which are kept: three a side for a one-step rush is six frames, four a side+for a two-step one nine. It is made from the frames as filmed: a drawing the flow repair made+inside it is made again (`supersedes`), never made from, and a stretch never ends on one. A stretch+never holds a frame given way, refused, or read off the flow turning back. Four a side is taken+only where it eases the part more than three by over 2 % (`EASE_SLACK`); one stretch a loop, the+worst rush that has one.++**The times.** How far the part has gone is the path of its coverage's centre inside each window+that reads the rush, in px, through the frames as filmed: a centre moves as far as the part does,+where the distance between two blurred states stops growing once they no longer overlap, and a+rush split by it would come out faster in the middle than the search reckoned. Every frame of the+stretch is given a time, on a grid of a twentieth of a step (`EASE_GRID`); of the timings that go+forward and keep, in every step,++- each body measure — the foot line's centre and the body's mass, x (`loop.foot_centre`,+ `loop.body_centre`: the reference `--anchor feet` reads drift on), and the lowest solid row, y,+ the ground it stands on (`repair.drift_points`) — within the stretch's largest step as it played,+ and half a pixel (`DRIFT_PIXEL` − `EASE_MARGIN`), drawn between the frames as filmed, and+- every other window of the flow reading — the rest of the body — within its own largest step in+ the stretch: no leg or arm hurried past what it did there,++`repair.ease_times` takes the one whose largest change of the part's step from one step to the next,+from the step into the stretch to the step out of it, is least (`accel`): the part speeds up and+slows down as gradually as the body lets it, from the speed it came in with to the speed it goes on+with — an ease in and out whose ends are its own. Of the timings within 2 % of that, the one nearest+the frames' own times, so a frame the part does not need moved keeps its time.++**Made, then read again.** Each drawing not at its own time is made by RIFE between the two frames+as filmed either side of its time, at that fraction of the way between them (in frames), and shown+on every frame the drawing was; a time on a frame as filmed is that frame. One call a drawing made,+at most nine, outside the three of the flow groups (`ease_calls`). The stretch is taken only where,+on the frames made:++| Read on the frames made | Refused for (`rejected_for`) |+|---|---|+| no made frame carries an interpolation fault (section 4) | `fault` |+| no body measure moves in a step more than a pixel past the stretch's largest step as it played — the measures are read on whole pixels, the ground on a row (`drift`: `bound`, `moved`, `over`) | `drift` |+| the part's largest step over the stretch falls (`part`) | `no gain` |+| no frame of the stretch is read further off the flow than before and at or over its limit (`off_max`) | `off the flow` |+| no rush is read in the stretch in a window the part does not rush in: the rest of the body was hurried | `a new rush` |++A refused stretch keeps the loop as the flow groups left it; the loop keeps its length and every+frame outside the stretch is as it was.++| On the synthetic walker (the stand-in in-between of `tests/video/test_loop_ease.py`) | Part's largest step | Frames made |+|---|---|---|+| the tail 5 % of a cycle short | 3.8 → 2.6 | 8, at four a side, 7 calls |+| 8 % | 4.9 → 2.6 | 8, 8 calls |+| a tenth | 5.8 → 2.7, no rush left | 8, 8 calls |+| a quarter, after the flow repair | 7.2 → 5.0, still read a rush (3.7) | 9, 9 calls |+| a quarter, on twos | 3.4 → 1.6 (on its drawings) | 8 drawings, 16 frames, 8 calls |++A quarter of a cycle is too far to spread out of sight over four drawings a side without hurrying+the legs past their own largest step: the rush falls by three tenths and is left, named in `surge_after`.+On a Mac's GPU a call is a second or so; on Modal's CPU with `-x -z` twelve to thirty seconds a+280 × 520 frame (section 1), so a loop that rushes costs two to four and a half minutes more, and a+loop that does not, nothing.++`jump_repair` carries `surge` (the worst rush on the loop the flow groups left: `from`, `to`,+`steps`, `frames`, `windows`, `ratio`, `speed`, `around`), `surge_after` (on the loop as it now+plays, or `null`), and `ease_skipped` where a rush was read and no stretch was made (`no+interpolator`, `the loop is too short to ease it`, `the frames around it were given way, refused,+or flung against the way`, `no timing keeps the body in bound`). The round `why: ease` carries the+`surge` it eased, `width`, `anchors` (the frames kept at its ends), `frames` and `drawings` (the+stretch in play order), `sources` (the frames as filmed it was made from), `supersedes`, `span`+(frames from anchor to anchor), `made` (per drawing: `frames`, `time` and `own` in frames from the+first anchor, `from`, `t`, `proposal`, `faults`, `look`), `accel` (`before`, `chosen`), `part`+(`windows`, `step_max_before`, `step_max_after`), `drift`, `off_max`, `calls`, `faults`, `look` and+`outcome`, and `replaced` or `rejected_for`. The record's `replaced` holds the frames it changed, the+seam gate reads the rendered cells, and the summary names them (`eased`). Without RIFE the rush is+cut as filmed with a warning line (`why`: "RIFE not installed — the rush cut as filmed"), and+`--repair on` refuses.+## 3. The jolt index — reported on every walk, a gate only when askedA loop whose steps change unevenly jolts even when no single step is a jump. Every walk or rundiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex cd4d9a8..592db38 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -930,7 +930,11 @@ most three calls and never made from or beside a frame made (`--repair auto`, ththe cut as filmed, is replaced in the same stage first: by RIFE's frame between the two cleanframes beside it, else by the clean frame beside it, else kept and named (`ghost_given_way`,`ghost_kept`) — a walk of one direction is delivered as cut and never meets the alignment that would-take a clean frame there. The report's `jump_repair` names the frames. RIFE+take a clean frame there. Then a part that keeps its way and rushes — a tail that runs short of+the cycle, rushing on at the wrap — has the three or four drawings either side of the rush made+again at times that spread it, made from the frames as filmed, the body's feet, mass and ground+line moving no further in a step, nor the rest of it faster, than they did there (the eased+retime, up to nine calls of its own). The report's `jump_repair` names the frames. RIFEis installed once with `sprite-gen rife install`; without it a loop that needs a frame is cut asfilmed with a warning, each filmed ghost given way to the clean frame beside it (`--repair on`fails instead). A frame shown twice in a row is one frame of the GIF and WebP, checked so, and the seam gate reads a frame given way as filmed (`seam_as_filmed`). See [loop repair](loop-repair.md). The repaired loop's jolt index and the head's frame-to-framediff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex c0ac19d..fcd33e6 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -894,11 +894,12 @@ def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate |required: bool, screen: dict[str, Any]) -> tuple[list[Image.Image], dict[str, Any]]:"""`repair_mod.repair_jumps` on the cut as filmed and its ghost `screen`, with RIFE located onlyonce a frame is to be made: a loop with no frame off its flow and no ghost between two clean frames- needs no binary. The report names the interpolator that made the frames.+ needs no binary, nor one with no part that rushes (the eased retime, `repair.surges`). The report names the+ interpolator that made the frames.A frame to make and no RIFE installed: `required` lets `RifeNotInstalled` through; otherwise- each filmed ghost gives way to the clean frame beside it, a jump (a frame off the flow) stays as- filmed, and the record says why where a jump was left (`rife`, `install`; `applied` false where+ each filmed ghost gives way to the clean frame beside it, a jump (a frame off the flow) and a rush stay as+ filmed, and the record says why where a jump or a rush was left (`rife`, `install`; `applied` false wherenothing was replaced)."""made_by: list[dict[str, str]] = []calls = 0@@ -925,6 +926,11 @@ def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate |record.update(why="RIFE not installed — cut as filmed" if not record["replaced"] else"RIFE not installed — the jump cut as filmed, each filmed ghost given way to the clean frame beside it",rife=str(exc), install=rife_mod.INSTALL_COMMAND)+ elif record.get("ease_skipped") == "no interpolator":+ # no jump, but a part that rushes: the frames either side of it were to be made again at eased times+ record.update(why="RIFE not installed — the rush cut as filmed" if not record["replaced"] else+ "RIFE not installed — the rush cut as filmed, each filmed ghost given way to the clean frame beside it",+ rife=str(exc), install=rife_mod.INSTALL_COMMAND)return repaired, recordframes = repairedrecord["applied"] = bool(record["replaced"])@@ -1420,8 +1426,8 @@ def run_loop(except (ValueError, rife_mod.RifeUnavailable) as exc:fix = (f"install RIFE (`{rife_mod.INSTALL_COMMAND}`), or pass --repair auto to cut it as filmed with a warning"if isinstance(exc, rife_mod.RifeNotInstalled) else "fix RIFE, or pass --repair off to cut it as filmed")- error = (f"video-loop: {exc}; the loop has a frame to make (after a jump, or for a filmed ghost between two clean "- f"frames) — {fix} (docs/loop-repair.md)")+ error = (f"video-loop: {exc}; the loop has a frame to make (after a jump, for a part that rushes, or for a filmed "+ f"ghost between two clean frames) — {fix} (docs/loop-repair.md)")shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error) from exc@@ -1452,11 +1458,16 @@ def run_loop(print(f"video-loop: warning: {what} with RIFE's frame between its neighbours, which may "f"cross-fade two drawings inside its outline (crossfade {proposal['crossfade']:.4f}); kept, a reading to ""look at — see it in the loop, or cut it with --repair off (docs/loop-repair.md section 4)", file=sys.stderr)- if "rife" in report_base["jump_repair"]:+ if "unmade" in report_base["jump_repair"]:unmade = report_base["jump_repair"]["unmade"]print(f"video-loop: warning: a jump frame was not repaired (frames {unmade['frames']}, {unmade['off']:.2f}x its ""region's usual step off the line between its neighbours) — RIFE is not installed, so the loop is cut as filmed; "f"run `{rife_mod.INSTALL_COMMAND}` and cut it again (docs/loop-repair.md)", file=sys.stderr)+ elif "rife" in report_base["jump_repair"]:+ rush = report_base["jump_repair"]["surge"]+ print(f"video-loop: warning: a part of the loop rushes (frames {rush['frames']}, {rush['ratio']:.1f}x its steps "+ "either side) and was not eased — RIFE is not installed, so the loop is cut as filmed; "+ f"run `{rife_mod.INSTALL_COMMAND}` and cut it again (docs/loop-repair.md section 2)", file=sys.stderr)else:report_base["jump_repair"] = {"applied": False, "why": "--repair off" if repair == "off" else f"not a gait state ({state})"}if prof.gait:@@ -1735,6 +1746,9 @@ def run(**kwargs: object) -> int:summary[key] = payload[key]if payload.get("jump_repair", {}).get("replaced"):summary["jump_repair"] = {k: payload["jump_repair"][k] for k in ("replaced", "off_max_before", "off_max_after")}+ eased = [r for r in payload["jump_repair"]["rounds"] if r.get("why") == "ease" and r["outcome"] == "accepted"]+ if eased:+ summary["jump_repair"]["eased"] = eased[0]["replaced"]summary["strip"] = {k: payload["strip"][k] for k in ("path", "frames", "w", "h", "body_h", "delay_ms")}print(json.dumps(summary, ensure_ascii=False, indent=2))return 0diff --git a/sprite_gen/video/repair.py b/sprite_gen/video/repair.pyindex 53d6df5..9f8786a 100644--- a/sprite_gen/video/repair.py+++ b/sprite_gen/video/repair.py@@ -13,6 +13,12 @@ ghost screen names a filmed ghost is replaced in the same stage, before the flowRIFE's frame between its neighbours where both are clean and it has no fault, else by the cleanframe beside it (docs/loop-repair.md section 4).+A part can also keep its way and still rush: a tail that runs short of the cycle covers at the wrap in one step what+it covers in eight elsewhere. The surge reading (`surges`) reads that speed; the frames either side of the rush, three+or four drawings each way, are made again by RIFE at times chosen so the part's speed rises and falls gradually+(`ease_times`), while the body's feet, mass and ground line move no further in a step, nor the rest of the body+faster, than they did in that stretch (docs/loop-repair.md section 2, "The eased retime").+Measured on the loop as it plays — cyclic, the last frame followed by the first — and insidethe union box of the body over the whole loop, the way the strip cells are cut, so a frame'sscore does not depend on where the canvas put the body.@@ -31,6 +37,7 @@ from PIL import Imagefrom sprite_gen._deps import npfrom sprite_gen.video import held as held_mod+from sprite_gen.video import legs as legs_modfrom sprite_gen.video.rife import Interpolate, crossfade, ghost, outline_shift, smearfrom sprite_gen.video.interpolation_quality import clean_beside, faults, ghost_screen, looks@@ -202,12 +209,13 @@ def flow_drawings(states: np.ndarray) -> tuple[list[list[int]], int]:return runs, hold-def _flow(frames: list[Image.Image], box: tuple[int, int, int, int] | None) -> dict[str, Any]:+def _flow(frames: list[Image.Image], box: tuple[int, int, int, int] | None,+ drawings: tuple[list[list[int]], int] | None = None) -> dict[str, Any]:"""The loop's path read on its drawings: their states, the runs of frames that show them, the windows,and per drawing and window the distance off the path, the step out and the turn, and the windows' usual- step."""+ step. `drawings` (runs, hold) reads it on those drawings instead of the ones `flow_drawings` finds."""states = flow_states(frames, box)- runs, hold = flow_drawings(states)+ runs, hold = drawings if drawings is not None else flow_drawings(states)path = states[[run[0] for run in runs]]windows = flow_windows(states.shape[1], states.shape[2])off, step, turn = _flow_read(path, windows)@@ -335,6 +343,338 @@ def flow_targets(frames: list[Image.Image], *, limit: float = FLOW_LIMIT, span:return record+# --- the eased retime (docs/loop-repair.md section 2, "The eased retime") ---------------------------------------++# A part can go on the way it was going and still jump: a tail that runs short of the cycle rushes on at the wrap,+# covering in one step what it covers in eight elsewhere. A frame there lies near enough the line between its+# neighbours that the flow reading lets it pass, or takes it out and leaves the rush halved over two steps. The+# surge reading reads the speed itself: a run of one or two steps over the steps either side of it, in a window+# where it goes on the way it came. The frames either side of it are then made again at times chosen so the part's+# speed rises and falls gradually, as far as the body's own steps there allow.+SURGE_LIMIT = 3.0 # a run's mean step, in its window's usual steps, at or over which a part may rush ...+SURGE_RATIO = 3.0 # ... and that many times the mean of the SURGE_AROUND steps either side of it: it rushes+SURGE_AROUND = 3+SURGE_SPAN = 2 # steps in a row a rush is read over at most+EASE_WIDTHS = (3, 4) # drawings either side of the rush made again, between two frames as filmed+EASE_GRID = 20 # times the search tries per step between two drawings+EASE_SLACK = 0.02 # of the timings within this share of the least change of the part's step, the nearest its own+# A made frame's body measures may move in a step up to the stretch's largest step as it played and DRIFT_PIXEL more:+# they are read on whole pixels (the ground is a row). The search keeps EASE_MARGIN inside that, as a made frame's feet+# and mass land a little off the line between its two frames that the search reads them on.+DRIFT_PIXEL = 1.0+EASE_MARGIN = 0.5+DRIFT_MEASURES = ("foot_centre", "body_centre", "ground")+++def drift_points(frame: Image.Image) -> np.ndarray:+ """Where the body stands in `frame`: the foot line's centre and the body's mass, x (`loop.foot_centre`,+ `loop.body_centre`, the reference `--anchor feet` reads drift on), and the lowest solid row (`legs.LOW_ALPHA`), y,+ the ground it stands on. NaN for an empty frame."""+ from sprite_gen.video import loop as loop_mod # loop imports this module++ box = frame.getchannel("A").point(lambda v: 255 if v >= ALPHA_SOLID else 0).getbbox()+ rows = np.nonzero((np.asarray(frame.getchannel("A")) >= legs_mod.LOW_ALPHA).any(axis=1))[0]+ if box is None or rows.size == 0:+ return np.full(len(DRIFT_MEASURES), np.nan)+ return np.array([loop_mod.foot_centre(frame, box), loop_mod.body_centre(frame, box), float(rows.max())])+++def _surges(flow: dict[str, Any]) -> list[dict[str, Any]]:+ """The rushes of a loop's path (`_flow`), worst first, none sharing a step: per run of 1..SURGE_SPAN steps from+ drawing `d`, the windows where its mean step is at least SURGE_LIMIT usual steps and SURGE_RATIO times the+ mean of the SURGE_AROUND steps either side, and no drawing from its first to its last turns back."""+ rel = flow["step"] / flow["scale"]+ turn = flow["turn"]+ n = len(rel)+ if n < 2 * SURGE_AROUND + SURGE_SPAN + 1:+ return []+ found = []+ for r in range(1, SURGE_SPAN + 1):+ for d in range(n):+ run = [(d + i) % n for i in range(r)]+ around = [(d - 1 - i) % n for i in range(SURGE_AROUND)] + [(d + r + i) % n for i in range(SURGE_AROUND)]+ speed, base = rel[run].mean(axis=0), rel[around].mean(axis=0)+ ratio = speed / np.maximum(base, 1e-12)+ onward = (turn[[(d + i) % n for i in range(r + 1)]] >= 0).all(axis=0)+ hit = np.nonzero((speed >= SURGE_LIMIT) & (ratio >= SURGE_RATIO) & onward)[0]+ if hit.size:+ w = int(hit[ratio[hit].argmax()])+ found.append({"d": d, "r": r, "W": [int(x) for x in hit], "ratio": float(ratio[w]),+ "speed": float(speed[w]), "around": float(base[w])})+ taken: list[dict[str, Any]] = []+ for s in sorted(found, key=lambda s: (-s["ratio"], s["r"], s["d"])):+ steps = {(s["d"] + i) % n for i in range(s["r"])}+ if not any(steps & {(t["d"] + i) % n for i in range(t["r"])} for t in taken):+ taken.append(s)+ return taken+++def _said_surge(s: dict[str, Any], flow: dict[str, Any]) -> dict[str, Any]:+ runs, n = flow["runs"], len(flow["runs"])+ return {"from": runs[s["d"]][0], "to": runs[(s["d"] + s["r"]) % n][0], "steps": s["r"],+ "frames": [t for i in range(s["r"] + 1) for t in runs[(s["d"] + i) % n]],+ "windows": [[round(v, 4) for v in flow["fractions"][w]] for w in s["W"]],+ "ratio": round(s["ratio"], 4), "speed": round(s["speed"], 4), "around": round(s["around"], 4)}+++def surges(frames: list[Image.Image], *, box: tuple[int, int, int, int] | None = None) -> list[dict[str, Any]]:+ """The runs of steps where a part of the loop rushes (docs/loop-repair.md section 2, "The eased retime"), worst+ first, none sharing a step: one or two steps in a row whose mean step, in a window of the flow reading, is at+ least SURGE_LIMIT of its usual steps and SURGE_RATIO times the mean of the SURGE_AROUND steps either side, where+ the part goes on the way it came through them (a step that turns back is a frame flung, the flow repair's). Read+ on the loop's drawings (`flow_drawings`). Each: the frames it runs `from` and `to` (first frames of its drawings),+ its `steps`, the `frames` of its drawings, the `windows` that read it (fractions of the box), and in the one that+ reads it most its `ratio`, `speed` and `around` (usual steps)."""+ flow = _flow(frames, box)+ return [_said_surge(s, flow) for s in _surges(flow)]+++def ease_times(times: np.ndarray, progress: np.ndarray, body: np.ndarray, bound: np.ndarray, into: np.ndarray,+ out: np.ndarray, *, own: Iterable[float], allowed: np.ndarray | None = None,+ slack: float = EASE_SLACK) -> dict[str, Any] | None:+ """The times to make a stretch's frames at (docs/loop-repair.md section 2, "The eased retime").++ `times` is the grid searched, 0 (the drawing before the stretch) to T (the drawing after), EASE_GRID points a step;+ `progress` (windows, times) how far the part has gone there in each window it rushes in, and `into` and `out` its+ step into the first time and out of the last, in one unit; `body` (measures, times) where the body stands there and+ `bound` how far each measure may move in a step; `allowed` (times, times), where given, the steps from one time to a+ later one the rest of the body allows; `own` the frames' own times, on the grid, in order.++ Of the timings that go forward and keep every step in bound and allowed, the one whose largest change of the part's+ step from one step to the next — from `into`, through the stretch, to `out` — is least (`accel`): its speed rises and+ falls as gradually as the body lets it. Of those within `slack` of that, the one nearest the frames' own times (the+ least sum of squares), so a frame the part does not need moved keeps its time. None where no timing keeps in bound."""+ own_at = [int(round(float(np.interp(t, times, np.arange(len(times)))))) for t in own]+ m, G = len(own_at), len(times)+ if m == 0:+ return {"accel": 0.0, "times": []}+ later = np.arange(G)[None, :] > np.arange(G)[:, None]+ ok = later & np.all(np.abs(body[:, None, :] - body[:, :, None]) <= bound[:, None, None] + 1e-9, axis=0)+ if allowed is not None:+ ok &= allowed+ step = progress[:, None, :] - progress[:, :, None] # (windows, p, q): the part's step from time p to time q+ end = G - 1++ def solve(limit: float | None) -> tuple[float, list[int]] | None:+ cost = np.full((G, G), np.inf) # cost[p, q]: the frame before at p, this one at q+ first = np.abs(step[:, 0, :] - into[:, None]).max(axis=0)+ live = ok[0] & (True if limit is None else first <= limit)+ cost[0, live] = first[live] if limit is None else (np.arange(G)[live] - own_at[0]) ** 2.0+ back = []+ for i in range(1, m):+ new, arg = np.full((G, G), np.inf), np.zeros((G, G), dtype=np.int64)+ for p in range(G):+ before = np.nonzero(np.isfinite(cost[:, p]))[0]+ after = np.nonzero(ok[p])[0]+ if not before.size or not after.size:+ continue+ acc = np.abs(step[:, p, after][:, None, :] - step[:, before, p][:, :, None]).max(axis=0)+ if limit is None:+ c = np.maximum(cost[before, p][:, None], acc)+ else:+ c = np.where(acc <= limit, cost[before, p][:, None] + (after[None, :] - own_at[i]) ** 2.0, np.inf)+ j = c.argmin(axis=0)+ new[p, after] = c[j, np.arange(after.size)]+ arg[p, after] = before[j]+ back.append(arg)+ cost = new+ ps, qs = np.nonzero(np.isfinite(cost) & ok[:, end][None, :])+ if not ps.size:+ return None+ last = np.maximum(np.abs(step[:, qs, end] - step[:, ps, qs]).max(axis=0),+ np.abs(out[:, None] - step[:, qs, end]).max(axis=0))+ total = np.maximum(cost[ps, qs], last) if limit is None else np.where(last <= limit, cost[ps, qs], np.inf)+ k = int(total.argmin())+ if not np.isfinite(total[k]):+ return None+ path = [int(qs[k]), int(ps[k])]+ for arg in reversed(back):+ path.append(int(arg[path[-1], path[-2]]))+ return float(total[k]), list(reversed(path))[1:]++ least = solve(None)+ if least is None:+ return None+ near = solve(least[0] * (1 + slack) + 1e-9)+ chosen = near[1] if near is not None else least[1]+ return {"accel": least[0], "times": [float(times[g]) for g in chosen]}+++def _part_places(path: np.ndarray, window: tuple[int, int, int, int]) -> np.ndarray:+ """Per drawing of a path (`_flow`), the centre of its coverage inside `window` (y0, y1, x0, x1 of the path's grid),+ (y, x) in cells. Where a part moves through the window its centre moves with it, as far as it goes: a step's+ distance between two blurred states stops growing once they no longer overlap, the centre's does not."""+ y0, y1, x0, x1 = window+ a = path[:, y0:y1, x0:x1, 0]+ ys, xs = np.mgrid[y0:y1, x0:x1]+ mass = np.maximum(a.sum(axis=(1, 2)), 1e-12)+ return np.stack([(a * ys).sum(axis=(1, 2)) / mass, (a * xs).sum(axis=(1, 2)) / mass], axis=1)+++def _part_accel(progress: np.ndarray, at: list[float], times: np.ndarray, into: np.ndarray, out: np.ndarray) -> float:+ """The largest change of the part's step from one step to the next over a stretch shown at `at` (with 0 and T)."""+ reached = np.stack([np.interp([0.0, *at, float(times[-1])], times, p) for p in progress])+ steps = np.concatenate([into[:, None], np.diff(reached, axis=1), out[:, None]], axis=1)+ return float(np.abs(np.diff(steps, axis=1)).max())+++def _ease(frames: list[Image.Image], out: list[Image.Image], interpolate: Interpolate | None,+ box: tuple[int, int, int, int], blocked: set[int], made: set[int], reads: bool,+ record: dict[str, Any], ease: bool) -> list[Image.Image]:+ """The eased retime stage of `repair_jumps`, on the loop `out` as the ghost and flow rounds left it.++ `blocked` holds the frames no stretch may hold (given way, refused; the frames read off the flow against the way+ are added here), `made` the frames the flow rounds made: a stretch makes them again, never from them, and never+ ends on one. Records `surge` and, where a stretch was made, an `ease` round (`ease_calls`); `ease_skipped` says why+ none was. With `ease` false the surge is read and nothing made."""+ flow = _flow(out, box)+ found = _surges(flow)+ record["surge"] = _said_surge(found[0], flow) if found else None+ if not found:+ return out+ if not ease:+ record["ease_skipped"] = "not asked"+ return out+ runs, n = flow["runs"], len(flow["runs"])+ count = len(out)+ first = [run[0] for run in runs]+ rel = flow["step"] / flow["scale"]+ # a drawing off the flow that turns back is a frame flung, not the rush: nothing is eased over it+ read = _drawing_scores(flow)+ blocked = blocked | {t for d in range(n) if read["off"][d] >= FLOW_LIMIT and read["turn"][d] < 0 for t in runs[d]}+ points = [drift_points(out[t]) for t in first]+ cell = (box[2] - box[0]) / flow["path"].shape[2] # px a cell of the path's grid+ plans = []+ why = "the frames around it were given way, refused, or flung against the way"+ for s in found:+ for k in EASE_WIDTHS:+ T = s["r"] + 2 * k+ if T >= n:+ why = "the loop is too short to ease it"+ continue+ stretch = [(s["d"] - k + i) % n for i in range(T + 1)] # drawings in play order, the two kept at the ends+ ends = (stretch[0], stretch[-1])+ if any(t in blocked for d in stretch for t in runs[d]) or any(t in made for d in ends for t in runs[d]):+ continue+ sources = [i for i, d in enumerate(stretch) if not set(runs[d]) & made]+ W = s["W"]+ # how far the part has gone: the path of its window's coverage centre, px, through the frames as filmed+ places = [_part_places(flow["path"], flow["windows"][w]) * cell for w in W]+ progress_at = np.array([[0.0, *np.cumsum([float(np.linalg.norm(pl[stretch[j]] - pl[stretch[i]]))+ for i, j in zip(sources, sources[1:])])] for pl in places])+ grid = np.arange(0, T * EASE_GRID + 1) / EASE_GRID+ progress = np.stack([np.interp(grid, sources, p) for p in progress_at])+ seen = np.array([points[d] for d in stretch])+ if not np.isfinite(seen).all():+ continue+ bound = np.abs(np.diff(seen, axis=0)).max(axis=0)+ body = np.stack([np.interp(grid, sources, seen[sources, j]) for j in range(seen.shape[1])])+ into = np.array([float(np.linalg.norm(pl[stretch[0]] - pl[(stretch[0] - 1) % n])) for pl in places])+ after = np.array([float(np.linalg.norm(pl[(stretch[-1] + 1) % n] - pl[stretch[-1]])) for pl in places])+ own = list(range(1, T))+ # the rest of the body, window by window, moves in no step further than it did in a step of the stretch+ rest = [w for w in range(len(flow["windows"])) if w not in W]+ allowed = np.ones((len(grid), len(grid)), dtype=bool)+ for w in rest:+ y0, y1, x0, x1 = flow["windows"][w]+ x = np.stack([flow["path"][stretch[i]][y0:y1, x0:x1].ravel() for i in sources])+ at = np.stack([np.interp(grid, sources, x[:, j]) for j in range(x.shape[1])], axis=1)+ sq = (at * at).sum(axis=1)+ dist = np.sqrt(np.maximum(sq[:, None] + sq[None, :] - 2 * at @ at.T, 0.0)) / flow["scale"][w]+ allowed &= dist <= max(float(rel[d, w]) for d in stretch[:-1]) + 1e-9+ result = ease_times(grid, progress, body, bound + DRIFT_PIXEL - EASE_MARGIN, into, after, own=own,+ allowed=allowed)+ if result is None:+ why = "no timing keeps the body in bound"+ continue+ plans.append({"surge": s, "k": k, "stretch": stretch, "sources": sources, "W": W, "progress": progress,+ "grid": grid, "bound": bound, "into": into, "after": after, "result": result,+ "accel_before": _part_accel(progress, [float(t) for t in own], grid, into, after)})+ if plans:+ break+ if not plans:+ record["ease_skipped"] = why+ return out+ least = min(p["result"]["accel"] for p in plans)+ plan = next(p for p in plans if p["result"]["accel"] <= least * (1 + EASE_SLACK) + 1e-9) # the narrower, as good+ if interpolate is None:+ record["ease_skipped"] = "no interpolator"+ return out+ s, stretch, sources = plan["surge"], plan["stretch"], plan["sources"]+ span_frames = (first[stretch[-1]] - first[stretch[0]]) % count+ at_frames = [((first[d] - first[stretch[0]]) % count) for d in stretch]+ new = list(out)+ made_rows, calls = [], 0+ for i, d in enumerate(stretch[1:-1], start=1):+ tau = plan["result"]["times"][i - 1]+ drawing = runs[d]+ row: dict[str, Any] = {"frames": drawing, "time": round(float(np.interp(tau, range(len(stretch)), at_frames)), 4),+ "own": at_frames[i]}+ if abs(tau - i) < 1e-9:+ row.update({"from": None, "t": None, "proposal": None, "faults": [], "look": []})+ made_rows.append(row)+ continue+ j = max(x for x in range(len(sources) - 1) if sources[x] <= tau + 1e-9)+ p, q = stretch[sources[j]], stretch[sources[j + 1]]+ fp, fq = at_frames[sources[j]], at_frames[sources[j + 1]]+ t = (float(np.interp(tau, range(len(stretch)), at_frames)) - fp) / (fq - fp)+ a, b = frames[first[p]], frames[first[q]]+ if t < 1e-9:+ frame = a+ row.update({"from": [first[p], first[p]], "t": 0.0, "proposal": None, "faults": [], "look": []})+ else:+ frame = interpolate(a, b, t)+ calls += 1+ if frame.mode != "RGBA" or frame.size != out[drawing[0]].size:+ raise ValueError("repair interpolator must return an RGBA frame of the original size")+ measure = {**smear(frame, a, b), "outline_shift": outline_shift(frame, a, b),+ "ghost": ghost(frame) if reads else None, "crossfade": crossfade(frame, a, b, t)}+ row.update({"from": [first[p], first[q]], "t": round(t, 4), "proposal": measure,+ "faults": faults(measure) + ([] if frame.getchannel("A").getbbox() else ["empty"]),+ "look": looks(measure)})+ made_rows.append(row)+ for k in drawing:+ new[k] = frame+ after_flow = _flow(new, box, (runs, flow["hold"]))+ moved = np.abs(np.diff(np.array([drift_points(new[first[d]]) for d in stretch]), axis=0)).max(axis=0)+ over = bool(np.any(~np.isfinite(moved)) or np.any(moved > plan["bound"] + DRIFT_PIXEL + 1e-9))+ W = plan["W"]+ part_before = float(max(rel[d, w] for d in stretch[:-1] for w in W))+ rel_after = after_flow["step"] / after_flow["scale"]+ part_after = float(max(rel_after[d, w] for d in stretch[:-1] for w in W))+ off_before = float(read["off"][stretch].max())+ off_after = float((after_flow["off"] / after_flow["scale"]).max(axis=1)[stretch].max())+ wrong = sorted({f for r in made_rows for f in r["faults"]})+ inside = set(stretch)+ # a rush the stretch did not have, in a window the part does not rush in: the retime hurried the rest of the body+ rushes = [x for x in _surges(after_flow)+ if {(x["d"] + i) % n for i in range(x["r"] + 1)} & inside and set(x["W"]) - set(W)]+ rejected = ((["fault"] if wrong else []) + (["drift"] if over else []) + (["no gain"] if part_after >= part_before else [])+ + (["off the flow"] if off_after >= FLOW_LIMIT and off_after > off_before else [])+ + (["a new rush"] if rushes else []))+ changed = [t for d in stretch[1:-1] for t in runs[d] if new[t] is not out[t]]+ round_: dict[str, Any] = {+ "why": "ease", "surge": _said_surge(s, flow), "width": plan["k"], "anchors": [first[stretch[0]], first[stretch[-1]]],+ "frames": [t for d in stretch[1:-1] for t in runs[d]], "drawings": [runs[d] for d in stretch[1:-1]],+ "sources": [first[stretch[i]] for i in sources], "supersedes": sorted(t for t in changed if t in made),+ "span": span_frames, "made": made_rows,+ "accel": {"before": round(plan["accel_before"], 4), "chosen": round(plan["result"]["accel"], 4)},+ "part": {"windows": [[round(v, 4) for v in flow["fractions"][w]] for w in W],+ "step_max_before": round(part_before, 4), "step_max_after": round(part_after, 4)},+ "drift": {"measures": list(DRIFT_MEASURES), "bound": [round(float(v), 3) for v in plan["bound"]],+ "moved": [round(float(v), 3) for v in moved], "over": over},+ "off_max": {"before": round(off_before, 4), "after": round(off_after, 4)}, "calls": calls, "faults": wrong,+ "look": sorted({w for r in made_rows for w in r["look"]}), "outcome": "rejected" if rejected else "accepted"}+ if rejected:+ round_["rejected_for"] = rejected+ else:+ round_["replaced"] = changed+ out = new+ record["rounds"].append(round_)+ record["ease_calls"] = calls+ return out++def _give_way(frames: list[Image.Image], j: int, ghosts: dict[int, float], interpolate: Interpolate | None,out: list[Image.Image]) -> dict[str, Any]:"""The round of a filmed ghost at `j` (`why` ghost), its cell replaced in `out` where it gives way.@@ -375,7 +715,7 @@ def _give_way(frames: list[Image.Image], j: int, ghosts: dict[int, float], interdef repair_jumps(frames: list[Image.Image], interpolate: Interpolate | None, *, facing: str = "right",limit: float = FLOW_LIMIT, span: int = FLOW_SPAN, max_frames: int = MAX_REPAIRS,- screen: dict[str, Any] | None = None) -> tuple[list[Image.Image], dict[str, Any]]:+ screen: dict[str, Any] | None = None, ease: bool = True) -> tuple[list[Image.Image], dict[str, Any]]:"""Replace each filmed ghost the screen names, then take out each group of frames off the loop's flow andmake it again with RIFE between the frames either side, worst first (docs/loop-repair.md section 2).@@ -395,8 +735,16 @@ def repair_jumps(frames: list[Image.Image], interpolate: Interpolate | None, *,(`refused`); a made drawing that cross-fades two drawings inside its silhouette is still taken,its round naming it (`look`). `interpolate` may be None: a ghost then gives way to the clean framebeside it, and the flow search stops at the first group it would make, naming it (`unmade`). The- flow is read again after each group, on the union box of the original loop. `facing` reads nothing- here: it is recorded for the jump guard of `video-loop-compare` (`restoration.jump`)."""+ flow is read again after each group, on the union box of the original loop. Then, on the loop as the rounds left+ it, the eased retime (`why` ease, `_ease`; `ease` false reads the rush and makes nothing): the worst rush+ (`surges`, recorded as `surge`) is eased over a stretch of EASE_WIDTHS drawings either side, made from the frames+ as filmed (a frame the flow made inside it is made again, `supersedes`), each drawing at the time `ease_times`+ chooses and shown on every frame it was; the stretch is taken only where no made frame has a fault, no body+ measure moves further than the stretch did and a pixel (`drift`), the part's largest step falls (`part`), no+ frame is left further off the flow than the limit and before, and no new rush appears in the rest of the body+ (`rejected_for` names what failed). Its calls are its own, outside `max_frames` (`ease_calls`). `surge_after`+ is the reading of the loop as it now plays. `facing` reads nothing here: it is recorded for the jump guard of+ `video-loop-compare` (`restoration.jump`)."""out = list(frames)n = len(out)box = union_box(frames)@@ -467,6 +815,16 @@ def repair_jumps(frames: list[Image.Image], interpolate: Interpolate | None, *,record["rounds"].append(round_)record.update(replaced=replaced, refused=refused, attempts=calls, stopped=stopped, unfixed=plan["unfixed"],off_max_after=plan["off_max_before"])+ given = {j for j in replaced if j in ghosts}+ blocked = given | set(refused)+ out = _ease(frames, out, interpolate, box, blocked, set(replaced) - given, reads, record, ease)+ eased = [r for r in record["rounds"] if r["why"] == "ease" and r["outcome"] == "accepted"]+ if eased:+ record["replaced"] = [*replaced, *(t for t in eased[0]["replaced"] if t not in replaced)]+ record["off_max_after"] = round(float(flow_scores(out, box=box)["off"].max()), 4)+ if record["surge"] is not None:+ later = _flow(out, box)+ record["surge_after"] = next((_said_surge(s, later) for s in _surges(later)), None)return out, recorddiff --git a/tests/video/test_loop_ease.py b/tests/video/test_loop_ease.pynew file mode 100644index 0000000..e25d624--- /dev/null+++ b/tests/video/test_loop_ease.py@@ -0,0 +1,292 @@+# SPDX-License-Identifier: Apache-2.0+"""The eased retime (docs/loop-repair.md section 2, "The eased retime"): where a part rushes — a run of one or+two steps far faster than the steps around it, going the way it was going — the frames either side are made+again at times the search chooses, so the part's speed rises and falls gradually; the body's feet, mass and+ground line move no further in a step than they did anywhere in that stretch, the loop keeps its length, and+every frame outside the stretch is the video's own. A frame flung against the way is the flow repair's, not+a rush; an ordinary walk has none.++The loops are the walker of tests/video/test_loop_flow.py, whose tail can run short of the cycle so that it+rushes on at the wrap (`lag`). The interpolator is a stand-in that draws the walker between two frames the way+an optical-flow in-between does: the body at the time between them, the tail moved on between its two places."""++from __future__ import annotations++import json+import math++import numpy as np+import pytest+from PIL import Image, ImageOps++from sprite_gen.video import loop as loop_mod+from sprite_gen.video import repair+from tests.video.test_loop_flow import N, _against, _frame, _loop+from tests.video.test_loop_repair import _keyed, _no_rife++LAG = 0.25 # the tail a quarter of a cycle short: the flow repair takes one frame at the wrap, and a rush is left+++def _walk(n: int = N, *, lag: float = 0.0, hold: int = 1, flung: dict[int, float] | None = None) -> list[Image.Image]:+ """`_loop` of tests/video/test_loop_flow.py with every dark part drawn whole (`dark_whole`), so that a+ frame drawn between two phases has no more dark pixels than they have (the smear reading counts them)."""+ flung = flung or {}+ drawn = [t - t % hold for t in range(n)]+ return [_frame(d, n, tail_off=_against(d, n) * flung.get(d, 0.0), tail_lag=lag * d / n, dark_whole=True) for d in drawn]+++class Lerp:+ """A stand-in RIFE for the walker: between filmed frames a and b at t, the body at the time t of the way from+ a to b and the tail moved on t of the way from its place in a to its place in b (forward, as it sways). Records+ each call as (a, b, t) by the filmed frames' indices, and refuses a frame it did not film."""++ def __init__(self, filmed: list[Image.Image], *, lag: float = 0.0, hold: int = 1, n: int = N):+ self.at = {id(f): k for k, f in enumerate(filmed)}+ self.n, self.lag, self.hold = n, lag, hold+ self.calls: list[tuple[int, int, float]] = []+ self.made: list[Image.Image] = []++ def _sway(self, k: int) -> float:+ d = k - k % self.hold+ return 2 * math.pi * d * (1 - self.lag) / self.n++ def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ ka, kb = self.at[id(a)], self.at[id(b)] # KeyError: made from a frame that was not filmed+ self.calls.append((ka, kb, round(t, 4)))+ da, db = ka - ka % self.hold, kb - kb % self.hold+ body = da + t * ((db - da) % self.n)+ sa, sb = self._sway(ka), self._sway(kb)+ while sb < sa:+ sb += 2 * math.pi+ sway = sa + t * (sb - sa)+ self.made.append(_frame(body, self.n, tail_lag=(2 * math.pi * body / self.n - sway) / (2 * math.pi),+ dark_whole=True))+ return self.made[-1]+++def _drift(frames: list[Image.Image], segment: list[int]) -> np.ndarray:+ """The largest step over the segment's steps, in play order, of where the body stands: the foot line's centre+ and the body's mass (`--anchor feet`'s drift reference) and the lowest solid row."""+ def where(f: Image.Image) -> np.ndarray:+ box = f.getchannel("A").point(lambda v: 255 if v >= 8 else 0).getbbox()+ rows = np.nonzero((np.asarray(f.getchannel("A")) >= 128).any(axis=1))[0]+ return np.array([loop_mod.foot_centre(f, box), loop_mod.body_centre(f, box), float(rows.max())])++ points = [where(frames[k]) for k in segment]+ return np.max(np.abs(np.diff(points, axis=0)), axis=0)+++def _ease(record: dict) -> dict:+ (round_,) = [r for r in record["rounds"] if r["why"] == "ease"]+ return round_+++def test_a_tail_that_rushes_on_at_the_wrap_is_eased_over_the_frames_either_side():+ frames = _walk(lag=LAG)+ flow_only, before = repair.repair_jumps(frames, Lerp(frames, lag=LAG), ease=False)+ assert [r["why"] for r in before["rounds"]] == ["flow"] # the flow takes one frame at the wrap, and leaves a rush+ assert before["surge"] is not None and before["surge_after"] is not None+ lerp = Lerp(frames, lag=LAG)+ out, record = repair.repair_jumps(frames, lerp)+ round_ = _ease(record)+ assert round_["outcome"] == "accepted" and round_["width"] in repair.EASE_WIDTHS+ segment = [*[round_["anchors"][0]], *round_["frames"], round_["anchors"][1]]+ assert [(k - segment[0]) % N for k in segment] == list(range(len(segment))) # one stretch, in play order+ assert {N - 1, 0} <= set(round_["frames"]) and len(round_["frames"]) == 2 * round_["width"] + round_["surge"]["steps"] - 1+ assert len(out) == N and all(out[k] is frames[k] for k in range(N) if k not in round_["frames"])+ # every frame is made from two frames as filmed, never from a frame made — the flow's frame at the wrap is made again+ flow_frames = set(before["rounds"][0]["frames"])+ assert flow_frames <= set(round_["frames"]) and round_["supersedes"] == sorted(flow_frames)+ assert all(not {a, b} & flow_frames for a, b, _ in lerp.calls)+ # the rush is spread: the part's largest step over the stretch falls by a quarter or more, and its speed changes+ # less from step to step. A quarter of a cycle is too far to spread out of sight over the stretch without hurrying+ # the legs, and the legs may go no faster than they did there.+ assert round_["part"]["step_max_after"] <= 3 / 4 * round_["part"]["step_max_before"]+ assert round_["accel"]["chosen"] < round_["accel"]["before"] / 2+ # no drift: the feet, the body's mass and the ground line move no further in a step than they did there, to within+ # the pixel they are read on+ assert np.all(_drift(out, segment) <= _drift(flow_only, segment) + repair.DRIFT_PIXEL)+ changed = {k for k in round_["frames"] if out[k] is not frames[k]}+ assert round_["replaced"] == sorted(changed, key=round_["frames"].index) and len(changed) >= len(round_["frames"]) - 2+ assert set(record["replaced"]) == flow_frames | changed+++def test_a_rush_the_flow_reading_lets_pass_is_eased_too():+ # A tail a tenth of a cycle short reads under the flow's limit: no frame is taken out, and it still rushes.+ frames = _walk(lag=0.1)+ assert repair.flow_targets(frames)["groups"] == []+ out, record = repair.repair_jumps(frames, Lerp(frames, lag=0.1))+ round_ = _ease(record)+ assert round_["outcome"] == "accepted" and round_["supersedes"] == []+ assert record["surge"]["ratio"] >= repair.SURGE_RATIO and record["surge_after"] is None+ assert len(out) == N and all(out[k] is frames[k] for k in range(N) if k not in round_["frames"])+++def test_an_ordinary_walk_has_no_rush_and_nothing_is_made():+ for frames in (_loop(), _loop(hold=2), _walk(), _walk(hold=2)):+ assert repair.surges(frames) == []+ out, record = repair.repair_jumps(frames, lambda a, b, t: pytest.fail("nothing to make"))+ assert record["surge"] is None and all(o is f for o, f in zip(out, frames))+ assert not [r for r in record["rounds"] if r["why"] == "ease"]+++def test_a_frame_flung_against_the_way_is_not_a_rush():+ # Its steps in and out are large, and the second goes back the way the first came: the flow repair's frame.+ assert repair.surges(_loop(flung={12: 12})) == [] and repair.surges(_walk(flung={12: 12})) == []+++def test_on_twos_each_drawing_is_made_once_and_shown_for_both_its_frames():+ frames = _walk(lag=LAG, hold=2)+ lerp = Lerp(frames, lag=LAG, hold=2)+ out, record = repair.repair_jumps(frames, lerp)+ round_ = _ease(record)+ assert record["hold"] == 2 and round_["outcome"] == "accepted"+ assert all(len(d) == 2 and out[d[0]] is out[d[1]] for d in round_["drawings"])+ assert len(lerp.calls) <= len(round_["drawings"]) + len(record["rounds"][0]["drawings"])+ assert len(out) == N and all(out[k] is frames[k] for k in range(N) if k not in round_["frames"])+++def test_a_made_frame_that_moves_the_body_further_than_the_stretch_did_refuses_the_ease():+ frames = _walk(lag=LAG)+ flow_only, _ = repair.repair_jumps(frames, Lerp(frames, lag=LAG), ease=False)+ lerp = Lerp(frames, lag=LAG)++ def pushed(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ made = lerp(a, b, t)+ if len(lerp.calls) <= 1: # the flow's frame at the wrap, as before+ return made+ moved = Image.new("RGBA", made.size, (0, 0, 0, 0))+ moved.paste(made, (12 if len(lerp.calls) % 2 else 0, 0)) # every other made frame pushed sideways+ return moved++ out, record = repair.repair_jumps(frames, pushed)+ round_ = _ease(record)+ assert round_["outcome"] == "rejected" and "drift" in round_["rejected_for"] and round_["drift"]["over"]+ assert [f.tobytes() for f in out] == [f.tobytes() for f in flow_only] # the loop as the flow left it+ assert set(record["replaced"]) == set(record["rounds"][0]["frames"])+++def test_a_made_frame_at_fault_refuses_the_ease_and_the_loop_stays_as_the_flow_left_it():+ frames = _walk(lag=LAG)+ flow_only, _ = repair.repair_jumps(frames, Lerp(frames, lag=LAG), ease=False)+ lerp = Lerp(frames, lag=LAG)++ def melted(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ made = lerp(a, b, t)+ if len(lerp.calls) != 3:+ return made+ pixels = np.asarray(made).copy()+ dark = (pixels[..., :3].max(axis=2) < 70) & (pixels[..., 3] > 0)+ pixels[dark, :3] = (200, 200, 220) # the outlines melted into the fill+ return Image.fromarray(pixels, "RGBA")++ out, record = repair.repair_jumps(frames, melted)+ round_ = _ease(record)+ assert round_["outcome"] == "rejected" and "outline" in round_["faults"] and "fault" in round_["rejected_for"]+ assert [f.tobytes() for f in out] == [f.tobytes() for f in flow_only]+++def test_without_an_interpolator_a_rush_is_named_and_nothing_is_made():+ frames = _walk(lag=0.1)+ out, record = repair.repair_jumps(frames, None)+ assert record["surge"] is not None and record["ease_skipped"] == "no interpolator"+ assert all(o is f for o, f in zip(out, frames)) and record["replaced"] == []+++def test_it_eases_the_same_frames_whichever_way_the_body_faces():+ frames = _walk(lag=0.1)+ mirrored = [ImageOps.mirror(f) for f in frames]+ lerp = Lerp(frames, lag=0.1)+ index = {id(m): k for k, m in enumerate(mirrored)}++ def mirror_lerp(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ return ImageOps.mirror(lerp(frames[index[id(a)]], frames[index[id(b)]], t))++ _, record = repair.repair_jumps(frames, Lerp(frames, lag=0.1))+ _, flipped = repair.repair_jumps(mirrored, mirror_lerp)+ assert _ease(flipped)["frames"] == _ease(record)["frames"] and _ease(flipped)["outcome"] == "accepted"+++# --- the search (repair.ease_times) -------------------------------------------------------------------------------+++def test_the_search_keeps_every_frame_at_its_own_time_where_the_part_moves_evenly():+ times = np.arange(0, 8.0 + 1e-9, 1 / repair.EASE_GRID)+ progress = times[None, :] * 1.0 # one usual step a frame+ body = np.stack([times * 2.0, times * 0.5, np.zeros_like(times)]) # the body walks on evenly+ result = repair.ease_times(times, progress, body, np.array([2.0, 0.5, 1.0]), np.array([1.0]), np.array([1.0]),+ own=list(range(1, 8)))+ assert result["accel"] == pytest.approx(0.0, abs=1e-9) and result["times"] == pytest.approx(list(range(1, 8)))+++def test_the_search_spreads_a_rush_as_far_as_the_body_lets_it():+ # The part covers nine usual steps in the fourth of eight steps, one in each of the others. The body moves one+ # px a step and may move up to two: the times can bunch round the rush, but no step may cover more than two.+ times = np.arange(0, 8.0 + 1e-9, 1 / repair.EASE_GRID)+ per_step = np.array([1, 1, 1, 9, 1, 1, 1, 1], dtype=float)+ progress = np.interp(times, np.arange(9), np.concatenate([[0], np.cumsum(per_step)]))[None, :]+ body = np.stack([times, np.zeros_like(times), np.zeros_like(times)])+ result = repair.ease_times(times, progress, body, np.array([2.0, 1.0, 1.0]), np.array([1.0]), np.array([1.0]),+ own=list(range(1, 8)))+ chosen = np.array([0.0, *result["times"], 8.0])+ assert np.all(np.diff(chosen) <= 2.0 + 1e-9) and np.all(np.diff(chosen) > 0)+ steps = np.diff(np.interp(chosen, times, progress[0]))+ assert steps.max() < 9 and result["accel"] < 8 # spread over more than one step+ assert np.all(np.abs(np.diff(np.concatenate([[1.0], steps, [1.0]]))) <= result["accel"] + 1e-9)+++# --- video-loop --repair auto (sprite_gen/video/loop.py) ---------------------------------------------------------+++class NearestLerp(Lerp):+ """`Lerp` for frames as video-loop hands them over (read back from disk and cleaned): each is the filmed frame+ nearest it."""++ def __init__(self, filmed: list[Image.Image], **kw):+ super().__init__(filmed, **kw)+ self.filmed = [np.asarray(f, dtype=np.int16) for f in filmed]++ def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ near = [int(np.argmin([np.abs(np.asarray(x, dtype=np.int16) - f).mean() for f in self.filmed])) for x in (a, b)]+ self.at = {id(a): near[0], id(b): near[1]}+ return super().__call__(a, b, t)+++def _cut(tmp_path, frames: list[Image.Image], **kw):+ return loop_mod.run_loop(_keyed(tmp_path, frames), tmp_path / "out", fps=24.0, state="walk", min_len=None, max_len=None,+ n_out=None, seam_max=1000.0, name="w", report_path=tmp_path / "w.json", cycle_mode="fixed",+ start=0, length=N, anchor="none", **kw)+++def test_video_loop_eases_the_rush_and_plays_the_frames_made(tmp_path, capsys):+ frames = _walk(lag=0.1)+ lerp = NearestLerp(frames, lag=0.1)+ rep = _cut(tmp_path, frames, interpolate=lerp)+ jr = rep["jump_repair"]+ round_ = _ease(jr)+ assert round_["outcome"] == "accepted" and jr["applied"] is True and jr["surge_after"] is None+ assert set(round_["replaced"]) <= set(jr["replaced"]) and rep["seam_measurement"] == "rendered-cells"+ cells = sorted((tmp_path / "out" / "cycle").glob("frame-*.png"))+ assert len(cells) == N # the loop keeps its length+ made = {k: m for m in round_["made"] if m["proposal"] is not None for k in m["frames"]}+ assert made and len(made) == len(lerp.made)+ for k, image in zip(sorted(made, key=round_["frames"].index), lerp.made):+ assert np.array_equal(np.asarray(Image.open(cells[k])), np.asarray(image))+ assert json.loads((tmp_path / "w.json").read_text())["jump_repair"]["rounds"][-1]["why"] == "ease"+++def test_a_rush_without_rife_is_cut_as_filmed_with_a_warning(tmp_path, monkeypatch, capsys):+ _no_rife(monkeypatch, tmp_path)+ frames = _walk(lag=0.1)+ rep = _cut(tmp_path, frames)+ jr = rep["jump_repair"]+ assert jr["applied"] is False and jr["replaced"] == [] and jr["ease_skipped"] == "no interpolator"+ assert jr["why"] == "RIFE not installed — the rush cut as filmed" and jr["install"] == "sprite-gen rife install"+ warning = [line for line in capsys.readouterr().err.splitlines() if "rushes" in line]+ assert len(warning) == 1 and "sprite-gen rife install" in warning[0] and "not eased" in warning[0]+++def test_repair_on_without_rife_refuses_a_rush(tmp_path, monkeypatch):+ _no_rife(monkeypatch, tmp_path)+ with pytest.raises(SystemExit, match=r"for a part that rushes.*sprite-gen rife install"):+ _cut(tmp_path, _walk(lag=0.1), repair="on")diff --git a/tests/video/test_loop_flow.py b/tests/video/test_loop_flow.pyindex 50da080..2534b7c 100644--- a/tests/video/test_loop_flow.py+++ b/tests/video/test_loop_flow.py@@ -24,9 +24,11 @@ W, H, N = 240, 300, 36SIZE_JUMP = 1.4 # a step this many times the loop's median: the size reading's jump, which picked frames before the flow reading-def _frame(t: int, n: int, *, tail_off: float = 0.0, tail_lag: float = 0.0) -> Image.Image:+def _frame(t: float, n: int, *, tail_off: float = 0.0, tail_lag: float = 0.0, dark_whole: bool = False) -> Image.Image:"""Phase t/n of one gait cycle; `tail_off` puts the tail that many px off its sway, `tail_lag` its sway- that many cycles behind."""+ that many cycles behind. The arm is drawn over the torso's outline and the second leg over the first leg (as dark+ as a line) and foot, each covering more or less of them by the phase; `dark_whole` draws the arm behind the torso,+ the first leg lighter than a line and both feet over both legs, so every phase shows its dark parts whole."""im = Image.new("RGBA", (W, H), (0, 0, 0, 0))d = ImageDraw.Draw(im)phi = 2 * math.pi * t / n@@ -35,16 +37,25 @@ def _frame(t: int, n: int, *, tail_off: float = 0.0, tail_lag: float = 0.0) -> Itx, ty = 70 + 22 * math.sin(sway) + tail_off, 130 + bob - 10 * math.cos(sway)d.polygon([(110, 120 + bob), (110, 150 + bob), (tx - 20, ty + 20), (tx - 30, ty - 25)], fill=(220, 120, 40, 255))d.ellipse((tx - 50, ty - 40, tx - 10, ty + 10), fill=(240, 150, 60, 255))+ arm = 0.4 * math.sin(phi + math.pi + 0.6 * math.sin(phi)) + 0.3+ if dark_whole:+ d.line((150, 110 + bob, 150 + 60 * math.sin(arm), 110 + bob + 60 * math.cos(arm)), fill=(240, 210, 180, 255), width=12)# quick through the swing, slow through the stance: the coverage step varies a lot over an ordinary cycleswing = 0.5 * math.sin(phi + 0.6 * math.sin(phi))- for hip, angle, colour in ((120, swing, (70, 60, 120, 255)), (128, -swing, (90, 80, 150, 255))):+ feet = []+ near = (80, 70, 130, 255) if dark_whole else (70, 60, 120, 255) # the darker is as dark as a line+ for hip, angle, colour in ((120, swing, near), (128, -swing, (90, 80, 150, 255))):x1, y1 = hip + 95 * math.sin(angle), 175 + bob + 95 * math.cos(angle)d.line((hip, 175 + bob, x1, y1), fill=colour, width=16)- d.ellipse((x1 - 12, y1 - 7, x1 + 14, y1 + 7), fill=(40, 30, 30, 255))+ feet.append((x1 - 12, y1 - 7, x1 + 14, y1 + 7))+ if not dark_whole:+ d.ellipse(feet[-1], fill=(40, 30, 30, 255))+ for foot in feet if dark_whole else ():+ d.ellipse(foot, fill=(40, 30, 30, 255))d.rectangle((100, 100 + bob, 150, 185 + bob), fill=(200, 200, 220, 255), outline=(20, 20, 20, 255), width=3)d.ellipse((96, 40 + bob, 156, 102 + bob), fill=(240, 210, 180, 255), outline=(20, 20, 20, 255), width=3)- arm = 0.4 * math.sin(phi + math.pi + 0.6 * math.sin(phi)) + 0.3- d.line((150, 110 + bob, 150 + 60 * math.sin(arm), 110 + bob + 60 * math.cos(arm)), fill=(240, 210, 180, 255), width=12)+ if not dark_whole:+ d.line((150, 110 + bob, 150 + 60 * math.sin(arm), 110 + bob + 60 * math.cos(arm)), fill=(240, 210, 180, 255), width=12)return im