Skip to content

SolarRenderer: Few-Step Generative Reference Rendering

Python
11.9 KB
Raw Blame
"""Comparison-video visualization and publication contract."""

from __future__ import annotations

import hashlib
import json
import os
import re
import shutil
import subprocess
import tempfile
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal

from solarwm.errors import BackendContractError


@dataclass(frozen=True)
class ComparisonValidationRecord:
    slot: int
    compare_path: Path
    manifest_path: Path


def _sample_slug(value: object, *, max_length: int = 160) -> str:
    text = str(value).strip()
    slug = re.sub(r"[^A-Za-z0-9_.-]+", "_", text).strip("._")
    if not slug:
        slug = hashlib.blake2s(text.encode()).hexdigest()[:16]
    if len(slug) <= max_length:
        return slug
    digest = hashlib.blake2s(text.encode()).hexdigest()[:16]
    return f"{slug[: max_length - len(digest) - 2]}__{digest}"


def encode_compare_mp4(
    reference: Any,
    generated: Any,
    *,
    fps: float,
    layout: Literal["btchw", "bcthw"],
    value_range: Literal["zero_one", "minus_one_one"],
) -> bytes:
    """Encode the left-GT/right-GEN H.264 visualization."""

    import torch

    def canonical(value: Any, name: str) -> Any:
        if value.ndim != 5 or int(value.shape[0]) != 1:
            raise BackendContractError(
                f"validation compare {name} has unexpected shape {tuple(value.shape)}"
            )
        result = value if layout == "btchw" else value.permute(0, 2, 1, 3, 4)
        if int(result.shape[2]) != 3:
            raise BackendContractError(
                f"validation compare {name} is not RGB: {tuple(result.shape)}"
            )
        # Backends keep source pixels on CPU while decoded generations normally
        # remain on the local CUDA device. The comparison is encoded by
        # ffmpeg on the host, so normalize both sides on CPU before joining.
        result = result.detach().to(device="cpu", dtype=torch.float32)
        if value_range == "minus_one_one":
            result = result.mul(0.5).add(0.5)
        return torch.nan_to_num(result, nan=0.0, posinf=1.0, neginf=0.0).clamp_(0, 1)

    gt = canonical(reference, "GT")
    gen = canonical(generated, "GEN")
    frames = min(int(gt.shape[1]), int(gen.shape[1]))
    if frames < 1 or tuple(gt.shape[2:]) != tuple(gen.shape[2:]):
        raise BackendContractError(
            f"validation compare GT/GEN shapes differ: gt={tuple(gt.shape)} gen={tuple(gen.shape)}"
        )
    joined = torch.cat((gt[:, :frames], gen[:, :frames]), dim=-1)
    array = joined[0].permute(0, 2, 3, 1).mul(255.0).to(torch.uint8).cpu().numpy()
    height, width = int(array.shape[1]), int(array.shape[2])
    executable = shutil.which("ffmpeg")
    if executable is None:
        raise BackendContractError("validation compare requires ffmpeg")
    with tempfile.TemporaryDirectory(prefix="solarwm-validation-compare-") as directory:
        target = Path(directory) / "compare.mp4"
        command = [
            executable,
            "-hide_banner",
            "-loglevel",
            "error",
            "-f",
            "rawvideo",
            "-pix_fmt",
            "rgb24",
            "-s:v",
            f"{width}x{height}",
            "-r",
            f"{float(fps):g}",
            "-i",
            "pipe:0",
            "-an",
            "-c:v",
            "libx264",
            "-pix_fmt",
            "yuv420p",
            "-movflags",
            "+faststart",
            "-y",
            str(target),
        ]
        result = subprocess.run(command, input=array.tobytes(), capture_output=True, check=False)
        if result.returncode or not target.is_file():
            detail = result.stderr.decode("utf-8", errors="replace")[-2000:]
            raise BackendContractError(f"ffmpeg failed to encode validation compare: {detail}")
        return target.read_bytes()


