Skip to content

Official Codebase of 3DCodeVerse

Python
14.2 KB
Raw Blame
"""Render a built ``scene_blender`` workspace: Blender makes the pictures, the JS host measures.

``render_blender_scene`` runs four steps with one output format: (1) ``fit_orbit.mjs`` fits the orbit
rig to the build's census; (2) ``render_bpy_scene.py`` renders the authored cameras x times plus the
first ``MAX_JUDGE_OVERVIEWS`` overviews in Blender (GPU runs hold a machine-wide flock slot, CPU
fallback); (3) ``render_scene.mjs --external-frames`` does the geometry checks and frame stats on the
census GLB; (4) ``render_scene.render_set_from_metrics`` builds the RenderSet.  ``metrics.json`` adds
``language`` and ``blender`` keys.
"""
from __future__ import annotations

import json
import logging
import time
from collections.abc import Sequence
from pathlib import Path
from typing import Any

from codeverse3d.config import Settings, get_settings
from codeverse3d.contracts.artifacts import RenderSet
from codeverse3d.contracts.plan import BBox, CameraPlan
from codeverse3d.conventions import (
    SCENE_TIMES,
    SCENE_VIEWS,
    ViewPreset,
    from_authoring_frame,
    to_authoring_frame,
)
from codeverse3d.proc import (
    ProcResult,
    Slots,
    SlotsBusy,
    read_json_or_none,
    run_subprocess,
    write_json_atomic,
)
from codeverse3d.spatial._render_common import out_directory, view_specs
from codeverse3d.spatial.render_scene import (
    MAX_JUDGE_OVERVIEWS,
    SceneRenderError,
    plan_bounds,
    render_set_from_metrics,
    run_scene_script,
)
from codeverse3d.workspace import Workspace

log = logging.getLogger(__name__)

DRIVER = Path(__file__).resolve().parent.parent / "languages" / "wrappers" / "render_bpy_scene.py"
#: the language whose authoring frame the .blend is in
FRAME_LANGUAGE = "scene_blender"
LANGUAGE = "scene_blender"
JOB_NAME = "blender_job.json"
RESULT_NAME = "blender_frames.json"
EXTERNAL_NAME = "blender_views.json"
SLOT_DIR = "blender_gpu"
#: keys of a view entry (render_scene.mjs's view schema)
_VIEW_KEYS = ("name", "kind", "path", "time_s", "position", "lookAt", "fov", "render_ms")


def gpu_slots(settings: Settings | None = None) -> Slots:
    """The machine-wide GPU Blender render slots (``<cache_dir>/slots/blender_gpu/NN.lock``)."""
    s = settings or get_settings()
    return Slots(s.render.blender_gpu_slots, s.cache_dir / "slots" / SLOT_DIR)


def _to_blender(v: Sequence[float]) -> list[float]:
    return list(to_authoring_frame(v, FRAME_LANGUAGE))


def _to_glb(v: Sequence[float]) -> list[float]:
    return [round(c, 5) for c in from_authoring_frame(v, FRAME_LANGUAGE)]


# --------------------------------------------------------------------------- pixels
def _run_driver(blend: Path, job: dict[str, Any], out_dir: Path, *, device: str, timeout_s: float,
                settings: Settings) -> tuple[ProcResult, dict[str, Any] | None]:
    from codeverse3d.languages.blender import blender_env

    job = {**job, "device": device}
    job_path = out_dir / JOB_NAME
    result_path = out_dir / RESULT_NAME
    result_path.unlink(missing_ok=True)
    write_json_atomic(job_path, job)
    blender = settings.resolve_blender()
    if not blender:
        raise SceneRenderError("no Blender binary (set C3D_BINARIES__BLENDER or put blender-5.2 on PATH)")
    cmd = [blender, "-b", "--factory-startup", str(blend), "--python", str(DRIVER), "--", str(job_path)]
    proc = run_subprocess(cmd, cwd=out_dir, env=blender_env(), timeout_s=timeout_s)
    result = read_json_or_none(result_path)
    return proc, result if isinstance(result, dict) and proc.returncode == 0 else None


