Official Codebase of 3DCodeVerse
Python
"""Deterministic inter-frame motion for scene renders.
``motion_rows`` diffs the first and last rendered frame of each camera into ``MotionRow``s;
``motion_summary_text`` renders the table the judge and the ``scene_frames`` gate read.
"""
from __future__ import annotations
import logging
from collections.abc import Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import numpy as np
from PIL import Image
from codeverse3d.proc import read_json_or_none
#: per-channel 0..255 difference above which a pixel counts as changed
PIXEL_DELTA = 8
#: share of changed pixels at (or above) which a camera counts as showing motion
MOVING_FRAC = 0.004
#: a change this strong on even a few pixels (a lit window, a spark) is motion too
STRONG_DELTA = 60
STRONG_FRAC = 0.0008
log = logging.getLogger(__name__)
@dataclass(frozen=True)
class MotionRow:
"""Measured change between the first and last frame of ONE camera."""
name: str
kind: str
t0: float
t1: float
changed_frac: float
strong_frac: float
max_delta: int
mean_delta: float
@property
def moving(self) -> bool:
return self.changed_frac >= MOVING_FRAC or self.strong_frac >= STRONG_FRAC
@property
def authored(self) -> bool:
return self.kind == "authored"
def as_line(self) -> str:
return (f"{self.name} [{self.kind}]: {self.changed_frac:.1%} of pixels changed between "
f"t={self.t0:g}s and t={self.t1:g}s (max Δ {self.max_delta}/255) — "
+ ("MOVING" if self.moving else "STATIC"))
def as_dict(self) -> dict[str, Any]:
return {
"name": self.name, "kind": self.kind, "t0": self.t0, "t1": self.t1,
"changed_frac": round(self.changed_frac, 5), "strong_frac": round(self.strong_frac, 5),
"max_delta": self.max_delta, "mean_delta": round(self.mean_delta, 3), "moving": self.moving,
}
def _load(path: Path) -> np.ndarray | None:
try:
with Image.open(path) as im:
return np.asarray(im.convert("RGB"), dtype=np.int16)
except (OSError, ValueError):
return None
def _pair_rows(entries: Sequence[dict[str, Any]], out_dir: Path) -> list[MotionRow]:
by_name: dict[str, list[dict[str, Any]]] = {}
for v in entries:
if not isinstance(v, dict):
continue
by_name.setdefault(str(v.get("name", "?")), []).append(v)
rows: list[MotionRow] = []
for name, views in by_name.items():
timed = sorted(views, key=lambda v: float(v.get("time_s") or 0.0))
if len(timed) < 2:
continue
first, last = timed[0], timed[-1]
t0, t1 = float(first.get("time_s") or 0.0), float(last.get("time_s") or 0.0)
if t1 <= t0:
continue
a, b = _load(out_dir / str(first.get("path", ""))), _load(out_dir / str(last.get("path", "")))
if a is None or b is None or a.shape != b.shape:
continue
diff = np.abs(a - b).max(axis=2)
rows.append(MotionRow(
name=name, kind=str(first.get("kind") or "authored"), t0=t0, t1=t1,
changed_frac=float((diff > PIXEL_DELTA).mean()),
strong_frac=float((diff > STRONG_DELTA).mean()),
max_delta=int(diff.max()), mean_delta=float(diff.mean()),
))
order = {str(v.get("name")): i for i, v in enumerate(entries)}
rows.sort(key=lambda r: (r.kind != "authored", order.get(r.name, 999)))
return rows
def motion_rows(metrics: dict[str, Any], out_dir: Path | str) -> list[MotionRow]:
"""One row per camera rendered at ≥ 2 times (authored first); unreadable views are skipped (not measured, not static)."""
entries = metrics.get("views") or []
if not isinstance(entries, list):
return []
return _pair_rows(entries, Path(out_dir))
def scene_moves(rows: Sequence[MotionRow]) -> bool | None:
"""Did anything move on an AUTHORED camera? ``None`` = not measured."""
authored = [r for r in rows if r.authored]
if not authored:
return None
return any(r.moving for r in authored)
def motion_summary_text(rows: Sequence[MotionRow], *, max_rows: int = 10) -> str:
"""The table the judge and refine prompts read (empty string = nothing measured)."""
if not rows:
return ""
moves = scene_moves(rows)
shown = [r for r in rows if r.authored] or list(rows)
head = ("MEASURED MOTION (harness pixel diff of the authored cameras between the first and last animation "
"time; deterministic, so treat it as a FACT — the two times sit in different montage images and are "
"not reliably comparable by eye):")
lines = [head, *[f"- {r.as_line()}" for r in shown[:max_rows]]]
if moves is True:
movers = [r.name for r in shown if r.moving]
lines.append(f"→ the scene IS animating ({', '.join(movers[:5])} change between the samples): the defect "
"`nothing_moves` is FALSE, and an acceptance item that asks only for visible movement between "
"t0 and t1 is verified by these numbers.")
elif moves is False:
lines.append("→ no authored camera changed by more than a rounding error: the scene is frozen, "
"`nothing_moves` is TRUE and no animation acceptance item is verified.")
return "\n".join(lines)
def motion_from_dir(out_dir: Path | str) -> list[MotionRow]:
"""Measure ``<out_dir>/metrics.json``."""
d = Path(out_dir)
metrics = read_json_or_none(d / "metrics.json")
return [] if metrics is None else motion_rows(metrics, d)
def motion_text_for(out_dir: Path | str) -> str:
"""``motion_summary_text`` for one render directory; ``""`` on any problem (never fails a round)."""
try:
return motion_summary_text(motion_from_dir(out_dir))
except Exception as e: # noqa: BLE001 — judge context must never break a round
log.warning("motion text failed for %s: %s", out_dir, e)
return ""