def _comparison_manifest(
    manifest: Mapping[str, Any],
    *,
    step: int,
    pass_name: str,
    compare_path: str,
    cases: int,
    dp_world_size: int,
    sp_size: int,
    logical_world_size_per_round: int,
) -> dict[str, Any]:
    case = manifest["case"]
    metadata = case.get("metadata", {})
    generation_pass = metadata.get("generation_pass", {})
    slot = int(case["slot"])
    dp_rank = slot % int(dp_world_size)
    round_index = slot // int(logical_world_size_per_round)
    shape = manifest.get("shape", ())
    output_pixel_frames = int(shape[1]) if len(shape) >= 2 else None
    if metadata.get("output_pixel_frames") is not None:
        output_pixel_frames = int(metadata["output_pixel_frames"])
    rollout_latent_frames = generation_pass.get(
        "output_rollout_latent_frames",
        generation_pass.get("rollout_latent_frames", metadata.get("rollout_latent_frames")),
    )
    comparison = {
        "rank": dp_rank * int(sp_size),
        "global_rank": dp_rank * int(sp_size),
        "dp_rank": dp_rank,
        "sp_rank": 0,
        "sp_size": int(sp_size),
        "logical_validation_rank": slot,
        "logical_rank_within_round": slot % int(logical_world_size_per_round),
        "logical_validation_world_size": int(cases),
        "logical_world_size_per_round": int(logical_world_size_per_round),
        "validation_round_index": round_index,
        "validation_num_rounds": int(cases) // int(logical_world_size_per_round),
        "source_pixel_frames": metadata.get("source_pixel_frames"),
        "source_num_frames": metadata.get("source_num_frames"),
        "validation_noise_seed": int(case["noise_seed"]),
        "step": int(step),
        "video_id": metadata.get("key", case["sample_id"]),
        "dataset": metadata.get("dataset"),
        "scene": metadata.get("scene"),
        "start_frame": int(case["start_frame"]),
        "T_pix": output_pixel_frames,
        "T_lat": rollout_latent_frames,
        "train_T_lat": metadata.get("train_latent_frames"),
        "rollout_T_lat": rollout_latent_frames,
        "collective_rollout_T_lat": generation_pass.get("rollout_latent_frames"),
        "variable_rollout_by_source": bool(
            generation_pass.get("variable_rollout_by_source", False)
        ),
        "variable_rollout_start_adjusted": bool(
            metadata.get("variable_rollout_start_adjusted", False)
        ),
        "generation_mode": generation_pass.get("mode", metadata.get("generation_mode")),
        "active_pass_name": pass_name,
        "inference_mode": generation_pass.get("solver", metadata.get("inference_mode")),
        "camera_translation_transform": metadata.get("camera_translation_transform"),
        "sample_solver": generation_pass.get("solver", metadata.get("sample_solver")),
        "num_inference_steps": generation_pass.get(
            "num_inference_steps", metadata.get("num_inference_steps")
        ),
        "weights_source": generation_pass.get("weights", metadata.get("weights_source")),
        "requested_video_id": metadata.get("requested_key"),
        "requested_start_frame": metadata.get("requested_start_frame"),
        "validation_input_status": metadata.get("validation_input_status", "requested"),
        "artifact_valid": metadata.get("artifact_valid", True) is not False,
        "compare_mp4": compare_path,
        "video_stats": manifest.get("metrics", {}),
        "generated_latents_finite": manifest.get("metrics", {}).get("finite_fraction") == 1.0,
        "error": metadata.get("recoverable_input_error"),
        "solarwm_manifest": manifest,
    }
    denoising_step_list = manifest.get("provenance", {}).get("denoising_step_list")
    if denoising_step_list is not None:
        comparison["denoising_step_list"] = [int(value) for value in denoising_step_list]
    return comparison


