Skip to content

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

fix(video): a staff that closes at the top and swings below the hand is cut two steps long — held_edge

Soohong Kim9dbf7995767f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 140009f..457356a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased - A staff that closes at the top and swings below the hand is cut two steps long
+
+- **Output change: once the top of the silhouette jumps at its first choice, `video-loop --anchor motion-auto` reads the held part below its top too, and may cut two steps long.** A staff that turns about the hand once in two steps comes back to the same place at the top band half its turn later, moving the other way: v2.35.0 chose again on the top band alone, took such a cut — the top closed — and the shaft under the hand swung back at the wrap, with no warning. Now, behind the seam pop only, the side of the body the top band sits on is read row by row on the silhouette's outer edge (`repair.held_side`, `repair.side_edges`, `repair.held_edge` on the frames the search chooses from, `loop.HeldEdge`): per row, the cut's first and last frames against the clip's frames after its last and before its first, in place and in speed, over the row's median step in the loop; the 80th percentile over the rows is the held seam, closing under **1.2** (`repair.HELD_EDGE_REFERENCE`). Among the candidates whose top does not jump, one whose held side closes is taken (the usual 15 % of the best score, then the smallest held seam). Where no cut one step long closes it, windows twice a candidate's length are read — two cycles of a confirmed repeat, not themselves seen repeating — and one whose held side closes and whose top does not jump is cut: the report's `cycle.cycles` is `2`, and `strip.json` carries `cycles: 2`. A cut with fewer than two clip frames either side of it cannot be read: `skipped`, counted under `unread`, never chosen. `cycle.seam_pop.held_edge` records `side`, `reference`, `measured`, `unread`, `cycles`, `chosen` and `two_cycle` (lengths tried, `measured`, `unread`, `top_pops`, `closing`); a candidate row carries `held_edge` (`null` with `held_edge_skipped`). A first choice whose top does not jump reads nothing new: a walk without a part held above its head is cut, written and warned about byte for byte as before. [docs/loop-repair.md](docs/loop-repair.md#the-held-side--a-staff-that-closes-at-the-top-and-swings-below-the-hand).
+- **New warning: a held part that no window one or two steps long closes.** The top band's cut stands and `jolt.warnings` and stderr gain `the held part does not close at the wrap on the <side> side of the silhouette, below its top: …x its rows' median step (over 1.2); no window one or two cycles long closes it — it swings on a beat of its own`; a held side that could not be read is said as well. Nothing fails on it.
+- **Output change: `video-cycle-align` keeps a loop cut two steps long on purpose two steps long.** A loop whose `strip.json` says `cycles: 2` is not stopped as a suspect (its suspects carry `status: "declared"`), counts half its length toward the set's length, and is resampled to twice that length; its row and its `strip.json` `cycle_align` carry `cycles_kept`. Before, the screen stopped the set on it, and `--cycles <loop>=2` cut the held part's wrap back in while `=1` played it twice as fast. A `--cycles` count given for it is still the last word. Every loop without `cycles` in its `strip.json` is aligned as before.
+- **`tests/video/test_loop_prop_seam_held.py`** draws a walker stepping every 24 frames with a staff turning about the hand every 48: v2.35.0 cuts it one step long where the top closes and the staff's foot swings back at the wrap at twice its largest step inside the loop; now every cut one step long whose top closes reads a held seam of 2.0 to 5.2, and the window two steps long taken reads 0. A staff swinging with the step below a pennant that sways on its own beat stays one step long (0 to 0.5); a staff whose foot swings every 37 frames is kept on the top band's cut and warned about; a walk without a staff reads nothing below its top; the set alignment keeps the two-step loop at twice the set's length.
+
## v2.35.0 - A staff that swings on its own beat is not cut where it jumps
- **Output change: `video-loop --anchor motion-auto` chooses its cut again when the top of the silhouette jumps into the first frame.** A staff, a flag or a raised spear held above the head can sway on a beat slower than the steps; a cut one step long then ends with it elsewhere, the body closes and the held part jumps at the wrap. The seam ratio is an area measure and a thin rod hardly moves it, so such a cut passed. The search now weighs, for its first choice, the top band's step into the first frame over the loop's median step (`repair.seam_pop`, on the frames it chooses from, moved by the analysis translation; the median a pixel at least), counted only when the wrap is that band's largest step. Over the bound (**10**, `repair.SEAM_POP_REFERENCE`) every candidate is measured, and among those under it the cut is taken from the scores within the usual 15 % of the best, smallest jump first. The report's `cycle.seam_pop` records `first_choice`, `applied`, `measured`, `unread` and `chosen` (or `why` when every candidate read jumps and the first choice is kept). A cut whose top band cannot be read — a frame with nothing in it — has no jump to rank: it is recorded `skipped` (why) in place of a `pop` (`first_choice.skipped`; a candidate row's `seam_pop` is `null` with `seam_pop_skipped`), counted under `unread`, and never chosen as one that closes; a first choice that cannot be read is kept. A first choice under the bound is kept and nothing past it is measured: a loop without such a part is cut, written and warned about byte for byte as before. [docs/loop-repair.md](docs/loop-repair.md#the-seam-pop--a-part-held-above-the-head-swinging-on-its-own-beat).
diff --git a/SKILL.md b/SKILL.md
index 3ba8059..250b35d 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -138,4 +138,4 @@ Scene creation consumes finished assets and remains optional. Asset metadata own
## Contracts and advanced tools
-[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between auto` (the default: a made frame that melted takes the nearer source frame) or `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides, or `--foot <loop>=left|right` (`video-set --align-foot <item>=…`) once you have looked at the first strike frame of a loop the report lists under `unnamed_feet`), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)) — and a clip the engine names for one: when the alignment report's `retake` lists a loop (reason `held-drawings`: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it ([loop-repair](docs/loop-repair.md) section 4). When `video-loop` warns that the top of the silhouette jumps into the loop's first frame (a staff or flag held above the head, swinging on its own beat), that part does not close at the cut: look at the loop, and try `--cycle fixed` with a cut two steps long before filming again; a walk refused for no cycle names in its report's `cycle.candidates` the windows it measured, best first, for a cut you must deliver anyway ([loop-repair](docs/loop-repair.md) section 3, "The seam pop").
+[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between auto` (the default: a made frame that melted takes the nearer source frame) or `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides, or `--foot <loop>=left|right` (`video-set --align-foot <item>=…`) once you have looked at the first strike frame of a loop the report lists under `unnamed_feet`), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)) — and a clip the engine names for one: when the alignment report's `retake` lists a loop (reason `held-drawings`: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it ([loop-repair](docs/loop-repair.md) section 4). `video-loop --anchor motion-auto` already cuts a walk two steps long where a staff held above the head closes only there (`cycle.cycles: 2`, and `video-cycle-align` keeps both cycles at twice the set's length — do not count it down with `--cycles`). When `video-loop` warns that the top of the silhouette jumps into the loop's first frame (a staff or flag held above the head, swinging on its own beat), or that the held part does not close at the wrap below its top, that part does not close at the cut: look at the loop, and try `--cycle fixed` with another cut before filming again; a walk refused for no cycle names in its report's `cycle.candidates` the windows it measured, best first, for a cut you must deliver anyway ([loop-repair](docs/loop-repair.md) section 3, "The seam pop" and "The held side").
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index 93366e9..5f34a4a 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -281,7 +281,8 @@ plays:
within the usual 15 % of the best and the smallest pop (`cycle.seam_pop`: `first_choice`,
`applied`, `measured`, `unread`, `chosen`). A first choice that does not pop is kept, and nothing past it
is measured, so a loop without such a part is cut exactly as before. If every candidate read pops,
- the first choice is kept (`why`) and the warning below says so.
+ the first choice is kept (`why`) and the warning below says so. Once the first choice pops, the held
+ part is read below its top too, and the cut may come out two steps long ("The held side" below).
- **A cut whose top cannot be read is not one that closes.** A frame with nothing in the top band
(a tip flung far above the rest in one frame) leaves the cut without a jump to read: it is
recorded `skipped` (why) in place of `pop` — `first_choice.skipped`, or on a candidate row
@@ -298,9 +299,72 @@ plays:
walker of `tests/video/test_loop_prop_seam.py` — steps every 24 frames, a staff above its head swaying every 61 — reads 12 to 18 at the cuts the area
measure alone chose, and 0 at the cuts chosen again.
- **What it does not see**: a held part that never reaches the top band (a spear held level, a
- sword at the hip), and the lower end of a staff whose top closes while the shaft still swings
- about the hand. A clip like that may need a cut two steps long, which the search does not make;
- `--cycle fixed` cuts one ([loop review](loop-review.md)).
+ sword at the hip). The lower end of a staff whose top closes while the shaft still swings about the
+ hand is read by the held side below, behind this pop.
+
+### The held side — a staff that closes at the top and swings below the hand
+
+A staff that turns about the hand once in two steps comes back to the same place at the top band
+half its turn later, moving the other way. A cut one step long taken there closes the top —
+`seam_pop` reads nothing — and the shaft under the hand swings back at the wrap. No cut one step
+long closes such a staff; a cut two steps long does.
+
+Nothing that reads the whole silhouette sees it on its own. On a walk without a held part the
+silhouette's outer edges are hair, an arm or a foot, and a local jump at the wrap — read per tile,
+per row edge, on thin parts only, or as a repeat one cycle on against two — reads as high on some
+walks without a staff as on a staff that does not close. So the held side is read **only behind
+the seam pop**: on a search whose first choice popped at the top, where the top band has found that
+something is held, and on which side of the body.
+
+`repair.held_edge`, on the frames the search chooses from (moved by the analysis translation,
+`loop.HeldEdge`):
+
+| Step | What |
+|---|---|
+| side | the side of the body's centre the top band sits on, for the popping first choice (`repair.held_side`) |
+| edge | per row of the silhouette, its outermost column on that side (`repair.side_edges`) |
+| per row | a loop closes where its last frame is the clip's frame before its first, and its first the clip's frame after its last: those two places, and the steps into and out of each against the clip's own steps there (a part back in its place but moving the other way swings back at the wrap), their mean over the row's median step inside the loop — a floor of 0.5 % of the body height, a pixel at least |
+| `seam` | the 80th percentile over the rows; the held side `closes` under **1.2** (`repair.HELD_EDGE_REFERENCE`) |
+
+A cut with fewer than two clip frames on either side has nothing to read its wrap against: it is
+`skipped` (why), counted under `unread`, and never chosen.
+
+`--anchor motion-auto`, once its first choice pops (`cycle.seam_pop.held_edge`: `side`, `reference`,
+`measured`, `unread`, `cycles`, `chosen`, and `two_cycle` when it looked there):
+
+1. Among the candidates whose top does not pop, those whose held side closes: the scores within the
+ usual 15 % of the best, then the smallest held seam (`cycles: 1`). A candidate row carries
+ `held_edge` (`null` with `held_edge_skipped` where it could not be read).
+2. If no candidate one step long closes it: **windows twice a candidate's length** (every length
+ 2L − 1 to 2L + 1 for a candidate length L, at every start the clip holds). Such a window is two
+ cycles of a repeat the search confirmed, not itself seen repeating — a three-second clip cannot
+ show a window two steps long twice. One whose held side closes and whose top does not pop (a top
+ that cannot be read is not taken) is cut, the smallest held seam first: `cycle.cycles` is **2**,
+ `cycle.period_local` half its length, `cycle.seam_pop.chosen.cycles` 2 and `strip.json` `cycles: 2`.
+ `two_cycle` records the lengths tried and how many were `measured`, `unread`, `top_pops` and
+ `closing`.
+3. If no window one or two steps long closes it, the top band's choice stands (as above),
+ `held_edge.chosen` records its seam, and `jolt.warnings` and stderr gain
+ `video-loop: warning: the held part does not close at the wrap on the right side of the
+ silhouette, below its top: 5.50x its rows' median step (over 1.2); no window one or two cycles
+ long closes it — it swings on a beat of its own`. A side that could not be read is said as well.
+
+A first choice whose top does not pop reads nothing here: a walk without a part held above its head
+is cut, written and warned about exactly as before.
+
+The bound sits between cuts that close a held staff and cuts where it swings back at the wrap. The
+synthetic walker of `tests/video/test_loop_prop_seam_held.py` — steps every 24 frames, a staff
+turning about the hand every 48 — reads 2.0 to 5.2 at every cut one step long whose top closes and
+0 at the window two steps long taken; with the staff swinging every step instead it reads 0 to 0.5,
+and the cut stays one step long. Below a staff on a beat neither one step nor two closes (every 37
+frames) every cut one step long whose top closes reads 4.25 or more and no window two steps long
+closes: the top band's cut stands, and it is warned about.
+
+- **What it does not see**: a held part on the other side of the body from the top band (the top
+ band names the side), and a held part whose cut needs more than two steps. A window two steps long
+ needs the clip to hold it with two frames either side: a three-second clip of 30-frame steps has
+ few starts for one. `--cycle fixed` cuts any window ([loop review](loop-review.md)); a two-step
+ cut made that way is not marked `cycles: 2`, and the set alignment asks for its count.
## 4. One cycle for a direction set — `video-cycle-align`, `video-set --align-cycles auto`
@@ -315,6 +379,13 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-
[--foot side-walk=left] [--state walk] [--report set/walk.cycle-align.json]
```
+- **A loop cut two steps long on purpose is counted already.** `video-loop --anchor motion-auto`
+ cuts two steps where a held part closes only there (section 3, "The held side") and marks it
+ `cycles: 2` in `strip.json`. The alignment does not stop on it: its length counts per cycle toward
+ the set's length, and it is resampled to twice that length, keeping both cycles (`cycles_kept` on
+ its row and in its `strip.json` `cycle_align`; its suspects carry `status: "declared"`). A
+ `--cycles` count given for it is still the last word: `--cycles <loop>=2` takes one cycle out of
+ it (the held part then swings back at that cut's wrap), `=1` aligns it at the set's length.
- **Two cycles in one loop are stopped, and counted by whoever looks**: one length for the set is
one beat only if every loop holds one cycle. A loop that holds two strides, resampled to the
set's length, walks twice as fast as the rest, arms and legs alike — and pixels cannot tell it
diff --git a/docs/loop-review.md b/docs/loop-review.md
index 5f29e33..ab5f430 100644
--- a/docs/loop-review.md
+++ b/docs/loop-review.md
@@ -96,7 +96,10 @@ the lag minimum. When the top of the silhouette jumps into that cut's first fram
a staff or flag held above the head, swinging on its own beat — the candidates are measured
and the cut is chosen again among those whose top was read and closes ([loop repair](loop-repair.md)
section 3, "The seam pop"; `cycle.seam_pop`). A first choice whose top closes, or cannot be read, is kept and
-nothing more is measured. An explicit `--max-len` is never widened; without one, only the gait
+nothing more is measured. Once it pops, the held part is read below its top as well, on the side
+the top band sits on: a cut whose shaft closes under the hand is taken first, and where no cut one
+step long closes it, a window two steps long is (`cycle.cycles: 2`; [loop repair](loop-repair.md)
+section 3, "The held side"). An explicit `--max-len` is never widened; without one, only the gait
fallback below looks past the state's window, and only after this search found nothing.
### The gait fallback: a slow walk, or a walk toward the camera
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 129df43..7285849 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -694,7 +694,8 @@ was 17). `video-loop` therefore:
changes few pixels and hardly moves it. `--anchor motion-auto` also weighs the top
of the silhouette at the wrap and chooses again when it jumps, and every walk or run
reports that jump and warns on it ([loop repair](loop-repair.md) section 3,
- "The seam pop").
+ "The seam pop"). Once the top jumps, the held part is read below its top too, and a staff
+ that closes only on two steps is cut two steps long (`cycle.cycles: 2`, "The held side").
This neighbourhood check measures temporal consistency, not anatomical leg
identity. A consistently repeated malformed motion can still score well; visual
@@ -768,7 +769,9 @@ swings the stride twice a step; a diagonal view's two steps open the feet unequa
`review_recommended` keeps its meaning (the ambiguous-harmonic retention above). The record is for
the set stage: `video-cycle-align` screens every loop by the same rule, stops a set on a suspect,
and takes one cycle out of a loop only when told how many it holds (`--cycles`, [loop
-repair](loop-repair.md) section 4). The local search of `--anchor motion-auto` records the same.
+repair](loop-repair.md) section 4). The local search of `--anchor motion-auto` records the same. A
+loop that search cut two cycles long on purpose (a held part that closes only there, `cycles: 2` in
+`strip.json`) is counted already: the set stage keeps both cycles at twice the set's length.
The rule leans one way on purpose: a suspect costs a look, a miss a loop that plays twice as fast.
A run's half step repeats as well as most of its strides do, so a run set is suspected nearly
every time and stops until its loops are counted; a walk's half step is under its floor more
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index 07da8db..385a1d1 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -36,6 +36,12 @@ it is, `--cycles <loop>=k` takes one cycle — a k-th of it, from the start whos
is the most like it — out of the loop as filmed (`take_cycle`) and aligns that. Nothing changes the
number of cycles in a loop but `--cycles`.
+A loop `video-loop` cut two cycles long on purpose — a part it holds swings once in two cycles and
+closes only there (its strip metadata says `cycles`, docs/loop-repair.md section 3, "The held side")
+— is counted already: it is not a suspect to stop on, its length counts per cycle toward the set's,
+and it is resampled to that many times the set's length, keeping its cycles (`cycles_kept`). A
+`--cycles` count for it is still the last word.
+
Where a loop's view cannot tell its feet apart (`start_foot` null, with `foot_why`), it starts on its
larger strike, and the report names it under `unnamed_feet` with its two strike frames as they now
stand in `cycle/` (`candidates`, the first being the frame it starts on) — for whoever looks, a
@@ -530,7 +536,9 @@ def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: list
if "follow" in meta or (loop_dir / loop_mod.FOLLOW_SOURCE).exists():
record["follow_cleared"] = True
(loop_dir / loop_mod.FOLLOW_SOURCE).unlink(missing_ok=True)
- merged = {**{k: v for k, v in meta.items() if k not in strip_meta and k not in ("cycle_align", "follow")}, **strip_meta}
+ merged = {**{k: v for k, v in meta.items() if k not in strip_meta and k not in ("cycle_align", "follow", "cycles")}, **strip_meta}
+ if record.get("cycles_kept", 1) > 1:
+ merged["cycles"] = record["cycles_kept"]
if meta.get("foot_anchor") and meta.get("foot_anchor") != "feet":
merged["foot_anchor"] = meta["foot_anchor"]
cells = [strip.crop((k * strip_meta["w"], 0, (k + 1) * strip_meta["w"], strip_meta["h"])) for k in range(strip_meta["frames"])]
@@ -631,13 +639,20 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
given = _resolve_cycles(cycles, loops)
told = _resolve_loops("--foot", feet, loops, handed_mod.SIDES)
screens = [cycle_screen(frames, fps=fps, state=state or meta.get("state")) for (_, _, meta, _), frames in zip(loops, sources)]
+ # Cycles a loop keeps: what its cutter declared (`cycles`, a cut two cycles long on purpose) unless
+ # a --cycles count says otherwise.
+ kept = {i: int(meta.get("cycles") or 1) for i, (_, _, meta, _) in enumerate(loops)}
suspects: list[dict[str, Any]] = []
taken: dict[int, dict[str, Any]] = {}
cycle_warnings: list[str] = []
for i, ((d, meta_path, _, _), screen) in enumerate(zip(loops, screens)):
k = given.get(i)
+ if k is not None:
+ kept[i] = 1
if screen["suspects"]:
- status = "stopped" if k is None and multi_cycle == "fail" else "warned" if k is None else "counted"
+ declared = k is None and kept[i] > 1
+ status = ("declared" if declared else "stopped" if k is None and multi_cycle == "fail"
+ else "warned" if k is None else "counted")
suspects.append({"dir": str(d), "name": meta_path.name[: -len(".strip.json")], "length": len(sources[i]),
"status": status, "cycles_given": k,
"candidates": [{key: row[key] for key in ("period", "seconds", "divisor", "cycles", "periodicity", "pose",
@@ -676,7 +691,8 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
f"{max(row['cycles'] for row in e['candidates'])} times as fast as the rest if it does"
for e in suspects if e["status"] == "warned"]
lengths = [len(f) for f in sources]
- target = length if length is not None else round(statistics.median(lengths))
+ # A loop kept two cycles long counts one cycle's length toward the set's, and is made that many times as long.
+ target = length if length is not None else round(statistics.median(n / kept[i] for i, n in enumerate(lengths)))
located: list[dict[str, str]] = []
def lazy(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
@@ -691,7 +707,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
aligned = []
for i, ((d, *_), frames, view) in enumerate(zip(loops, sources, views or [None] * len(loops))):
try:
- out, facts = resample(frames, target, lazy, between=between)
+ out, facts = resample(frames, target * kept[i], lazy, between=between)
strike = foot_strike(out, view=view, foot=start_foot, given=told.get(i))
except rife_mod.RifeNotInstalled as exc:
raise rife_mod.RifeNotInstalled(f"{d}: {exc}") from exc
@@ -703,16 +719,16 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
record = {**facts, "drawings": drawings, "retake": again, "turned_by": start, "turned_on": strike["by"], "view": view, "start_foot": strike["start_foot"],
"start_foot_source": strike["start_foot_source"],
# the two strikes as they stand in the rebuilt cycle/: the larger first
- "strikes": [(k - start) % target for k in strike["strikes"]],
+ "strikes": [(k - start) % len(out) for k in strike["strikes"]],
**{key: strike[key] for key in ("foot", "foot_why", "foot_given", "foot_unnamed_why", "foot_disagrees") if key in strike},
"stride_swing": strike["stride_swing"], "reach_swing": strike["reach_swing"],
"fps": round(fps, 4), "source": SOURCE_DIR, "cycles_given": given.get(i), "cycle_screen": screens[i],
- **({"cycle_taken": taken[i]} if i in taken else {}),
- "made_at": [(k - start) % target for k in facts["made_at"]]}
+ **({"cycle_taken": taken[i]} if i in taken else {}), "cycles_kept": kept[i],
+ "made_at": [(k - start) % len(out) for k in facts["made_at"]]}
if "nearest_at" in facts:
- record["nearest_at"] = sorted((k - start) % target for k in facts["nearest_at"])
+ record["nearest_at"] = sorted((k - start) % len(out) for k in facts["nearest_at"])
if "smear" in facts:
- record["smear"] = sorted(({**m, "at": (m["at"] - start) % target} for m in facts["smear"]), key=lambda m: m["at"])
+ record["smear"] = sorted(({**m, "at": (m["at"] - start) % len(out)} for m in facts["smear"]), key=lambda m: m["at"])
aligned.append((out[start:] + out[:start], record))
rows = []
for (d, meta_path, meta, _), (out, record) in zip(loops, aligned):
diff --git a/sprite_gen/video/local_cycle.py b/sprite_gen/video/local_cycle.py
index 64e67bd..d1f5012 100644
--- a/sprite_gen/video/local_cycle.py
+++ b/sprite_gen/video/local_cycle.py
@@ -60,12 +60,78 @@ def _mark(row, measured):
row['seam_pop_skipped'] = measured['skipped']
-def _shape_rank(candidates, chosen, wrap_pop):
+def _held(measured):
+ """A window's held side as `cycle.seam_pop.held_edge` records it: its seam, or why it could not be read."""
+ return {'skipped': measured['skipped']} if 'skipped' in measured else {'seam': measured['seam'], 'closes': measured['closes']}
+
+
+def _held_rank(candidates, calm, chosen, wrap_pop, held_edge):
+ """Below the top band (`held_edge`, repair.held_edge on the side the popping first choice holds its
+ part): among the calm candidates, those whose held side closes, the same score tolerance, then the
+ smallest held seam. When no one-cycle candidate closes it, windows twice a candidate's length
+ (`cycles` 2): a part swinging once in two cycles closes only there. Such a window is two cycles of
+ a repeat the search confirmed, not itself seen repeating; it is taken when its held side closes and
+ its top does not pop, the smallest held seam first. Returns (picked or None, record)."""
+ side = held_edge.side(chosen['start'], chosen['length'])
+ if 'skipped' in side:
+ return None, {'method': 'held-side-edge-v1', 'skipped': side['skipped']}
+ side = side['side']
+ record = {'method': 'held-side-edge-v1', 'side': side, 'reference': held_edge.reference}
+ closing = []
+ unread = 0
+ for row in calm:
+ measured = held_edge.seam(row['start'], row['length'], side)
+ row['held_edge'] = measured.get('seam')
+ if 'skipped' in measured:
+ row['held_edge_skipped'] = measured['skipped']
+ unread += 1
+ elif measured['closes']:
+ closing.append(row)
+ record.update(measured=len(calm)-unread, unread=unread)
+ if closing:
+ cutoff = min(row['score'] for row in closing)*1.15+1e-8
+ picked = min((row for row in closing if row['score'] <= cutoff),
+ key=lambda row: (row['held_edge'], row['seam_pop'], row['score'], row['start'], row['length']))
+ record.update(cycles=1, chosen={'start': picked['start'], 'length': picked['length'], 'seam': picked['held_edge'], 'closes': True})
+ return picked, record
+ lengths = sorted({2*row['length']+d for row in candidates for d in (-1, 0, 1)})
+ windows = []
+ counts = {'measured': 0, 'unread': 0, 'top_pops': 0}
+ for length in lengths:
+ for start in range(held_edge.frames-length+1):
+ measured = held_edge.seam(start, length, side)
+ if 'skipped' in measured:
+ counts['unread'] += 1
+ continue
+ counts['measured'] += 1
+ if not measured['closes']:
+ continue
+ top = wrap_pop(start, length)
+ if 'skipped' in top or top['pops']:
+ counts['top_pops'] += 1 # a top that pops, or one that could not be read, is not taken
+ continue
+ windows.append({'start': start, 'length': length, 'cycles': 2, 'period_local': round(length/2),
+ 'held_edge': measured['seam'], 'seam_pop': top['pop'],
+ 'repeat': 'two cycles of a confirmed repeat, not itself seen repeating'})
+ record['two_cycle'] = {'lengths': [lengths[0], lengths[-1]], **counts, 'closing': len(windows)}
+ if windows:
+ picked = min(windows, key=lambda row: (row['held_edge'], row['seam_pop'], row['start'], row['length']))
+ record.update(cycles=2, chosen={'start': picked['start'], 'length': picked['length'], 'seam': picked['held_edge'], 'closes': True})
+ return picked, record
+ return None, record
+
+
+def _shape_rank(candidates, chosen, wrap_pop, held_edge=None):
"""Choose again when the chosen cut's top pops at the wrap (`wrap_pop`, repair.seam_pop on the
analysed frames): among the candidates whose top was read and does not pop, the same score
tolerance, then the smallest pop. Nothing is measured past the first choice when it does not pop,
or when its top could not be read (kept, `skipped`), so a cut without a thin part swinging on its
- own beat is chosen exactly as before. A candidate whose top could not be read is not chosen."""
+ own beat is chosen exactly as before. A candidate whose top could not be read is not chosen.
+
+ With `held_edge` (loop.HeldEdge), a popping first choice has its held part read below the top too
+ (`_held_rank`): a cut whose held side closes is taken first, one or two cycles long. Where none
+ closes, the choice is the top band's, and `held_edge.chosen` records that it does not close (the
+ jolt warns, repair.held_edge_verdict)."""
first = wrap_pop(chosen['start'], chosen['length'])
record = {'method': 'top-band-wrap-v1', 'reference': first['reference'],
'first_choice': {'start': chosen['start'], 'length': chosen['length'], **_read(first)},
@@ -82,21 +148,36 @@ def _shape_rank(candidates, chosen, wrap_pop):
elif not measured['pops']:
calm.append(row)
record.update(measured=len(candidates)-unread, unread=unread)
+ held = None
+ if held_edge is not None:
+ picked, held = _held_rank(candidates, calm, chosen, wrap_pop, held_edge)
+ record['held_edge'] = held
+ if picked is not None:
+ record.update(applied=True, chosen={'start': picked['start'], 'length': picked['length'], 'pop': picked['seam_pop'],
+ **({'cycles': 2} if picked.get('cycles') == 2 else {})})
+ return picked, record
if not calm:
record['why'] = 'every candidate whose top was read pops at the wrap; the first choice is kept'
- return chosen, record
- cutoff = min(row['score'] for row in calm)*1.15+1e-8
- picked = min((row for row in calm if row['score'] <= cutoff),
- key=lambda row: (row['seam_pop'], row['score'], row['start'], row['length']))
- record.update(applied=True, chosen={'start': picked['start'], 'length': picked['length'], 'pop': picked['seam_pop']})
+ picked = chosen
+ else:
+ cutoff = min(row['score'] for row in calm)*1.15+1e-8
+ picked = min((row for row in calm if row['score'] <= cutoff),
+ key=lambda row: (row['seam_pop'], row['score'], row['start'], row['length']))
+ record.update(applied=True, chosen={'start': picked['start'], 'length': picked['length'], 'pop': picked['seam_pop']})
+ if held is not None and 'side' in held:
+ measured = held_edge.seam(picked['start'], picked['length'], held['side'])
+ held['chosen'] = {'start': picked['start'], 'length': picked['length'], **_held(measured)}
return picked, record
def detect(distances, trajectory, *, min_len, max_len, gait_floor,
- periodicity_min, double_tolerance, double_search, max_fraction=.5, signals=None, wrap_pop=None):
+ periodicity_min, double_tolerance, double_search, max_fraction=.5, signals=None, wrap_pop=None,
+ held_edge=None):
"""`wrap_pop(start, length)`, when given, is the top band's jump at that cut's wrap
(repair.seam_pop): a chosen cut that pops is chosen again (`_shape_rank`), and a search that finds
- nothing raises with the windows it refused, popping ones last (`ValueError.diagnostics`)."""
+ nothing raises with the windows it refused, popping ones last (`ValueError.diagnostics`).
+ `held_edge` (loop.HeldEdge) reads the held side below the top of a cut chosen again; the cut it
+ takes may be two cycles long (`cycles` 2 in the result)."""
n = len(distances)
# A cycle has to be seen repeating: half the clip by default, more for the gait fallback.
lo, hi = max(6, min_len), min(max_len, int(n*max_fraction))
@@ -190,7 +271,7 @@ def detect(distances, trajectory, *, min_len, max_len, gait_floor,
key=lambda row: (row['start'], row['score'], row['length']))
shape = None
if wrap_pop is not None:
- chosen, shape = _shape_rank(candidates, chosen, wrap_pop)
+ chosen, shape = _shape_rank(candidates, chosen, wrap_pop, held_edge)
radius, js = _around(chosen['start'], chosen['length'])
profile = _profile(distances, js, radius, lo, hi)
fundamental = period_mod.screen(
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index e14d0e4..ab8018e 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -856,11 +856,10 @@ def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate |
return frames, record
-def wrap_pop_on(frames: list[Image.Image], analysis: dict[str, Any]) -> Any:
- """`repair.seam_pop` of a cut (start, length) of `frames`, each moved by the analysis translation
- `auto_motion.analyse` measured (its drift taken out, the way the cut will be corrected): the
- top band's jump at the wrap, for `local_cycle.detect` to rank its candidates by. Alpha only,
- cropped once to the clip's subject; a cut's value is kept once measured."""
+def moved_alpha(frames: list[Image.Image], analysis: dict[str, Any]) -> list[np.ndarray]:
+ """The alpha of every frame, each moved by the analysis translation `auto_motion.analyse` measured
+ (its drift taken out, the way the cut will be corrected), cropped once to the clip's subject:
+ what `wrap_pop_on` and `HeldEdge` read a cut on."""
shifts = np.rint(np.asarray(analysis["analysis_only_translation_xy"], dtype=np.float64)).astype(int)
pad = int(np.abs(shifts).max()) + 1
boxes = [f.getchannel("A").point(lambda v: 255 if v >= repair_mod.ALPHA_SOLID else 0).getbbox() for f in frames]
@@ -873,6 +872,13 @@ def wrap_pop_on(frames: list[Image.Image], analysis: dict[str, Any]) -> Any:
crop = np.asarray(f.getchannel("A").crop(box))
a[pad + dy:pad + dy + crop.shape[0], pad + dx:pad + dx + crop.shape[1]] = crop
moved.append(a)
+ return moved
+
+
+def wrap_pop_on(moved: list[np.ndarray]) -> Any:
+ """`repair.seam_pop` of a cut (start, length) of the moved alpha (`moved_alpha`): the top band's
+ jump at the wrap, for `local_cycle.detect` to rank its candidates by. A cut's value is kept once
+ measured."""
measured: dict[tuple[int, int], dict[str, Any]] = {}
def pop(start: int, length: int) -> dict[str, Any]:
@@ -887,6 +893,36 @@ def wrap_pop_on(frames: list[Image.Image], analysis: dict[str, Any]) -> Any:
return pop
+class HeldEdge:
+ """The held side of the moved alpha (`moved_alpha`), read by `local_cycle` only once a cut's top
+ band pops: `side` of a cut (`repair.held_side`, or `skipped`) and `seam` of a cut on a side
+ (`repair.held_edge`, or `skipped` with why). A side's edges are read once, on first use."""
+
+ reference = repair_mod.HELD_EDGE_REFERENCE
+
+ def __init__(self, moved: list[np.ndarray]):
+ self.moved = moved
+ self.frames = len(moved)
+ self._edges: dict[str, np.ndarray] = {}
+
+ def _masks(self, start: int, stop: int) -> list[np.ndarray]:
+ return [a >= repair_mod.HELD_EDGE_ALPHA for a in self.moved[start:stop]]
+
+ def side(self, start: int, length: int) -> dict[str, Any]:
+ try:
+ return {"side": repair_mod.held_side(self._masks(start, start + length))}
+ except ValueError as exc:
+ return {"skipped": str(exc)}
+
+ def seam(self, start: int, length: int, side: str) -> dict[str, Any]:
+ if side not in self._edges:
+ self._edges[side] = repair_mod.side_edges(self._masks(0, self.frames), side)
+ try:
+ return repair_mod.held_edge(self._edges[side], start, length)
+ except ValueError as exc:
+ return {"skipped": str(exc), "reference": repair_mod.HELD_EDGE_REFERENCE}
+
+
def run_loop(
frames_dir: Path,
out_dir: Path,
@@ -990,8 +1026,9 @@ def run_loop(
detect = dict(gait_floor=round(prof.min_seconds*fps), periodicity_min=PERIODICITY_MIN,
double_tolerance=GAIT_DOUBLE_TOL, double_search=GAIT_DOUBLE_SEARCH)
try:
+ moved = moved_alpha(source_frames, analysis)
cycle = local_cycle.detect(D, trajectory, min_len=lo, max_len=hi, signals=leg_signals(source_frames),
- wrap_pop=wrap_pop_on(source_frames, analysis), **detect)
+ wrap_pop=wrap_pop_on(moved), held_edge=HeldEdge(moved), **detect)
except ValueError as first:
# A front or back gait that walked toward the camera, or a slow one: one more
# search, recorded (`gait_fallback`), and only after the first found nothing.
@@ -1010,9 +1047,11 @@ def run_loop(
fallback["window"] = [lo, hi_long]
report_base["gait_fallback"] = fallback
try:
+ moved = moved_alpha(source_frames, analysis)
cycle = local_cycle.detect(D, trajectory, min_len=lo, max_len=hi_long,
max_fraction=gait_fallback.LONG_CYCLE_FRACTION if max_len is None else .5,
- signals=leg_signals(source_frames), wrap_pop=wrap_pop_on(source_frames, analysis), **detect)
+ signals=leg_signals(source_frames), wrap_pop=wrap_pop_on(moved),
+ held_edge=HeldEdge(moved), **detect)
except ValueError as second:
failed = ValueError(f"{second} (also with the gait fallback: window [{lo}, {hi_long}], "
f"scale drift {drift['drift']:+.1%}{', undone' if fallback['scale_undone'] else ''})")
@@ -1129,6 +1168,8 @@ def run_loop(
reference = {"jolt_max": repair_mod.JOLT_REFERENCE, "head_step_max": repair_mod.HEAD_STEP_REFERENCE}
warnings = repair_mod.jolt_verdict(jolt, **reference)
warnings += repair_mod.seam_pop_verdict(jolt, head_step_max=repair_mod.HEAD_STEP_REFERENCE)
+ # The held side below the top, read on the source frames when the cut was chosen again (local_cycle).
+ warnings += repair_mod.held_edge_verdict(cycle.get("seam_pop"))
gated = repair != "off" and (jolt_max is not None or head_step_max is not None)
over = repair_mod.jolt_verdict(jolt, jolt_max=jolt_max, head_step_max=head_step_max) if gated else []
report_base["jolt"] = {**jolt, "reference": reference, "warnings": warnings,
@@ -1160,6 +1201,10 @@ def run_loop(
if state:
# `video-cycle-align` reads the gait floor of this state when it screens a loop for two cycles.
strip_meta["state"] = str(state).strip().lower()
+ if cycle.get("cycles", 1) > 1:
+ # A cut two cycles long, taken so a part swinging once in two closes (local_cycle._held_rank):
+ # `video-cycle-align` keeps both, at twice the set's length, instead of asking for a count.
+ strip_meta["cycles"] = cycle["cycles"]
# `video-cycle-align` reads the hold here, over the cut (`cycle_drawings`) and over the clip
# (`drawings`, where the cut is too short to read): read on the keyed steps, since `--anchor
# motion-auto` moves each frame of a pair apart in the cut it writes (sprite_gen/video/held.py).
@@ -1319,6 +1364,8 @@ def run(**kwargs: object) -> int:
"seam_pop": payload["jolt"]["seam_pop"].get("pop")}
if payload["cycle"].get("seam_pop", {}).get("applied"):
summary["cycle"]["seam_pop"] = payload["cycle"]["seam_pop"]
+ if payload["cycle"].get("cycles", 1) > 1:
+ summary["cycle"]["cycles"] = payload["cycle"]["cycles"]
if payload.get("jump_repair", {}).get("replaced"):
summary["jump_repair"] = {k: payload["jump_repair"][k] for k in ("replaced", "score_max_before", "score_max_after")}
summary["strip"] = {k: payload["strip"][k] for k in ("path", "frames", "w", "h", "body_h", "delay_ms")}
diff --git a/sprite_gen/video/repair.py b/sprite_gen/video/repair.py
index db97555..aa63f3e 100644
--- a/sprite_gen/video/repair.py
+++ b/sprite_gen/video/repair.py
@@ -141,6 +141,19 @@ HEAD_MEDIAN_FLOOR = 0.05 # % of body height: a median step below this is the tr
# the cut is chosen from. Above it the cut is chosen again (`--anchor motion-auto`), and a pop that
# stays is a warning line.
SEAM_POP_REFERENCE = 10.0
+# The held side's seam (docs/loop-repair.md section 3, "The held side"): a held part that swings on
+# its own beat misses below its top too — under the hand, where the top band does not reach. Read
+# on the silhouette's outer edge on the side the top band sits on, row by row: how far the cut's
+# wrap is from the clip's own way on there, in place and in speed, over that row's median step in
+# the loop; the HELD_EDGE_QUANTILE-th percentile of the rows. Under HELD_EDGE_REFERENCE the held
+# side closes. On a walk without a held part the edge is the hair or an arm, and the same reading
+# runs as high as on a staff that does not close, so it is read only on a cut whose top band pops
+# (`--anchor motion-auto` chooses again there), where the top band has found the held part and its
+# side. The bound sits between cuts that close a held staff and cuts where it swings back at the wrap.
+HELD_EDGE_REFERENCE = 1.2
+HELD_EDGE_QUANTILE = 80
+HELD_EDGE_FLOOR = 0.005 # of the body height, a pixel at least: a row's median step under it is the edge's rounding
+HELD_EDGE_ALPHA = 128 # alpha at or above this is the edge (0..255)
def jolt_index(step_values: np.ndarray) -> float:
@@ -225,6 +238,92 @@ def seam_pop(alphas: list[np.ndarray]) -> dict[str, Any]:
return record
+def held_side(masks: list[np.ndarray]) -> str:
+ """The side of the body the top band (HEAD_BAND) sits on, "left" or "right": where a part held
+ higher than the head is held. `masks` are a cut's frames, True where the body is."""
+ stack = np.stack(masks)
+ rows = np.where(stack.any(axis=(0, 2)))[0]
+ if rows.size == 0:
+ raise ValueError("every loop frame is fully transparent")
+ top, bottom = int(rows.min()), int(rows.max())
+ band = stack[:, top:top + max(1, int(max(1, bottom - top) * HEAD_BAND))]
+ cols = np.arange(stack.shape[2])
+ body, tip = stack.sum(axis=(0, 1)), band.sum(axis=(0, 1))
+ return "right" if float((tip * cols).sum()) / float(tip.sum()) >= float((body * cols).sum()) / float(body.sum()) else "left"
+
+
+def side_edges(masks: list[np.ndarray], side: str) -> np.ndarray:
+ """(frames, rows): each row's outermost body column on `side`, NaN where the row is empty."""
+ stack = np.stack(masks)
+ filled = stack.any(axis=2)
+ if side == "right":
+ edge = stack.shape[2] - 1 - stack[:, :, ::-1].argmax(axis=2)
+ else:
+ edge = stack.argmax(axis=2)
+ out = edge.astype(np.float64)
+ out[~filled] = np.nan
+ return out
+
+
+def held_edge(edges: np.ndarray, start: int, length: int) -> dict[str, Any]:
+ """The held side's seam of a cut (start, length) of a clip whose side edges are `edges`
+ (`side_edges`), section 3, "The held side".
+
+ A loop closes where its last frame is the frame before its first and its first the frame after its
+ last: per row, the cut's first frame against the clip's frame after its last, its last against the
+ clip's frame before its first, and the step into and out of each against the clip's own (a part
+ that comes back to its place moving the other way swings back at the wrap). Their mean over the
+ row's median step in the loop, a floor of HELD_EDGE_FLOOR; the HELD_EDGE_QUANTILE-th percentile
+ over the rows is `seam`, and the held side `closes` under HELD_EDGE_REFERENCE. Raises ValueError
+ for a cut with fewer than two clip frames on either side, or no row to read."""
+ n = len(edges)
+ s, L = start, length
+ if s < 2 or s + L + 1 >= n:
+ raise ValueError("the clip has no two frames either side of the cut to read its wrap against")
+ loop = edges[s:s + L]
+ rows = np.where(np.isfinite(loop).any(axis=0))[0]
+ if rows.size == 0:
+ raise ValueError("every loop frame is fully transparent")
+ steps = np.abs(np.diff(np.vstack([loop, loop[:1]]), axis=0))
+ terms = np.stack([np.abs(edges[s] - edges[s + L]),
+ np.abs((edges[s + 1] - edges[s]) - (edges[s + L + 1] - edges[s + L])),
+ np.abs(edges[s + L - 1] - edges[s - 1]),
+ np.abs((edges[s + L - 1] - edges[s + L - 2]) - (edges[s - 1] - edges[s - 2]))])
+ with np.errstate(invalid="ignore"):
+ counted = np.isfinite(steps).sum(axis=0)
+ median = np.where(counted > 0, np.nanmedian(np.where(counted > 0, steps, 0.0), axis=0), np.nan)
+ read = np.isfinite(terms).sum(axis=0)
+ mean = np.where(read > 0, np.nansum(terms, axis=0) / np.maximum(read, 1), np.nan)
+ floor = max(1.0, HELD_EDGE_FLOOR * float(rows.max() - rows.min()))
+ ratio = mean / np.maximum(median, floor)
+ ratio = ratio[np.isfinite(ratio)]
+ if ratio.size == 0:
+ raise ValueError("no row has the held side's edge in the frames its wrap is read on")
+ seam = round(float(np.percentile(ratio, HELD_EDGE_QUANTILE)), 3)
+ return {"seam": seam, "closes": seam < HELD_EDGE_REFERENCE, "rows": int(ratio.size), "reference": HELD_EDGE_REFERENCE}
+
+
+def held_edge_verdict(shape: dict[str, Any] | None) -> list[str]:
+ """The held side of a cut chosen again on its top band (`cycle.seam_pop.held_edge`), in words, when
+ the chosen cut does not close it or it could not be read; empty otherwise (and for a cut whose top
+ band did not pop, where it is not read)."""
+ held = (shape or {}).get("held_edge")
+ if not held:
+ return []
+ if "skipped" in held:
+ return [f"the top of the silhouette jumps at the first choice, and the side its held part is on could not be read "
+ f"({held['skipped']}): whether the part closes below its top at this cut is not known"]
+ chosen = held["chosen"]
+ if "skipped" in chosen:
+ return [f"the held part's side ({held['side']}) could not be read at this cut ({chosen['skipped']}): whether it "
+ "closes below its top is not known"]
+ if chosen["closes"]:
+ return []
+ return [f"the held part does not close at the wrap on the {held['side']} side of the silhouette, below its top: "
+ f"{chosen['seam']:.2f}x its rows' median step (over {held['reference']:g}); no window one or two cycles long "
+ "closes it — it swings on a beat of its own"]
+
+
def measure_jolt(frames: list[Image.Image], *, facing: str = "right") -> dict[str, Any]:
"""The jolt index of a loop as it plays, and the head's frame-to-frame moves."""
al = coverage(frames, union_box(frames))
diff --git a/tests/video/test_loop_prop_seam.py b/tests/video/test_loop_prop_seam.py
index f4478e7..be698a3 100644
--- a/tests/video/test_loop_prop_seam.py
+++ b/tests/video/test_loop_prop_seam.py
@@ -75,7 +75,13 @@ def test_motion_auto_does_not_cut_where_the_staff_jumps(tmp_path):
"--anchor", "motion-auto", "--repair", "off"]) == 0
report = json.loads((out / "loop.loop.report.json").read_text())
cycle = report["cycle"]
- assert cycle["length"] in (STEP - 1, STEP, STEP + 1)
+ # One step long, or two where the staff below the tip closes only there: a staff swaying every 61
+ # frames turns back at the wrap of every one-step cut whose tip closes (docs/loop-repair.md
+ # section 3, "The held side"), and a window two steps long is marked so.
+ if cycle.get("cycles") == 2:
+ assert cycle["length"] in (2 * STEP - 1, 2 * STEP, 2 * STEP + 1)
+ else:
+ assert cycle["length"] in (STEP - 1, STEP, STEP + 1)
# The cut closes the staff too: its tip at the wrap moves no more than a step inside the loop moves it.
assert _wrap_over_step(cycle["start"], cycle["length"], 1.0) <= 1.5
# The first choice, by the area measure alone, ended with the tip elsewhere; it was chosen again.
@@ -83,7 +89,7 @@ def test_motion_auto_does_not_cut_where_the_staff_jumps(tmp_path):
assert shape["applied"] is True and shape["first_choice"]["pop"] > repair.SEAM_POP_REFERENCE
first = shape["first_choice"]
assert _wrap_over_step(first["start"], first["length"], 1.0) > 3
- assert shape["chosen"] == {"start": cycle["start"], "length": cycle["length"], "pop": shape["chosen"]["pop"]}
+ assert {k: shape["chosen"][k] for k in ("start", "length")} == {"start": cycle["start"], "length": cycle["length"]}
assert report["jolt"]["seam_pop"]["pops"] is False
assert not any("jumps into the loop's first frame" in line for line in report["jolt"]["warnings"])
diff --git a/tests/video/test_loop_prop_seam_held.py b/tests/video/test_loop_prop_seam_held.py
new file mode 100644
index 0000000..cd68e51
--- /dev/null
+++ b/tests/video/test_loop_prop_seam_held.py
@@ -0,0 +1,304 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A held staff that swings once in two steps closes below the hand only on a cut two steps long
+(docs/loop-repair.md section 3, "The held side").
+
+The walker steps every 24 frames; the staff it holds turns about the hand once every 48, its tip
+above the head one way and its foot below the hand the other. A cut one step long whose top closes
+takes the staff where its tip passes the same place moving the other way: the top band reads no
+jump, and the foot swings back at the wrap. `--anchor motion-auto` reads the held side's edge on a
+cut whose top popped, and takes a window two steps long when no one-step cut closes it.
+
+Synthetic frames only; the staff's foot is known in closed form, so the tests read the cut against it."""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image, ImageDraw
+
+from sprite_gen.video import align, local_cycle, loop, repair
+
+STEP, SWING, TIP, LOW, PHASE, FRAMES = 24, 48, 14, 14, math.pi / 2, 97
+
+
+def _foot(k: int, swing: int = SWING) -> float:
+ """The staff foot's sideways place against the body, px."""
+ return -LOW * math.sin(2 * math.pi * k / swing + PHASE)
+
+
+def _walker(k: int, *, staff: bool = True, tip_swing: int = SWING, foot_swing: int = SWING,
+ tip_amp: float = TIP, flag: tuple[int, float] | None = None) -> Image.Image:
+ """A walker holding a staff at the hand: a rod up to the tip and one down to the foot, each turning
+ on its own beat (one staff, turning about the hand, when the two beats are the same). `flag`
+ (beat, phase) hangs a pennant off the tip that sways on a beat of its own."""
+ im = Image.new("RGBA", (300, 240))
+ d = ImageDraw.Draw(im)
+ x = 45 + k
+ y = 70 + round(k * .2) + round(3 * math.sin(k * 2 * math.pi / STEP))
+ d.rectangle((x, y, x + 28, y + 30), fill=(210, 150, 60, 255))
+ d.rectangle((x - 3, y + 32, x + 30, y + 78), fill=(20, 90, 180, 255))
+ leg = round(12 * math.sin(k * 2 * math.pi / STEP))
+ d.rectangle((x + leg, y + 79, x + 6 + leg, y + 119), fill=(80, 30, 60, 255))
+ d.rectangle((x + 24 - leg, y + 79, x + 30 - leg, y + 119), fill=(30, 60, 90, 255))
+ d.point((x + leg + 2, y + 85 + k % 12), fill=(240, 240, 240, 255)) # no two frames the same picture
+ if not staff:
+ return im
+ hand = (x + 38, y + 50)
+ tip = (hand[0] + tip_amp * math.sin(2 * math.pi * k / tip_swing + PHASE), y - 45)
+ d.line([hand, tip], fill=(120, 80, 40, 255), width=3)
+ d.line([hand, (hand[0] + 8 + _foot(k, foot_swing), y + 122)], fill=(120, 80, 40, 255), width=3)
+ d.ellipse((tip[0] - 4, tip[1] - 4, tip[0] + 4, tip[1] + 4), fill=(230, 200, 60, 255))
+ if flag is not None:
+ fx = tip[0] - 12 + 14 * math.sin(2 * math.pi * k / flag[0] + flag[1])
+ d.ellipse((fx - 5, tip[1] - 12, fx + 5, tip[1] - 2), fill=(200, 40, 40, 255))
+ return im
+
+
+def _keyed(root: Path, **kw) -> Path:
+ keyed = root / "keyed"
+ keyed.mkdir(parents=True)
+ for k in range(FRAMES):
+ _walker(k, **kw).save(keyed / f"{k:03}.png")
+ return keyed
+
+
+def _cut(root: Path, keyed: Path) -> dict:
+ out = root / "out"
+ assert loop.main(["--frames-dir", str(keyed), "--out-dir", str(out), "--state", "walk",
+ "--anchor", "motion-auto", "--repair", "off"]) == 0
+ return json.loads((out / "loop.loop.report.json").read_text())
+
+
+def _foot_miss(start: int, length: int, swing: int = SWING) -> float:
+ """How far the cut's wrap is from the staff foot's own way on, in place and in speed, over the
+ largest step the foot takes inside the cut."""
+ f = lambda k: _foot(k, swing) # noqa: E731
+ s, L = start, length
+ inner = max(abs(f(k + 1) - f(k)) for k in range(s, s + L - 1))
+ place = abs(f(s) - f(s + L))
+ speed = abs((f(s + 1) - f(s)) - (f(s + L + 1) - f(s + L)))
+ return max(place, speed) / inner
+
+
[email protected](scope="module")
+def held(tmp_path_factory) -> tuple[Path, dict]:
+ root = tmp_path_factory.mktemp("held")
+ return root, _cut(root, _keyed(root))
+
+
+def test_motion_auto_takes_two_steps_where_the_held_staff_closes_only_there(held):
+ root, report = held
+ cycle = report["cycle"]
+ shape = cycle["seam_pop"]
+ # The staff's foot closes at the cut: at the wrap it is where, and moving as, the clip had it.
+ assert _foot_miss(cycle["start"], cycle["length"]) <= 0.5
+ # The first choice popped at the top; a one-step cut whose top closes swings the foot back.
+ assert shape["first_choice"]["pop"] > repair.SEAM_POP_REFERENCE
+ calm_one_step = [r for r in cycle["candidates"] if r.get("held_edge") is not None]
+ assert calm_one_step and all(r["held_edge"] >= repair.HELD_EDGE_REFERENCE for r in calm_one_step)
+ assert min(_foot_miss(r["start"], r["length"]) for r in calm_one_step) > 1.5
+ # So the cut is two steps long, and the staff's foot closes there.
+ assert cycle["cycles"] == 2 and cycle["length"] in (2 * STEP - 1, 2 * STEP, 2 * STEP + 1)
+ held_edge = shape["held_edge"]
+ assert held_edge["side"] == "right" and held_edge["cycles"] == 2
+ assert held_edge["chosen"] == {"start": cycle["start"], "length": cycle["length"], "seam": held_edge["chosen"]["seam"], "closes": True}
+ assert shape["chosen"]["cycles"] == 2 and shape["applied"] is True
+ strip = json.loads((root / "out" / "loop.strip.json").read_text())
+ assert strip["cycles"] == 2 and strip["cycle_frames"] == cycle["length"]
+ assert not any("held part" in line for line in report["jolt"]["warnings"])
+
+
+def test_a_held_part_that_swings_with_the_step_is_cut_one_step_long(tmp_path):
+ """A pennant at the tip sways on a beat of its own (61 frames) and pops at the first choice; the
+ staff stands straight above the hand and swings with the step below it, so a one-step cut whose
+ top closes closes below the hand too and is taken."""
+ report = _cut(tmp_path, _keyed(tmp_path, tip_amp=0, foot_swing=STEP, flag=(61, 3.0)))
+ cycle = report["cycle"]
+ shape = cycle["seam_pop"]
+ assert shape["first_choice"]["pop"] > repair.SEAM_POP_REFERENCE and shape["applied"] is True
+ assert "cycles" not in cycle and cycle["length"] in (STEP - 1, STEP, STEP + 1)
+ assert shape["held_edge"]["cycles"] == 1 and shape["held_edge"]["chosen"]["closes"] is True
+ assert "two_cycle" not in shape["held_edge"]
+ assert _foot_miss(cycle["start"], cycle["length"], STEP) <= 0.5
+
+
+def test_a_held_part_no_window_closes_is_kept_on_the_top_bands_choice_and_warned(tmp_path):
+ """The foot swings every 37 frames: neither one step nor two closes it. The cut is the top band's,
+ and the jolt says the held part does not close."""
+ report = _cut(tmp_path, _keyed(tmp_path, tip_swing=SWING, foot_swing=37))
+ cycle = report["cycle"]
+ held_edge = cycle["seam_pop"]["held_edge"]
+ assert "cycles" not in cycle and held_edge["two_cycle"]["closing"] == 0
+ assert held_edge["chosen"]["closes"] is False and held_edge["chosen"]["seam"] >= repair.HELD_EDGE_REFERENCE
+ lines = [line for line in report["jolt"]["warnings"] if "held part does not close" in line]
+ assert len(lines) == 1 and "right side" in lines[0]
+
+
+def test_a_walk_whose_top_does_not_pop_reads_nothing_below_it(tmp_path):
+ report = _cut(tmp_path, _keyed(tmp_path, staff=False))
+ shape = report["cycle"]["seam_pop"]
+ assert shape["applied"] is False and "held_edge" not in shape and "cycles" not in report["cycle"]
+ assert not any(r.get("held_edge") is not None for r in report["cycle"]["candidates"])
+
+
+# --- the held side, read on edges -------------------------------------------------------------
+
+def _edges(series: list[float], rows: int = 30) -> np.ndarray:
+ """A rod edge at the same column on every row, per frame."""
+ return np.repeat(np.asarray(series, dtype=np.float64)[:, None], rows, axis=1)
+
+
+def test_held_edge_reads_place_and_speed_at_the_wrap():
+ period = 24
+ wave = [100 + 10 * math.sin(2 * math.pi * k / period) for k in range(80)]
+ closes = repair.held_edge(_edges(wave), 10, period)
+ assert closes["closes"] is True and closes["seam"] < 0.2 and closes["rows"] == 30
+ # Half a period: the edge comes back to its place moving the other way — it swings back at the wrap.
+ swings = repair.held_edge(_edges([100 + 10 * math.sin(2 * math.pi * k / 48) for k in range(80)]), 12, period)
+ assert swings["closes"] is False and swings["seam"] > repair.HELD_EDGE_REFERENCE
+ # A row empty in some frames is read on the frames it has; a row empty everywhere is not read.
+ gappy = _edges(wave)
+ gappy[:, :5] = np.nan
+ gappy[11, 5] = np.nan
+ assert repair.held_edge(gappy, 10, period)["rows"] == 25
+
+
+def test_held_edge_needs_two_clip_frames_either_side_of_the_cut():
+ edges = _edges([100.0 + k % 24 for k in range(60)])
+ for start, length in ((1, 24), (0, 24), (35, 24), (36, 24)):
+ with pytest.raises(ValueError, match="no two frames either side"):
+ repair.held_edge(edges, start, length)
+ assert "seam" in repair.held_edge(edges, 2, 24) and "seam" in repair.held_edge(edges, 34, 24)
+ with pytest.raises(ValueError, match="transparent"):
+ repair.held_edge(np.full((60, 10), np.nan), 10, 24)
+
+
+def test_held_side_is_the_side_the_top_band_sits_on():
+ body = np.zeros((100, 60), bool)
+ body[30:100, 20:40] = True
+ right, left = body.copy(), body.copy()
+ right[0:30, 48:50] = True
+ left[0:30, 8:10] = True
+ assert repair.held_side([right, right]) == "right" and repair.held_side([left]) == "left"
+ edges = repair.side_edges([right], "right")
+ assert edges[0, 10] == 49 and edges[0, 50] == 39
+ assert repair.side_edges([left], "left")[0, 10] == 8
+ with pytest.raises(ValueError):
+ repair.held_side([np.zeros((10, 10), bool)])
+
+
+def test_held_edge_verdict_speaks_only_for_a_held_side_that_does_not_close():
+ assert repair.held_edge_verdict(None) == [] and repair.held_edge_verdict({"applied": False}) == []
+ closes = {"held_edge": {"side": "right", "reference": 1.2, "chosen": {"start": 1, "length": 46, "seam": 0.7, "closes": True}}}
+ assert repair.held_edge_verdict(closes) == []
+ misses = {"held_edge": {"side": "left", "reference": 1.2, "chosen": {"start": 1, "length": 23, "seam": 2.1, "closes": False}}}
+ (line,) = repair.held_edge_verdict(misses)
+ assert "left side" in line and "2.10x" in line and "over 1.2" in line
+ (line,) = repair.held_edge_verdict({"held_edge": {"method": "held-side-edge-v1", "skipped": "every loop frame is fully transparent"}})
+ assert "could not be read" in line
+ (line,) = repair.held_edge_verdict({"held_edge": {"side": "right", "reference": 1.2,
+ "chosen": {"start": 0, "length": 23, "skipped": "the clip has no two frames"}}})
+ assert "could not be read at this cut" in line
+
+
+# --- choosing on it ---------------------------------------------------------------------------
+
+class _FakeHeld:
+ """A `loop.HeldEdge` reading a table: (start, length) -> seam, or a reason string it cannot read."""
+
+ @property
+ def reference(self):
+ return repair.HELD_EDGE_REFERENCE
+
+ def __init__(self, table, frames=80, side="right"):
+ self.table, self.frames, self._side = table, frames, side
+ self.read = []
+
+ def side(self, start, length):
+ return {"skipped": self._side} if self._side.startswith("no ") else {"side": self._side}
+
+ def seam(self, start, length, side):
+ self.read.append((start, length))
+ value = self.table.get((start, length), 5.0)
+ if isinstance(value, str):
+ return {"skipped": value, "reference": self.reference}
+ return {"seam": value, "closes": value < self.reference, "rows": 30, "reference": self.reference}
+
+
+def _pop(table, default=0.0):
+ def pop(start, length):
+ value = table.get((start, length), default)
+ return {"pop": value, "pops": value > repair.SEAM_POP_REFERENCE, "reference": repair.SEAM_POP_REFERENCE}
+ return pop
+
+
+ROWS = [{"start": 0, "length": 24, "score": 1.0}, {"start": 3, "length": 24, "score": 1.01}, {"start": 6, "length": 24, "score": 1.05}]
+
+
+def test_shape_rank_takes_a_one_cycle_cut_whose_held_side_closes():
+ candidates = [dict(r) for r in ROWS]
+ fake = _FakeHeld({(3, 24): 1.0, (6, 24): 0.5})
+ chosen, record = local_cycle._shape_rank(candidates, candidates[0], _pop({(0, 24): 14.0}), fake)
+ assert chosen["start"] == 6 and record["held_edge"]["cycles"] == 1
+ assert record["chosen"] == {"start": 6, "length": 24, "pop": 0.0}
+ assert all(length == 24 for _, length in fake.read) # nothing two cycles long was read
+
+
+def test_shape_rank_takes_two_cycles_when_no_one_cycle_cut_closes_and_never_an_unread_one():
+ candidates = [dict(r) for r in ROWS]
+ fake = _FakeHeld({(3, 24): "the clip has no two frames either side of the cut to read its wrap against",
+ (10, 48): 0.9, (12, 47): 0.4, (20, 49): 0.3})
+ chosen, record = local_cycle._shape_rank(candidates, candidates[0], _pop({(0, 24): 14.0, (20, 49): 12.0}), fake)
+ # (20, 49) closes below but its top pops: not taken. (12, 47) has the smallest held seam left.
+ assert (chosen["start"], chosen["length"], chosen["cycles"]) == (12, 47, 2)
+ held = record["held_edge"]
+ assert held["cycles"] == 2 and held["unread"] == 1 and held["two_cycle"]["closing"] == 2
+ assert held["two_cycle"]["top_pops"] == 1 and held["two_cycle"]["lengths"] == [47, 49]
+ assert candidates[1]["held_edge"] is None and candidates[1]["held_edge_skipped"]
+ assert record["chosen"] == {"start": 12, "length": 47, "pop": 0.0, "cycles": 2}
+
+
+def test_shape_rank_without_a_closing_window_keeps_the_top_bands_choice_and_records_it():
+ candidates = [dict(r) for r in ROWS]
+ chosen, record = local_cycle._shape_rank(candidates, candidates[0], _pop({(0, 24): 14.0}), _FakeHeld({}, frames=60))
+ assert chosen["start"] == 3 and record["chosen"]["pop"] == 0.0 and "cycles" not in chosen
+ assert record["held_edge"]["chosen"] == {"start": 3, "length": 24, "seam": 5.0, "closes": False}
+ assert record["held_edge"]["two_cycle"]["closing"] == 0
+ # A side that cannot be read: the top band's choice, and the record says why.
+ candidates = [dict(r) for r in ROWS]
+ chosen, record = local_cycle._shape_rank(candidates, candidates[0], _pop({(0, 24): 14.0}), _FakeHeld({}, side="no head"))
+ assert chosen["start"] == 3 and record["held_edge"] == {"method": "held-side-edge-v1", "skipped": "no head"}
+
+
+def test_shape_rank_reads_no_held_side_when_the_first_choice_does_not_pop():
+ fake = _FakeHeld({})
+ candidates = [dict(r) for r in ROWS]
+ chosen, record = local_cycle._shape_rank(candidates, candidates[0], _pop({}), fake)
+ assert chosen["start"] == 0 and "held_edge" not in record and fake.read == []
+
+
+# --- the set ----------------------------------------------------------------------------------
+
+def test_cycle_align_keeps_a_two_cycle_loop_two_cycles_at_twice_the_set_length(held, tmp_path):
+ """The two-step loop is counted already: not a suspect to stop on, resampled to twice the length
+ the set takes from its one-step loop, and still marked two cycles."""
+ root, report = held
+ one_step = tmp_path / "plain"
+ plain = _cut(one_step, _keyed(one_step, staff=False))
+ lengths = [report["cycle"]["length"], plain["cycle"]["length"]]
+ out = align.align_set([root / "out", one_step / "out"], between="nearest")
+ two, one = out["loops"]
+ target = round(float(np.median([lengths[0] / 2, lengths[1]])))
+ assert out["length"] == target and two["to"] == 2 * target and one["to"] == target
+ assert two["cycles_kept"] == 2 and one["cycles_kept"] == 1
+ assert all(e["status"] == "declared" for e in out["suspects"] if e["dir"] == str((root / "out").resolve()))
+ assert json.loads((root / "out" / "loop.strip.json").read_text())["cycles"] == 2
+ assert "cycles" not in json.loads((one_step / "out" / "loop.strip.json").read_text())
+ # A count given for it is still the last word: one cycle taken out of it, no longer marked two.
+ out = align.align_set([root / "out", one_step / "out"], between="nearest", cycles={str(root / "out"): 2})
+ assert out["loops"][0]["cycles_kept"] == 1 and "cycle_taken" in out["loops"][0]
+ assert "cycles" not in json.loads((root / "out" / "loop.strip.json").read_text())