Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video): reject faulty jump repairs and compare delivered samples
Soohong Kim582e2cf4f853
diff --git a/SKILL.md b/SKILL.mdindex 37e6dce..5130157 100644--- a/SKILL.md+++ b/SKILL.md@@ -102,6 +102,7 @@ hold the arms still, and check the loop with `handed-check --state walk`.| Continue or edit an existing clip | `video-extend`, `video-edit` | [video](docs/video.md) || Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) || A soft part of a walk loop follows the body (a chest, a belly): an ellipse in the first cell, after `video-cycle-align` | `video-follow` | [video-pipeline](docs/video-pipeline.md#6-follow-through--video-follow) |+| Compare the currently displayed loop with a final candidate, including after follow-through | `video-loop-compare` | [loop-comparison](docs/loop-comparison.md) || Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`; a loop the report lists under `unnamed_feet` — its view could not tell the feet apart, or only by too small a margin (`low-margin`): look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left|right`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) || Ordinary image or edit | `gen --provider codex` or `gen --provider grok` (subscription routes) | [gen](docs/gen.md) || Image generation with no login available (server, container, SaaS) | `gen --provider openai` — server/SaaS route on `OPENAI_API_KEY`, **billed per call**, never a default or a fallback | [gen](docs/gen.md#subscription-first--openai-is-named-or-it-does-not-run) |diff --git a/docs/README.md b/docs/README.mdindex ef87793..4979d14 100644--- a/docs/README.md+++ b/docs/README.md@@ -60,6 +60,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.|---|---|| [run-contract.md](run-contract.md) | The atlas pipeline's normative contract: stages, the run-dir folder tree, curation-view display, atomic extract, concurrency scope || [architecture.md](architecture.md) | How the code is laid out: domains, stage ownership, the numeric SSoT, the cell model, extraction internals, runtime manifest |+| [loop-comparison.md](loop-comparison.md) | Final loop artifact digests, comparable quality axes and explicit unknown verdicts |## Request authoring (pipeline A inputs)diff --git a/docs/loop-comparison.md b/docs/loop-comparison.mdnew file mode 100644index 0000000..aaa98ac--- /dev/null+++ b/docs/loop-comparison.md@@ -0,0 +1,113 @@+# Comparing delivered loops++`video-loop-compare` reads the **final strip and metadata**, including any+`video-follow` changes. A loop report supplies provenance; its seam score and+pass status do not describe later pixels and are never used as comparison scores.++```bash+sprite-gen video-loop-compare \+ --baseline-strip current.strip.png --baseline-meta current.strip.json \+ --baseline-report current.loop.json \+ --candidate-strip final.strip.png --candidate-meta final.strip.json \+ --candidate-report candidate.loop.json --report comparison.json+```++All inputs are read only. Exit 0 means a comparison was produced, including an+`unknown` verdict. Invalid JSON, image/metadata geometry disagreement, empty+frames, invalid numeric timing and I/O failures are errors, with nonzero exit.+The output cannot overwrite an input. The JSON written to `--report` is also+printed to stdout.++## Report contract++The report has `kind: "sprite-gen-video-loop-comparison"`, `schema_version: 1`+and `metric_version: "same-sample-defects-v1"`.++| Field | Meaning |+|---|---|+| `verdict` | `improved`, `non_regressing`, `regressed`, or `unknown` |+| `reasons` | Machine-readable codes explaining the verdict; an input-specific reason starts with `baseline:` or `candidate:` |+| `baseline`, `candidate` | The actual artifacts, decoded pixels, frame count, cell size, timing, source cut, producer and follow presence |+| `<side>.artifacts.{strip,meta,report}.{sha256,bytes}` | SHA-256 and size of each **original file's bytes**; JSON whitespace is significant |+| `<side>.pixels_sha256` | SHA-256 of the ordered decoded RGBA cell bytes |+| `measurement_engine.implementation_sha256` | Fingerprint of the video implementation and CLI that performed the measurement |+| `axes.<axis>` | `baseline`, `candidate`, `comparable`, `reason`, `status` for that axis |+| `limits` | What the comparison does not establish |++Freeze the bytes to be uploaded before invoking the comparison, then upload+those exact bytes. An application binds their digests to its active revision,+checks that revision again before activation, and owns its acceptance decision.+An application that automatically replaces a result should accept **only+`improved`**. Revision IDs, database transactions and billing are outside the+engine. A comparator error must remain an error; it is not permission to adopt+a candidate on an old seam score.++## What v1 can order++The order is deliberately limited to measured defects at **the same original+sample times, playback timing, crop and scale**. `video-loop` records the+ordered original keyed PNG sequence hash, count and fps in `source`, and a+`source_cut` in strip metadata. The source identity is read before cleanup,+size hold and anchoring. The strip builder records its actual `sample_indices`+and `source_rect`; foot anchoring has no fixed source rectangle.++The comparator requires consistent source evidence on both sides. It does not+regenerate a baseline, infer provenance from a filesystem path, rotate a cycle,+resample time, align each body to remove its bob, or assign a foot identity from+a silhouette peak. A different cut, a cycle-aligned strip without a proven+source mapping, legacy evidence, missing/inconsistent timing or unverified+coordinates returns `unknown`. Different cuts with different seam-ratio+denominators are therefore never ranked by those ratios.++For comparable inputs, each frame's `dark_excess`, `outline_loss` and+`partial_excess` is measured against its two actual final neighbours with+`rife.smear`. Positive excess is compared frame by frame, without averaging+away a worse frame. The seam is the mean absolute difference of premultiplied+RGBA over the shared native cell canvas, also reported per second. A worsening+component yields `regressed`; no weighted total score is constructed.++An improvement additionally needs **byte-identical alpha coverage at each+sample**. This proves preservation of the silhouette's pose, bob and size+without making an aesthetic assumption that less motion is better. Changed+coverage with no measured regression is `unknown`: v1 cannot certify the+intended deformation of feet, hair or soft parts. This is a limitation, not a+request to hold every frame still. Equal pixels and timing are+`non_regressing`, never `improved`. Non-regression describes these axes only,+not the drawing's overall quality.++Colour changes must be confined to frames that previously failed the shared+interpolation policy (`smear` or `outline`), and those changed frames must now+pass it. Other drawings stay byte-identical. A smaller seam obtained by+flattening colour animation is not sufficient: it returns+`changed-unfaulted-drawings-unverified`. A remaining interpolation fault returns+`interpolation-fault-remains`. These are `unknown` unless another comparable+axis already proves a regression.++`body_motion` reuses the common-body tracker from `video-follow`.+`top_band_motion` is the existing silhouette-top observation, which may follow+an accessory instead of a head. Both are descriptive; reducing their motion+is not scored as improvement. Rigid scale pumping is not inferred from a+changing silhouette bounding box.++Both automatic and fixed gait cuts emit `gait.status: "unverified"` with+`reason: "own-foot-contacts-not-identified"`, cut-local silhouette signals and+any existing search screens. These signals neither identify the character's+own feet nor prove two alternating contacts. Comparing the same source samples+preserves their relative phase; it does not certify that the source was a+correct gait cycle.++Common reason codes include `identical-pixels-and-timing`,+`measured-defect-reduced-with-motion-preserved`, `no-measured-defect-improvement`,+`different-source-samples-phase-unverified`, `different-timing`,+`spatial-basis-unverified`, `changed-coverage-pose-preservation-unverified`,+`changed-unfaulted-drawings-unverified`, `interpolation-fault-remains`,+`<axis>:regressed`, and the input-prefixed `source-provenance-missing`,+`source-provenance-invalid`, `source-provenance-inconsistent`,+`source-report-unverified`, `source-samples-unverified`,+`source-geometry-invalid`, `source-geometry-inconsistent`,+`source-timing-inconsistent`, `aligned-source-phase-unverified`,+`loop-playback-unverified`, `timing-missing`, `cycle-duration-missing`,+`timing-inconsistent`, `nonuniform-timing-unsupported`.++See [loop repair](loop-repair.md) for proposal rejection and the interpolation+quality bounds, and [video pipeline](video-pipeline.md) for processing stages.diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex b84d5a7..d887552 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -168,18 +168,32 @@ over the loop — and the larger is the step's score.| A jump | a score of at least **1.4** (`JUMP_RATIO`) | the ponytail cuts the experiment found sat at 1.5–2.5; a smooth take's worst step sits near 1.3 || The hair box | (0, 0.30)–(0.45, 0.80) of the union box for a right-facing body; mirrored for `--facing left` | below the head and behind the body, where a ponytail cut at the wrong moment jumps || The frame remade | the frame after the jump; but when the step *into* frame k is a jump too and larger than the step after k+1, frame k itself (a single stray frame breaks two steps) | remaking the frame after a stray frame leaves the stray standing |-| How | RIFE's frame half way between the frame's two neighbours | every other frame stays the video's own |-| How many | at most **3** (`MAX_REPAIRS`), worst first, scores re-read after each | a loop that needs more is jolting everywhere, not jumping once |+| How | propose RIFE's frame half way between the two neighbours, inspect it, then adopt it only without interpolation faults | a rejected proposal keeps the original middle frame; every other frame stays the video's own |+| How many | at most **3 calls** (`MAX_REPAIRS`), rejected proposals included, worst eligible target first | a loop that needs more is jolting everywhere, not jumping once || Never | a frame next to one already made | two made frames side by side are made from each other and melt the legs |Re-making every frame (an offset of half a frame) is not offered: it softens the frames thatwere fine, and it was judged "not corrected" (2026-10-03).-The report's `jump_repair` carries `replaced` (cycle frame indices), each round's step, score and-its whole/hair parts, `score_max_before` / `score_max_after`, why it stopped, and which-interpolator made the frames. When a frame was replaced the seam gate measures the rendered cells+Blocked targets are skipped while independent candidates remain. Scores are re-read+after adoption; a rejected target is never retried in that run. The circular last/first+adjacency rule and call budget still apply. The shared `interpolation_quality` policy+is the same one used by cycle alignment: `dark_excess > 0.001` or+`outline_loss > 0.05` rejects a proposal. An empty proposal is also rejected.+The original middle frame is retained, not a duplicate of either neighbour.++The report's `jump_repair` carries `replaced` (cycle frame indices), `attempts`,+`blocked` targets, and each round's step, target, score, whole/hair parts,+`original` and `proposal` measurements, `faults`, and `outcome` (`accepted` or+`rejected`). It also records `score_max_before` / `score_max_after`, why it stopped,+and which interpolator made the proposals. Rejection is not overall quality failure+or success: original drawing changes and normal gait motion can remain.+When a frame was replaced the seam gate measures the rendered cells(`seam_measurement: rendered-cells`), because the source frames no longer say what plays.+To compare an active result with a final candidate after all processing, use+[`video-loop-compare`](loop-comparison.md); a seam pass alone is not an improvement.+RIFE is located only when a frame is to be made. A loop with a jump and no RIFE is cut as filmedwith a warning under `--repair auto`, and fails under `--repair on` (section 1, "Without RIFE").`--repair off` cuts the loop as filmed and records `jump_repair: {"applied": false, "why":diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.pyindex c0320f1..62deb66 100644--- a/sprite_gen/_modules.py+++ b/sprite_gen/_modules.py@@ -28,6 +28,7 @@ MODULE_DOMAIN = {'batch': 'video','align': 'video','follow': 'video',+ 'compare': 'video','rife_install': 'video','clip_prompt': 'video','prepare': 'gen',diff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex 5fd6d4d..365b8f1 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -22,6 +22,7 @@ from sprite_gen.video import loop as video_loopfrom sprite_gen.video import clip_prompt as video_promptfrom sprite_gen.video import align as video_alignfrom sprite_gen.video import follow as video_follow+from sprite_gen.video import compare as video_comparefrom sprite_gen.video import rife_installfrom sprite_gen.effects import recolor, shadowfrom sprite_gen.scene import render, inspect_scene@@ -354,6 +355,11 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callabvideo_loop.add_arguments,video_loop.run,),+ "video-loop-compare": (+ "Compare final loop strip/meta bytes; report improvement, regression or unverified evidence.",+ video_compare.add_arguments,+ video_compare.run,+ ),"video-set": ("Directions x states end to end (canvas -> video -> frames -> loop), rate-limit aware, one report per item.",video_batch.add_arguments,diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex 3630eb1..e53c60f 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -78,6 +78,7 @@ from sprite_gen.video import legs as legs_modfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import period as period_modfrom sprite_gen.video import rife as rife_mod+from sprite_gen.video.interpolation_quality import SMEAR_WARN, OUTLINE_WARN, faultsSNAP = 0.03 # a sample time within this of a source frame takes that frameSOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop again@@ -106,14 +107,6 @@ DEFAULT_BETWEEN = "auto"# set before anything is rewritten, warn aligns it as it is and names the loop in the warnings.MULTI_CYCLE = ("fail", "warn")CYCLES = (1, 2, 3) # what --cycles <loop>=k may say a loop holds-# A made frame whose dark pixels inside the body exceed both neighbours' by this fraction of its-# solid pixels is named in the report's warnings: a smear, not a dark part that moved.-SMEAR_WARN = 0.001-# A made frame whose coverage edge has no outline beyond both neighbours' by this fraction of its-# edge (`rife.smear`'s `outline_loss`) has melted: legs that crossed too far for the flow became one-# shape of fill, or a limb a pale ghost. Outlined legs crossing too far melt at 32 %, a short step-# the flow follows stays under 3 % (tests/video/test_rife.py; docs/loop-repair.md section 4).-OUTLINE_WARN = 0.05# A loop whose source holds its drawings (two or three frames each, sprite_gen/video/held.py) and that# the set's length leaves at fewer than this many drawings a second, with at least UNMADE_MIN of the# frames between them not made (taken from the nearer source frame, or kept with a fault), is a take@@ -179,13 +172,6 @@ def _retake_line(name: str, r: dict[str, Any]) -> str:"fixes it; no interpolator draws legs that swap places across a gap this wide (docs/loop-repair.md section 4)")-def faults(measure: dict[str, float]) -> list[str]:- """What is wrong with a made frame, by its `rife.smear` measure: `smear` (dark beyond both- neighbours, SMEAR_WARN) and `outline` (outline lost beyond both, OUTLINE_WARN)."""- return ([*(["smear"] if measure["dark_excess"] > SMEAR_WARN else []),- *(["outline"] if measure["outline_loss"] > OUTLINE_WARN else [])])--def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Interpolate | None,*, between: str = DEFAULT_BETWEEN) -> tuple[list[Image.Image], dict[str, Any]]:"""`frames` as one cycle, resampled to `length` frames at times k·L/length (offset 0).diff --git a/sprite_gen/video/compare.py b/sprite_gen/video/compare.pynew file mode 100644index 0000000..1a9ce06--- /dev/null+++ b/sprite_gen/video/compare.py@@ -0,0 +1,283 @@+# SPDX-License-Identifier: Apache-2.0+"""Compare final loop artifacts, with explicit limits on what can be ordered.++No quality values from an upstream loop report are used. That report supplies+source provenance only; follow-through may have changed every delivered pixel.+The v1 order is deliberately narrow: same source samples, timing and coordinates,+with unchanged coverage to prove preservation of the filmed silhouette motion.+"""++from __future__ import annotations++import argparse+import io+import json+import math+from dataclasses import dataclass+from pathlib import Path+from typing import Any++from PIL import Image++from sprite_gen._deps import np+from sprite_gen.spec.runio import atomic_write_text+from sprite_gen.video import evidence, follow, repair, rife+from sprite_gen.video.interpolation_quality import faults++METRIC_VERSION = "same-sample-defects-v1"+KIND = "sprite-gen-video-loop-comparison"+++def _number(value: Any) -> bool:+ return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)+++def _positive_int(value: Any, name: str) -> int:+ if not isinstance(value, int) or isinstance(value, bool) or value < 1:+ raise ValueError(f"{name} must be a positive integer")+ return value+++def _json(data: bytes, name: str) -> dict[str, Any]:+ value = json.loads(data)+ if not isinstance(value, dict):+ raise ValueError(f"{name} must be a JSON object")+ return value+++@dataclass+class Loop:+ frames: list[Image.Image]+ meta: dict[str, Any]+ source_report: dict[str, Any]+ artifacts: dict[str, Any]+ delay: float | None++ @classmethod+ def read(cls, strip: Path, meta: Path, report: Path) -> Loop:+ # Read each artifact once. Hash and measure the same snapshot, including JSON whitespace.+ data = {k: p.read_bytes() for k, p in (("strip", strip), ("meta", meta), ("report", report))}+ m, r = _json(data["meta"], "meta"), _json(data["report"], "report")+ n, w, h = (_positive_int(m.get(k), k) for k in ("frames", "w", "h"))+ with Image.open(io.BytesIO(data["strip"])) as im:+ if im.format != "PNG" or im.size != (n * w, h) or getattr(im, "n_frames", 1) != 1:+ raise ValueError("strip must be a single PNG whose size agrees with meta frames/w/h")+ sheet = im.convert("RGBA")+ frames = [sheet.crop((k * w, 0, (k + 1) * w, h)) for k in range(n)]+ if any(not f.getchannel("A").getbbox() for f in frames):+ raise ValueError("strip contains a fully transparent frame")+ delay = m.get("delay_ms")+ if delay is not None and (not _number(delay) or delay <= 0):+ raise ValueError("delay_ms must be finite and positive")+ artifacts = {k: {"sha256": evidence.digest(b), "bytes": len(b)} for k, b in data.items()}+ return cls(frames, m, r, artifacts, delay)++ def timing_issue(self) -> str | None:+ if self.delay is None:+ return "timing-missing"+ if "durations_ms" in self.meta:+ return "nonuniform-timing-unsupported"+ seconds = self.meta.get("cycle_seconds")+ if not _number(seconds):+ return "cycle-duration-missing"+ # The writer rounds delay_ms to .01 ms and cycle_seconds to .0001 s.+ if abs(seconds * 1000 - self.delay * len(self.frames)) > .005 * len(self.frames) + .05 + 1e-9:+ return "timing-inconsistent"+ return None++ def provenance_issue(self) -> str | None:+ cut = self.meta.get("source_cut")+ src = self.source_report.get("source")+ cycle = self.source_report.get("cycle")+ if not all(isinstance(v, dict) for v in (cut, src, cycle)):+ return "source-provenance-missing"+ if self.source_report.get("kind") != "sprite-gen-video-loop-report" or self.source_report.get("status") != "passed":+ return "source-report-unverified"+ sha = src.get("sha256")+ if (src.get("kind") != "keyed-frame-sequence" or not isinstance(sha, str) or len(sha) != 64+ or any(c not in "0123456789abcdef" for c in sha)+ or not isinstance(src.get("frames"), int) or isinstance(src["frames"], bool) or src["frames"] < 1+ or not _number(src.get("fps")) or src["fps"] <= 0):+ return "source-provenance-invalid"+ start, length, samples = cut.get("start"), cut.get("length"), cut.get("samples")+ if (not isinstance(start, int) or isinstance(start, bool) or start < 0+ or not isinstance(length, int) or isinstance(length, bool) or length < 2+ or start + length > src["frames"] or not isinstance(samples, list)+ or len(samples) != len(self.frames) or any(not isinstance(k, int) or isinstance(k, bool) for k in samples)+ or samples != sorted(set(samples)) or any(k < start or k >= start + length for k in samples)):+ return "source-samples-unverified"+ if (cut.get("source") != src or cycle.get("start") != start or cycle.get("length") != length+ or self.source_report.get("fps") != src["fps"] or self.source_report.get("frames_total") != src["frames"]):+ return "source-provenance-inconsistent"+ if self.meta.get("cycle_frames") != length:+ return "source-samples-unverified"+ expected = [start + round(k * length / len(samples)) for k in range(len(samples))]+ if samples != expected:+ return "source-samples-unverified"+ if not _number(self.meta.get("cycle_seconds")) or abs(self.meta["cycle_seconds"] - length / src["fps"]) > .00005 + 1e-9:+ return "source-timing-inconsistent"+ if "cycle_align" in self.meta:+ return "aligned-source-phase-unverified"+ if self.meta.get("loop") is not True:+ return "loop-playback-unverified"+ rect = self.meta.get("source_rect")+ if rect is not None and (not isinstance(rect, list) or len(rect) != 4 or not all(_number(v) for v in rect)+ or rect[2] <= rect[0] or rect[3] <= rect[1]):+ return "source-geometry-invalid"+ reported_strip = self.source_report.get("strip")+ if not isinstance(reported_strip, dict) or any(self.meta.get(k) != reported_strip.get(k)+ for k in ("w", "h", "frames", "scale", "source_rect", "foot_anchor")):+ return "source-geometry-inconsistent"+ return None++ def describe(self) -> dict[str, Any]:+ return {"artifacts": self.artifacts, "frames": len(self.frames), "cell": list(self.frames[0].size),+ "timing": {"delay_ms": self.delay, "duration_ms": self.delay * len(self.frames) if self.delay else None},+ "source_cut": self.meta.get("source_cut"), "producer": self.source_report.get("producer"),+ "gait": self.source_report.get("gait"), "follow": "follow" in self.meta,+ "pixels_sha256": evidence.digest(b"".join(f.tobytes() for f in self.frames))}+++def _measure(loop: Loop) -> dict[str, Any]:+ frames = loop.frames+ rgba = [np.asarray(f, dtype=np.float64) / 255 for f in frames]+ # Fixed native cell area; no private per-cut median in the denominator.+ premul = [np.dstack((a[..., :3] * a[..., 3:], a[..., 3])) for a in rgba]+ seam = float(np.abs(premul[-1] - premul[0]).mean())+ quality = [rife.smear(f, frames[k - 1], frames[(k + 1) % len(frames)]) for k, f in enumerate(frames)]+ body: dict[str, Any]+ try:+ y, x, height, worn = follow.body_motion(frames)+ body = {"x_px": x.tolist(), "y_px": y.tolist(), "height_px": height, "worn_px": worn}+ except ValueError as exc:+ body = {"unknown": str(exc)}+ try:+ head = repair.head_track([a[..., 3] for a in rgba])+ except ValueError as exc:+ head = {"unknown": str(exc)}+ return {"seam": {"premultiplied_rgba_mae": seam,+ "per_second": seam * 1000 / loop.delay if loop.delay else None},+ "interpolation": {"frames": quality, "faults": [faults(q) for q in quality]},+ "body_motion": body, "top_band_motion": head}+++def _axis(a: Any, b: Any, comparable: bool, reason: str, status: str = "unknown") -> dict[str, Any]:+ return {"baseline": a, "candidate": b, "comparable": comparable, "reason": reason, "status": status}+++def _order(a: list[float], b: list[float]) -> str:+ # No tradeoffs/averaging: one worsening component is a regression.+ delta = np.asarray(b) - np.asarray(a)+ if (delta > 1e-9).any():+ return "regressed"+ return "improved" if (delta < -1e-9).any() else "non_regressing"+++def compare(baseline: Loop, candidate: Loop) -> dict[str, Any]:+ a, b = baseline, candidate+ ma, mb = _measure(a), _measure(b)+ reasons = []+ for side, loop in (("baseline", a), ("candidate", b)):+ for issue in (loop.timing_issue(), loop.provenance_issue()):+ if issue:+ reasons.append(f"{side}:{issue}")+ same_samples = (not reasons and a.meta["source_cut"] == b.meta["source_cut"])+ if not reasons and not same_samples:+ reasons.append("different-source-samples-phase-unverified")+ same_timing = a.delay == b.delay and len(a.frames) == len(b.frames)+ if not same_timing:+ reasons.append("different-timing")+ # A fixed crop and scale put both arrays in the same coordinate system. Per-frame+ # foot anchoring or an unrecorded/legacy crop cannot establish this.+ geometry_keys = ("w", "h", "source_rect", "scale", "foot_anchor")+ same_geometry = (all(k in a.meta and k in b.meta and a.meta[k] == b.meta[k] for k in geometry_keys)+ and isinstance(a.meta.get("source_rect"), list) and len(a.meta["source_rect"]) == 4+ and _number(a.meta.get("scale")) and a.meta["scale"] > 0)+ if not same_geometry:+ reasons.append("spatial-basis-unverified")+ comparable = bool(same_samples and same_timing and same_geometry and not reasons)+ same_coverage = (comparable and all(x.getchannel("A").tobytes() == y.getchannel("A").tobytes()+ for x, y in zip(a.frames, b.frames)))+ same_pixels = comparable and all(x.tobytes() == y.tobytes() for x, y in zip(a.frames, b.frames))+ changed = [k for k, (x, y) in enumerate(zip(a.frames, b.frames)) if x.tobytes() != y.tobytes()] if comparable else []+ # A smaller seam may just be a flattened drawing. Only frames with a pre-existing+ # shared interpolation fault may change for an automatic improvement claim.+ confined = comparable and all(ma["interpolation"]["faults"][k] for k in changed)+ cleared = comparable and all(not mb["interpolation"]["faults"][k] for k in changed)+ axes = {+ "phase": _axis(a.meta.get("source_cut"), b.meta.get("source_cut"), bool(same_samples),+ "same-source-samples" if same_samples else "source-phase-unverified",+ "non_regressing" if same_samples else "unknown"),+ "silhouette_motion": _axis("coverage-as-delivered", "coverage-as-delivered", comparable,+ "identical-coverage-preserves-bob-and-pose" if same_coverage else "changed-coverage-pose-preservation-unverified",+ "non_regressing" if same_coverage else "unknown"),+ "body_motion": _axis(ma["body_motion"], mb["body_motion"], comparable and all("unknown" not in m["body_motion"] for m in (ma, mb)),+ "observation-only-less-motion-is-not-better"),+ "top_band_motion": _axis(ma["top_band_motion"], mb["top_band_motion"], comparable and all("unknown" not in m["top_band_motion"] for m in (ma, mb)),+ "silhouette-top-not-an-identified-head"),+ "scale": _axis(a.meta.get("scale"), b.meta.get("scale"), comparable,+ "identical-coverage-preserves-size" if same_coverage else "rigid-scale-not-inferred-from-bbox",+ "non_regressing" if same_coverage else "unknown"),+ "drawing_preservation": _axis([], changed, comparable,+ "unchanged-unfaulted-drawings" if confined else "changed-unfaulted-drawings-unverified",+ "non_regressing" if confined else "unknown"),+ }+ seam_status = _order([ma["seam"]["premultiplied_rgba_mae"]], [mb["seam"]["premultiplied_rgba_mae"]]) if comparable else "unknown"+ axes["seam"] = _axis(ma["seam"], mb["seam"], comparable, "native-common-canvas-no-relative-denominator", seam_status)+ for metric in ("dark_excess", "outline_loss", "partial_excess"):+ va, vb = ([max(0.0, q[metric]) for q in m["interpolation"]["frames"]] for m in (ma, mb))+ axes[metric] = _axis(va, vb, comparable, "same-sample-excess-beyond-both-neighbours",+ _order(va, vb) if comparable else "unknown")+ statuses = [axes[k]["status"] for k in ("seam", "dark_excess", "outline_loss", "partial_excess")]+ if not comparable:+ verdict = "unknown"+ elif "regressed" in statuses:+ verdict = "regressed"+ reasons.extend(f"{k}:regressed" for k, v in axes.items() if v["status"] == "regressed")+ elif not same_coverage:+ verdict = "unknown"+ reasons.append("changed-coverage-pose-preservation-unverified")+ elif same_pixels:+ verdict = "non_regressing"+ reasons.append("identical-pixels-and-timing")+ elif not confined:+ verdict = "unknown"+ reasons.append("changed-unfaulted-drawings-unverified")+ elif not cleared:+ verdict = "unknown"+ reasons.append("interpolation-fault-remains")+ elif "improved" in statuses:+ verdict = "improved"+ reasons.append("measured-defect-reduced-with-motion-preserved")+ else:+ verdict = "non_regressing"+ reasons.append("no-measured-defect-improvement")+ return {"kind": KIND, "schema_version": 1, "metric_version": METRIC_VERSION,+ "measurement_engine": evidence.engine_identity(), "verdict": verdict, "reasons": reasons,+ "baseline": a.describe(), "candidate": b.describe(), "axes": axes,+ "limits": ["same-sample defect comparison, not overall animation quality",+ "own-foot identity and intended drawing changes are not certified",+ "changed coverage requires pose review; no motion flattening or resampling"]}+++def add_arguments(parser: argparse.ArgumentParser) -> None:+ for side in ("baseline", "candidate"):+ for artifact in ("strip", "meta", "report"):+ parser.add_argument(f"--{side}-{artifact}", required=True, type=Path)+ parser.add_argument("--report", required=True, type=Path)+++def run(**kwargs: Any) -> int:+ output = Path(kwargs["report"])+ paths = {s: {k: Path(kwargs[f"{s}_{k}"]) for k in ("strip", "meta", "report")} for s in ("baseline", "candidate")}+ try:+ if any(output.resolve() == p.resolve() for row in paths.values() for p in row.values()):+ raise ValueError("comparison report cannot overwrite an input artifact")+ payload = compare(Loop.read(**paths["baseline"]), Loop.read(**paths["candidate"]))+ text = json.dumps(payload, indent=2, allow_nan=False) + "\n"+ output.parent.mkdir(parents=True, exist_ok=True)+ atomic_write_text(output, text)+ except (OSError, ValueError, TypeError) as exc:+ raise SystemExit(f"video-loop-compare: {exc}") from exc+ print(text, end="")+ return 0diff --git a/sprite_gen/video/evidence.py b/sprite_gen/video/evidence.pynew file mode 100644index 0000000..7f69546--- /dev/null+++ b/sprite_gen/video/evidence.py@@ -0,0 +1,45 @@+# SPDX-License-Identifier: Apache-2.0+"""Source identity and gait evidence shared by automatic and explicit loop cuts."""++from __future__ import annotations++import hashlib+from pathlib import Path+from typing import Any++from PIL import Image++from sprite_gen.video import legs+++def digest(data: bytes) -> str:+ return hashlib.sha256(data).hexdigest()+++def engine_identity() -> dict[str, str]:+ """Fingerprint the measured video implementation, including an unreleased checkout."""+ root = Path(__file__).parent+ files = [*sorted(root.glob("*.py")), root.parent / "cli.py"]+ return {"implementation_sha256": digest(b"".join(p.name.encode() + b"\0" + p.read_bytes() for p in files))}+++def source_identity(files: list[Path], fps: float) -> dict[str, Any]:+ """Ordered original keyed-file bytes, before anchoring, cleanup, or size hold."""+ return {"kind": "keyed-frame-sequence", "sha256": digest(b"".join(bytes.fromhex(digest(p.read_bytes())) for p in files)),+ "frames": len(files), "fps": fps}+++def gait_observation(frames: list[Image.Image], cycle: dict[str, Any]) -> dict[str, Any]:+ """Silhouette signals are observations, never a count of identified foot contacts."""+ record: dict[str, Any] = {+ "status": "unverified", "reason": "own-foot-contacts-not-identified",+ "cut": {"start": cycle["start"], "length": cycle["length"]},+ "screens": {k: cycle[k] for k in ("fundamental", "step_screen", "steps") if k in cycle},+ }+ try:+ signals = legs.strike_signals(frames)+ record["silhouette"] = {"signals": signals, "swings": legs.swings(signals),+ "legs_by": legs.legs_by(signals)}+ except ValueError as exc:+ record["silhouette"] = {"status": "unread", "reason": str(exc)}+ return recorddiff --git a/sprite_gen/video/interpolation_quality.py b/sprite_gen/video/interpolation_quality.pynew file mode 100644index 0000000..cf7fe6e--- /dev/null+++ b/sprite_gen/video/interpolation_quality.py@@ -0,0 +1,15 @@+# SPDX-License-Identifier: Apache-2.0+"""The shared acceptance policy for RIFE frames in repair and cycle alignment.++Measurements live in ``rife.smear``; these are the existing alignment bounds,+also applied before replacing a filmed middle frame during jump repair.+"""++SMEAR_WARN = 0.001+OUTLINE_WARN = 0.05+++def faults(measure: dict[str, float]) -> list[str]:+ """Smear inside the body or outline loss beyond both neighbours."""+ return ([*(["smear"] if measure["dark_excess"] > SMEAR_WARN else []),+ *(["outline"] if measure["outline_loss"] > OUTLINE_WARN else [])])diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex aa2cb2e..94ac82b 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -53,6 +53,7 @@ from sprite_gen.video import legs as legs_modfrom sprite_gen.video import period as period_modfrom sprite_gen.video import repair as repair_modfrom sprite_gen.video import rife as rife_mod+from sprite_gen.video import evidence as evidence_modfrom sprite_gen.video.frames import drop_specksANALYSIS_SIZE = 96 # thumbnail edge for the distance matrix@@ -732,6 +733,8 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,strip.alpha_composite(im, (k * w, 0))meta = {"frames": len(cells),+ "sample_indices": idx,+ "source_rect": [left, top, right, bottom] if not feet else None,"w": w,"h": h,# how the cycle was cut, and whether a runtime should repeat it: a one-shot@@ -877,7 +880,7 @@ def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate |record["applied"] = bool(record["replaced"])if made_by:record["interpolator"] = {"kind": "rife-ncnn-vulkan", **made_by[0]}- elif record["replaced"]:+ elif record["attempts"]:record["interpolator"] = {"kind": "injected"}return frames, record@@ -1107,6 +1110,8 @@ def run_loop(target = (report_path or (out_dir / f"{name}.loop.report.json")).expanduser().resolve()report_base = {"kind": "sprite-gen-video-loop-report", "frames_dir": str(frames_dir),+ "source": evidence_mod.source_identity(files, fps),+ "producer": evidence_mod.engine_identity(),"out_dir": str(out_dir), "state": state, "fps": fps, "frames_total": n,"window": [lo, hi], "profile": prof.why, "cycle_mode": cycle_mode,"seam_max": seam_max,@@ -1263,6 +1268,8 @@ def run_loop(specks += dframes.append(im)+ if prof.gait:+ report_base["gait"] = evidence_mod.gait_observation(frames, cycle)cycle_seconds = L / fpswrap_dx = 0if anchor == "body":@@ -1353,6 +1360,8 @@ def run_loop(strip, strip_meta = build_strip(frames, 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 else None,standing_frame=standing_frame)+ strip_meta["source_cut"] = {"source": report_base["source"], "start": i, "length": L,+ "samples": [i + k for k in strip_meta["sample_indices"]]}# The scaled-back frames are read for the last time above; the cycle cells keep them.shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)if state:@@ -1484,7 +1493,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--body-height", type=int, help="scale so the STANDING height (the subject in the clip's first frame, i.e. the base still's pose) is this many px — the same value across states gives the same character size; --strip-height stays the cap")parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="motion-auto: automatic stable regions, local repeat selection and XY ramp (walk/run); motion: fixed cut with explicit regions; body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")parser.add_argument("--anchor-region", type=motion_anchor.parse_region, action="append", help="motion anchor only: repeat twice with head then torso x0,y0,x1,y1 in the first selected frame; requires --cycle fixed and at least 6 frames")- parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): in a walk or run loop, a frame that follows a jump (a step 1.4x the median, whole body or the hair behind it) is replaced by RIFE's frame between its neighbours, at most 3 and never two side by side, recorded in the report (docs/loop-repair.md); where no RIFE is installed a loop that needs a frame is cut as filmed with a warning (`sprite-gen rife install` adds RIFE); on: the same repair, but no RIFE fails the loop; off: cut as filmed")+ parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): propose RIFE's frame between the neighbours of a jump (a step 1.4x the median, whole body or the hair behind it); adopt only without smear/outline faults, at most 3 calls and never two adopted frames side by side (docs/loop-repair.md). Rejected proposals keep the original. Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")parser.add_argument("--jolt-max", type=float, default=None, help=f"walk/run: fail the repaired loop when its jolt index (how far each step strays from its neighbours' mean, over the median step) exceeds this. Default: no gate — the index is reported and a value over {repair_mod.JOLT_REFERENCE} is a warning line")parser.add_argument("--head-step-max", type=float, default=None, help=f"walk/run: fail the repaired loop when the head's largest sideways move in one frame exceeds this %% of the body height. Default: no gate — reported, and over {repair_mod.HEAD_STEP_REFERENCE} is a warning line")parser.add_argument("--facing", choices=FACINGS, default="right", help="which way the body faces in the frames (default right): the hair the jump search watches is behind it")diff --git a/sprite_gen/video/repair.py b/sprite_gen/video/repair.pyindex 433bca5..e249ce3 100644--- a/sprite_gen/video/repair.py+++ b/sprite_gen/video/repair.py@@ -20,11 +20,12 @@ from typing import Anyfrom PIL import Imagefrom sprite_gen._deps import np-from sprite_gen.video.rife import Interpolate+from sprite_gen.video.rife import Interpolate, smear+from sprite_gen.video.interpolation_quality import faults# A step this many times the loop's median step (whole body, or the hair behind it) is a jump.JUMP_RATIO = 1.4-# Frames replaced at most per loop. A loop that needs more is jolting everywhere, not jumping+# Interpolation calls at most per loop, including rejected proposals. A loop that needs more is jolting everywhere, not jumping# once, and a few made frames do not fix it (the jolt index, section 3, says so instead).MAX_REPAIRS = 3# The hair behind a right-facing body, below the head, as fractions of the union box: where a@@ -78,8 +79,10 @@ def repair_jumps(frames: list[Image.Image], interpolate: Interpolate | None, *,ratio: float = JUMP_RATIO, max_frames: int = MAX_REPAIRS) -> tuple[list[Image.Image], dict[str, Any]]:"""Replace the frame that breaks each jump with RIFE's frame between its neighbours, worst jump first.- At most `max_frames`, and never next to a frame already made: two made frames side by side- are made from each other and melt the legs. `interpolate` may be None while no jump is+ At most `max_frames` calls, and never next to a frame already made: two made frames side by side+ are made from each other and melt the legs. A proposal with a shared interpolation-quality+ fault keeps the original middle frame. Blocked and rejected targets do not end the search+ for independent targets. `interpolate` may be None while no jump isfound; it is asked for only when a frame is to be made (a ValueError says so otherwise).Scores are re-read after each replacement, on the union box of the original loop."""out = list(frames)@@ -89,37 +92,62 @@ def repair_jumps(frames: list[Image.Image], interpolate: Interpolate | None, *,record: dict[str, Any] = {"ratio": ratio, "max_frames": max_frames, "facing": facing, "hair_box": list(hair_box(facing)),"score_max_before": round(float(first["score"].max()), 4), "replaced": [], "rounds": [],+ "blocked": [], "attempts": 0,}if n < 4:record.update(stopped="loop shorter than 4 frames", score_max_after=record["score_max_before"])return out, recordreplaced: list[int] = []- stopped = f"{max_frames} frames replaced"+ attempted: set[int] = set()+ blocked: set[int] = set()+ stopped = f"{max_frames} interpolation calls used"scores = firstfor _ in range(max_frames):- k = int(np.argmax(scores["score"]))- score = float(scores["score"][k])- if score < ratio:- stopped = f"no step at or above {ratio}x the median"+ selected = None+ for k0 in np.argsort(-scores["score"], kind="stable"):+ k = int(k0)+ score = float(scores["score"][k])+ if score < ratio:+ break+ # Two jumps around a stray frame point back to that frame; a single cut points+ # to the frame after the step. This is the existing target rule, worst first.+ before, after = float(scores["score"][(k - 1) % n]), float(scores["score"][(k + 1) % n])+ j = k if before >= ratio and before > after else (k + 1) % n+ if j in replaced or (j - 1) % n in replaced or (j + 1) % n in replaced:+ if j not in blocked:+ record["blocked"].append({"target": j, "reason": "already-made-or-adjacent"})+ blocked.add(j)+ continue+ if j in attempted:+ continue+ selected = (k, j, score)break- # A jump is a step; the frame to remake is the one that broke it. A cut (the ponytail- # lands somewhere new and stays) breaks only step k, and the frame after it is remade- # half way. A single stray frame breaks the step into it and the step out of it: when- # the step before k is also a jump and larger than the step after k+1, frame k is the- # stray one, and remaking the frame after it would leave it standing.- before, after = float(scores["score"][(k - 1) % n]), float(scores["score"][(k + 1) % n])- j = k if before >= ratio and before > after else (k + 1) % n- if j in replaced or (j - 1) % n in replaced or (j + 1) % n in replaced:- stopped = f"the worst jump (frame {j}) sits next to a frame already made"+ if selected is None:+ stopped = (f"no step at or above {ratio}x the median" if float(scores["score"].max()) < ratio+ else "no independent unattempted target; remaining targets rejected or next to a frame already made")break+ k, j, score = selectedif interpolate is None:raise ValueError(f"frame {j} follows a jump ({score:.2f}x the median step) and no interpolator is available")- out[j] = interpolate(out[(j - 1) % n], out[(j + 1) % n], 0.5)- replaced.append(j)- record["rounds"].append({"step": [k, (k + 1) % n], "score": round(score, 4), "whole": round(float(scores["whole"][k]), 4),- "hair": round(float(scores["hair"][k]), 4), "replaced": j})- scores = jump_scores(out, facing=facing, box=box)+ a, b = out[(j - 1) % n], out[(j + 1) % n]+ made = interpolate(a, b, 0.5)+ if made.mode != "RGBA" or made.size != out[j].size:+ raise ValueError("repair interpolator must return an RGBA frame of the original size")+ attempted.add(j)+ measure = smear(made, a, b)+ wrong = faults(measure)+ if not made.getchannel("A").getbbox():+ wrong.append("empty")+ record["rounds"].append({"step": [k, (k + 1) % n], "target": j, "score": round(score, 4),+ "whole": round(float(scores["whole"][k]), 4), "hair": round(float(scores["hair"][k]), 4),+ "original": smear(out[j], a, b), "proposal": measure, "faults": wrong,+ "outcome": "rejected" if wrong else "accepted", **({"replaced": j} if not wrong else {})})+ if not wrong:+ out[j] = made+ replaced.append(j)+ scores = jump_scores(out, facing=facing, box=box)record["replaced"] = replaced+ record["attempts"] = len(attempted)record["stopped"] = stoppedrecord["score_max_after"] = round(float(scores["score"].max()), 4)return out, recorddiff --git a/tests/video/test_loop_compare.py b/tests/video/test_loop_compare.pynew file mode 100644index 0000000..3af3870--- /dev/null+++ b/tests/video/test_loop_compare.py@@ -0,0 +1,176 @@+# SPDX-License-Identifier: Apache-2.0+"""Final pixels and comparable source times own the comparison, never old report scores."""++import hashlib+import json++import pytest+from PIL import Image, ImageDraw++from sprite_gen.cli import main+from sprite_gen.video import compare, evidence+++def _frames():+ frames = []+ for k in range(12):+ im = Image.new("RGBA", (48, 64))+ d = ImageDraw.Draw(im)+ y = [0, 1, 2, 1, 0, -1][k % 6]+ d.rectangle((14, 8 + y, 34, 48 + y), fill=(220, 170, 120), outline=(20, 20, 20), width=2)+ # Two alternating feet and a twice-per-cycle bob remain in every comparison.+ d.rectangle((12 + k % 6, 49, 20 + k % 6, 59), fill=(30, 30, 30))+ d.rectangle((26 - k % 6, 49, 34 - k % 6, 59), fill=(30, 30, 30))+ frames.append(im)+ return frames+++def _lose_outline(frame):+ im = frame.copy()+ pixels = im.load()+ for y in range(5, 49):+ for x in range(im.width):+ if pixels[x, y] == (20, 20, 20, 255):+ pixels[x, y] = (220, 170, 120, 255)+ return im+++def _artifact(tmp_path, name, frames=None):+ frames = frames or _frames()+ folder = tmp_path / name+ folder.mkdir()+ n, w, h = len(frames), *frames[0].size+ strip = Image.new("RGBA", (n * w, h))+ for k, f in enumerate(frames):+ strip.paste(f, (k * w, 0))+ files = {k: folder / fn for k, fn in (("strip", "strip.png"), ("meta", "strip.json"), ("report", "loop.json"))}+ strip.save(files["strip"])+ src = {"kind": "keyed-frame-sequence", "sha256": "a" * 64, "frames": 36, "fps": 24.0}+ m = {"frames": n, "w": w, "h": h, "delay_ms": 41.67, "cycle_seconds": .5, "cycle_frames": n, "loop": True,+ "scale": 1.0, "source_rect": [0, 0, w, h], "foot_anchor": "none",+ "source_cut": {"source": src, "start": 4, "length": n, "samples": list(range(4, 4 + n))}}+ files["meta"].write_text(json.dumps(m) + "\n")+ files["report"].write_text(json.dumps({"kind": "sprite-gen-video-loop-report", "status": "passed", "source": src,+ "fps": 24.0, "frames_total": 36, "cycle": {"start": 4, "length": n},+ "strip": m, "resampled_seam_ratio": .1, "jolt": {"passed": True}}))+ return files+++def _edit(path, mutate):+ doc = json.loads(path.read_text())+ mutate(doc)+ path.write_text(json.dumps(doc))+++def _compare(a, b):+ return compare.compare(compare.Loop.read(**a), compare.Loop.read(**b))+++def test_identical_final_pixels_are_not_improvement_and_digests_are_exact_bytes(tmp_path):+ a, b = _artifact(tmp_path, "a"), _artifact(tmp_path, "b")+ b["meta"].write_text(b["meta"].read_text() + "\n\n")+ _edit(b["report"], lambda d: d.update(resampled_seam_ratio=.00001))+ r = _compare(a, b)+ assert r["verdict"] == "non_regressing" and r["reasons"] == ["identical-pixels-and-timing"]+ for side, paths in (("baseline", a), ("candidate", b)):+ for key, path in paths.items():+ assert r[side]["artifacts"][key]["sha256"] == hashlib.sha256(path.read_bytes()).hexdigest()+ assert r["baseline"]["artifacts"]["meta"] != r["candidate"]["artifacts"]["meta"]+++def test_actual_outline_improvement_preserves_bob_and_inverse_is_regression(tmp_path):+ bad = _frames()+ bad[5] = _lose_outline(bad[5])+ a, b = _artifact(tmp_path, "bad", bad), _artifact(tmp_path, "good")+ r = _compare(a, b)+ assert r["verdict"] == "improved"+ assert r["axes"]["outline_loss"]["status"] == "improved"+ assert r["axes"]["silhouette_motion"]["status"] == "non_regressing"+ assert r["axes"]["body_motion"]["baseline"] == r["axes"]["body_motion"]["candidate"]+ assert _compare(b, a)["verdict"] == "regressed"+++def test_follow_after_a_good_report_is_measured_from_final_pixels(tmp_path):+ good = _artifact(tmp_path, "good")+ final = _frames()+ final[5] = _lose_outline(final[5])+ bad = _artifact(tmp_path, "bad-final", final)+ _edit(bad["meta"], lambda d: d.update(follow={"gain": 1}))+ assert _compare(good, bad)["verdict"] == "regressed"+ assert _compare(good, bad)["candidate"]["follow"] is True++[email protected]("change,reason", [+ (lambda d: d.pop("source_cut"), "source-provenance-missing"),+ (lambda d: d.pop("delay_ms"), "timing-missing"),+ (lambda d: d.update(delay_ms=80), "timing-inconsistent"),+ (lambda d: d.update(cycle_align={"shift": 0}), "aligned-source-phase-unverified"),+ (lambda d: d.pop("source_rect"), "spatial-basis-unverified"),+])+def test_missing_or_inconsistent_evidence_is_unknown(tmp_path, change, reason):+ a, b = _artifact(tmp_path, "a"), _artifact(tmp_path, "b")+ _edit(b["meta"], change)+ r = _compare(a, b)+ assert r["verdict"] == "unknown" and any(reason in s for s in r["reasons"])+++def test_different_cut_with_favourable_report_ratio_cannot_win(tmp_path):+ a, b = _artifact(tmp_path, "a"), _artifact(tmp_path, "b")+ def cut(d):+ d["source_cut"].update(start=6, samples=list(range(6, 18)))+ _edit(b["meta"], cut)+ _edit(b["report"], lambda d: d.update(cycle={"start": 6, "length": 12}, resampled_seam_ratio=0))+ r = _compare(a, b)+ assert r["verdict"] == "unknown"+ assert "different-source-samples-phase-unverified" in r["reasons"]+ assert r["axes"]["seam"]["comparable"] is False+++def test_a_flattened_pose_is_never_certified_as_improved(tmp_path):+ a = _artifact(tmp_path, "a")+ b = _artifact(tmp_path, "frozen", [_frames()[0]] * 12)+ assert _compare(a, b)["verdict"] in ("unknown", "regressed")+++def test_flattening_colour_motion_with_the_same_alpha_cannot_win_on_seam(tmp_path):+ frames = _frames()+ # Draw a changing shirt colour inside identical coverage, including at the seam.+ coloured = []+ for k, frame in enumerate(frames):+ im = frame.copy()+ ImageDraw.Draw(im).rectangle((19, 25, 29, 35), fill=(120 + k * 5, 160, 190, 255))+ coloured.append(im)+ a = _artifact(tmp_path, "colour-motion", coloured)+ b = _artifact(tmp_path, "flattened-colour", frames)+ r = _compare(a, b)+ assert r["axes"]["silhouette_motion"]["status"] == "non_regressing"+ assert r["verdict"] in ("unknown", "regressed")+++def test_cli_writes_unknown_successfully_and_refuses_corrupt_input_or_overwrite(tmp_path, capsys):+ a, b = _artifact(tmp_path, "a"), _artifact(tmp_path, "b")+ _edit(b["report"], lambda d: d.pop("source"))+ args = ["video-loop-compare"]+ for side, paths in (("baseline", a), ("candidate", b)):+ for key, path in paths.items():+ args.extend([f"--{side}-{key}", str(path)])+ output = tmp_path / "comparison.json"+ assert main(args + ["--report", str(output)]) == 0+ r = json.loads(output.read_text())+ assert r["kind"] == compare.KIND and r["verdict"] == "unknown"+ assert json.loads(capsys.readouterr().out) == r+ with pytest.raises(SystemExit, match="cannot overwrite"):+ main(args + ["--report", str(a["meta"])])+ _edit(b["meta"], lambda d: d.update(w=1))+ with pytest.raises(SystemExit, match="size agrees"):+ main(args + ["--report", str(output)])+ b["meta"].write_text("{")+ with pytest.raises(SystemExit, match="video-loop-compare"):+ main(args + ["--report", str(output)])+++def test_gait_evidence_is_observation_for_fixed_and_automatic(tmp_path):+ for kind in ("fixed", "periodic"):+ r = evidence.gait_observation(_frames(), {"start": 0, "length": 12, "kind": kind})+ assert r["status"] == "unverified" and r["reason"] == "own-foot-contacts-not-identified"+ assert "signals" in r["silhouette"]diff --git a/tests/video/test_loop_repair.py b/tests/video/test_loop_repair.pyindex 1e3d6d2..28b7c3f 100644--- a/tests/video/test_loop_repair.py+++ b/tests/video/test_loop_repair.py@@ -18,7 +18,7 @@ from pathlib import Pathimport numpy as npimport pytest-from PIL import Image+from PIL import Image, ImageDrawfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import repair@@ -90,7 +90,7 @@ def test_a_smooth_loop_is_left_alone_and_needs_no_interpolator():def test_at_most_three_and_never_next_to_a_made_frame():filmed, truth = _loop({3: 14, 9: 13, 15: 12, 20: 11})out, record = repair.repair_jumps(filmed, TrueMiddle(filmed, truth))- assert len(record["replaced"]) == 3 and record["stopped"] == "3 frames replaced"+ assert len(record["replaced"]) == 3 and record["stopped"] == "3 interpolation calls used"assert record["replaced"][0] == 3 and set(record["replaced"]) < {3, 9, 15, 20} # worst first, only stray framesfilmed, truth = _loop({8: 14, 9: 14}) # two jump frames side by side@@ -109,6 +109,51 @@ def test_the_hair_watched_is_behind_the_body_whichever_way_it_faces():assert repair.hair_box("left") == (0.55, 0.30, 1.0, 0.80)+def test_blocked_worst_target_does_not_hide_an_independent_jump():+ filmed, truth = _loop({8: 14, 9: 14, 18: 10})+ fake = TrueMiddle(filmed, truth)+ out, record = repair.repair_jumps(filmed, fake)+ assert 18 in record["replaced"] and out[18] is truth[18]+ assert record["blocked"] and len(fake.calls) <= repair.MAX_REPAIRS+ assert all((k + 1) % N not in record["replaced"] for k in record["replaced"])+++def test_bad_outline_proposals_preserve_originals_and_consume_the_call_budget():+ filmed, truth = _loop({3: 14, 9: 13, 15: 12, 20: 11})+ for frame in filmed + truth:+ d = ImageDraw.Draw(frame)+ d.rectangle((50, 30, 69, 99), outline=(10, 10, 10, 255), width=2)+ d.rectangle((48, 10, 71, 29), outline=(10, 10, 10, 255), width=2)+ before = [f.tobytes() for f in filmed]+ fake = TrueMiddle(filmed, truth)++ def melted(a, b, t):+ pixels = np.asarray(fake(a, b, t)).copy()+ dark = (pixels[..., :3].max(axis=2) < 70) & (pixels[..., 3] > 0)+ pixels[dark, :3] = (200, 180, 150)+ return Image.fromarray(pixels, "RGBA")++ out, record = repair.repair_jumps(filmed, melted)+ assert record["replaced"] == []+ assert record["attempts"] == len(fake.calls) == repair.MAX_REPAIRS+ assert len({r["target"] for r in record["rounds"]}) == repair.MAX_REPAIRS+ assert all(r["outcome"] == "rejected" and "outline" in r["faults"] for r in record["rounds"])+ assert [f.tobytes() for f in out] == before == [f.tobytes() for f in filmed]+++def test_circular_adjacency_and_zero_call_budget():+ filmed, truth = _loop({0: 16, N - 1: 15, 12: 10})+ fake = TrueMiddle(filmed, truth)+ _, record = repair.repair_jumps(filmed, fake)+ made = record["replaced"]+ assert 12 in made and not (0 in made and N - 1 in made)+ assert all((k + 1) % N not in made for k in made)+ no_calls = TrueMiddle(filmed, truth)+ out, record = repair.repair_jumps(filmed, no_calls, max_frames=0)+ assert not no_calls.calls and record["attempts"] == 0+ assert all(a is b for a, b in zip(out, filmed))++def _keyed(tmp_path: Path, frames: list[Image.Image]) -> Path:d = tmp_path / "keyed"d.mkdir()diff --git a/tests/video/test_rife.py b/tests/video/test_rife.pyindex dadb857..a7c7f0b 100644--- a/tests/video/test_rife.py+++ b/tests/video/test_rife.py@@ -231,3 +231,20 @@ def test_real_rife_melts_legs_crossing_too_far_and_alignment_takes_the_nearer_frassert facts["made_at"] == [1, 3] and all(m["faults"] == ["outline"] and m["method"] == "rife" for m in facts["smear"])out, facts = align.resample(list(near), 4, interpolate)assert facts["made_at"] == [1, 3] and facts["nearest_at"] == [] and all(not m["faults"] for m in facts["smear"])++[email protected](not _real_rife_available(), reason="rife-ncnn-vulkan not installed (SPRITE_GEN_RIFE / PATH / sprite-gen rife install)")+def test_real_rife_repair_rejects_outline_loss_and_keeps_the_original_middle(monkeypatch):+ from sprite_gen.video import repair++ frames = [_walker(20, -20), _walker(8, -8), _walker(-5, 5), _walker(10, -10)]+ before = [f.tobytes() for f in frames]+ # Isolate adoption from candidate detection: this target spans the wide crossing+ # above, where the actual external RIFE loses an outline the original middle has.+ scores = np.array([3., 2., 1., 1.])+ monkeypatch.setattr(repair, "jump_scores", lambda *a, **kw: {k: scores for k in ("whole", "hair", "score")})+ interpolate = rife.Rife()+ out, facts = repair.repair_jumps(frames, interpolate)+ assert interpolate.made == facts["attempts"] == 1+ assert facts["replaced"] == [] and facts["rounds"][0]["faults"] == ["outline"]+ assert [f.tobytes() for f in out] == before == [f.tobytes() for f in frames]