def publish_comparison_partition(
    source: Path,
    destination: Path,
    *,
    step: int,
    pass_name: str,
    cases: int,
    dp_world_size: int,
    sp_size: int,
    run_root: Path,
    logical_world_size_per_round: int | None = None,
) -> tuple[ComparisonValidationRecord, ...]:
    """Merge one node/rank partition into the common comparison directory."""

    cases_per_round = (
        int(cases) if logical_world_size_per_round is None else int(logical_world_size_per_round)
    )
    if int(cases) < 1 or cases_per_round < 1 or int(cases) % cases_per_round:
        raise BackendContractError("comparison validation cases must form complete logical rounds")

    compare_dir = destination / "compare"
    manifest_dir = destination / "manifests"
    compare_dir.mkdir(parents=True, exist_ok=True)
    manifest_dir.mkdir(parents=True, exist_ok=True)
    records = []
    for sample_dir in sorted(source.glob("slot-*")):
        manifest = json.loads((sample_dir / "manifest.json").read_text(encoding="utf-8"))
        case = manifest["case"]
        metadata = case.get("metadata", {})
        slot = int(case["slot"])
        key = _sample_slug(metadata.get("key") or case["sample_id"])
        start = int(case["start_frame"])
        dp_rank = slot % int(dp_world_size)
        round_index = slot // cases_per_round
        filename = (
            f"rank{slot:03d}_round{round_index:02d}_dp{dp_rank:03d}_{key}_start{start:06d}.mp4"
        )
        source_compare = sample_dir / "compare.mp4"
        if not source_compare.is_file():
            raise BackendContractError(f"validation slot {slot} lacks compare.mp4")
        compare_path = compare_dir / filename
        try:
            os.link(source_compare, compare_path)
        except FileExistsError as exc:
            raise BackendContractError(
                f"comparison validation compare already exists: {compare_path}"
            ) from exc
        relative = compare_path.relative_to(run_root).as_posix()
        comparison_manifest = _comparison_manifest(
            manifest,
            step=step,
            pass_name=pass_name,
            compare_path=relative,
            cases=cases,
            dp_world_size=dp_world_size,
            sp_size=sp_size,
            logical_world_size_per_round=cases_per_round,
        )
        manifest_path = manifest_dir / f"rank_{slot:03d}.json"
        payload = (json.dumps(comparison_manifest, ensure_ascii=False, indent=2) + "\n").encode()
        descriptor = os.open(
            manifest_path,
            os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_WRONLY,
            0o444,
        )
        try:
            with os.fdopen(descriptor, "wb", closefd=True) as handle:
                handle.write(payload)
                handle.flush()
                os.fsync(handle.fileno())
        except Exception:
            compare_path.unlink(missing_ok=True)
            manifest_path.unlink(missing_ok=True)
            raise
        records.append(ComparisonValidationRecord(slot, compare_path, manifest_path))
    if not records:
        raise BackendContractError(f"comparison validation source has no slots: {source}")
    return tuple(records)


def publish_comparison_complete(
    destination: Path,
    *,
    step: int,
    pass_name: str,
    local_slots: int,
    global_slots: int,
) -> None:
    payload = (
        json.dumps(
            {
                "schema": "solarwm.validation-comparison.v1",
                "step": int(step),
                "pass": pass_name,
                "local_slots": int(local_slots),
                "global_slots": int(global_slots),
                "compare_layout": "ground_truth_left_generated_right",
            },
            allow_nan=False,
            ensure_ascii=False,
            separators=(",", ":"),
            sort_keys=True,
        )
        + "\n"
    ).encode()
    target = destination / "COMPLETE.json"
    if target.exists():
        return
    temporary = target.with_name(
        f".{target.name}.{hashlib.blake2s(payload).hexdigest()[:16]}.partial"
    )
    temporary.write_bytes(payload)
    try:
        os.link(temporary, target)
    except FileExistsError:
        pass
    finally:
        temporary.unlink(missing_ok=True)


__all__ = [
    "ComparisonValidationRecord",
    "encode_compare_mp4",
    "publish_comparison_complete",
    "publish_comparison_partition",
]