def _failure(proc: ProcResult) -> str:
    from codeverse3d.languages._common import strip_blender_noise

    tail = strip_blender_noise(proc.stderr + "\n" + proc.stdout)[-800:]
    return f"exit {proc.returncode}" + (f": {tail}" if tail else "")


def render_frames(blend: Path, out_dir: Path, job: dict[str, Any], *, timeout_s: float,
                  settings: Settings | None = None) -> dict[str, Any]:
    """Run the Blender driver under the GPU-slot policy; result json + ``fallback`` / ``slot_wait_ms``.

    GPU: take a slot (wait ≤ ``blender_gpu_wait_s``); all busy, or a GPU run that dies → CPU.  A timeout raises without retry."""
    s = settings or get_settings()
    fallback = ""
    wait_ms = 0
    if s.render.blender_device == "cpu":
        device = "CPU"
    else:
        slots = gpu_slots(s)
        t0 = time.monotonic()
        try:
            fd: int | None = slots.take(s.render.blender_gpu_wait_s)
        except SlotsBusy:
            fd = None
            fallback = f"all {slots.n} GPU render slots busy for {s.render.blender_gpu_wait_s:g}s ({slots.root})"
        wait_ms = int((time.monotonic() - t0) * 1000)
        device = "GPU" if fd is not None else "CPU"
        if fd is not None:
            try:
                proc, result = _run_driver(blend, job, out_dir, device="GPU", timeout_s=timeout_s, settings=s)
            finally:
                Slots.give(fd)
            if proc.timed_out:
                raise SceneRenderError(f"blender render timed out after {timeout_s:.0f}s on the GPU")
            if result is not None:
                return {**result, "fallback": result.get("device_fallback") or "", "slot_wait_ms": wait_ms}
            fallback = f"GPU render failed ({_failure(proc)[:300]})"
            device = "CPU"
    if fallback:
        log.warning("scene_blender render on the CPU: %s", fallback)
    proc, result = _run_driver(blend, job, out_dir, device=device, timeout_s=timeout_s, settings=s)
    if proc.timed_out:
        raise SceneRenderError(f"blender render timed out after {timeout_s:.0f}s on the {device}")
    if result is None:
        raise SceneRenderError(f"blender render driver failed: {_failure(proc)}")
    return {**result, "fallback": fallback or result.get("device_fallback") or "", "slot_wait_ms": wait_ms}


# --------------------------------------------------------------------------- orbit
def fit_orbit(census_path: Path, views: Sequence[ViewPreset], *, width: int, height: int,
              bounds: BBox | None, timeout_s: float = 60.0) -> dict[str, Any]:
    """``fit_orbit.mjs`` on a census: ``{framing_bbox, cameras}`` in the GLB frame (``{}`` on failure)."""
    args = ["--census", str(census_path), "--orbit-views", json.dumps(view_specs(views)),
            "--width", str(width), "--height", str(height)]
    if bounds is not None:
        args += ["--bounds", json.dumps({"min": list(bounds.min), "max": list(bounds.max)})]
    try:
        return dict(run_scene_script("fit_orbit.mjs", args, timeout_s=timeout_s).summary)
    except SceneRenderError as e:
        log.warning("orbit fit failed: %s", e)
        return {}


def _pixel_orbit(specs: list[dict[str, Any]]) -> set[str]:
    """The rig views that get Blender pixels: the first ``MAX_JUDGE_OVERVIEWS`` overviews (the judge's tiles)."""
    return set([str(o["name"]) for o in specs if str(o["name"]).startswith("overview")][:MAX_JUDGE_OVERVIEWS])


