Official Codebase of 3DCodeVerse
Python
"""Per-frame and temporal metrics of a rendered frame sequence, and the ``gl_frames`` gate built on them.
``data["kind"]`` of a finding is one of nan · black · blown · static · flicker · duplicate · low_detail.
"""
from __future__ import annotations
from collections.abc import Sequence
from pathlib import Path
import numpy as np
from PIL import Image
from pydantic import BaseModel, Field
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity
GATE = "gl_frames"
BLACK_LUM = 0.03
BLOWN_LUM = 0.98
STATIC_DIFF = 0.002
FLICKER_DIFF = 0.35
DUPLICATE_DIFF = 1e-4
LOW_DETAIL_EDGE = 0.002
ANALYSIS_MAX_W = 512
class FrameStat(BaseModel):
time: float
path: str
mean_lum: float
std_lum: float
pct_black: float
pct_blown: float
colourfulness: float
edge_density: float
nan: int = 0
inf: int = 0
class SequenceStats(BaseModel):
frames: list[FrameStat] = Field(default_factory=list)
diffs: list[float] = Field(default_factory=list, description="mean |Δ| between consecutive frames (0..1)")
mean_diff: float = 0.0
max_diff: float = 0.0
n_duplicates: int = 0
static: bool = False
flicker: bool = False
any_nan: bool = False
mean_lum: float = 0.0
mean_colourfulness: float = 0.0
mean_edge_density: float = 0.0
all_black: bool = False
all_blown: bool = False
def summary_lines(self) -> list[str]:
out = [f"frames={len(self.frames)} mean_lum={self.mean_lum:.3f} colourfulness={self.mean_colourfulness:.3f} "
f"edge_density={self.mean_edge_density:.4f} motion(mean|Δ|)={self.mean_diff:.4f} max|Δ|={self.max_diff:.4f} "
f"duplicates={self.n_duplicates}" + (" NaN/Inf!" if self.any_nan else "")]
for f in self.frames:
out.append(f" t={f.time:g}s lum={f.mean_lum:.3f}±{f.std_lum:.3f} black={f.pct_black:.0%} blown={f.pct_blown:.0%} "
f"colour={f.colourfulness:.3f} edges={f.edge_density:.4f}" + (f" nan={f.nan} inf={f.inf}" if f.nan or f.inf else ""))
return out
# --------------------------------------------------------------------------- per frame
def load_rgb(path: str | Path, max_w: int = ANALYSIS_MAX_W) -> np.ndarray:
im = Image.open(path).convert("RGB")
if im.width > max_w:
im = im.resize((max_w, max(1, round(im.height * max_w / im.width))), Image.BILINEAR)
return np.asarray(im, dtype=np.float32) / 255.0
def luminance(rgb: np.ndarray) -> np.ndarray:
return rgb[..., 0] * 0.2126 + rgb[..., 1] * 0.7152 + rgb[..., 2] * 0.0722
def colourfulness(rgb: np.ndarray) -> float:
"""Hasler-Süsstrunk colourfulness on 0..1 floats (≈0 grey, ~0.3+ vivid)."""
r, g, b = rgb[..., 0], rgb[..., 1], rgb[..., 2]
rg = r - g
yb = 0.5 * (r + g) - b
std = float(np.hypot(rg.std(), yb.std()))
mean = float(np.hypot(rg.mean(), yb.mean()))
return std + 0.3 * mean
def edge_density(lum: np.ndarray, threshold: float = 0.02) -> float:
gy, gx = np.gradient(lum)
mag = np.hypot(gx, gy)
return float((mag > threshold).mean())
def frame_stat(path: str | Path, *, time: float, nan: int = 0, inf: int = 0, rgb: np.ndarray | None = None) -> FrameStat:
rgb = load_rgb(path) if rgb is None else rgb
lum = luminance(rgb)
return FrameStat(time=time, path=str(path), mean_lum=float(lum.mean()), std_lum=float(lum.std()),
pct_black=float((lum < BLACK_LUM).mean()), pct_blown=float((lum > BLOWN_LUM).mean()),
colourfulness=colourfulness(rgb), edge_density=edge_density(lum), nan=nan, inf=inf)
# --------------------------------------------------------------------------- sequence
def sequence_stats(frames: Sequence[tuple[float, str | Path]], *, nan_counts: Sequence[tuple[int, int]] | None = None) -> SequenceStats:
"""``frames`` = [(time, png_path)] sorted by time; ``nan_counts`` aligned [(nan, inf)]."""
ordered = sorted(enumerate(frames), key=lambda it: it[1][0])
stats: list[FrameStat] = []
arrays: list[np.ndarray] = []
for orig_i, (t, p) in ordered:
rgb = load_rgb(p)
nan, inf = (nan_counts[orig_i] if nan_counts and orig_i < len(nan_counts) else (0, 0))
stats.append(frame_stat(p, time=t, nan=nan, inf=inf, rgb=rgb))
arrays.append(rgb)
diffs: list[float] = []
for a, b in zip(arrays, arrays[1:], strict=False):
if a.shape != b.shape:
diffs.append(1.0)
continue
diffs.append(float(np.abs(a - b).mean()))
seq = SequenceStats(frames=stats, diffs=diffs)
if stats:
seq.mean_lum = float(np.mean([f.mean_lum for f in stats]))
seq.mean_colourfulness = float(np.mean([f.colourfulness for f in stats]))
seq.mean_edge_density = float(np.mean([f.edge_density for f in stats]))
seq.all_black = all(f.pct_black > 0.97 for f in stats)
seq.all_blown = all(f.pct_blown > 0.97 for f in stats)
seq.any_nan = any(f.nan or f.inf for f in stats)
if diffs:
seq.mean_diff = float(np.mean(diffs))
seq.max_diff = float(np.max(diffs))
seq.n_duplicates = sum(1 for d in diffs if d < DUPLICATE_DIFF)
# MAX, not mean: 'static' is a scoring cap, so no sampled pair may have changed.
seq.static = seq.max_diff < STATIC_DIFF
seq.flicker = seq.max_diff > FLICKER_DIFF and len(diffs) >= 2
return seq
# --------------------------------------------------------------------------- gate
def frame_gate(seq: SequenceStats, *, motion_expected: bool = True, gate: str = GATE) -> GateReport:
"""Findings the judge, refiner and caps consume."""
f: list[GateFinding] = []
def add(sev: Severity, kind: str, msg: str, hint: str, target: str = "overall", **data: object) -> None:
f.append(GateFinding(gate=gate, severity=sev, target=target, message=msg, fix_hint=hint, data={"kind": kind, **data}))
if not seq.frames:
add(Severity.ERROR, "no_frames", "no frames were rendered", "the program must produce at least one frame")
return GateReport.of(gate, f)
if seq.any_nan:
bad = [fr for fr in seq.frames if fr.nan or fr.inf]
add(Severity.ERROR, "nan", f"NaN/Inf pixels in {len(bad)} frame(s) (first at t={bad[0].time:g}s: nan={bad[0].nan} inf={bad[0].inf})",
"guard divisions (x / max(d, 1e-4)), sqrt/pow/log of negatives (max(x, 0.0)), normalize(vec) of zero vectors, "
"and acos/asin arguments (clamp(x, -1.0, 1.0)); never let a colour be NaN",
n_frames=len(bad))
if seq.all_black:
add(Severity.ERROR, "black", f"frames are essentially black (mean luminance {seq.mean_lum:.3f})",
"something must be visible: check the final fragColor assignment, the raymarch hit test, camera direction and "
"that colours are not multiplied to zero (the gate flags frames where 97 % of pixels are under 0.03)")
elif seq.all_blown:
add(Severity.ERROR, "blown", f"frames are blown out white (mean luminance {seq.mean_lum:.3f})",
"tone-map the result into 0..1 and keep accumulated glow sums bounded (the gate flags frames where 97 % of pixels are over 0.98)")
if seq.static and motion_expected:
add(Severity.WARN, "static", f"frames do not change over time (largest |Δ| between any two sampled frames {seq.max_diff:.4f}); the shader looks static",
"use u_time for motion: move what is in the scene, rotate, animate noise offsets, move lights — the judge compares frames at t=0..6s")
elif seq.n_duplicates and motion_expected:
add(Severity.INFO, "duplicate", f"{seq.n_duplicates} consecutive frame pair(s) are identical",
"make sure every sampled time differs visibly (continuous motion rather than rare jumps)")
if seq.flicker:
add(Severity.WARN, "flicker", f"very large frame-to-frame change (max |Δ| {seq.max_diff:.3f}); flicker or hard cuts",
"avoid discontinuous functions of u_time (fract/mod jumps, random per-frame seeds); motion should be continuous")
if seq.mean_edge_density < LOW_DETAIL_EDGE and not seq.all_black and not seq.all_blown:
add(Severity.WARN, "low_detail", f"very low visual detail (edge density {seq.mean_edge_density:.4f}); the image is a near-flat gradient",
"the frame is a near-flat gradient: give the subject the structure the brief describes (edges, shapes, texture at the scales it has)")
return GateReport.of(gate, f)