Skip to content

Official Codebase of 3DCodeVerse

Python
6.1 KB
Raw Blame
"""Enums and small value types used everywhere."""

from __future__ import annotations

from collections.abc import Collection
from enum import StrEnum
from typing import Annotated, Literal

from pydantic import BaseModel, ConfigDict, Field

Vec3 = Annotated[tuple[float, float, float], Field(description="x, y, z")]


class Track(StrEnum):
    """What kind of 3D thing we are producing."""

    STATIC_OBJECT = "static_object"
    ARTICULATED_OBJECT = "articulated_object"
    SCENE = "scene"
    GRAPHICS = "graphics"  # shader / OpenGL effects (2D/2.5D/3D procedural graphics)


class Language(StrEnum):
    """Raw authoring language of the deliverable (no SDKs on top)."""

    BLENDER = "blender"  # pure bpy script → GLB/STL
    CADQUERY = "cadquery"  # pure cadquery script → STEP/STL/GLB
    THREEJS = "threejs"  # procedural three.js (ESM) → GLB via GLTFExporter
    URDF_BLENDER = "urdf_blender"  # bpy link meshes + hand-written URDF
    SCENE_THREEJS = "scene_threejs"  # multi-file three.js scene (+GLSL, +GLB assets)
    SCENE_BLENDER = "scene_blender"  # multi-file bpy scene (+GLB heroes), rendered by Blender
    GLSL_SHADER = "glsl_shader"  # Shadertoy-style fragment shader (GLSL 330/ES 3.0), rendered by moderngl
    OPENGL_PYTHON = "opengl_python"  # raw OpenGL via moderngl + GLSL (multi-pass, geometry, FBOs)


#: languages allowed per track
TRACK_LANGUAGES: dict[Track, tuple[Language, ...]] = {
    Track.STATIC_OBJECT: (Language.BLENDER, Language.CADQUERY, Language.THREEJS),
    Track.ARTICULATED_OBJECT: (Language.URDF_BLENDER,),
    Track.SCENE: (Language.SCENE_THREEJS, Language.SCENE_BLENDER),
    Track.GRAPHICS: (Language.GLSL_SHADER, Language.OPENGL_PYTHON),
}

#: the rubric (``judges/rubrics/<name>.yaml``) each track is judged on
TRACK_RUBRIC: dict[Track, str] = {
    Track.STATIC_OBJECT: "static_object",
    Track.ARTICULATED_OBJECT: "articulated",
    Track.SCENE: "scene",
    Track.GRAPHICS: "shader",
}

#: entry file inside the workspace per language — the file a build starts from.
ENTRY_FILE: dict[Language, str] = {
    Language.BLENDER: "src/model.py",
    Language.CADQUERY: "src/model.py",
    Language.URDF_BLENDER: "src/model.py",
    Language.THREEJS: "src/object.js",
    Language.SCENE_THREEJS: "src/scene.js",
    Language.SCENE_BLENDER: "src/scene.py",
    Language.GLSL_SHADER: "src/shader.frag",
    Language.OPENGL_PYTHON: "src/program.py",
}


# ------------------------------------------------------------------ joint coupling
#: |multiplier| below this is a coupling that transmits no motion (shared by plan, lint and loader).
MIMIC_MIN_MULTIPLIER = 1e-9


class MimicSpec(BaseModel):
    """One joint as the coupling rules see it, in whatever vocabulary the caller has.

    ``key`` is the caller's canonical name (the plan folds case and underscores, URDF
    does not); ``name`` is what its messages should print.
    """

    model_config = ConfigDict(frozen=True)

    key: str
    name: str
    movable: bool
    target: str | None = None  # key of the joint this one follows; None = drives itself
    multiplier: float = 1.0
    offset: float = 0.0
    lower: float | None = None  # this joint's own limits, when it declares them
    upper: float | None = None


class MimicIssue(BaseModel):
    """One broken coupling rule.  ``kind`` is what is wrong, ``joint``/``target`` are
    names as written, ``detail`` carries the joint a cycle closes through."""

    model_config = ConfigDict(frozen=True)

    joint: str
    kind: Literal["immobile", "zero_multiplier", "self", "unknown_target", "immobile_target",
                  "cycle", "out_of_range"]
    target: str
    detail: str = ""


def mimic_issues(specs: Collection[MimicSpec]) -> list[MimicIssue]:
    """Every rule a ``<mimic>`` has to satisfy, checked once over the whole joint set.

    Callers render the issues in their own vocabulary and decide what is fatal
    (``out_of_range`` is only a warning: the coupling still poses the mechanism).
    """
    order = list(specs)
    by_key = {s.key: s for s in order}
    out: list[MimicIssue] = []
    for s in order:
        if s.target is None:
            continue
        if not s.movable:
            out.append(MimicIssue(joint=s.name, kind="immobile", target=s.target))
        if abs(s.multiplier) < MIMIC_MIN_MULTIPLIER:
            out.append(MimicIssue(joint=s.name, kind="zero_multiplier", target=s.target))
        if s.target == s.key:
            out.append(MimicIssue(joint=s.name, kind="self", target=s.name))
            continue
        src = by_key.get(s.target)
        if src is None:
            out.append(MimicIssue(joint=s.name, kind="unknown_target", target=s.target))
            continue
        if not src.movable:
            out.append(MimicIssue(joint=s.name, kind="immobile_target", target=src.name))
        reach = _driven_range(s, src)
        if reach is not None:
            out.append(MimicIssue(joint=s.name, kind="out_of_range", target=src.name,
                                  detail=f"[{reach[0]:.4g}, {reach[1]:.4g}]"))
        seen, cur = {s.key}, src
        while cur.target is not None:
            if cur.key in seen:
                out.append(MimicIssue(joint=s.name, kind="cycle", target=s.target, detail=cur.name))
                break
            seen.add(cur.key)
            nxt = by_key.get(cur.target)
            if nxt is None:
                break  # that joint reports its own unknown target on its own turn
            cur = nxt
    return out


def _driven_range(follower: MimicSpec, driver: MimicSpec) -> tuple[float, float] | None:
    """Where the coupling takes ``follower`` if outside its own limits, else ``None``.

    Slack is 1 % of the follower's span, absorbing multiplier/limit rounding.
    """
    if None in (follower.lower, follower.upper, driver.lower, driver.upper):
        return None
    ends = (follower.multiplier * driver.lower + follower.offset,
            follower.multiplier * driver.upper + follower.offset)
    lo, hi = min(ends), max(ends)
    slack = max(1e-6, 0.01 * (follower.upper - follower.lower))
    if lo < follower.lower - slack or hi > follower.upper + slack:
        return lo, hi
    return None