Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(frames): a drawing cut by its own frame is read as its border, leftover key passes only as the body's rim, and a refused run hands nothing over
Soohong Kimf180fab01d0c
diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.pyindex f0ca94f..16a1d31 100644--- a/sprite_gen/video/frames.py+++ b/sprite_gen/video/frames.py@@ -21,12 +21,27 @@ into it, reaches the band first) — and the two failwith different messages: residual points at `video-canvas` normalization of thebase still, subject contact at a taller/wider canvas.+A drawing can be cut by its own frame: a bust whose sleeve runs off the left and whose hair runs+off the top touches those edges in every frame, and no canvas gives it room there. The check+reads that on the clip's first frame (`edge_border`): a side whose outermost row or column the+subject covers for at least `BORDER_MIN_FRACTION` of its length is the drawing's own **border**,+and contact there is accepted in every frame. Contact on any other side is still the subject+framed too tight (a hand that leaves the right). Leftover key is still refused, save the body's+rim the matte cut loose: a key-only piece under `SPECK_MIN_PX` lying wholly within `RIM_REACH`+px of the frame's body, on a border side the frame's subject reaches. A first frame that+crosses no side is judged and worded as before, and the numbers a refusal gives are the pixels+the border does not take.+`--allow-subject-edge-contact` accepts the second and keeps the first: a clip madefrom a `video-canvas --fit tight` frame is clipped on purpose, but a frame where onlyleftover key background reaches the edge is still a keying defect. A frame where thesubject touches the edge carries key-tinted fringe pixels beside it and is accepted withthem. The contacts stay in the report.+The keyed frames are handed over as `keyed/` only by a run that passed. A refused run keeps+them as `keyed.refused/` (no `keyed/`, not even an earlier run's), and its report, written+either way, says `status`.+A **speck** is not the subject either: a fleck the model drew drifting across the background,well away from the body, that survived the matte. Every keyed frame has its specks erased(`drop_specks`) before the edge check reads it, so a few pale pixels drifting through the edge@@ -45,6 +60,7 @@ import jsonimport mathimport shutilimport subprocess+import sysfrom pathlib import Pathfrom typing import Any@@ -77,6 +93,17 @@ SPILL_REFERENCE_MAX = 0.005 # the still's own key material ≤ the engine's smaSPILL_REFERENCE_MARGIN = 1SPILL_REFERENCE_MAX_PIXELS = 6_000_000EDGE_MAX_PIXELS = 0 # any opaque pixel on the top/left/right edge band = contact+SIDES = ("top", "left", "right")+# The drawing's own border (`edge_border`): a side the first frame's subject covers on its outermost row or+# column for this share of its length. A drawing cut there (a sleeve, hair off the top) covers far more; a+# strand's tip grazing the edge covers less.+BORDER_MIN_FRACTION = 0.02+# The body's rim the matte cut loose: on a border side, a key-only piece is accepted when it lies wholly within+# RIM_REACH px of the frame's body (each way and diagonally) and holds fewer than SPECK_MIN_PX pixels — a few+# pixels of a thin outline the key was blended into, left at the edge between strands. Anything larger or farther+# is leftover background, refused as before.+RIM_REACH = 10+REFUSED_SUFFIX = ".refused" # keyed/ of a refused run: keyed.refused/# Specks (`drop_specks`). A component under SPECK_MIN_FRACTION of the frame's largest one, or under# SPECK_MIN_PX, is small; more than SPECK_APART of the largest one's height from it, far. `video-loop`# reads the size by the same two numbers when it erases the loose pieces of a cut (`drop_specks` with@@ -234,45 +261,99 @@ def edge_contact(image: Image.Image) -> dict[str, int]:return {"top": top, "left": left, "right": right}-def classify_edge_contact(raw: Image.Image, keyed: Image.Image, chroma_key: tuple[int, int, int] | None,- painted_key: tuple[int, int, int] | None = None) -> dict[str, int]:- """Split the opaque edge-band pixels into `subject` and `residual` (leftover key background).+def _bands(h: int, w: int) -> dict[str, np.ndarray]:+ """The top/left/right edge bands, EDGE_ROWS deep; a corner pixel is in two."""+ bands = {side: np.zeros((h, w), dtype=bool) for side in SIDES}+ bands["top"][:EDGE_ROWS, :] = True+ bands["left"][:, :EDGE_ROWS] = True+ bands["right"][:, max(0, w - EDGE_ROWS):] = True+ return bands- A contact pixel whose *raw* colour carries the declared key's hue signature- (`is_border_key_candidate`; the leaning greens only when `painted_key`, the background the- frame was keyed from, leans itself: `extract._painted_key_leans`) is either background the- matte failed to erase or the subject's own rim: a body reaching the band brings its- antialiased edge, the key blended into it, there first. It is residual only when the opaque piece of the keyed frame it belongs to — its opaque- pixels, corners joining them, the pieces `drop_specks` reads — holds no pixel off the key's- signature: background on its own. Joined to one, it is the subject's. Without a chroma key- (matte route) every contact is the subject.- """++def _edge_pixels(raw: Image.Image, keyed: Image.Image, chroma_key: tuple[int, int, int] | None,+ painted_key: tuple[int, int, int] | None = None) -> dict[str, np.ndarray]:+ """`classify_edge_contact`'s pixels: the edge bands (`bands`), the opaque pixels in them (`contact`), the+ `residual` among those and the `rim` among the residual."""alpha = np.asarray(keyed.convert("RGBA"))[..., 3]h, w = alpha.shape- band = np.zeros((h, w), dtype=bool)- band[:EDGE_ROWS, :] = True- band[:, :EDGE_ROWS] = True- band[:, max(0, w - EDGE_ROWS):] = True+ bands = _bands(h, w)opaque = alpha > 0- contact = band & opaque- total = int(contact.sum())+ contact = (bands["top"] | bands["left"] | bands["right"]) & opaque+ none = np.zeros((h, w), dtype=bool)+ out = {"bands": bands, "contact": contact, "residual": none, "rim": none}keyed_channels, unkeyed_channels = _key_channel_split(chroma_key) if chroma_key is not None else ([], [])- if not total or not keyed_channels:- return {"subject": total, "residual": 0}+ if not contact.any() or not keyed_channels:+ return outlean = painted_key is not None and _painted_key_leans(painted_key, keyed_channels, unkeyed_channels)keyish = _border_key_candidate_field(np.asarray(raw.convert("RGB"), dtype=np.int32), keyed_channels, unkeyed_channels,lean=lean)suspect = contact & keyishif not suspect.any():- return {"subject": total, "residual": 0}- ys, starts, stops, labels, _ = _components(opaque, diagonal=True)+ return out+ ys, starts, stops, labels, sizes = _components(opaque, diagonal=True)piece = np.zeros((h, w), dtype=np.int64)for y, x0, x1, label in zip(ys, starts, stops, labels):piece[y, x0:x1] = labelowned = np.zeros(len(ys), dtype=bool) # pieces holding a pixel off the key's signatureowned[piece[opaque & ~keyish]] = True- residual = int((suspect & ~owned[piece]).sum())- return {"subject": total - residual, "residual": residual}+ residual = suspect & ~owned[piece]+ out["residual"] = residual+ if residual.any() and owned.any():+ body = opaque & (piece == int(np.where(owned, sizes, -1).argmax()))+ apart = np.zeros(len(ys), dtype=bool) # pieces with a pixel farther than RIM_REACH from the body+ apart[piece[opaque & ~_near(body, RIM_REACH)]] = True+ out["rim"] = residual & ~apart[piece] & (sizes[piece] < SPECK_MIN_PX)+ return out+++def classify_edge_contact(raw: Image.Image, keyed: Image.Image, chroma_key: tuple[int, int, int] | None,+ painted_key: tuple[int, int, int] | None = None) -> dict[str, int]:+ """Split the opaque edge-band pixels into `subject` and `residual` (leftover key background),+ and count the `rim` among the residual.++ A contact pixel whose *raw* colour carries the declared key's hue signature+ (`is_border_key_candidate`; the leaning greens only when `painted_key`, the background the+ frame was keyed from, leans itself: `extract._painted_key_leans`) is either background the+ matte failed to erase or the subject's own rim: a body reaching the band brings its+ antialiased edge, the key blended into it, there first. It is residual only when the opaque piece of the keyed frame it belongs to — its opaque+ pixels, corners joining them, the pieces `drop_specks` reads — holds no pixel off the key's+ signature: background on its own. Joined to one, it is the subject's. Without a chroma key+ (matte route) every contact is the subject.++ `rim` is the residual in a piece of fewer than SPECK_MIN_PX pixels lying wholly within+ RIM_REACH px of the frame's body — the largest piece holding a pixel off the key's signature,+ as `drop_specks` reads the largest piece as the body: what the border takes of the residual+ (`key_frames`), whatever side it is on.+ """+ pixels = _edge_pixels(raw, keyed, chroma_key, painted_key)+ residual = int(pixels["residual"].sum())+ return {"subject": int(pixels["contact"].sum()) - residual, "residual": residual, "rim": int(pixels["rim"].sum())}+++def _border(pixels: dict[str, np.ndarray] | None, size: tuple[int, int], frame: str) -> dict[str, Any]:+ """The drawing's own border, read on the first frame's edge pixels (`_edge_pixels`; None: it touches no edge),+ `size` (w, h): `edge_border` in the report."""+ w, h = size+ outer = {side: 0 for side in SIDES}+ if pixels is not None:+ subject = pixels["contact"] & ~pixels["residual"]+ outer = {"top": int(subject[0].sum()), "left": int(subject[:, 0].sum()), "right": int(subject[:, -1].sum())}+ length = {"top": w, "left": h, "right": h}+ return {"frame": frame, "sides": [s for s in SIDES if outer[s] and outer[s] >= BORDER_MIN_FRACTION * length[s]],+ "outer_px": outer, "min_fraction": BORDER_MIN_FRACTION, "rim_reach": RIM_REACH, "rim_under_px": SPECK_MIN_PX}+++def _taken(pixels: dict[str, np.ndarray], sides: list[str]) -> np.ndarray:+ """The edge pixels the border takes: the subject on a border side, and the rim on a border side the frame's+ subject reaches. A corner pixel is taken only when both its sides take it."""+ bands, subject = pixels["bands"], pixels["contact"] & ~pixels["residual"]+ subject_taken, rim_taken = subject.copy(), pixels["rim"].copy()+ for side in SIDES:+ if side not in sides:+ subject_taken &= ~bands[side]+ if side not in sides or not (subject & bands[side]).any():+ rim_taken &= ~bands[side]+ return subject_taken | rim_takendef _reference_window(reference: Path, key: str) -> tuple[str, Image.Image | None, tuple[int, int, int] | None, dict[str, Any]]:@@ -332,6 +413,30 @@ def decide_spill(reference: Path, key: str) -> dict[str, Any]:"reference_fringe_policy": "dark-only", **facts}+class KeyingRefused(SystemExit):+ """A refused keying (`key_frames`): its message, and the report of the frames it keyed, for `run_frames` to+ write with `status: refused`."""++ def __init__(self, message: str, report: dict[str, Any]) -> None:+ super().__init__(message)+ self.report = report+++def refused_dir(keyed_dir: Path) -> Path:+ """Where a refused run keeps the frames it keyed: `keyed.refused/` beside `keyed/`."""+ return keyed_dir.with_name(keyed_dir.name + REFUSED_SUFFIX)+++def _withdraw(keyed_dir: Path) -> Path:+ """Take back what an earlier run handed over, and give this run an empty working folder (returned): until this+ run passes, `keyed_dir` holds nothing."""+ work = keyed_dir.with_name(f".{keyed_dir.name}.work")+ shutil.rmtree(keyed_dir, ignore_errors=True)+ shutil.rmtree(work, ignore_errors=True)+ work.mkdir(parents=True)+ return work++def key_frames(raw_files: list[Path],keyed_dir: Path,@@ -343,17 +448,34 @@ def key_frames(decontam: str = "off",alpha_mode: str = "chroma",) -> dict[str, Any]:+ """Key `raw_files` into `keyed_dir` and read their edges; the report. The frames are keyed in a working folder+ beside it and handed over as `keyed_dir` when the run passes; a run that does not pass leaves them as+ `refused_dir(keyed_dir)` and no `keyed_dir`. A refusal raises `KeyingRefused`, carrying the report."""from . import effectif alpha_mode not in effect.ALPHA_MODES:raise SystemExit(f"video-frames: unknown --alpha-mode {alpha_mode!r}")- if alpha_mode == "brightness":- if decontam != "off":- raise SystemExit("video-frames: brightness alpha does not use --decontam")- return effect.key_frames(raw_files, keyed_dir)- if spill not in ("small", "full"):+ if alpha_mode == "brightness" and decontam != "off":+ raise SystemExit("video-frames: brightness alpha does not use --decontam")+ if alpha_mode == "chroma" and spill not in ("small", "full"):raise SystemExit(f"video-frames: key_frames takes a resolved spill mode (small|full), got {spill!r}")if decontam not in DECONTAM_MODES:raise SystemExit(f"video-frames: unknown --decontam {decontam!r}; expected one of {', '.join(DECONTAM_MODES)}")+ work = _withdraw(keyed_dir)+ try:+ report = (effect.key_frames(raw_files, work) if alpha_mode == "brightness" else+ _key_chroma(raw_files, work, key=key, check_edges=check_edges, spill=spill, allow_subject=allow_subject,+ decontam=decontam))+ except BaseException:+ shutil.rmtree(refused_dir(keyed_dir), ignore_errors=True)+ work.rename(refused_dir(keyed_dir))+ raise+ shutil.rmtree(refused_dir(keyed_dir), ignore_errors=True)+ work.rename(keyed_dir)+ return report+++def _key_chroma(raw_files: list[Path], keyed_dir: Path, *, key: str, check_edges: bool, spill: str, allow_subject: bool,+ decontam: str) -> dict[str, Any]:clip_palette: dict[str, Any] | None = Nonedecontam_first: dict[str, Any] | None = Nonedecontam_totals = {name: 0 for name in DECONTAM_STAT_KEYS}@@ -361,10 +483,43 @@ def key_frames(# Full correction lowers the tint threshold as well as lifting the size cap.spill_max = SPILL_FULL_FRACTION if spill == "full" else Nonespill_tint = SPILL_FULL_MIN_TINT if spill == "full" else None- keyed_dir.mkdir(parents=True, exist_ok=True)+ policy = "off" if not check_edges else ("subject-allowed" if allow_subject else "border")+ border: dict[str, Any] | None = Nonerows: list[dict[str, Any]] = []contacts: list[dict[str, Any]] = []- for src in raw_files:+ # What the border does not take, frame by frame, worded as a contact is (`_edge_contact_message`).+ untaken: list[dict[str, Any]] = []++ def summary() -> dict[str, Any]:+ report = {+ "frames": len(rows),+ "alpha_zero_pct_min": min(r["alpha_zero_pct"] for r in rows),+ "alpha_zero_pct_max": max(r["alpha_zero_pct"] for r in rows),+ "specks": {"dropped": sum(r["specks"] for r in rows), "frames": sum(1 for r in rows if r["specks"]),+ "min_fraction": SPECK_MIN_FRACTION, "min_px": SPECK_MIN_PX, "apart": SPECK_APART},+ "edge_contacts": contacts,+ "edge_policy": policy,+ **({"edge_border": border} if policy == "border" else {}),+ "rows": rows,+ }+ if decontam != "off" and decontam_first is not None:+ report["decontam"] = {+ "mode": decontam,+ "fit": DECONTAM_FIT,+ "palette_source": f"clip (learned on {decontam_first['frame']})",+ "palette": decontam_first["palette"],+ "palette_keyfree": decontam_first["palette_keyfree"],+ "key_material_share": decontam_first["key_material_share"],+ "material_spread": decontam_first["material_spread"],+ "edge_band": decontam_first["edge_band"],+ "applied_frames": decontam_applied,+ "totals": decontam_totals,+ }+ else:+ report["decontam"] = {"mode": decontam, "applied_frames": 0}+ return report++ for k, src in enumerate(raw_files):dst = keyed_dir / src.namestats = cutout(src, dst, key=key, spill_max_fraction=spill_max, spill_min_tint=spill_tint,spill_require_hue=spill == "full", decontam=decontam, decontam_fit=DECONTAM_FIT,@@ -392,55 +547,57 @@ def key_frames(row["decontam"] = {"applied": False, "reason": done.get("reason")}if check_edges:contact = edge_contact(image)- if any(v > EDGE_MAX_PIXELS for v in contact.values()):+ touched = any(v > EDGE_MAX_PIXELS for v in contact.values())+ pixels = None+ if touched:chroma = stats.get("chroma_key")painted = stats.get("chroma_key_painted")- contact.update(classify_edge_contact(Image.open(src), image, tuple(chroma) if chroma else None,- tuple(painted) if painted else None))+ pixels = _edge_pixels(Image.open(src), image, tuple(chroma) if chroma else None, tuple(painted) if painted else None)+ residual = int(pixels["residual"].sum())+ contact.update(subject=int(pixels["contact"].sum()) - residual, residual=residual, rim=int(pixels["rim"].sum()))contact["key_painted"] = stats.get("chroma_key_painted")+ if policy == "border" and k == 0:+ border = _border(pixels, (w, h), src.name)+ if border["sides"]:+ print(f"video-frames: the first frame's subject runs off the {_sides(border['sides'])} — read as the "+ "drawing's own border, where contact is accepted in every frame (`edge_border` in the report)",+ file=sys.stderr)+ if touched:+ if policy == "border":+ taken = _taken(pixels, border["sides"])+ off = pixels["contact"] & ~taken+ contact["border"] = int(taken.sum())+ contact["off"] = {side: int((off & pixels["bands"][side]).sum()) for side in SIDES}+ if off.any():+ lone = int((off & pixels["residual"]).sum())+ untaken.append({"frame": src.name, **contact["off"], "subject": int(off.sum()) - lone, "residual": lone,+ "key_painted": contact["key_painted"]})contacts.append({"frame": src.name, **contact})row["edge"] = contactif hist[0] == 0:- raise SystemExit(f"video-frames: {src.name} keyed to 0% transparency — the background is not the chroma key")+ rows.append(row)+ raise KeyingRefused(f"video-frames: {src.name} keyed to 0% transparency — the background is not the chroma key",+ summary())rows.append(row)- report = {- "frames": len(rows),- "alpha_zero_pct_min": min(r["alpha_zero_pct"] for r in rows),- "alpha_zero_pct_max": max(r["alpha_zero_pct"] for r in rows),- "specks": {"dropped": sum(r["specks"] for r in rows), "frames": sum(1 for r in rows if r["specks"]),- "min_fraction": SPECK_MIN_FRACTION, "min_px": SPECK_MIN_PX, "apart": SPECK_APART},- "edge_contacts": contacts,- "edge_policy": "off" if not check_edges else ("subject-allowed" if allow_subject else "refuse"),- "rows": rows,- }- if decontam != "off" and decontam_first is not None:- report["decontam"] = {- "mode": decontam,- "fit": DECONTAM_FIT,- "palette_source": f"clip (learned on {decontam_first['frame']})",- "palette": decontam_first["palette"],- "palette_keyfree": decontam_first["palette_keyfree"],- "key_material_share": decontam_first["key_material_share"],- "material_spread": decontam_first["material_spread"],- "edge_band": decontam_first["edge_band"],- "applied_frames": decontam_applied,- "totals": decontam_totals,- }- else:- report["decontam"] = {"mode": decontam, "applied_frames": 0}- if contacts and check_edges:- if not allow_subject:- raise SystemExit(_edge_contact_message(contacts))+ report = summary()+ if untaken:+ raise KeyingRefused(_edge_contact_message(untaken), report)+ if contacts and policy == "subject-allowed":# Only a frame where the key alone reaches the edge is leftover background. Where the# subject touches it too, the key-tinted pixels beside it are its antialiased fringe or# a reflection of the key on it (a silver armour on green) — the same reading# `_edge_contact_message` gives a mixed contact.- residual = [c for c in contacts if c["residual"] > 0 and c["subject"] == 0]- if residual:- raise SystemExit(_residual_message(residual))+ residual_only = [c for c in contacts if c["residual"] > 0 and c["subject"] == 0]+ if residual_only:+ raise KeyingRefused(_residual_message(residual_only), report)return report+def _sides(sides: list[str]) -> str:+ return (f"{sides[0]} edge" if len(sides) == 1 else+ f"{', '.join(sides[:-1])} and {sides[-1]} edges")++def _worst(contacts: list[dict[str, Any]]) -> tuple[dict[str, Any], str]:worst = max(contacts, key=lambda c: c["top"] + c["left"] + c["right"])return worst, f"(worst {worst['frame']}: top {worst['top']} / left {worst['left']} / right {worst['right']} px)"@@ -499,15 +656,25 @@ def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool,if not clip.is_file():raise SystemExit(f"video-frames: clip not found: {clip}")out_dir = out_dir.expanduser().resolve()- meta = probe(clip)raw_dir = out_dir / "raw"keyed_dir = out_dir / "keyed"+ target = (report_path or (out_dir / "frames.report.json")).expanduser().resolve()+ # From here the run reads the clip: an earlier run's keyed frames are no longer handed over (`key_frames`).+ shutil.rmtree(keyed_dir, ignore_errors=True)+ meta = probe(clip)decision = ({"mode": "off", "reason": "brightness alpha"} if alpha_mode == "brightness" elsedecide_spill(Path(reference).expanduser().resolve(), key) if spill == "auto" else {"mode": spill, "reason": "explicit"})files = extract(clip, raw_dir, meta["stream_index"])- report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"], allow_subject=allow_subject_edge_contact, decontam=decontam, alpha_mode=alpha_mode)- payload = {"kind": "sprite-gen-video-frames-report", "clip": str(clip), "out_dir": str(out_dir), "raw_dir": str(raw_dir), "keyed_dir": str(keyed_dir), "key": key, "spill": decision, **meta, **report}- target = (report_path or (out_dir / "frames.report.json")).expanduser().resolve()+ head = {"kind": "sprite-gen-video-frames-report", "clip": str(clip), "out_dir": str(out_dir), "raw_dir": str(raw_dir)}+ try:+ report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"], allow_subject=allow_subject_edge_contact, decontam=decontam, alpha_mode=alpha_mode)+ except KeyingRefused as refused:+ # The run's record, written whatever it found: the frames it keyed are in `refused_dir`, and nothing is handed over.+ payload = {**head, "status": "refused", "error": str(refused), "keyed_dir": None, "refused_dir": str(refused_dir(keyed_dir)),+ "key": key, "spill": decision, **meta, **refused.report}+ atomic_write_text(target, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")+ raise+ payload = {**head, "status": "passed", "keyed_dir": str(keyed_dir), "key": key, "spill": decision, **meta, **report}if source_manifest is not None:from sprite_gen.video.evidence import engine_identitypayload["producer"] = engine_identity()diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 499ad3c..ea4809b 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -127,6 +127,8 @@ CYCLE_SOURCE_DIR = "cycle.source"# The strip as it was before `video-follow` moved a region of it; a later follow-through reads# from it, and a new cut or alignment removes it (docs/video-pipeline.md section 6).FOLLOW_SOURCE = "follow.source.png"+# A refused cut hands nothing over (`refuse`); the frames it wrote, if it got that far, are kept here to look at.+CYCLE_REFUSED_DIR = "cycle.refused"# A gait's period is a fact about the body, not about how long the clip runs: the@@ -886,6 +888,30 @@ def verify_animation(path: Path, *, expect_frames: int, check_stale: bool, expecreturn report+def handed_over(out_dir: Path, name: str) -> list[Path]:+ """What a cut that passed hands over in `out_dir`: its frames (`cycle/`), the strip and its metadata, the GIF and+ the WebP, and what a later alignment and follow-through keep beside them (`cycle.source/`, `follow.source.png`)."""+ return [out_dir / "cycle", out_dir / CYCLE_SOURCE_DIR, out_dir / FOLLOW_SOURCE, out_dir / f"{name}.strip.png",+ out_dir / f"{name}.strip.json", out_dir / f"{name}.gif", out_dir / f"{name}.webp"]+++def refuse(target: Path, out_dir: Path, name: str, report: dict[str, Any], *, cut_written: bool = False) -> None:+ """Refuse the cut: take back all an earlier cut handed over in `out_dir` (`handed_over`), so a caller that does not+ read the exit code finds nothing to pass on, and write the report (`status: failed`). A cut this run wrote stays as+ `cycle.refused/`, in place of an earlier one."""+ out_dir = out_dir.expanduser().resolve()+ shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)+ shutil.rmtree(out_dir / CYCLE_REFUSED_DIR, ignore_errors=True)+ if cut_written:+ (out_dir / "cycle").rename(out_dir / CYCLE_REFUSED_DIR)+ for path in handed_over(out_dir, name):+ if path.is_dir():+ shutil.rmtree(path)+ else:+ path.unlink(missing_ok=True)+ write_loop_report(target, report)++def write_loop_report(target: Path, payload: dict[str, Any]) -> None:"""Strict JSON, including refusals with undefined (zero-motion) ratios."""def finite(value: Any) -> Any:@@ -1599,11 +1625,10 @@ def run_loop(# Whatever chose the cut — a search, a count, --cycle fixed or pinned — it is inside the caller's bounds.window.hold(cycle)except (SystemExit, ValueError) as exc:- shutil.rmtree(out_dir.expanduser().resolve() / FALLBACK_FRAMES_DIR, ignore_errors=True)refused = getattr(exc, "diagnostics", cycle)- write_loop_report(target, {**report_base, "status": "failed", "error": str(exc),- "cycle": _from_lead_in(refused, skip) if skip and not shifted else refused,- "periodic_attempt": periodic_attempt})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": str(exc),+ "cycle": _from_lead_in(refused, skip) if skip and not shifted else refused,+ "periodic_attempt": periodic_attempt})if isinstance(exc, ValueError):raise SystemExit(f"video-loop: {exc}") from excraise@@ -1660,8 +1685,7 @@ def run_loop()except ValueError as exc:error = f"video-loop: {exc}"- shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)- write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error) from excreport_base["motion_anchor"] = motionif anchor in ("none", "body") and cycle["kind"] != "lifetime":@@ -1696,8 +1720,7 @@ def run_loop(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, for a part that rushes, at a wrap a part "f"on its own beat does not close, or for a filmed 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})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error) from excif overlap is not None:report_base["wrap_overlap"] = overlap@@ -1767,8 +1790,7 @@ def run_loop(f"{', after repairing frames ' + str(report_base['jump_repair']['replaced']) if report_base['jump_repair'].get('replaced') else ''}); ""the motion does not play smoothly — regenerate the clip"f"{' (the jump repair did not run: RIFE is not installed — ' + rife_mod.INSTALL_COMMAND + ')' if 'rife' in report_base['jump_repair'] else ''}")- shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)- write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error)for line in warnings:print(f"video-loop: warning: {line} (reference bound; the loop is kept — docs/loop-repair.md)", file=sys.stderr)@@ -1788,6 +1810,7 @@ def run_loop(shutil.rmtree(out_dir / CYCLE_SOURCE_DIR, ignore_errors=True)# A new cut makes a follow-through over the old strip stale (`video-follow` reads this source).(out_dir / FOLLOW_SOURCE).unlink(missing_ok=True)+ shutil.rmtree(out_dir / CYCLE_REFUSED_DIR, ignore_errors=True)for k, im in enumerate(frames):im.save(cycle_dir / f"frame-{k:03d}.png")# The standing height is the base still's pose as filmed, the clip's first frame — but a video model that@@ -1800,10 +1823,15 @@ def run_loop(report_base["cut_size"] = gait_fallback.size_change(gait_fallback.body_size(Image.open(files[0]).convert("RGBA")), cut_sizes)if abs(report_base["cut_size"]["change"]) >= gait_fallback.SIZE_HOLD_MIN:standing_frame = i- strip_of = partial(build_strip, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),- standing_src=standing_height(files[standing_frame], standing_frame) if body_height is not None and cycle["kind"] != "lifetime" else None,- standing_frame=standing_frame)- strip, strip_meta = strip_of(frames)+ try:+ strip_of = partial(build_strip, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),+ standing_src=standing_height(files[standing_frame], standing_frame) if body_height is not None and cycle["kind"] != "lifetime" else None,+ standing_frame=standing_frame)+ strip, strip_meta = strip_of(frames)+ except SystemExit as exc:+ # No body to measure or to crop the strip to: the cut is refused like any other.+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": str(exc), "cycle": cycle}, cut_written=True)+ raise# The cut as its seam is read: each cell given way to the frame beside it as filmed (`seam_as_filmed`).seam_frames = [as_filmed.get(k, f) for k, f in enumerate(frames)]strip_meta["source_cut"] = {"source": report_base["source"], "start": i, "length": L,@@ -1881,10 +1909,10 @@ def run_loop(f"exceeds {cycle['pin_tolerance']:.4f}); {what} — regenerate the clip with ""--last-frame set to its first frame")- write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle,- "resampled_seam": resampled_seam,- "resampled_inner_mean_adjacent": resampled_adjacent,- "resampled_seam_ratio": seam_ratio})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle,+ "resampled_seam": resampled_seam,+ "resampled_inner_mean_adjacent": resampled_adjacent,+ "resampled_seam_ratio": seam_ratio}, cut_written=True)raise SystemExit(error)elif not single_play and seam_ratio > seam_max:error = (@@ -1892,26 +1920,32 @@ def run_loop(f"({cycle['kind']} length {L} frames from {i}); the cycle does not close — ""regenerate with a complete return to the starting pose")- write_loop_report(target, {**report_base, "status": "failed", "error": error,- "cycle": cycle, "periodic_attempt": periodic_attempt,- "resampled_seam": resampled_seam,- "resampled_inner_mean_adjacent": resampled_adjacent,- "resampled_seam_ratio": seam_ratio})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error,+ "cycle": cycle, "periodic_attempt": periodic_attempt,+ "resampled_seam": resampled_seam,+ "resampled_inner_mean_adjacent": resampled_adjacent,+ "resampled_seam_ratio": seam_ratio}, cut_written=True)raise SystemExit(error)# GIF has binary transparency. Bake the effect onto its declared black preview# background instead of turning its faint partial-alpha glow into opaque dark pixels.gif_background = "#000000" if cycle["kind"] == "lifetime" else Nonegif_pick = [effect.on_black(im) for im in pick] if gif_background is not None else pick- save_clean_gif(gif_pick, gif_path, duration_ms=delay_ms, loop=None if single_play else 0,- alpha_threshold=128, opaque=gif_background is not None)- write_webp(pick, webp_path, delay_ms=delay_ms, workdir=out_dir / ".webp-frames", **({"loop": 1} if single_play else {}))- shutil.rmtree(out_dir / ".webp-frames", ignore_errors=True)- # A filmed ghost given way to the frame beside it is that frame shown twice in a row: one frame of the GIF or WebP- shown = shown_runs(pick)- gif_report = verify_animation(gif_path, expect_frames=shown_runs(gif_pick), check_stale=False,- **({"expected_loop": None} if single_play else {}),- **({"background": gif_background} if gif_background is not None else {}))- webp_report = verify_animation(webp_path, expect_frames=shown, check_stale=True, **({"expected_loop": 1} if single_play else {}))+ try:+ save_clean_gif(gif_pick, gif_path, duration_ms=delay_ms, loop=None if single_play else 0,+ alpha_threshold=128, opaque=gif_background is not None)+ write_webp(pick, webp_path, delay_ms=delay_ms, workdir=out_dir / ".webp-frames", **({"loop": 1} if single_play else {}))+ shutil.rmtree(out_dir / ".webp-frames", ignore_errors=True)+ # A filmed ghost given way to the frame beside it is that frame shown twice in a row: one frame of the GIF or WebP+ shown = shown_runs(pick)+ gif_report = verify_animation(gif_path, expect_frames=shown_runs(gif_pick), check_stale=False,+ **({"expected_loop": None} if single_play else {}),+ **({"background": gif_background} if gif_background is not None else {}))+ webp_report = verify_animation(webp_path, expect_frames=shown, check_stale=True, **({"expected_loop": 1} if single_play else {}))+ except SystemExit as exc:+ # The GIF or WebP could not be written (no img2webp) or failed its verification: nothing of the cut is handed over.+ shutil.rmtree(out_dir / ".webp-frames", ignore_errors=True)+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": str(exc), "cycle": cycle}, cut_written=True)+ raisepayload = {**report_base,