# --------------------------------------------------------------------------- entry
def render_blender_scene(
    ws: Workspace,
    out_dir: Path,
    *,
    cameras: list[CameraPlan] | None = None,
    orbit: bool = True,
    times: Sequence[float] = SCENE_TIMES,
    width: int = 1024,
    height: int = 576,
    sheet: bool = True,
    orbit_views: Sequence[ViewPreset] = SCENE_VIEWS,
    timeout_s: float | None = None,
    bounds: BBox | None = None,
    blend: Path | None = None,
    census: Path | None = None,
    glb: Path | None = None,
    samples: int | None = None,
) -> RenderSet:
    """Authored cameras (+ the orbit rig) × ``times`` rendered by Blender → a RenderSet (three.js-schema ``metrics.json``).

    ``cameras=None`` uses the cameras the .blend carries; explicit ones (GLB frame) replace them.  A missing .blend gives
    an empty RenderSet with ``console_errors``; a driver that cannot run raises ``SceneRenderError``."""
    s = get_settings()
    out_dir = out_directory(out_dir, clean=("metrics.json", "views.json", RESULT_NAME, EXTERNAL_NAME))
    blend = blend or ws.artifacts / "scene.blend"
    census = census or ws.artifacts / "census.json"
    glb = glb or ws.artifacts / "census.glb"
    times = sorted({float(t) for t in times}) or [0.0]
    tmo = float(timeout_s or s.limits.render_timeout_s)
    t_all = time.monotonic()
    if not blend.is_file():
        return _empty(out_dir, f"no {blend.name}: the build did not save the scene (see build.json)",
                      width=width, height=height, orbit_views=orbit_views)
    # 1. the orbit rig, fitted to the census content (GLB frame)
    fit: dict[str, Any] = {}
    if orbit and orbit_views:
        if census.is_file():
            fit = fit_orbit(census, orbit_views, width=width, height=height, bounds=bounds or plan_bounds(ws))
        else:
            log.warning("no %s: the orbit rig is not rendered", census)
    orbit_specs: list[dict[str, Any]] = list(fit.get("cameras") or [])
    # 2. pixels
    pixel = _pixel_orbit(orbit_specs)
    job_cams = [{"name": c.name, "kind": "authored", "position": _to_blender(c.position), "look_at": _to_blender(c.look_at),
                 "fov": c.fov, "no_fog": False, "times": times} for c in cameras or []]
    job_cams += [{"name": o["name"], "kind": "orbit", "position": _to_blender(o["position"]),
                  "look_at": _to_blender(o["lookAt"]), "fov": o.get("fov") or 50.0, "no_fog": bool(o.get("noFog")),
                  "times": times[:1]} for o in orbit_specs if o["name"] in pixel]
    job = {"out": str(out_dir), "result": str(out_dir / RESULT_NAME), "samples": int(samples or s.render.blender_samples), "frame_time_limit_s": s.render.blender_frame_time_limit_s,
           "width": width, "height": height, "times": times, "authored": cameras is None, "cameras": job_cams}
    frames = render_frames(blend, out_dir, job, timeout_s=tmo, settings=s)
    views = [_glb_view(f) for f in frames.get("frames") or []]
    write_json_atomic(out_dir / EXTERNAL_NAME, views)
    # 3. geometry: authored cameras as Blender saw them + the whole rig
    specs = [{"name": c["name"], "kind": c.get("kind") or "authored", "position": _to_glb(c["position"]),
              "lookAt": _to_glb(c["look_at"]), "fov": c.get("fov")}
             for c in frames.get("cameras") or [] if c.get("kind") == "authored"]
    specs += [{**o, "kind": "orbit"} for o in orbit_specs]
    metrics, geometry_error = _geometry_pass(ws, out_dir, specs, times=times, width=width, height=height,
                                             timeout_s=tmo, glb=glb)
    if not metrics.get("views"):
        metrics["views"] = views
    # 4. merge the Blender facts; one schema downstream
    errors = [f"blender: {e}" for e in frames.get("errors") or []]
    if geometry_error:
        errors.append(geometry_error)
    metrics["console_errors"] = list(metrics.get("console_errors") or []) + [e for e in errors
                                                                             if e not in (metrics.get("console_errors") or [])]
    metrics["ok"] = bool(metrics.get("ok", True)) and not errors and bool(views)
    metrics["language"] = LANGUAGE
    metrics["renderer"] = _renderer_line(frames)
    if fit.get("framing_bbox") is not None:
        metrics["framing_bbox"] = fit["framing_bbox"]
    warnings = list(metrics.get("host_warnings") or [])
    if frames.get("fallback"):
        warnings.append(f"rendered on the CPU: {frames['fallback']}")
    metrics["host_warnings"] = warnings
    metrics["blender"] = {"engine": frames.get("engine"), "device": frames.get("device"), "samples": frames.get("samples")}
    metrics["duration_ms"] = int((time.monotonic() - t_all) * 1000)
    write_json_atomic(out_dir / "metrics.json", metrics)
    write_json_atomic(out_dir / "views.json", metrics["views"])
    for w in warnings:
        log.warning("render_blender_scene: %s", w)
    return render_set_from_metrics(out_dir, metrics, width=width, height=height, orbit_views=orbit_views, sheet=sheet,
                                   duration_ms=metrics["duration_ms"])


