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): reject faulty jump repairs and compare delivered samples

Soohong Kim582e2cf4f853
diff --git a/SKILL.md b/SKILL.md
index 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.md
index 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.md
new file mode 100644
index 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.md
index 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 that
were 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 filmed
with 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.py
index 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.py
index 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_loop
from sprite_gen.video import clip_prompt as video_prompt
from sprite_gen.video import align as video_align
from sprite_gen.video import follow as video_follow
+from sprite_gen.video import compare as video_compare
from sprite_gen.video import rife_install
from sprite_gen.effects import recolor, shadow
from sprite_gen.scene import render, inspect_scene
@@ -354,6 +355,11 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
video_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.py
index 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_mod
from sprite_gen.video import loop as loop_mod
from sprite_gen.video import period as period_mod
from sprite_gen.video import rife as rife_mod
+from sprite_gen.video.interpolation_quality import SMEAR_WARN, OUTLINE_WARN, faults
SNAP = 0.03 # a sample time within this of a source frame takes that frame
SOURCE_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.py
new file mode 100644
index 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 0
diff --git a/sprite_gen/video/evidence.py b/sprite_gen/video/evidence.py
new file mode 100644
index 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 record
diff --git a/sprite_gen/video/interpolation_quality.py b/sprite_gen/video/interpolation_quality.py
new file mode 100644
index 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.py
index 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_mod
from sprite_gen.video import period as period_mod
from sprite_gen.video import repair as repair_mod
from sprite_gen.video import rife as rife_mod
+from sprite_gen.video import evidence as evidence_mod
from sprite_gen.video.frames import drop_specks
ANALYSIS_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 += d
frames.append(im)
+ if prof.gait:
+ report_base["gait"] = evidence_mod.gait_observation(frames, cycle)
cycle_seconds = L / fps
wrap_dx = 0
if 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.py
index 433bca5..e249ce3 100644
--- a/sprite_gen/video/repair.py
+++ b/sprite_gen/video/repair.py
@@ -20,11 +20,12 @@ from typing import Any
from PIL import Image
from 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 is
found; 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, record
replaced: list[int] = []
- stopped = f"{max_frames} frames replaced"
+ attempted: set[int] = set()
+ blocked: set[int] = set()
+ stopped = f"{max_frames} interpolation calls used"
scores = first
for _ 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 = selected
if 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"] = stopped
record["score_max_after"] = round(float(scores["score"].max()), 4)
return out, record
diff --git a/tests/video/test_loop_compare.py b/tests/video/test_loop_compare.py
new file mode 100644
index 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.py
index 1e3d6d2..28b7c3f 100644
--- a/tests/video/test_loop_repair.py
+++ b/tests/video/test_loop_repair.py
@@ -18,7 +18,7 @@ from pathlib import Path
import numpy as np
import pytest
-from PIL import Image
+from PIL import Image, ImageDraw
from sprite_gen.video import loop as loop_mod
from 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 frames
filmed, 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.py
index 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_fr
assert 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]