Skip to content

SUPRA-Tex: 3D Generation with Super-Aligned Texture

9.9 KB
Raw Blame
"""Back-camera v4 math, adapted to the current SupraTex camera handoff.

The geometry is never rescaled here. For scalar SupraTex cameras the physical
distance is ``distance * mesh_scale``, exactly as in the texture pipeline.
Explicit OpenCV matrices already describe physical coordinates and are not
scaled again. The resulting v4 camera always has an effective mesh scale of 1.
"""

from __future__ import annotations

import math
from typing import Any, Mapping

import numpy as np

PROTOCOL_ID = "supratex.back_view_camera.v4"
PACK_SCHEMA = "supratex.back_normal_pack.v3"
ADAPTER_ID = "supratex.back_view_camera.v4"
CANONICAL_CONTRACT = "canonical_distance_fov_v1"
FULL_CV_CONTRACT = "full_cv_fixed_negative_z_from_translation_dual_v1"
RESOLUTION = 1024
NEAR, FAR = 0.05, 20.0
YAW_RANGE_DEG, PITCH_RANGE_DEG = 15.0, 10.0
SCALE_RANGE = (0.8, 1.6)
COARSE_RES, FINE_RES = 256, 512
DRIFT_PENALTY_PER_RAD, SCALE_PENALTY_PER_LOG = 0.05, 0.01
BORDER_PX, INFEASIBLE = 2, 10.0
EXTRINSIC_ATOL = 1e-5
# This repository makes the protocol's qualitative "close to 1" check explicit.
NORMAL_SIGN_MIN = 0.9


def _finite(value: Any, name: str) -> float:
    try:
        result = float(value)
    except (TypeError, ValueError) as error:
        raise ValueError(f"{name} must be finite") from error
    if not math.isfinite(result):
        raise ValueError(f"{name} must be finite")
    return result


def intrinsics_from_fov(fov: float) -> np.ndarray:
    """Normalized square-image intrinsics, without a GPU dependency."""
    fov = _finite(fov, "camera_angle_x")
    if not 0.0 < fov < math.pi:
        raise ValueError("camera_angle_x must be between 0 and pi")
    focal = 0.5 / math.tan(fov / 2.0)
    return np.array([[focal, 0.0, 0.5], [0.0, focal, 0.5], [0.0, 0.0, 1.0]])


def front_extrinsic(tx: float, ty: float, distance: float) -> np.ndarray:
    """Delivery-v4 OpenCV w2c: q = [x-tx, -(y-ty), distance-z]."""
    return np.array([[1.0, 0.0, 0.0, -tx], [0.0, -1.0, 0.0, ty],
                     [0.0, 0.0, -1.0, distance], [0.0, 0.0, 0.0, 1.0]])


def _matrix(value: Any, shape: tuple[int, int], name: str) -> np.ndarray:
    try:
        matrix = np.asarray(value, dtype=np.float64)
    except (TypeError, ValueError) as error:
        raise ValueError(f"{name} must be a finite {shape} matrix") from error
    if matrix.shape != shape or not np.isfinite(matrix).all():
        raise ValueError(f"{name} must be a finite {shape} matrix")
    return matrix


def parse_front_camera(camera: Mapping[str, Any]) -> dict[str, Any]:
    """Validate the production camera and return its physical v4 equivalent.

    A translation-only off-axis input is rejected: SupraTex's existing scalar
    camera path does not consume translation_dual. Explicit matrices are needed
    for such a camera so back rendering and front texturing use the same rays.
    """
    source_distance = _finite(camera.get("distance"), "distance")
    mesh_scale = _finite(camera.get("mesh_scale", 1.0), "mesh_scale")
    if source_distance <= 0.0 or mesh_scale <= 0.0:
        raise ValueError("distance and mesh_scale must be positive")
    fov = _finite(camera.get("camera_angle_x"), "camera_angle_x")
    intrinsic = intrinsics_from_fov(fov)
    explicit = "extrinsic" in camera
    has_intrinsic = "projection_intrinsic" in camera or "intrinsic" in camera
    if explicit != has_intrinsic:
        raise ValueError("explicit cameras require both extrinsic and intrinsic matrices")
    translation = camera.get("translation_dual")
    if translation is not None:
        translation = np.asarray(translation, dtype=np.float64)
        if translation.shape != (3,) or not np.isfinite(translation).all():
            raise ValueError("translation_dual must contain three finite values")
    if explicit:
        extrinsic = _matrix(camera["extrinsic"], (4, 4), "extrinsic")
        tx, ty, distance = -extrinsic[0, 3], extrinsic[1, 3], extrinsic[2, 3]
        if distance <= 0.0 or not math.isclose(distance, source_distance, abs_tol=1e-6, rel_tol=0.0):
            raise ValueError("explicit Delivery-v4 camera depth must equal distance")
        expected = front_extrinsic(tx, ty, distance)
        if not np.allclose(extrinsic, expected, atol=EXTRINSIC_ATOL, rtol=0.0):
            raise ValueError("extrinsic is not a Delivery-v4 fixed-negative-Z camera")
        if translation is not None and not np.allclose(translation, [tx, ty, distance], atol=1e-6, rtol=0.0):
            raise ValueError("translation_dual differs from the production extrinsic")
        source_intrinsic = _matrix(camera.get("projection_intrinsic", camera.get("intrinsic")),
                                   (3, 3), "intrinsic")
        if not np.allclose(source_intrinsic, intrinsic, atol=EXTRINSIC_ATOL, rtol=0.0):
            raise ValueError("explicit intrinsic does not match camera_angle_x")
        intrinsic = source_intrinsic
        distance_policy = "explicit_matrices_are_physical"
    else:
        if translation is not None and not np.allclose(translation, [0.0, 0.0, source_distance], atol=1e-6, rtol=0.0):
            raise ValueError("off-axis translation requires production extrinsic and intrinsic matrices")
        tx, ty, distance = 0.0, 0.0, source_distance * mesh_scale
        if not math.isfinite(distance):
            raise ValueError("effective camera distance must be finite")
        extrinsic = front_extrinsic(tx, ty, distance)
        distance_policy = "distance_times_mesh_scale"
    off_axis = abs(tx) > 1e-12 or abs(ty) > 1e-12
    contract = FULL_CV_CONTRACT if off_axis else CANONICAL_CONTRACT
    declared = camera.get("camera_contract")
    if declared is not None and declared not in {CANONICAL_CONTRACT, FULL_CV_CONTRACT}:
        raise ValueError(f"unsupported camera_contract: {declared!r}")
    if off_axis and declared == CANONICAL_CONTRACT:
        raise ValueError("off-axis camera cannot declare a canonical camera_contract")
    return {
        "distance": float(distance), "fov": fov, "mesh_scale": 1.0,
        "source_distance": source_distance, "source_mesh_scale": mesh_scale,
        "distance_policy": distance_policy, "explicit": explicit,
        "camera_contract": contract, "off_axis": bool(off_axis),
        "translation_dual": [float(tx), float(ty), float(distance)],
        "front_eye": [float(tx), float(ty), float(distance)],
        "front_look_at": [float(tx), float(ty), 0.0],
        "back_look_at": [float(-tx), float(ty), 0.0],
        "exact_back_eye": [float(-tx), float(ty), float(-distance)],
        "extrinsic": extrinsic, "intrinsic": intrinsic,
    }