def _glb_view(f: dict[str, Any]) -> dict[str, Any]:
    """A Blender frame record → a render_scene.mjs view entry (GLB frame)."""
    v = {"name": f["name"], "kind": f.get("kind") or "authored", "path": f["path"], "time_s": f["time_s"],
         "position": _to_glb(f["position"]), "lookAt": _to_glb(f["look_at"]), "fov": f.get("fov"),
         "render_ms": f.get("render_ms")}
    return {k: v[k] for k in _VIEW_KEYS}


def _renderer_line(frames: dict[str, Any]) -> str:
    bits = [f"Blender {frames.get('blender', '?')}", str(frames.get("engine", "?")), str(frames.get("device", "?"))]
    if frames.get("device_names"):
        bits.append("/".join(frames["device_names"]))
    if frames.get("samples"):
        bits.append(f"{frames['samples']} spp")
    return " · ".join(bits)


def _geometry_pass(ws: Workspace, out_dir: Path, specs: list[dict[str, Any]], *, times: Sequence[float], width: int,
                   height: int, timeout_s: float, glb: Path) -> tuple[dict[str, Any], str]:
    """render_scene.mjs --external-frames → (its metrics payload, an error line or '')."""
    if not specs:
        return {"views": [], "camera_checks": [], "console_errors": []}, ""
    args = ["--ws", str(ws.root), "--out", str(out_dir), "--glb", str(glb),
            "--cameras", json.dumps(specs), "--orbit-views", "none",
            "--times", ",".join(f"{t:g}" for t in times), "--width", str(width), "--height", str(height),
            "--fps-seconds", "0", "--timeout-ms", str(int(timeout_s * 1000)),
            "--no-settle", "--no-post", "--external-frames", str(out_dir / EXTERNAL_NAME)]
    try:
        run_scene_script("render_scene.mjs", args, timeout_s=timeout_s + 30)
    except SceneRenderError as e:
        metrics = read_json_or_none(out_dir / "metrics.json") or {}
        return metrics, f"geometry pass: {str(e).splitlines()[0][:400]}"
    return read_json_or_none(out_dir / "metrics.json") or {}, ""


def _empty(out_dir: Path, error: str, *, width: int, height: int, orbit_views: Sequence[ViewPreset]) -> RenderSet:
    metrics = {"ok": False, "language": LANGUAGE, "renderer": "", "views": [], "camera_checks": [], "fps": None,
               "census": None, "shader_errors": [], "console_errors": [error]}
    write_json_atomic(out_dir / "metrics.json", metrics)
    write_json_atomic(out_dir / "views.json", [])
    return render_set_from_metrics(out_dir, metrics, width=width, height=height, orbit_views=orbit_views)