def back_eye(distance: float, dyaw_deg: float, pitch_deg: float, scale: float,
             look_at=(0.0, 0.0, 0.0)) -> np.ndarray:
    """Position around the 180-degree world-Y back view, with an offset target."""
    yaw, pitch = math.pi + math.radians(dyaw_deg), math.radians(pitch_deg)
    offset = distance * scale * np.array([math.sin(yaw) * math.cos(pitch),
                                         math.sin(pitch), math.cos(yaw) * math.cos(pitch)])
    return np.asarray(look_at, dtype=np.float64) + offset


def look_at_extrinsic(eye, target) -> np.ndarray:
    """OpenCV look-at matrix for validation and CPU camera tests."""
    eye, target = np.asarray(eye, dtype=np.float64), np.asarray(target, dtype=np.float64)
    forward = target - eye
    norm = np.linalg.norm(forward)
    if not math.isfinite(float(norm)) or norm < 1e-12:
        raise ValueError("camera eye and look-at must be distinct finite positions")
    forward /= norm
    right = np.cross(forward, [0.0, 1.0, 0.0])
    if np.linalg.norm(right) < 1e-12:
        raise ValueError("camera direction is parallel to its up vector")
    right /= np.linalg.norm(right)
    down = np.cross(forward, right)
    rotation = np.stack([right, down, forward])
    result = np.eye(4)
    result[:3, :3], result[:3, 3] = rotation, -rotation @ eye
    return result


def touches_border(mask: np.ndarray, px: int = BORDER_PX) -> np.ndarray:
    """Whether any foreground occupies the fixed-width frame border."""
    mask = np.asarray(mask, dtype=bool)
    return (mask[..., :px, :].any(axis=(-2, -1)) | mask[..., -px:, :].any(axis=(-2, -1))
            | mask[..., :, :px].any(axis=(-2, -1)) | mask[..., :, -px:].any(axis=(-2, -1)))


def occupancy_score(front_occupancy, back_occupancy, dyaw_deg, pitch_deg, scale,
                    back_touches_border, front_touches_border):
    """The v4 objective compares occupied area, never silhouette overlap."""
    drift = np.deg2rad(np.abs(dyaw_deg) + np.abs(pitch_deg))
    return (1.0 - np.abs(np.asarray(back_occupancy) - front_occupancy)
            - DRIFT_PENALTY_PER_RAD * drift - SCALE_PENALTY_PER_LOG * np.abs(np.log(scale))
            - INFEASIBLE * np.asarray(back_touches_border) * np.logical_not(front_touches_border))


def normal_sign_check(normals: np.ndarray, mask: np.ndarray) -> dict[str, float | None]:
    """Measure the normal sign on each scanline's left/right/top boundary."""
    mask, normals = np.asarray(mask) > 0.5, np.asarray(normals)
    if normals.shape != (3, *mask.shape):
        raise ValueError("normal and mask shapes do not agree")
    rows, cols = np.where(mask.any(1))[0], np.where(mask.any(0))[0]
    left = [normals[0, row, np.argmax(mask[row])] for row in rows]
    right = [normals[0, row, mask.shape[1] - 1 - np.argmax(mask[row, ::-1])] for row in rows]
    top = [normals[1, np.argmax(mask[:, col]), col] for col in cols]
    return {"left_edge_nx_neg": float(np.mean(np.asarray(left) < 0)) if left else None,
            "right_edge_nx_pos": float(np.mean(np.asarray(right) > 0)) if right else None,
            "top_edge_ny_pos": float(np.mean(np.asarray(top) > 0)) if top else None}


def validate_normal_signs(checks: Mapping[str, Any]) -> None:
    for side in ("front", "back"):
        for field in ("left_edge_nx_neg", "right_edge_nx_pos", "top_edge_ny_pos"):
            value = _finite(checks.get(side, {}).get(field), f"{side}.{field}")
            if not NORMAL_SIGN_MIN <= value <= 1.0:
                raise ValueError(f"{side}.{field}={value:.4f} is below normal-sign gate {NORMAL_SIGN_MIN}")