Slim Gradio Space: infer + demo only

.gitignore

@@ -0,0 +1 @@
+*.pt

README.md

@@ -0,0 +1,27 @@
+---
+title: scatteringNet
+emoji: 🧊
+colorFrom: gray
+colorTo: yellow
+sdk: gradio
+app_file: src/gradio/app.py
+pinned: false
+license: mit
+short_description: "Occupancy fill: label inside points on a 3D mesh."
+---
+
+# scatteringNet — occupancy fill
+
+Public Gradio demo. Upload an OBJ (or pick a sample) and **Run model** to label query points inside the solid.
+
+[Code](https://github.com/PerryGu/scatteringNet)
+
+[Video](https://youtu.be/vU45O0Mu0o4)
+
+These sample meshes were not in the training catalog.
+
+**Weights.** After this slim tree is on the Space, upload:
+
+`models/2026-09-14_07-43-34_prim_extruded_nr45_knn24_n2048_n6/best.pt`
+
+This folder is infer + Gradio only. It is not the training repo.

config.yaml

@@ -0,0 +1,73 @@
+# Experiment settings for the occupancy MLP MVP.
+# `device` is still detected at runtime in src/config.py (CUDA vs CPU).
+
+# --- Model Architecture ---
+hidden: 64        # Number of hidden units (channels) per layer in the OccupancyMLP
+depth: 4          # Number of hidden linear layers in the MLP network
+seed: 1           # Same seed as the previous extrude_nr1 train
+
+# --- Path Configuration ---
+data_dir: "E:/Work_stuff/scatteringNet/data"  # Base root directory where all NPZ dataset files are stored
+
+# --- Training Hyperparameters ---
+epochs: 20        # Same length as the knn24-n2048 G5 clone (compare IoU to that best.pt)
+lr: 0.001         # Initial learning rate
+batch_size: 1024  # Points per optimizer step (GPU mini-batch)
+optimizer: adam   # adam | adamw | sgd
+# BCE inside-class weight. auto = n_outside / n_inside on the train split.
+# Omit or null = unweighted BCE (legacy / 18-09-31 clone). Head is unchanged.
+pos_weight: auto
+
+# --- Split ---
+# Whole meshes: 80% train / 20% val of unique OBJs. All NPZs of one OBJ stay on one side.
+# This split selects best.pt (not a locked holdout). Phase 2 Step 11 adds that.
+val_fraction: 0.20
+
+# --- Geometry ---
+# none = xyz-only OccupancyMLP. surface = envelope (XYZ + face normal) + OccupancyEncoder.
+# Occupancy labels stay in the NPZ. New trains write envelope_dim=6 on best.pt.
+shape_encoder: surface   # none / surface
+n_surface: 2048          # Envelope samples on the joined OBJ (area-weighted face darts)
+knn_k: 24                # Neighbors per query (not envelope count). Same head as knn24-n2048 inspect / G5 clone. Fresh train; do not resume that mix-75 best.pt.
+# knn_local_dim: 64      # z_local width; omit to use latent_dim / hidden
+# latent_dim: 64         # OccupancyEncoder z width; omit to use hidden
+
+# --- Catalog ---
+# npz_catalog wins over npz_glob. Each row is all meshes for that glob unless
+# max_shapes is set (unique OBJs, sampled with seed; still max_files_per_shape NPZs).
+# Varied/organic and combo* are omitted on purpose.
+# Fallback glob is unused while npz_catalog is set.
+# Smooth extruded_* is back (same glob as knn24-n2048 inspect). High-round
+# extrude_* stay s0.08. Primitives and nr1 stay s0.15. nr3 is omitted.
+# max_files_per_shape keeps lattice + one jitter.
+npz_glob: "exports/dataset/*.npz"
+npz_catalog:
+  - glob: "exports/dataset/cone_*.npz"
+  - glob: "exports/dataset/cube_*.npz"
+  - glob: "exports/dataset/cyl_*.npz"
+  - glob: "exports/dataset/gear_*.npz"
+  - glob: "exports/dataset/helix_*.npz"
+  - glob: "exports/dataset/pipe_*.npz"
+  - glob: "exports/dataset/platonic_*.npz"
+  - glob: "exports/dataset/prism_*.npz"
+  - glob: "exports/dataset/sphere_*.npz"
+  - glob: "exports/dataset/torus_*.npz"
+  - glob: "exports/dataset/extruded_*occupancy_s0.08*.npz"
+  - glob: "exports/dataset/extrude_*_nr1_*.npz"
+    max_shapes: 40
+  - glob: "exports/dataset/extrude_*_nr4_*occupancy_s0.08*.npz"
+    max_shapes: 90
+  - glob: "exports/dataset/extrude_*_nr5_*occupancy_s0.08*.npz"
+max_files_per_shape: 2
+
+# --- Run logs ---
+# Suffix for runs/<YYYY-MM-DD_HH-MM-SS>_<name>/. Device is detected at runtime, not stored here.
+run_name: prim_extruded_nr45_knn24_n2048_n6_pw 
+
+# --- Checkpoints ---
+# Scalar used to decide models/<run_id>/best.pt (strict improve). No last.pt.
+# The run snapshot (runs/<id>/config.yaml) records:
+#   total      — planned epoch count (copied from epochs)
+#   checkpoint — epoch index stored in best.pt (runtime; not a project knob)
+# val_iou = keep the epoch with the best inside overlap (not overall accuracy).
+checkpoint_metric: val_iou

docs/inspect_checkpoint.yaml

@@ -0,0 +1,5 @@
+# INSPECT checkpoint alias (single source of truth).
+# Both the Three.js inspect viewer and Gradio default to this run when
+# models/<id>/best.pt exists. Do not call this alias "best".
+# 2026-09-16 area-only and the pos_weight run are documented A/B logs only.
+run_id: "2026-09-14_07-43-34_prim_extruded_nr45_knn24_n2048_n6"

pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scatteringnet"
+version = "0.1.0"
+description = "Occupancy fill demo (Gradio Space)"
+requires-python = ">=3.10"
+dependencies = [
+    "numpy",
+    "pyyaml",
+    "trimesh>=4.0",
+]
+
+[tool.setuptools]
+package-dir = { "scatteringnet" = "src" }
+packages = [
+    "scatteringnet",
+    "scatteringnet.geometry",
+    "scatteringnet.viewer",
+]

requirements.txt

@@ -0,0 +1,4 @@
+numpy
+pyyaml
+trimesh>=4.0
+torch

scatteringnet/__init__.py

@@ -0,0 +1 @@
+"""Occupancy fill: catalog training, encoder, and inspect helper."""

scatteringnet/config.py

@@ -0,0 +1,611 @@
+"""Hybrid config loader for catalog occupancy training.
+
+Static experiment knobs live in ``config.yaml``. ``device`` is resolved
+here from CUDA availability. Training knobs (epochs, lr, batch_size,
+optimizer, catalog, val split) are YAML-owned so ``train_multi_npz``
+does not hardcode them.
+
+This module does not read ``.env`` and does not open NPZ files.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, TypedDict
+
+import torch
+import yaml
+
+# Repo root: src/config.py → parents[1].
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+_DEFAULT_YAML = _REPO_ROOT / "config.yaml"
+
+_REQUIRED_YAML_KEYS = (
+    "hidden",
+    "depth",
+    "seed",
+    "data_dir",
+    "epochs",
+    "lr",
+)
+
+
+class YamlKnobs(TypedDict):
+    """Subset of OccupancyConfig that is stored in YAML (paths as strings)."""
+
+    hidden: int
+    depth: int
+    seed: int
+    data_dir: str
+    epochs: int
+    lr: float
+    val_fraction: float
+    latent_dim: int | None
+    npz_glob: str
+    npz_paths: tuple[str, ...]
+    npz_catalog: tuple[tuple[str, int | None], ...]
+    max_files_per_shape: int | None
+    run_name: str
+    checkpoint_metric: str
+    batch_size: int
+    optimizer: str
+    n_surface: int
+    knn_k: int
+    knn_local_dim: int | None
+    shape_encoder: str
+    # Explicit BCE pos_weight; None when omitted or when auto is set.
+    pos_weight: float | None
+    pos_weight_auto: bool
+
+
+def get_device() -> torch.device:
+    """
+    CUDA when a GPU is visible; otherwise CPU.
+
+    Hugging Face CPU Spaces have no CUDA: infer still runs (slower).
+    ``SCATTERINGNET_DEVICE=cpu`` forces CPU even if a GPU exists.
+    ``SCATTERINGNET_DEVICE=cuda`` uses CUDA only when ``is_available()``;
+    otherwise it falls back to CPU (no crash).
+
+    Training scripts should still warn on a long catalog run on CPU.
+    """
+    forced = os.environ.get("SCATTERINGNET_DEVICE", "").strip().lower()
+    if forced == "cpu":
+        return torch.device("cpu")
+    if forced == "cuda":
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        return torch.device("cpu")
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    return torch.device("cpu")
+
+
+def repo_root() -> Path:
+    """Git / project root (folder that contains ``src/`` and ``config.yaml``)."""
+    return _REPO_ROOT
+
+
+def gpu_name(device: torch.device | None = None) -> str | None:
+    """
+    Human GPU name for the run snapshot (``None`` on CPU).
+
+    Uses ``cfg.device`` when given so a forced-CPU train does not stamp a
+    card that was not used.
+    """
+    dev = device if device is not None else get_device()
+    if dev.type != "cuda" or not torch.cuda.is_available():
+        return None
+    index = 0 if dev.index is None else int(dev.index)
+    if index < 0 or index >= torch.cuda.device_count():
+        return None
+    name = str(torch.cuda.get_device_name(index)).strip()
+    return name or None
+
+
+def _as_positive_int(name: str, value: Any) -> int:
+    """YAML may yield int or (rarely) str; occupancy dims must be int >= 1."""
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be an integer, got {value!r}") from exc
+    if parsed < 1:
+        raise ValueError(f"{name} must be >= 1, got {parsed}")
+    return parsed
+
+
+def _as_int_in_range(name: str, value: Any, lo: int, hi: int) -> int:
+    """Inclusive integer range (YAML ``knn_k`` is 0–4096)."""
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be an integer, got {value!r}") from exc
+    if parsed < lo or parsed > hi:
+        raise ValueError(f"{name} must be in [{lo}, {hi}], got {parsed}")
+    return parsed
+
+
+def _as_positive_float(name: str, value: Any) -> float:
+    """Learning-rate style knobs must be a finite float > 0."""
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a float, got {value!r}") from exc
+    if parsed <= 0.0 or parsed != parsed:
+        raise ValueError(f"{name} must be > 0, got {parsed}")
+    return parsed
+
+
+def _as_pos_weight_pair(raw: Mapping[str, Any]) -> tuple[float | None, bool]:
+    """
+    YAML ``pos_weight``: omit / null → unweighted BCE.
+
+    ``auto`` → compute n_outside / n_inside on the train split at train time.
+    A finite float > 0 is used as-is (1.0 is unweighted).
+    """
+    if "pos_weight" not in raw:
+        return None, False
+    value = raw["pos_weight"]
+    if value is None or value is False:
+        return None, False
+    if isinstance(value, str):
+        text = value.strip().lower()
+        if text in ("", "none", "off", "false"):
+            return None, False
+        if text == "auto":
+            return None, True
+    parsed = _as_positive_float("pos_weight", value)
+    return parsed, False
+
+
+def _as_open_unit_interval(name: str, value: Any) -> float:
+    """Hold-out fractions must be in (0, 1) so both splits are non-empty."""
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a float, got {value!r}") from exc
+    if parsed != parsed or parsed <= 0.0 or parsed >= 1.0:
+        raise ValueError(f"{name} must be in (0, 1), got {parsed}")
+    return parsed
+
+
+def _as_nonempty_path_string(name: str, value: Any) -> str:
+    if value is None or (isinstance(value, str) and not value.strip()):
+        raise ValueError(f"{name} must be a non-empty path string in config.yaml")
+    return str(value).strip()
+
+
+def _as_data_dir_string(value: Any) -> str:
+    return _as_nonempty_path_string("data_dir", value)
+
+
+def _as_optional_positive_int(name: str, value: Any) -> int | None:
+    """YAML null → unlimited catalog cap; otherwise int >= 1."""
+    if value is None:
+        return None
+    return _as_positive_int(name, value)
+
+
+def _as_run_name(value: Any) -> str:
+    """Optional YAML suffix for ``runs/<timestamp>_<name>/``; empty → ``run``."""
+    if value is None:
+        return "run"
+    text = str(value).strip()
+    return text if text else "run"
+
+
+_CHECKPOINT_METRIC_ALIASES = {
+    "test_acc": "val_acc",
+    "test_iou": "val_iou",
+}
+
+
+def _as_checkpoint_metric(value: Any) -> str:
+    """Name of the scalar used to decide ``best.pt`` (strict improve)."""
+    if value is None or (isinstance(value, str) and not value.strip()):
+        raise ValueError("checkpoint_metric must be a non-empty string")
+    name = str(value).strip()
+    return _CHECKPOINT_METRIC_ALIASES.get(name, name)
+
+
+def _as_val_fraction(raw: Mapping[str, Any]) -> float:
+    """Prefer ``val_fraction``; accept legacy ``test_fraction``."""
+    if "val_fraction" in raw:
+        return _as_open_unit_interval("val_fraction", raw["val_fraction"])
+    if "test_fraction" in raw:
+        return _as_open_unit_interval("test_fraction", raw["test_fraction"])
+    raise ValueError("Config YAML missing keys: val_fraction")
+
+
+def _as_optional_latent_dim(raw: Mapping[str, Any]) -> int | None:
+    """YAML omit / null → use ``hidden`` at train time."""
+    if "latent_dim" not in raw or raw["latent_dim"] is None:
+        return None
+    return _as_positive_int("latent_dim", raw["latent_dim"])
+
+
+# Names accepted in config.yaml ``optimizer``. Used by train_multi_npz.
+_ALLOWED_OPTIMIZERS = ("adam", "adamw", "sgd")
+# ``none`` = OccupancyMLP (xyz only). ``surface`` = envelope encoder.
+_ALLOWED_SHAPE_ENCODERS = ("none", "surface")
+
+
+def _as_optimizer(value: Any) -> str:
+    """Optimizer family for multi-NPZ train; default Adam."""
+    if value is None or (isinstance(value, str) and not str(value).strip()):
+        return "adam"
+    name = str(value).strip().lower()
+    if name not in _ALLOWED_OPTIMIZERS:
+        allowed = ", ".join(_ALLOWED_OPTIMIZERS)
+        raise ValueError(f"optimizer must be one of {allowed}, got {value!r}")
+    return name
+
+
+def _as_shape_encoder(value: Any) -> str:
+    """Occupancy head family; default xyz-only so older YAML still loads."""
+    if value is None or (isinstance(value, str) and not str(value).strip()):
+        return "none"
+    name = str(value).strip().lower()
+    if name not in _ALLOWED_SHAPE_ENCODERS:
+        allowed = ", ".join(_ALLOWED_SHAPE_ENCODERS)
+        raise ValueError(f"shape_encoder must be one of {allowed}, got {value!r}")
+    return name
+
+
+def _as_npz_paths(value: Any) -> tuple[str, ...]:
+    """Explicit NPZ list relative to data_dir (empty → use glob)."""
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        item = value.strip()
+        return (item,) if item else ()
+    if not isinstance(value, list):
+        raise ValueError(f"npz_paths must be a list of strings or null, got {type(value).__name__}")
+    out: list[str] = []
+    for i, raw in enumerate(value):
+        text = _as_nonempty_path_string(f"npz_paths[{i}]", raw)
+        out.append(text)
+    return tuple(out)
+
+
+def _as_npz_catalog(value: Any) -> tuple[tuple[str, int | None], ...]:
+    """Union of globs; optional ``max_shapes`` is unique meshes per glob."""
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise ValueError(
+            f"npz_catalog must be a list or null, got {type(value).__name__}"
+        )
+    out: list[tuple[str, int | None]] = []
+    for i, raw in enumerate(value):
+        if isinstance(raw, str):
+            glob_s = _as_nonempty_path_string(f"npz_catalog[{i}]", raw)
+            out.append((glob_s, None))
+            continue
+        if not isinstance(raw, Mapping):
+            raise ValueError(
+                f"npz_catalog[{i}] must be a glob string or mapping, "
+                f"got {type(raw).__name__}"
+            )
+        if "glob" not in raw:
+            raise ValueError(f"npz_catalog[{i}] missing glob")
+        glob_s = _as_nonempty_path_string(f"npz_catalog[{i}].glob", raw["glob"])
+        max_shapes: int | None = None
+        if "max_shapes" in raw and raw["max_shapes"] is not None:
+            max_shapes = _as_positive_int(
+                f"npz_catalog[{i}].max_shapes", raw["max_shapes"]
+            )
+        out.append((glob_s, max_shapes))
+    return tuple(out)
+
+
+def as_repo_relative(path: Path | str, *, root: Path | None = None) -> str:
+    """
+    POSIX string relative to the git repo when ``path`` is inside it.
+
+    Already-relative inputs are returned as POSIX. Absolute paths on another
+    drive (the dataset disk) cannot be repo-relative and stay absolute POSIX.
+    """
+    text = str(path).strip()
+    if not text:
+        return text
+    parsed = Path(text)
+    if not parsed.is_absolute():
+        return parsed.as_posix()
+    base = (root or _REPO_ROOT).resolve()
+    try:
+        return parsed.resolve().relative_to(base).as_posix()
+    except ValueError:
+        return parsed.resolve().as_posix()
+
+
+def as_data_relative(path: Path | str, data_dir: Path | str) -> str:
+    """
+    POSIX string relative to ``data_dir`` (``exports/...``, not ``E:/...``).
+
+    Already-relative inputs are returned as POSIX. Paths outside ``data_dir``
+    (unit-test temp trees) fall back to absolute POSIX.
+    """
+    text = str(path).strip()
+    if not text:
+        return text
+    parsed = Path(text)
+    if not parsed.is_absolute():
+        return parsed.as_posix()
+    root = Path(data_dir).expanduser().resolve()
+    resolved = parsed.expanduser().resolve()
+    try:
+        return resolved.relative_to(root).as_posix()
+    except ValueError:
+        return resolved.as_posix()
+
+
+def load_yaml_knobs(path: Path) -> YamlKnobs:
+    """
+    Read YAML settings. Does not check that data_dir exists on disk.
+
+    Parameters
+    ----------
+    path:
+        Path to ``config.yaml``.
+
+    Returns
+    -------
+    YamlKnobs
+        Typed dict of experiment knobs (paths still strings).
+    """
+    if not path.is_file():
+        raise FileNotFoundError(f"Config YAML not found: {path}")
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, Mapping):
+        raise ValueError(f"Config YAML must be a mapping, got {type(raw).__name__}")
+    missing = [k for k in _REQUIRED_YAML_KEYS if k not in raw]
+    if missing:
+        raise ValueError(f"Config YAML missing keys: {', '.join(missing)}")
+    pos_weight, pos_weight_auto = _as_pos_weight_pair(raw)
+    return {
+        "hidden": _as_positive_int("hidden", raw["hidden"]),
+        "depth": _as_positive_int("depth", raw["depth"]),
+        "seed": _as_positive_int("seed", raw["seed"]),
+        "data_dir": _as_data_dir_string(raw["data_dir"]),
+        "epochs": _as_positive_int("epochs", raw["epochs"]),
+        "lr": _as_positive_float("lr", raw["lr"]),
+        "val_fraction": _as_val_fraction(raw),
+        "latent_dim": _as_optional_latent_dim(raw),
+        "npz_glob": (
+            _as_nonempty_path_string("npz_glob", raw["npz_glob"])
+            if "npz_glob" in raw
+            else "exports/dataset/*.npz"
+        ),
+        "npz_paths": _as_npz_paths(raw.get("npz_paths")),
+        "npz_catalog": _as_npz_catalog(raw.get("npz_catalog")),
+        "max_files_per_shape": (
+            _as_optional_positive_int("max_files_per_shape", raw["max_files_per_shape"])
+            if "max_files_per_shape" in raw
+            else 2
+        ),
+        "run_name": (
+            _as_run_name(raw["run_name"]) if "run_name" in raw else "run"
+        ),
+        "checkpoint_metric": (
+            _as_checkpoint_metric(raw["checkpoint_metric"])
+            if "checkpoint_metric" in raw
+            else "val_acc"
+        ),
+        "batch_size": (
+            _as_positive_int("batch_size", raw["batch_size"])
+            if "batch_size" in raw
+            else 1024
+        ),
+        "optimizer": (
+            _as_optimizer(raw["optimizer"]) if "optimizer" in raw else "adam"
+        ),
+        "n_surface": (
+            _as_positive_int("n_surface", raw["n_surface"])
+            if "n_surface" in raw
+            else 1024
+        ),
+        "knn_k": (
+            _as_int_in_range("knn_k", raw["knn_k"], 0, 4096)
+            if "knn_k" in raw
+            else 0
+        ),
+        "knn_local_dim": (
+            _as_positive_int("knn_local_dim", raw["knn_local_dim"])
+            if "knn_local_dim" in raw
+            else None
+        ),
+        "shape_encoder": (
+            _as_shape_encoder(raw["shape_encoder"])
+            if "shape_encoder" in raw
+            else "none"
+        ),
+        "pos_weight": pos_weight,
+        "pos_weight_auto": pos_weight_auto,
+    }
+
+
+def _warn_missing_data_dir(data_dir: Path, yaml_path: Path) -> None:
+    """Print a terminal hint so the user can fix config.yaml (no .env involved)."""
+    print(
+        "\n"
+        "Dataset folder not found.\n"
+        f"  Looked for: {data_dir}\n"
+        "\n"
+        "Update `data_dir` in config.yaml to the folder that contains "
+        "`exports/` and `meshes/`.\n"
+        f"  Config file: {yaml_path}\n"
+    )
+
+
+def require_data_dir(data_dir: Path, *, yaml_path: Path) -> None:
+    """Validate the dataset root before training or NPZ loading."""
+    if data_dir.is_dir():
+        return
+    _warn_missing_data_dir(data_dir, yaml_path)
+    raise FileNotFoundError(
+        f"Dataset directory does not exist: {data_dir}. "
+        f"Set data_dir in {yaml_path}."
+    )
+
+
+@dataclass(frozen=True)
+class OccupancyConfig:
+    """Resolved experiment settings from YAML plus detected device."""
+
+    data_dir: Path
+    device: torch.device
+    hidden: int
+    depth: int
+    seed: int
+    epochs: int
+    lr: float
+    # Fraction of catalog **meshes** held out as val (selection split, not a locked test).
+    val_fraction: float
+    # Catalog knobs (optional in YAML; omitted keys keep these defaults).
+    npz_glob: str = "exports/dataset/*.npz"
+    npz_paths: tuple[str, ...] = ()
+    # ``(glob, max_shapes)`` rows. Empty → use ``npz_glob``. ``max_shapes``
+    # None keeps every mesh that glob hits (after ``max_files_per_shape``).
+    npz_catalog: tuple[tuple[str, int | None], ...] = ()
+    max_files_per_shape: int | None = 2
+    # Suffix for runs/<timestamp>_<name>/ (device stays runtime-only).
+    run_name: str = "run"
+    # Which logged scalar selects best.pt (strict improve).
+    checkpoint_metric: str = "val_acc"
+    # Encoder latent width; None → use ``hidden`` at train / infer time.
+    latent_dim: int | None = None
+    # Mini-batch size and optimizer family (train_multi_npz).
+    batch_size: int = 1024
+    optimizer: str = "adam"
+    # Envelope sample count (YAML). Used when ``shape_encoder`` is ``surface``.
+    n_surface: int = 1024
+    # 0 = global envelope z only. >0 = that many nearest envelope dots per query.
+    knn_k: int = 0
+    # Width of z_local; None → same as occupancy latent_dim / hidden.
+    knn_local_dim: int | None = None
+    # ``none`` keeps OccupancyMLP; ``surface`` uses the envelope PointNet.
+    shape_encoder: str = "none"
+    # BCE inside-class weight. None + auto=False = unweighted (legacy).
+    pos_weight: float | None = None
+    pos_weight_auto: bool = False
+
+
+def load_config(
+    yaml_path: Path | None = None,
+    *,
+    require_existing_data_dir: bool = True,
+) -> OccupancyConfig:
+    """
+    Compose OccupancyConfig from ``config.yaml`` (not from ``.env``).
+
+    When ``require_existing_data_dir`` is True (default), a missing folder
+    prints a short instruction and then raises FileNotFoundError — used for
+    training and data loading.
+
+    Parameters
+    ----------
+    yaml_path:
+        Config file; default is repo-root ``config.yaml``.
+    require_existing_data_dir:
+        If True, refuse to return a config whose ``data_dir`` is missing.
+
+    Returns
+    -------
+    OccupancyConfig
+        YAML knobs plus detected ``device``.
+    """
+    cfg_path = yaml_path or _DEFAULT_YAML
+    knobs = load_yaml_knobs(cfg_path)
+    data_dir = Path(knobs["data_dir"])
+    if require_existing_data_dir:
+        require_data_dir(data_dir, yaml_path=cfg_path)
+    return OccupancyConfig(
+        data_dir=data_dir,
+        device=get_device(),
+        hidden=knobs["hidden"],
+        depth=knobs["depth"],
+        seed=knobs["seed"],
+        epochs=knobs["epochs"],
+        lr=knobs["lr"],
+        val_fraction=knobs["val_fraction"],
+        latent_dim=knobs["latent_dim"],
+        npz_glob=knobs["npz_glob"],
+        npz_paths=knobs["npz_paths"],
+        npz_catalog=knobs["npz_catalog"],
+        max_files_per_shape=knobs["max_files_per_shape"],
+        run_name=knobs["run_name"],
+        checkpoint_metric=knobs["checkpoint_metric"],
+        batch_size=knobs["batch_size"],
+        optimizer=knobs["optimizer"],
+        n_surface=knobs["n_surface"],
+        knn_k=knobs["knn_k"],
+        knn_local_dim=knobs["knn_local_dim"],
+        shape_encoder=knobs["shape_encoder"],
+        pos_weight=knobs["pos_weight"],
+        pos_weight_auto=knobs["pos_weight_auto"],
+    )
+
+
+def encoder_latent_dim(cfg: OccupancyConfig) -> int:
+    """OccupancyEncoder ``z`` width: YAML ``latent_dim`` or ``hidden``."""
+    if cfg.latent_dim is None:
+        return int(cfg.hidden)
+    return int(cfg.latent_dim)
+
+
+def encoder_knn_local_dim(cfg: OccupancyConfig) -> int:
+    """Local envelope code width: YAML ``knn_local_dim`` or global latent."""
+    if cfg.knn_local_dim is None:
+        return encoder_latent_dim(cfg)
+    return int(cfg.knn_local_dim)
+
+
+def format_config(cfg: OccupancyConfig) -> str:
+    """
+    Pretty-print for CLI smoke checks.
+
+    Parameters
+    ----------
+    cfg:
+        Resolved config.
+
+    Returns
+    -------
+    str
+        Multi-line ``OccupancyConfig(...)`` dump.
+    """
+    return (
+        f"OccupancyConfig(\n"
+        f"  data_dir={cfg.data_dir}\n"
+        f"  device={cfg.device}\n"
+        f"  gpu={gpu_name(cfg.device)}\n"
+        f"  hidden={cfg.hidden}\n"
+        f"  depth={cfg.depth}\n"
+        f"  seed={cfg.seed}\n"
+        f"  epochs={cfg.epochs}\n"
+        f"  lr={cfg.lr}\n"
+        f"  val_fraction={cfg.val_fraction}\n"
+        f"  latent_dim={cfg.latent_dim}\n"
+        f"  npz_glob={cfg.npz_glob}\n"
+        f"  npz_paths={list(cfg.npz_paths)}\n"
+        f"  npz_catalog={list(cfg.npz_catalog)}\n"
+        f"  max_files_per_shape={cfg.max_files_per_shape}\n"
+        f"  run_name={cfg.run_name}\n"
+        f"  checkpoint_metric={cfg.checkpoint_metric}\n"
+        f"  batch_size={cfg.batch_size}\n"
+        f"  optimizer={cfg.optimizer}\n"
+        f"  n_surface={cfg.n_surface}\n"
+        f"  knn_k={cfg.knn_k}\n"
+        f"  knn_local_dim={cfg.knn_local_dim}\n"
+        f"  shape_encoder={cfg.shape_encoder}\n"
+        f"  pos_weight={cfg.pos_weight}\n"
+        f"  pos_weight_auto={cfg.pos_weight_auto}\n"
+        f")"
+    )
+
+
+if __name__ == "__main__":
+    print(format_config(load_config()))

scatteringnet/data_npz.py

@@ -0,0 +1,460 @@
+"""Load occupancy query points and labels from scatter NPZ files.
+
+:func:`load_points_labels` reads **one** file. A catalog resolver lists
+many NPZs (glob or explicit paths) without training.
+
+``load_points_labels`` still returns only ``points`` and ``labels``.
+``load_points_labels_mesh`` also resolves ``mesh_path`` against ``data_dir``.
+"""
+
+from __future__ import annotations
+
+import glob as globlib
+import random
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+# Labels are converted here (not deferred to the Dataset) so every caller gets
+# the same dtypes: float32 XYZ and float32 {0, 1} occupancy.
+PointsArray = NDArray[np.float32]
+LabelsArray = NDArray[np.float32]
+
+
+def load_points_labels(path: Path) -> tuple[PointsArray, LabelsArray]:
+    """
+    Read query coordinates and inside/outside labels from one NPZ file.
+
+    Parameters
+    ----------
+    path:
+        Path to a ``.npz`` with arrays ``points`` ``(N, 3)`` and
+        ``labels`` ``(N,)`` (typically uint8 0/1).
+
+    Returns
+    -------
+    points:
+        ``float32`` array of shape ``(N, 3)``.
+    labels:
+        ``float32`` array of shape ``(N,)`` with values in ``{0.0, 1.0}``
+        (0 = outside, 1 = inside).
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+
+    # allow_pickle=False: we only need numeric arrays, not object payloads.
+    with np.load(npz_path, allow_pickle=False) as raw:
+        files = set(raw.files)
+        if "points" not in files or "labels" not in files:
+            raise KeyError(
+                f"NPZ must contain 'points' and 'labels', got {sorted(files)} "
+                f"in {npz_path}"
+            )
+        points = np.asarray(raw["points"])
+        labels = np.asarray(raw["labels"])
+
+    if points.ndim != 2 or points.shape[1] != 3:
+        raise ValueError(
+            f"points must have shape (N, 3), got {tuple(points.shape)} in {npz_path}"
+        )
+    n = int(points.shape[0])
+    if labels.shape != (n,):
+        raise ValueError(
+            f"labels must have shape (N,) with N={n}, got {tuple(labels.shape)} "
+            f"in {npz_path}"
+        )
+
+    points_f32 = np.asarray(points, dtype=np.float32)
+    labels_f32 = np.asarray(labels, dtype=np.float32)
+    unique = np.unique(labels_f32)
+    if not np.all((unique == 0.0) | (unique == 1.0)):
+        raise ValueError(
+            f"labels must be in {{0, 1}}, got unique={unique.tolist()} in {npz_path}"
+        )
+    return points_f32, labels_f32
+
+
+def count_npz_points(path: Path | str) -> int:
+    """
+    Query count in one NPZ without keeping the arrays.
+
+    Catalog construct uses this so ``len(part)`` / ``n_points`` do not
+    require loading every lattice into RAM.
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+    with np.load(npz_path, allow_pickle=False) as raw:
+        files = set(raw.files)
+        if "points" not in files or "labels" not in files:
+            raise KeyError(
+                f"NPZ must contain 'points' and 'labels', got {sorted(files)} "
+                f"in {npz_path}"
+            )
+        n = int(np.asarray(raw["points"]).shape[0])
+        n_y = int(np.asarray(raw["labels"]).shape[0])
+    if n_y != n:
+        raise ValueError(
+            f"labels must have shape (N,) with N={n}, got N={n_y} in {npz_path}"
+        )
+    return n
+
+
+def count_npz_labels(path: Path | str) -> tuple[int, int]:
+    """
+    Outside / inside counts in one NPZ without keeping the point cloud.
+
+    Used for ``pos_weight: auto`` (n_outside / n_inside on the train split).
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+    with np.load(npz_path, allow_pickle=False) as raw:
+        if "labels" not in set(raw.files):
+            raise KeyError(f"NPZ must contain 'labels', got {sorted(raw.files)} in {npz_path}")
+        labels = np.asarray(raw["labels"]).reshape(-1)
+    # Labels are 0/1 occupancy; nonzero is inside.
+    n_in = int(np.count_nonzero(labels))
+    n_out = int(labels.size) - n_in
+    return n_out, n_in
+
+
+def read_npz_mesh_path(path: Path | str) -> str:
+    """
+    Read the stored ``mesh_path`` string from one occupancy NPZ.
+
+    Step 2 writes a ``data_dir``-relative POSIX path (for example
+    ``meshes/Primitives/Sphere/sphere_r0p5_sa16_sh16.obj``).
+
+    Parameters
+    ----------
+    path:
+        Occupancy ``.npz`` that contains ``mesh_path``.
+
+    Returns
+    -------
+    str
+        Stored path string (relative or absolute). Not resolved here.
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+    # allow_pickle=True: some exports store a 0-d string / object array.
+    with np.load(npz_path, allow_pickle=True) as raw:
+        if "mesh_path" not in raw.files:
+            raise KeyError(f"NPZ has no 'mesh_path' in {npz_path}")
+        stored = str(np.asarray(raw["mesh_path"]).item()).strip()
+    if not stored:
+        raise ValueError(f"mesh_path is empty in {npz_path}")
+    return stored
+
+
+def resolve_mesh_path(stored: str, data_dir: Path | str) -> Path:
+    """
+    Resolve a stored ``mesh_path`` against ``data_dir``.
+
+    Relative entries are joined to ``data_dir``. Absolute entries are
+    used as-is. Missing files raise ``FileNotFoundError``.
+
+    Parameters
+    ----------
+    stored:
+        Value from :func:`read_npz_mesh_path`.
+    data_dir:
+        Dataset root (``config.yaml`` ``data_dir``).
+
+    Returns
+    -------
+    Path
+        Existing resolved mesh file.
+    """
+    text = str(stored).strip()
+    if not text:
+        raise ValueError("mesh_path is empty")
+    item = Path(text)
+    root = Path(data_dir)
+    resolved = item if item.is_absolute() else (root / item)
+    resolved = resolved.resolve()
+    if not resolved.is_file():
+        raise FileNotFoundError(f"mesh not found: {resolved} (stored={text!r})")
+    return resolved
+
+
+def load_points_labels_mesh(
+    path: Path | str,
+    data_dir: Path | str,
+) -> tuple[PointsArray, LabelsArray, Path]:
+    """
+    Read occupancy arrays and resolve the source OBJ.
+
+    Keeps :func:`load_points_labels` unchanged (xyz + labels only).
+
+    Parameters
+    ----------
+    path:
+        Occupancy ``.npz`` with ``points``, ``labels``, and ``mesh_path``.
+    data_dir:
+        Root used to resolve a relative ``mesh_path``.
+
+    Returns
+    -------
+    points, labels, mesh_path:
+        Same arrays as :func:`load_points_labels`, plus the existing OBJ.
+    """
+    npz_path = Path(path)
+    points, labels = load_points_labels(npz_path)
+    stored = read_npz_mesh_path(npz_path)
+    mesh_path = resolve_mesh_path(stored, data_dir)
+    return points, labels, mesh_path
+
+
+def _is_combo_npz(path: Path) -> bool:
+    """True when the filename looks like a combo dump (excluded from the catalog)."""
+    return "combo" in path.name.lower()
+
+
+def shape_key(path: Path) -> str:
+    """
+    Group NPZs that belong to the same mesh.
+
+    Uses the stem before ``__`` (dataset_builder tag), else the full stem.
+
+    Parameters
+    ----------
+    path:
+        NPZ path.
+
+    Returns
+    -------
+    str
+        Stable key for ``max_files_per_shape``.
+    """
+    stem = Path(path).stem
+    if "__" in stem:
+        return stem.split("__", 1)[0]
+    return stem
+
+
+def _cap_per_shape(
+    paths: Sequence[Path],
+    max_files_per_shape: int | None,
+) -> list[Path]:
+    """Keep at most ``max_files_per_shape`` files per :func:`shape_key` (sorted order)."""
+    if max_files_per_shape is None:
+        return list(paths)
+    if max_files_per_shape < 1:
+        raise ValueError(f"max_files_per_shape must be >= 1 or None, got {max_files_per_shape}")
+    counts: dict[str, int] = {}
+    out: list[Path] = []
+    for path in paths:
+        key = shape_key(path)
+        taken = counts.get(key, 0)
+        if taken >= max_files_per_shape:
+            continue
+        counts[key] = taken + 1
+        out.append(path)
+    return out
+
+
+def _glob_npz(root: Path, pattern: str) -> list[Path]:
+    """Match ``pattern`` under ``root`` (``*`` / ``**``)."""
+    full = str(root / pattern)
+    recursive = "**" in pattern.replace("\\", "/")
+    found = globlib.glob(full, recursive=recursive)
+    return [Path(p).resolve() for p in found if Path(p).is_file()]
+
+
+def _is_parameterized_stem(path: Path) -> bool:
+    """
+    Maya catalog names are ``family_param_...``. Varied one-off stems
+    (``Cone.obj`` → ``Cone__occupancy.npz``) have no ``_`` in the shape key
+    and must not ride along when Windows glob is case-insensitive.
+    """
+    return "_" in shape_key(path)
+
+
+def _subsample_shapes(
+    paths: Sequence[Path],
+    max_shapes: int,
+    seed: int,
+) -> list[Path]:
+    """Keep NPZs for at most ``max_shapes`` unique :func:`shape_key` values."""
+    if max_shapes < 1:
+        raise ValueError(f"max_shapes must be >= 1, got {max_shapes}")
+    keys: list[str] = []
+    seen: set[str] = set()
+    for path in paths:
+        key = shape_key(path)
+        if key in seen:
+            continue
+        seen.add(key)
+        keys.append(key)
+    if max_shapes >= len(keys):
+        return list(paths)
+    # Sort then sample so the same seed always picks the same meshes.
+    chosen_keys = set(random.Random(int(seed)).sample(sorted(keys), max_shapes))
+    return [path for path in paths if shape_key(path) in chosen_keys]
+
+
+def resolve_npz_catalog(
+    data_dir: Path | str,
+    *,
+    npz_glob: str = "exports/dataset/*.npz",
+    npz_paths: Sequence[str | Path] | None = None,
+    npz_catalog: Sequence[tuple[str, int | None]] | None = None,
+    max_files_per_shape: int | None = 2,
+    exclude_combo: bool = True,
+    seed: int = 1,
+) -> list[Path]:
+    """
+    Resolve occupancy NPZ paths under ``data_dir`` (no point loading).
+
+    Priority: explicit ``npz_paths``, else ``npz_catalog`` (union of globs),
+    else ``npz_glob``. Relative entries are joined to ``data_dir``.
+    Missing files in ``npz_paths`` raise ``FileNotFoundError``.
+
+    Parameters
+    ----------
+    data_dir:
+        Dataset root (``config.yaml`` ``data_dir``).
+    npz_glob:
+        Single glob relative to ``data_dir`` (``*`` and ``**`` allowed).
+    npz_paths:
+        Explicit relative or absolute NPZ paths. Empty / None → use glob(s).
+    npz_catalog:
+        ``(glob, max_shapes)`` rows. ``max_shapes`` is unique meshes after
+        the per-shape file cap; ``None`` keeps every mesh the glob hits.
+    max_files_per_shape:
+        Cap per :func:`shape_key` after sort. ``None`` = no cap.
+    exclude_combo:
+        Drop filenames containing ``combo``.
+    seed:
+        RNG for ``max_shapes`` subsampling (YAML ``seed``).
+
+    Returns
+    -------
+    list[Path]
+        Sorted existing ``.npz`` files.
+    """
+    root = Path(data_dir)
+    chosen: list[Path]
+    if npz_paths:
+        chosen = []
+        for raw in npz_paths:
+            item = Path(raw)
+            resolved = item if item.is_absolute() else (root / item)
+            if not resolved.is_file():
+                raise FileNotFoundError(f"NPZ not found: {resolved}")
+            chosen.append(resolved.resolve())
+    elif npz_catalog:
+        # Union in YAML order. Same file from two globs is kept once.
+        seen: set[Path] = set()
+        chosen = []
+        for pattern, max_shapes in npz_catalog:
+            hit = _glob_npz(root, str(pattern))
+            if exclude_combo:
+                hit = [p for p in hit if not _is_combo_npz(p)]
+            hit = [
+                p
+                for p in hit
+                if p.suffix.lower() == ".npz" and _is_parameterized_stem(p)
+            ]
+            hit = sorted(hit)
+            hit = _cap_per_shape(hit, max_files_per_shape)
+            if max_shapes is not None:
+                hit = _subsample_shapes(hit, int(max_shapes), int(seed))
+            for path in hit:
+                if path in seen:
+                    continue
+                seen.add(path)
+                chosen.append(path)
+    else:
+        chosen = _glob_npz(root, npz_glob)
+
+    npz_only = [p for p in chosen if p.suffix.lower() == ".npz"]
+    if exclude_combo:
+        npz_only = [p for p in npz_only if not _is_combo_npz(p)]
+    if npz_catalog and not npz_paths:
+        # Already capped per glob; keep YAML union order (not a global sort).
+        capped = npz_only
+    else:
+        npz_only = sorted(npz_only)
+        capped = _cap_per_shape(npz_only, max_files_per_shape)
+    if not capped:
+        raise FileNotFoundError(
+            f"No occupancy NPZ files matched under {root} "
+            f"(glob={npz_glob!r}, catalog={bool(npz_catalog)}, "
+            f"explicit={bool(npz_paths)})"
+        )
+    return capped
+
+
+def _summarize(points: PointsArray, labels: LabelsArray) -> str:
+    n = int(points.shape[0])
+    inside = float(labels.mean()) if n else float("nan")
+    xyz_min = points.min(axis=0) if n else np.full(3, np.nan, dtype=np.float32)
+    xyz_max = points.max(axis=0) if n else np.full(3, np.nan, dtype=np.float32)
+    return (
+        f"N={n}\n"
+        f"inside_fraction={inside:.6f}\n"
+        f"xyz_min={xyz_min.tolist()}\n"
+        f"xyz_max={xyz_max.tolist()}"
+    )
+
+
+# Default smoke-check file from the v2 plan (dataset_test sphere).
+_SAMPLE_RELATIVE = Path("exports") / "dataset_test" / "sphere__raycast_z_raut_s0.15_inout.npz"
+
+
+if __name__ == "__main__":
+    import sys
+
+    from scatteringnet.config import load_config
+
+    cfg = load_config()
+    if "--catalog" in sys.argv:
+        paths = resolve_npz_catalog(
+            cfg.data_dir,
+            npz_glob=cfg.npz_glob,
+            npz_paths=cfg.npz_paths or None,
+            npz_catalog=cfg.npz_catalog or None,
+            max_files_per_shape=cfg.max_files_per_shape,
+            seed=cfg.seed,
+        )
+        print(f"data_dir={cfg.data_dir}")
+        print(f"npz_glob={cfg.npz_glob}")
+        print(f"npz_catalog={list(cfg.npz_catalog)}")
+        print(f"max_files_per_shape={cfg.max_files_per_shape}")
+        print(f"files={len(paths)}")
+        # Load a few files only — the full catalog can be thousands of NPZs.
+        preview = paths[:3]
+        n_all = 0
+        n_in = 0
+        for path in preview:
+            pts, labs = load_points_labels(path)
+            n = int(pts.shape[0])
+            inside = int((labs == 1.0).sum())
+            n_all += n
+            n_in += inside
+            print(
+                f"  {path.name} N={n} inside={inside} outside={n - inside}"
+            )
+        print(
+            f"preview_files={len(preview)} preview_N={n_all} "
+            f"preview_inside={n_in} preview_outside={n_all - n_in}"
+        )
+        from scatteringnet.dataset import OccupancyMultiNpzDataset, make_dataloader
+
+        ds = OccupancyMultiNpzDataset(paths)
+        loader = make_dataloader(ds.parts[0], batch_size=8, shuffle=False)
+        xyz, y = next(iter(loader))
+        print(f"files={len(ds)} n_points={ds.n_points} parts={len(ds.parts)}")
+        print(f"batch xyz={tuple(xyz.shape)} y={tuple(y.shape)}")
+    else:
+        sample = cfg.data_dir / _SAMPLE_RELATIVE
+        pts, labs = load_points_labels(sample)
+        print(f"file={sample}")
+        print(_summarize(pts, labs))

scatteringnet/geometry/__init__.py

@@ -0,0 +1,10 @@
+"""Training-side geometry: OBJ triangles and envelope samples."""
+
+from scatteringnet.geometry.mesh_io import clear_triangle_cache
+from scatteringnet.geometry.surface import clear_envelope_cache
+
+
+def clear_geometry_caches() -> None:
+    """Drop OBJ triangle and envelope process caches."""
+    clear_triangle_cache()
+    clear_envelope_cache()

scatteringnet/geometry/mesh_io.py

@@ -0,0 +1,80 @@
+"""Load OBJ triangle meshes for the NPZ ↔ mesh join.
+
+This module only returns ``vertices (V, 3)`` and ``faces (T, 3)``.
+It does **not** sample the envelope.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import numpy as np
+import trimesh
+from numpy.typing import NDArray
+
+from scatteringnet.geometry.trimesh_util import as_trimesh
+
+VerticesArray = NDArray[np.float32]
+FacesArray = NDArray[np.int32]
+
+# Same resolved OBJ can back several NPZs (``max_files_per_shape``). Cache
+# the triangle arrays so catalog load does not re-parse the file.
+_TRIANGLE_CACHE: dict[str, tuple[VerticesArray, FacesArray]] = {}
+
+
+def clear_triangle_cache() -> None:
+    """Drop cached OBJ arrays (tests / long-lived notebooks)."""
+    _TRIANGLE_CACHE.clear()
+
+
+def load_obj_triangles(
+    path: Path | str,
+    *,
+    cache: bool = True,
+) -> tuple[VerticesArray, FacesArray]:
+    """
+    Read one OBJ as triangle vertices and face indices.
+
+    Parameters
+    ----------
+    path:
+        Existing ``.obj`` file.
+    cache:
+        Reuse arrays for the same resolved path (catalog load).
+
+    Returns
+    -------
+    vertices:
+        ``float32`` array of shape ``(V, 3)``.
+    faces:
+        ``int32`` array of shape ``(T, 3)`` (0-based vertex indices).
+    """
+    obj_path = Path(path)
+    if not obj_path.is_file():
+        raise FileNotFoundError(f"OBJ not found: {obj_path}")
+    if obj_path.suffix.lower() != ".obj":
+        raise ValueError(f"expected .obj, got {obj_path.suffix!r} ({obj_path})")
+
+    cache_key = str(obj_path.resolve())
+    if cache and cache_key in _TRIANGLE_CACHE:
+        return _TRIANGLE_CACHE[cache_key]
+
+    # process=False keeps the authored vertices; we only need the join.
+    loaded = trimesh.load(obj_path, force=None, process=False)
+    mesh = as_trimesh(loaded)
+    vertices = np.asarray(mesh.vertices, dtype=np.float32)
+    faces = np.asarray(mesh.faces, dtype=np.int32)
+    if vertices.ndim != 2 or vertices.shape[1] != 3:
+        raise ValueError(
+            f"vertices must have shape (V, 3), got {tuple(vertices.shape)} in {obj_path}"
+        )
+    if faces.ndim != 2 or faces.shape[1] != 3:
+        raise ValueError(
+            f"faces must have shape (T, 3), got {tuple(faces.shape)} in {obj_path}"
+        )
+    if int(faces.shape[0]) < 1:
+        raise ValueError(f"OBJ has no triangles: {obj_path}")
+
+    arrays = (vertices, faces)
+    if cache:
+        _TRIANGLE_CACHE[cache_key] = arrays
+    return arrays

scatteringnet/geometry/surface.py

@@ -0,0 +1,154 @@
+"""Surface envelope samples from a triangle mesh.
+
+Area-weighted face darts (larger triangles get more samples). Each
+sample is ``(x, y, z, nx, ny, nz)``: position plus the unit normal of
+the triangle it sits on. World clouds are cached per
+``(mesh_key, n_surface, seed)``. AABB is applied to XYZ only.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import trimesh
+from numpy.typing import NDArray
+from trimesh.sample import sample_surface
+
+from scatteringnet.normalize import apply_normalization
+
+PointsArray = NDArray[np.float32]
+ENVELOPE_XYZ_DIM = 3
+ENVELOPE_FEAT_DIM = 6
+
+# Same OBJ + count + seed → same world samples (always 6-D).
+_ENVELOPE_CACHE: dict[tuple[str, int, int], PointsArray] = {}
+
+
+def clear_envelope_cache() -> None:
+    """Drop cached world-space envelopes (tests / long-lived notebooks)."""
+    _ENVELOPE_CACHE.clear()
+
+
+def _triangle_normals(verts: np.ndarray, faces: np.ndarray) -> NDArray[np.float64]:
+    v0 = verts[faces[:, 0]]
+    v1 = verts[faces[:, 1]]
+    v2 = verts[faces[:, 2]]
+    cross = np.cross(v1 - v0, v2 - v0)
+    length = np.linalg.norm(cross, axis=1, keepdims=True)
+    ok = length[:, 0] > 1e-12
+    normals = np.zeros_like(cross)
+    normals[ok] = cross[ok] / length[ok]
+    return normals
+
+
+def _pack_xyz_normal(xyz: np.ndarray, normals: np.ndarray) -> PointsArray:
+    """Concatenate XYZ with unit face normals → ``(N, 6)``."""
+    pos = np.asarray(xyz, dtype=np.float32)
+    nrm = np.asarray(normals, dtype=np.float32)
+    if pos.shape != nrm.shape or pos.ndim != 2 or pos.shape[1] != 3:
+        raise ValueError(
+            f"xyz/normals must be (N, 3), got {tuple(pos.shape)} / {tuple(nrm.shape)}"
+        )
+    length = np.linalg.norm(nrm, axis=1, keepdims=True)
+    ok = length[:, 0] > 1e-12
+    unit = np.zeros_like(nrm)
+    unit[ok] = nrm[ok] / length[ok]
+    return np.concatenate([pos, unit], axis=1)
+
+
+def apply_envelope_aabb(
+    env: np.ndarray, center: np.ndarray, scale: float
+) -> PointsArray:
+    """AABB-normalize XYZ; leave normals as unit directions."""
+    arr = np.asarray(env, dtype=np.float32)
+    if arr.ndim != 2 or arr.shape[1] not in (ENVELOPE_XYZ_DIM, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"envelope must be (N, 3) or (N, 6), got {tuple(arr.shape)}"
+        )
+    out = arr.copy()
+    out[:, :3] = apply_normalization(out[:, :3], center, scale)
+    return out
+
+
+def undo_envelope_aabb(
+    env: np.ndarray, center: np.ndarray, scale: float
+) -> PointsArray:
+    """Undo AABB on XYZ only."""
+    arr = np.asarray(env, dtype=np.float32)
+    if arr.ndim != 2 or arr.shape[1] not in (ENVELOPE_XYZ_DIM, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"envelope must be (N, 3) or (N, 6), got {tuple(arr.shape)}"
+        )
+    out = arr.copy()
+    c = np.asarray(center, dtype=np.float32).reshape(3)
+    out[:, :3] = out[:, :3] * np.float32(scale) + c
+    return out
+
+
+def project_envelope_dim(env: np.ndarray, dim: int) -> PointsArray:
+    """Keep XYZ+normal or drop to XYZ for an older checkpoint."""
+    arr = np.asarray(env, dtype=np.float32)
+    want = int(dim)
+    if want == ENVELOPE_FEAT_DIM:
+        if arr.ndim != 2 or arr.shape[1] != ENVELOPE_FEAT_DIM:
+            raise ValueError(f"expected (N, 6) envelope, got {tuple(arr.shape)}")
+        return arr
+    if want == ENVELOPE_XYZ_DIM:
+        if arr.ndim != 2 or arr.shape[1] not in (ENVELOPE_XYZ_DIM, ENVELOPE_FEAT_DIM):
+            raise ValueError(f"expected (N, 3|6) envelope, got {tuple(arr.shape)}")
+        return arr[:, :3]
+    raise ValueError(f"envelope dim must be 3 or 6, got {want}")
+
+
+def _sample_area(
+    verts: np.ndarray, tris: np.ndarray, count: int, seed: int
+) -> PointsArray:
+    mesh = trimesh.Trimesh(vertices=verts, faces=tris, process=False)
+    points, face_idx = sample_surface(mesh, count, seed=int(seed))
+    nrm = _triangle_normals(verts, tris)[np.asarray(face_idx, dtype=np.int64)]
+    out = _pack_xyz_normal(points, nrm)
+    if out.shape != (count, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"expected envelope shape {(count, ENVELOPE_FEAT_DIM)}, got {tuple(out.shape)}"
+        )
+    return out
+
+
+def sample_surface_points(
+    vertices: np.ndarray,
+    faces: np.ndarray,
+    n_surface: int,
+    *,
+    seed: int = 1,
+    cache_key: str | None = None,
+) -> PointsArray:
+    """
+    Sample ``n_surface`` envelope points as ``(N, 6)`` XYZ + unit normal.
+
+    Face-area weighted: larger triangles receive more darts. No crease
+    or fold path — unused ``envelope_mix`` on old checkpoints is ignored.
+    """
+    count = int(n_surface)
+    if count < 1:
+        raise ValueError(f"n_surface must be >= 1, got {count}")
+    verts = np.asarray(vertices, dtype=np.float64)
+    tris = np.asarray(faces, dtype=np.int64)
+    if verts.ndim != 2 or verts.shape[1] != 3:
+        raise ValueError(f"vertices must have shape (V, 3), got {tuple(verts.shape)}")
+    if tris.ndim != 2 or tris.shape[1] != 3:
+        raise ValueError(f"faces must have shape (T, 3), got {tuple(tris.shape)}")
+
+    key: tuple[str, int, int] | None = None
+    if cache_key is not None:
+        key = (str(cache_key), count, int(seed))
+        cached = _ENVELOPE_CACHE.get(key)
+        if cached is not None:
+            return cached
+
+    out = _sample_area(verts, tris, count, int(seed))
+    if out.shape != (count, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"expected envelope shape {(count, ENVELOPE_FEAT_DIM)}, got {tuple(out.shape)}"
+        )
+    if key is not None:
+        _ENVELOPE_CACHE[key] = out
+    return out

scatteringnet/geometry/trimesh_util.py

@@ -0,0 +1,19 @@
+"""Shared trimesh flatten. No Open3D — safe for train-side mesh_io."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import trimesh
+
+
+def as_trimesh(mesh: Any) -> trimesh.Trimesh:
+    """Flatten a Trimesh or a Scene of triangle meshes to one Trimesh."""
+    if isinstance(mesh, trimesh.Scene):
+        geoms = [g for g in mesh.geometry.values() if isinstance(g, trimesh.Trimesh)]
+        if not geoms:
+            raise ValueError("Scene contains no triangle meshes")
+        mesh = trimesh.util.concatenate(geoms)
+    if not isinstance(mesh, trimesh.Trimesh):
+        raise TypeError(f"Unsupported mesh type: {type(mesh)!r}")
+    return mesh

scatteringnet/infer_multi_npz.py

@@ -0,0 +1,202 @@
+"""Classify occupancy NPZs from ``models/<run_id>/best.pt``.
+
+Rebuilds ``OccupancyMLP`` or ``OccupancyEncoder`` from the checkpoint
+``kind``. Query XYZ (and envelope, when conditioned) use the stored
+per-mesh AABB, not a fresh map. Face-token checkpoints are rejected.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+
+from scatteringnet.config import OccupancyConfig, as_data_relative, load_config, repo_root
+from scatteringnet.data_npz import load_points_labels, load_points_labels_mesh
+from scatteringnet.geometry.mesh_io import load_obj_triangles
+from scatteringnet.geometry.surface import apply_envelope_aabb, project_envelope_dim, sample_surface_points
+from scatteringnet.metrics import occupancy_metrics
+from scatteringnet.normalize import apply_normalization
+from scatteringnet.occupancy_encoder import (
+    OccupancyEncoder,
+    envelope_dim_from_ckpt,
+    envelope_seed_from_ckpt,
+)
+from scatteringnet.occupancy_encoder import CHECKPOINT_KIND as ENCODER_KIND
+from scatteringnet.occupancy_mlp import OccupancyMLP
+from scatteringnet.occupancy_mlp import CHECKPOINT_KIND as MLP_KIND
+
+
+def resolve_best_pt(
+    *,
+    checkpoint: Path | str | None = None,
+    run_id: str | None = None,
+    root: Path | None = None,
+) -> Path:
+    """Resolve ``best.pt`` from an explicit path or ``runs/<id>/checkpoint_dir.txt``."""
+    base = (root or repo_root()).resolve()
+    if checkpoint is not None:
+        path = Path(checkpoint)
+        if not path.is_absolute():
+            path = base / path
+        if not path.is_file():
+            raise FileNotFoundError(f"checkpoint not found: {path}")
+        return path
+    if not run_id:
+        raise ValueError("pass checkpoint= or run_id=")
+    pointer = base / "runs" / str(run_id) / "checkpoint_dir.txt"
+    if not pointer.is_file():
+        raise FileNotFoundError(f"run pointer not found: {pointer}")
+    rel = pointer.read_text(encoding="utf-8").strip()
+    path = Path(rel)
+    if not path.is_absolute():
+        path = base / path
+    best = path / "best.pt" if path.is_dir() else path
+    if not best.is_file():
+        raise FileNotFoundError(f"best.pt not found: {best}")
+    return best
+
+
+def load_occupancy_model(
+    ckpt: dict[str, Any],
+    device: torch.device,
+) -> OccupancyMLP | OccupancyEncoder:
+    """Rebuild the head recorded in ``ckpt['kind']`` and load weights."""
+    hidden = int(ckpt["hidden"])
+    depth = int(ckpt["depth"])
+    kind = str(ckpt["kind"])
+    if kind == MLP_KIND:
+        model: OccupancyMLP | OccupancyEncoder = OccupancyMLP(hidden=hidden, depth=depth)
+    elif kind == ENCODER_KIND:
+        latent = int(ckpt["latent_dim"]) if ckpt.get("latent_dim") is not None else hidden
+        enc = str(ckpt.get("shape_encoder") or "surface").strip().lower()
+        if enc == "mesh":
+            raise ValueError(
+                "face-token occupancy checkpoints (shape_encoder='mesh') "
+                "are no longer supported"
+            )
+        knn_k = int(ckpt["knn_k"]) if ckpt.get("knn_k") is not None else 0
+        knn_local = None
+        if knn_k > 0 and ckpt.get("knn_local_dim") is not None:
+            knn_local = int(ckpt["knn_local_dim"])
+        model = OccupancyEncoder(
+            hidden=hidden,
+            depth=depth,
+            latent_dim=latent,
+            shape_encoder=enc,
+            knn_k=knn_k,
+            knn_local_dim=knn_local,
+            envelope_dim=envelope_dim_from_ckpt(ckpt),
+        )
+    else:
+        raise ValueError(f"unsupported checkpoint kind {kind!r}")
+    model.load_state_dict(ckpt["state_dict"])
+    return model.to(device).eval()
+
+
+def _part_for_npz(ckpt: dict[str, Any], npz_path: Path, data_dir: Path) -> dict[str, Any]:
+    rel = as_data_relative(npz_path, data_dir)
+    name = npz_path.name
+    for part in ckpt.get("parts") or []:
+        stored = str(part.get("npz", ""))
+        if stored == rel or Path(stored).name == name:
+            return part
+    raise KeyError(f"no AABB part for {npz_path.name} in checkpoint")
+
+
+def infer_npz(
+    cfg: OccupancyConfig,
+    *,
+    checkpoint: Path | str | None = None,
+    run_id: str | None = None,
+    npz_path: Path | str | None = None,
+    root: Path | None = None,
+) -> dict[str, float]:
+    """
+    Score one NPZ with ``best.pt``. Returns accuracy / IoU / F1.
+    """
+    ckpt_path = resolve_best_pt(checkpoint=checkpoint, run_id=run_id, root=root)
+    ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+    model = load_occupancy_model(ckpt, cfg.device)
+    if npz_path is None:
+        rels = ckpt.get("npz_paths") or []
+        if not rels:
+            raise ValueError("checkpoint has no npz_paths; pass npz_path=")
+        npz = cfg.data_dir / str(rels[0])
+    else:
+        npz = Path(npz_path)
+        if not npz.is_absolute():
+            npz = cfg.data_dir / npz
+    part = _part_for_npz(ckpt, npz, cfg.data_dir)
+    center = np.asarray(part["center"], dtype=np.float32)
+    scale = float(part["scale"])
+    geom = None
+    shape_id = None
+    enc = str(ckpt.get("shape_encoder", "none")).strip().lower()
+    if enc == "mesh":
+        raise ValueError(
+            "face-token occupancy checkpoints (shape_encoder='mesh') "
+            "are no longer supported"
+        )
+    if enc == "surface":
+        points, labels, mesh_path = load_points_labels_mesh(npz, cfg.data_dir)
+        vertices, faces = load_obj_triangles(mesh_path)
+        cache_key = str(mesh_path.resolve())
+        n_surface = int(ckpt.get("n_surface") or cfg.n_surface)
+        world = sample_surface_points(
+            vertices,
+            faces,
+            n_surface,
+            seed=envelope_seed_from_ckpt(ckpt),
+            cache_key=cache_key,
+        )
+        arr = apply_envelope_aabb(world, center, scale)
+        arr = project_envelope_dim(arr, envelope_dim_from_ckpt(ckpt))
+        geom = torch.from_numpy(arr).unsqueeze(0)
+        shape_id = torch.zeros((), dtype=torch.long)
+    else:
+        points, labels = load_points_labels(npz)
+    xyz = torch.from_numpy(apply_normalization(points, center, scale))
+    y = torch.from_numpy(np.asarray(labels, dtype=np.float32)).unsqueeze(1)
+    logits_rows: list[torch.Tensor] = []
+    with torch.no_grad():
+        for start in range(0, int(xyz.shape[0]), int(cfg.batch_size)):
+            sl = slice(start, start + int(cfg.batch_size))
+            batch_xyz = xyz[sl].to(cfg.device)
+            if geom is None:
+                logits_rows.append(model(batch_xyz).cpu())
+            else:
+                b = int(batch_xyz.shape[0])
+                geom_b = geom.expand(b, -1, -1).to(cfg.device)
+                sid = shape_id.expand(b).to(cfg.device)
+                logits_rows.append(model(batch_xyz, geom_b, sid).cpu())
+    logits = torch.cat(logits_rows, dim=0)
+    scores = occupancy_metrics(logits, y)
+    print(
+        f"checkpoint={ckpt_path} npz={npz.name} "
+        f"acc={scores.accuracy:.4f} iou={scores.inside_iou:.4f} "
+        f"f1={scores.inside_f1:.4f}"
+    )
+    return {
+        "accuracy": scores.accuracy,
+        "inside_iou": scores.inside_iou,
+        "inside_f1": scores.inside_f1,
+    }
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Infer occupancy from models/<id>/best.pt")
+    parser.add_argument("--checkpoint", default=None, help="Path to best.pt")
+    parser.add_argument("--run-id", default=None, help="runs/<id> folder name")
+    parser.add_argument("--npz", default=None, help="NPZ path (data_dir-relative or absolute)")
+    args = parser.parse_args()
+    infer_npz(
+        load_config(),
+        checkpoint=args.checkpoint,
+        run_id=args.run_id,
+        npz_path=args.npz,
+    )

scatteringnet/metrics.py

@@ -0,0 +1,156 @@
+"""Occupancy classification metrics from logits vs labels.
+
+The model emits raw logits (no sigmoid in ``forward``). Metrics apply
+sigmoid only at decision time so they stay consistent with
+``BCEWithLogitsLoss`` and with inference (threshold ``0.5``).
+
+Inside (label ``1``) is the product-relevant class: points that belong
+in the interior. Precision / recall are therefore reported for that
+class only. No extra packages (sklearn, etc.).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+from torch import Tensor
+
+
+@dataclass(frozen=True)
+class OccupancyMetrics:
+    """Pointwise occupancy scores for one batch or a full set of queries."""
+
+    accuracy: float
+    inside_precision: float
+    inside_recall: float
+    inside_iou: float
+    inside_f1: float
+
+
+def _safe_div(numerator: float, denominator: float) -> float:
+    """Return ``0.0`` when the count in the denominator is zero (no sklearn)."""
+    if denominator <= 0.0:
+        return 0.0
+    return numerator / denominator
+
+
+def _flatten_pair(logits: Tensor, labels: Tensor) -> tuple[Tensor, Tensor]:
+    """
+    Collapse ``(B, 1)`` or ``(B,)`` logits / labels to a shared 1-D view.
+
+    Last dim of logits is 1 when it comes from ``OccupancyMLP``; labels from
+    the Dataset match that. A 1-D label vector is accepted so callers do not
+    have to unsqueeze.
+    """
+    if logits.numel() != labels.numel():
+        raise ValueError(
+            f"logits and labels must have the same number of elements, "
+            f"got logits={tuple(logits.shape)} labels={tuple(labels.shape)}"
+        )
+    return logits.reshape(-1), labels.reshape(-1)
+
+
+def occupancy_metrics(
+    logits: Tensor,
+    labels: Tensor,
+    *,
+    threshold: float = 0.5,
+) -> OccupancyMetrics:
+    """
+    Accuracy plus inside precision / recall from occupancy logits.
+
+    Parameters
+    ----------
+    logits:
+        Unnormalized scores, shape ``(B, 1)`` or ``(B,)``. Positive → inside.
+    labels:
+        Float ``{0, 1}`` with the same number of elements as ``logits``.
+    threshold:
+        Decision cut on ``sigmoid(logit)``. Default ``0.5`` matches inference.
+
+    Returns
+    -------
+    OccupancyMetrics
+        Scalar floats on CPU (safe to print or average across batches).
+    """
+    # Sigmoid here only: training still uses BCE-with-logits on raw logits.
+    tp, fp, fn, correct, n = occupancy_counts(logits, labels, threshold=threshold)
+    return occupancy_metrics_from_counts(tp=tp, fp=fp, fn=fn, correct=correct, n=n)
+
+
+def occupancy_counts(
+    logits: Tensor,
+    labels: Tensor,
+    *,
+    threshold: float = 0.5,
+) -> tuple[float, float, float, float, float]:
+    """Return ``(tp, fp, fn, correct, n)`` for a micro-average over points."""
+    logits_flat, labels_flat = _flatten_pair(logits, labels)
+    pred_inside = logits_flat.sigmoid() >= threshold
+    true_inside = labels_flat > 0.5
+    pred_f = pred_inside.to(dtype=torch.float32)
+    true_f = true_inside.to(dtype=torch.float32)
+    tp = float((pred_f * true_f).sum().item())
+    fp = float((pred_f * (1.0 - true_f)).sum().item())
+    fn = float(((1.0 - pred_f) * true_f).sum().item())
+    correct = float((pred_inside == true_inside).to(dtype=torch.float32).sum().item())
+    n = float(pred_inside.numel())
+    return tp, fp, fn, correct, n
+
+
+def occupancy_metrics_from_counts(
+    *,
+    tp: float,
+    fp: float,
+    fn: float,
+    correct: float,
+    n: float,
+) -> OccupancyMetrics:
+    """Build metrics from accumulated confusion counts (point micro-average)."""
+    precision = _safe_div(tp, tp + fp)
+    recall = _safe_div(tp, tp + fn)
+    return OccupancyMetrics(
+        accuracy=_safe_div(correct, n),
+        inside_precision=precision,
+        inside_recall=recall,
+        inside_iou=_safe_div(tp, tp + fp + fn),
+        inside_f1=_safe_div(2.0 * precision * recall, precision + recall),
+    )
+
+
+def accuracy_from_logits(
+    logits: Tensor,
+    labels: Tensor,
+    *,
+    threshold: float = 0.5,
+) -> float:
+    """Fraction of points whose thresholded sigmoid matches the 0/1 label.
+
+    Parameters
+    ----------
+    logits, labels, threshold:
+        Same meaning as :func:`occupancy_metrics`.
+
+    Returns
+    -------
+    float
+        Accuracy in ``[0, 1]``.
+    """
+    return occupancy_metrics(logits, labels, threshold=threshold).accuracy
+
+
+if __name__ == "__main__":
+    # Deterministic 8-point batch: 4 true insides, 4 true outsides, all correct.
+    demo_logits = torch.tensor(
+        [[4.0], [3.0], [2.0], [1.0], [-1.0], [-2.0], [-3.0], [-4.0]]
+    )
+    demo_labels = torch.tensor(
+        [[1.0], [1.0], [1.0], [1.0], [0.0], [0.0], [0.0], [0.0]]
+    )
+    scores = occupancy_metrics(demo_logits, demo_labels)
+    print(f"accuracy={scores.accuracy:.4f}")
+    print(f"inside_precision={scores.inside_precision:.4f}")
+    print(f"inside_recall={scores.inside_recall:.4f}")
+    print(f"inside_iou={scores.inside_iou:.4f}")
+    print(f"inside_f1={scores.inside_f1:.4f}")

scatteringnet/normalize.py

@@ -0,0 +1,104 @@
+"""AABB normalization for occupancy XYZ.
+
+Maps a point cloud into a roughly ``[-1, 1]^3`` cube so the MLP sees
+comparable coordinates across differently sized meshes.
+
+  center = midpoint of the axis-aligned bounding box
+  scale  = maximum half-extent (longest AABB side / 2)
+
+Normalized point: ``(xyz - center) / scale``.
+This module does not touch the occupancy model.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+PointsArray = NDArray[np.float32]
+
+
+def compute_center_scale(points: np.ndarray) -> tuple[PointsArray, float]:
+    """
+    AABB center and max half-extent for an ``(N, 3)`` point array.
+
+    Parameters
+    ----------
+    points:
+        Query XYZ, shape ``(N, 3)``, at least one row.
+
+    Returns
+    -------
+    center:
+        ``float32`` vector of shape ``(3,)``.
+    scale:
+        Positive float (max half-extent). Raises if the cloud has no extent.
+    """
+    pts = np.asarray(points, dtype=np.float32)
+    if pts.ndim != 2 or pts.shape[1] != 3:
+        raise ValueError(f"points must have shape (N, 3), got {tuple(pts.shape)}")
+    if pts.shape[0] == 0:
+        raise ValueError("points must contain at least one row")
+
+    xyz_min = pts.min(axis=0)
+    xyz_max = pts.max(axis=0)
+    center = 0.5 * (xyz_min + xyz_max)
+    half_extents = 0.5 * (xyz_max - xyz_min)
+    scale = float(np.max(half_extents))
+    if scale <= 0.0:
+        raise ValueError(
+            "scale must be > 0; all points appear to share the same location"
+        )
+    return center.astype(np.float32, copy=False), scale
+
+
+def apply_normalization(
+    points: np.ndarray,
+    center: np.ndarray,
+    scale: float,
+) -> PointsArray:
+    """
+    Return ``(points - center) / scale`` as ``float32 (N, 3)``.
+
+    Parameters
+    ----------
+    points:
+        Query XYZ, shape ``(N, 3)``.
+    center:
+        AABB midpoint, shape ``(3,)``.
+    scale:
+        Positive max half-extent.
+
+    Returns
+    -------
+    ndarray
+        Normalized points, ``float32 (N, 3)``.
+    """
+    if scale <= 0.0:
+        raise ValueError(f"scale must be > 0, got {scale}")
+    pts = np.asarray(points, dtype=np.float32)
+    if pts.ndim != 2 or pts.shape[1] != 3:
+        raise ValueError(f"points must have shape (N, 3), got {tuple(pts.shape)}")
+    c = np.asarray(center, dtype=np.float32).reshape(3)
+    return (pts - c) / np.float32(scale)
+
+
+if __name__ == "__main__":
+    from scatteringnet.config import load_config
+    from scatteringnet.data_npz import load_points_labels
+
+    sample = (
+        load_config().data_dir
+        / "exports"
+        / "dataset_test"
+        / "sphere__raycast_z_raut_s0.15_inout.npz"
+    )
+    points, _labels = load_points_labels(sample)
+    center, scale = compute_center_scale(points)
+    normed = apply_normalization(points, center, scale)
+    recovered = normed[:3] * np.float32(scale) + center
+    print(f"file={sample}")
+    print(f"center={center.tolist()} scale={scale:.6f}")
+    print(f"normed_min={normed.min(axis=0).tolist()}")
+    print(f"normed_max={normed.max(axis=0).tolist()}")
+    print(f"inverse_ok={np.allclose(recovered, points[:3], rtol=1e-5, atol=1e-5)}")

scatteringnet/occupancy_encoder.py

@@ -0,0 +1,248 @@
+"""Geometry-conditioned occupancy: query XYZ plus a shape latent.
+
+``OccupancyMLP`` stays xyz-only. ``shape_encoder: surface`` is the
+envelope PointNet over ``(N, 6)`` XYZ + face normal (or ``(N, 3)``
+for older checkpoints). ``knn_k > 0`` adds per-query nearest-neighbor
+features (XYZ offset, plus the neighbor normal when the cloud is 6-D).
+The face-token head (``shape_encoder: mesh``) was removed.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from torch import Tensor
+
+from scatteringnet.occupancy_mlp import build_mlp
+
+# Distinct from OccupancyMLP so infer can tell the checkpoint apart.
+CHECKPOINT_KIND = "occupancy_encoder"
+
+
+class SurfaceEncoder(nn.Module):
+    """
+    Per-point MLP + max-pool (PointNet) over an envelope cloud.
+
+    Shapes
+    ------
+    envelope: ``(U, N, C)`` unique meshes; ``C`` is 3 (XYZ) or 6 (XYZ+n)
+    output:   ``(U, D)``    one latent per mesh
+    """
+
+    def __init__(
+        self, latent_dim: int = 64, hidden: int = 64, *, in_dim: int = 3
+    ) -> None:
+        super().__init__()
+        if latent_dim < 1:
+            raise ValueError(f"latent_dim must be >= 1, got {latent_dim}")
+        if hidden < 1:
+            raise ValueError(f"hidden must be >= 1, got {hidden}")
+        dim = int(in_dim)
+        if dim not in (3, 6):
+            raise ValueError(f"in_dim must be 3 or 6, got {dim}")
+        self.latent_dim = latent_dim
+        self.hidden = hidden
+        self.in_dim = dim
+        self.point_mlp = nn.Sequential(
+            nn.Linear(dim, hidden),
+            nn.ReLU(inplace=True),
+            nn.Linear(hidden, latent_dim),
+        )
+
+    def forward(self, envelope: Tensor) -> Tensor:
+        """Max-pool per-point features → one vector per unique mesh."""
+        if envelope.ndim != 3 or envelope.shape[-1] != self.in_dim:
+            raise ValueError(
+                f"envelope must have shape (U, N, {self.in_dim}), "
+                f"got {tuple(envelope.shape)}"
+            )
+        features = self.point_mlp(envelope)
+        return features.max(dim=1).values
+
+
+def knn_offsets(xyz: Tensor, envelope: Tensor, k: int) -> Tensor:
+    """
+    Offsets from each query to its ``k`` nearest envelope points.
+
+    Distances use XYZ only (AABB Euclidean). ``k`` is clamped to N.
+    If the cloud is ``(B, N, 6)``, each neighbor is
+    ``(dx, dy, dz, nx, ny, nz)`` — relative position plus that
+    neighbor's stored normal. Query points have no normal.
+
+    Shapes: ``xyz (B, 3)``, ``envelope (B, N, 3|6)`` → ``(B, k, 3|6)``.
+    """
+    if xyz.ndim != 2 or xyz.shape[-1] != 3:
+        raise ValueError(f"xyz must have shape (B, 3), got {tuple(xyz.shape)}")
+    if envelope.ndim != 3 or envelope.shape[-1] not in (3, 6):
+        raise ValueError(
+            f"envelope must have shape (B, N, 3 or 6), got {tuple(envelope.shape)}"
+        )
+    if int(xyz.shape[0]) != int(envelope.shape[0]):
+        raise ValueError(
+            f"xyz/envelope batch mismatch: {tuple(xyz.shape)} vs {tuple(envelope.shape)}"
+        )
+    n_env = int(envelope.shape[1])
+    if n_env < 1:
+        raise ValueError("envelope length N must be >= 1")
+    take = min(int(k), n_env)
+    if take < 1:
+        raise ValueError(f"k must be >= 1, got {k}")
+    feat = int(envelope.shape[-1])
+    # k-NN is position-only; extras (normals) ride along after the gather.
+    pos = envelope[..., :3]
+    dist = torch.linalg.norm(pos - xyz.unsqueeze(1), dim=-1)
+    idx = dist.topk(take, dim=-1, largest=False).indices
+    nbrs = torch.gather(envelope, 1, idx.unsqueeze(-1).expand(-1, -1, feat))
+    rel_xyz = nbrs[..., :3] - xyz.unsqueeze(1)
+    if feat == 3:
+        return rel_xyz
+    return torch.cat([rel_xyz, nbrs[..., 3:]], dim=-1)
+
+
+# Catalog trains used YAML seed 1. Old best.pt files omit ``seed``.
+DEFAULT_ENVELOPE_SEED = 1
+
+
+def envelope_seed_from_ckpt(ckpt: dict) -> int:
+    """
+    Envelope RNG seed this checkpoint was trained with.
+
+    New trains store ``seed`` on ``best.pt``. Older files omit it; do
+    not fall back to live YAML (that knob may have changed since train).
+    """
+    raw = ckpt.get("seed")
+    if raw is None:
+        return DEFAULT_ENVELOPE_SEED
+    return int(raw)
+
+
+def envelope_dim_from_ckpt(ckpt: dict) -> int:
+    """
+    Envelope channel count this checkpoint was trained with.
+
+    New trains store ``envelope_dim``. Older XYZ-only ``best.pt`` files
+    omit it; the first SurfaceEncoder Linear in-features is then 3.
+    """
+    raw = ckpt.get("envelope_dim")
+    if raw is not None:
+        dim = int(raw)
+        if dim not in (3, 6):
+            raise ValueError(f"envelope_dim must be 3 or 6, got {dim}")
+        return dim
+    weight = (ckpt.get("state_dict") or {}).get("surface.point_mlp.0.weight")
+    if weight is not None:
+        dim = int(weight.shape[1])
+        if dim in (3, 6):
+            return dim
+    return 3
+
+
+class OccupancyEncoder(nn.Module):
+    """
+    Occupancy logits from query XYZ and an envelope code.
+
+    Unique ``shape_id`` values are encoded **once** per batch, then
+    broadcast. ``knn_k > 0`` concatenates a local envelope code.
+
+    Shapes
+    ------
+    xyz:      ``(B, 3)``
+    geom:     ``(B, N, C)`` envelope; ``C`` is ``envelope_dim`` (3 or 6)
+    shape_id: ``(B,)`` long
+    output:   ``(B, 1)`` logits
+    """
+
+    def __init__(
+        self,
+        hidden: int = 64,
+        depth: int = 4,
+        latent_dim: int = 64,
+        *,
+        shape_encoder: str = "surface",
+        knn_k: int = 0,
+        knn_local_dim: int | None = None,
+        envelope_dim: int = 6,
+    ) -> None:
+        super().__init__()
+        if hidden < 1:
+            raise ValueError(f"hidden must be >= 1, got {hidden}")
+        if depth < 1:
+            raise ValueError(f"depth must be >= 1, got {depth}")
+        if latent_dim < 1:
+            raise ValueError(f"latent_dim must be >= 1, got {latent_dim}")
+        kind = str(shape_encoder).strip().lower()
+        if kind != "surface":
+            raise ValueError(
+                "OccupancyEncoder only supports shape_encoder='surface' "
+                f"(face-token 'mesh' was removed), got {shape_encoder!r}"
+            )
+        k = int(knn_k)
+        if k < 0:
+            raise ValueError(f"knn_k must be >= 0, got {k}")
+        local_dim = int(knn_local_dim) if knn_local_dim is not None else int(latent_dim)
+        if k > 0 and local_dim < 1:
+            raise ValueError(f"knn_local_dim must be >= 1, got {local_dim}")
+        ed = int(envelope_dim)
+        if ed not in (3, 6):
+            raise ValueError(f"envelope_dim must be 3 or 6, got {ed}")
+        self.hidden = hidden
+        self.depth = depth
+        self.latent_dim = latent_dim
+        self.shape_encoder = kind
+        self.knn_k = k
+        self.knn_local_dim = local_dim if k > 0 else 0
+        self.envelope_dim = ed
+        # Name ``surface`` is load-stable for existing envelope checkpoints.
+        self.surface = SurfaceEncoder(latent_dim=latent_dim, hidden=hidden, in_dim=ed)
+        self.token_dim = ed
+        head_in = 3 + latent_dim
+        if k > 0:
+            # Same PointNet block as the global envelope, over k neighbor features.
+            self.local = SurfaceEncoder(latent_dim=local_dim, hidden=hidden, in_dim=ed)
+            head_in += local_dim
+        self.head = build_mlp(head_in, hidden, depth)
+
+    def encode_unique(self, geom: Tensor, shape_id: Tensor) -> Tensor:
+        """
+        Encode each distinct ``shape_id`` once and scatter back to ``(B, D)``.
+
+        Parameters
+        ----------
+        geom, shape_id:
+            Batched envelope clouds and integer mesh ids (same length B).
+        """
+        if shape_id.ndim != 1 or int(shape_id.shape[0]) != int(geom.shape[0]):
+            raise ValueError(
+                f"shape_id must be (B,), got {tuple(shape_id.shape)} "
+                f"for geom {tuple(geom.shape)}"
+            )
+        unique_ids, inverse = torch.unique(shape_id, sorted=True, return_inverse=True)
+        hits = shape_id.unsqueeze(0) == unique_ids.unsqueeze(1)
+        first = hits.to(dtype=torch.int64).argmax(dim=1)
+        z_unique = self.surface(geom[first])
+        return z_unique[inverse]
+
+    def forward(
+        self,
+        xyz: Tensor,
+        geom: Tensor,
+        shape_id: Tensor,
+    ) -> Tensor:
+        """``cat(xyz, z_global[, z_local])`` → occupancy logit."""
+        if xyz.ndim != 2 or xyz.shape[-1] != 3:
+            raise ValueError(f"xyz must have shape (B, 3), got {tuple(xyz.shape)}")
+        if geom.ndim != 3 or geom.shape[-1] != self.token_dim:
+            raise ValueError(
+                f"geom must have shape (B, K, {self.token_dim}), got {tuple(geom.shape)}"
+            )
+        if int(xyz.shape[0]) != int(geom.shape[0]):
+            raise ValueError(
+                f"xyz/geom batch mismatch: {tuple(xyz.shape)} vs {tuple(geom.shape)}"
+            )
+        ids = shape_id.reshape(-1)
+        z_shape = self.encode_unique(geom, ids)
+        pieces = [xyz, z_shape]
+        if self.knn_k > 0:
+            rel = knn_offsets(xyz, geom, self.knn_k)
+            pieces.append(self.local(rel))
+        return self.head(torch.cat(pieces, dim=-1))

scatteringnet/occupancy_mlp.py

@@ -0,0 +1,87 @@
+"""Occupancy MLP: raw XYZ → inside/outside logit."""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from torch import Tensor
+
+# Checkpoint schema tag (not a YAML knob).
+CHECKPOINT_KIND = "occupancy_mlp"
+
+
+def build_mlp(in_dim: int, hidden: int, depth: int) -> nn.Sequential:
+    """Linear→ReLU × ``depth`` then a 1-logit head. Shared by OccupancyMLP."""
+    if in_dim < 1:
+        raise ValueError(f"in_dim must be >= 1, got {in_dim}")
+    if hidden < 1:
+        raise ValueError(f"hidden must be >= 1, got {hidden}")
+    if depth < 1:
+        raise ValueError(f"depth must be >= 1, got {depth}")
+    layers: list[nn.Module] = []
+    dim = in_dim
+    for _ in range(depth):
+        layers.append(nn.Linear(dim, hidden))
+        layers.append(nn.ReLU(inplace=True))
+        dim = hidden
+    layers.append(nn.Linear(dim, 1))
+    return nn.Sequential(*layers)
+
+
+class OccupancyMLP(nn.Module):
+    """
+    Tiny fully-connected occupancy field.
+
+    Maps a batch of 3D query coordinates to a single unnormalized logit per
+    point. A later training step will apply ``binary_cross_entropy_with_logits``
+    (do not softmax / sigmoid inside ``forward``).
+
+    Shapes
+    ------
+    xyz:    ``(B, 3)``  batch of query points (device follows the caller)
+    output: ``(B, 1)``  logits; positive → inside, negative → outside
+
+    Device
+    ------
+    Parameters live on whatever device the module was moved to
+    (``.to(device)`` / ``.cuda()``). ``xyz`` must already be on that same
+    device; this module does not copy tensors.
+    """
+
+    def __init__(self, hidden: int = 64, depth: int = 4) -> None:
+        """
+        Build Linear→ReLU blocks then a 1-logit head.
+
+        Parameters
+        ----------
+        hidden:
+            Channel width of each hidden Linear (must be ``>= 1``).
+        depth:
+            Number of hidden Linear+ReLU blocks (must be ``>= 1``).
+        """
+        super().__init__()
+        self.hidden = hidden
+        self.depth = depth
+        # First Linear is 3 → H; remaining blocks are H → H.
+        self.net = build_mlp(3, hidden, depth)
+
+    def forward(self, xyz: Tensor) -> Tensor:
+        """
+        Evaluate occupancy logits at query coordinates.
+
+        Parameters
+        ----------
+        xyz:
+            Float tensor of shape ``(B, 3)``. Last dim is Cartesian XYZ.
+
+        Returns
+        -------
+        Tensor
+            Float tensor of shape ``(B, 1)`` on the same device as ``xyz``.
+        """
+        if xyz.ndim != 2 or xyz.shape[-1] != 3:
+            raise ValueError(
+                f"xyz must have shape (B, 3), got {tuple(xyz.shape)}"
+            )
+        # Sequential Linear layers require matching dtype/device with parameters.
+        return self.net(xyz)

scatteringnet/viewer/__init__.py

@@ -0,0 +1 @@
+"""Three.js inspect helper (HTTP + Job A / Job B)."""

scatteringnet/viewer/infer_job.py

@@ -0,0 +1,536 @@
+"""Job A / B: classify uploaded points with a ``models/*/best.pt``.
+
+Reuses ``load_occupancy_model`` and AABB helpers. Envelope tokens follow
+the **checkpoint**, not live ``config.yaml``. Face-token checkpoints
+are rejected. Does not modify occupancy train/infer modules.
+"""
+
+from __future__ import annotations
+
+import base64
+import threading
+import time
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from scatteringnet.config import OccupancyConfig
+
+import numpy as np
+
+
+from scatteringnet.infer_multi_npz import load_occupancy_model  # noqa: E402
+from scatteringnet.geometry.mesh_io import load_obj_triangles  # noqa: E402
+from scatteringnet.geometry.surface import (  # noqa: E402
+    apply_envelope_aabb,
+    project_envelope_dim,
+    sample_surface_points,
+)
+from scatteringnet.metrics import occupancy_metrics  # noqa: E402
+from scatteringnet.normalize import apply_normalization, compute_center_scale  # noqa: E402
+from scatteringnet.occupancy_encoder import CHECKPOINT_KIND as ENCODER_KIND  # noqa: E402
+from scatteringnet.occupancy_encoder import envelope_dim_from_ckpt  # noqa: E402
+from scatteringnet.occupancy_encoder import envelope_seed_from_ckpt  # noqa: E402
+
+from scatteringnet.viewer.mesh_access import resolve_viewer_mesh  # noqa: E402
+from scatteringnet.viewer.model_access import match_checkpoint_part, resolve_viewer_checkpoint  # noqa: E402
+from scatteringnet.viewer.obj_fill import triangles_from_obj_text  # noqa: E402
+
+MAX_POINTS = 2_000_000
+
+# One occupancy head in this process. Same checkpoint + device → skip torch.load.
+_CACHE_LOCK = threading.Lock()
+_MODEL_CACHE: tuple[tuple[str, int, str], Any, dict[str, Any]] | None = None
+
+
+def clear_model_cache() -> None:
+    """Drop the cached head (tests / swapped GPU)."""
+    global _MODEL_CACHE
+    with _CACHE_LOCK:
+        _MODEL_CACHE = None
+
+
+def _model_cache_key(ckpt_path: Path, device: Any) -> tuple[str, int, str]:
+    stat = ckpt_path.stat()
+    return (str(ckpt_path.resolve()), int(stat.st_mtime_ns), str(device))
+
+
+def load_cached_occupancy(
+    run_id: str,
+    models_root: Path,
+    device: Any,
+) -> tuple[Any, dict[str, Any], Path, bool]:
+    """
+    Load ``best.pt`` once per (path, mtime, device).
+
+    Returns ``(model, ckpt, path, cache_hit)``. Switching run_id replaces
+    the slot so GPU RAM does not keep every inspect checkpoint.
+    """
+    import torch
+
+    ckpt_path = resolve_viewer_checkpoint(run_id, models_root)
+    key = _model_cache_key(ckpt_path, device)
+    global _MODEL_CACHE
+    with _CACHE_LOCK:
+        slot = _MODEL_CACHE
+        if slot is not None and slot[0] == key:
+            return slot[1], slot[2], ckpt_path, True
+    ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+    model = load_occupancy_model(ckpt, device)
+    with _CACHE_LOCK:
+        _MODEL_CACHE = (key, model, ckpt)
+    return model, ckpt, ckpt_path, False
+
+
+def _sync_if_cuda(device) -> None:
+    """Wait for GPU work so lap times are not just the CPU launch."""
+    import torch
+
+    dev = device if hasattr(device, "type") else torch.device(str(device))
+    if str(dev.type) == "cuda":
+        torch.cuda.synchronize()
+
+
+def _round_s(t0: float) -> float:
+    return round(time.perf_counter() - t0, 3)
+
+
+def pred_from_probs(probs: np.ndarray, threshold: float = 0.5) -> np.ndarray:
+    """Hard inside labels: 1 iff sigmoid probability is at least ``threshold``."""
+    t = float(threshold)
+    if not np.isfinite(t):
+        t = 0.5
+    t = min(1.0, max(0.0, t))
+    return (np.asarray(probs, dtype=np.float32).reshape(-1) >= t).astype(np.uint8)
+
+
+def _sigmoid_probs_and_pred(logits: Any) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Float32 sigmoid of a 1-D logit tensor, plus a 0.5-cut pred for tests/compat.
+
+    The inspect page re-cuts from ``prob_b64``; occupancy train metrics stay at 0.5.
+    """
+    import torch
+
+    probs = (
+        torch.sigmoid(logits.reshape(-1))
+        .detach()
+        .cpu()
+        .numpy()
+        .astype(np.float32, copy=False)
+    )
+    return probs, pred_from_probs(probs, 0.5)
+
+
+def aabb_for_viewer(
+    ckpt: dict[str, Any],
+    *,
+    npz_name: str,
+    mesh_path: str,
+    points: np.ndarray,
+    data_dir: Path | None,
+    vertices: np.ndarray | None = None,
+    uploaded_obj: bool = False,
+) -> tuple[np.ndarray, float, str]:
+    """
+    Checkpoint AABB when this catalog NPZ/mesh was trained; else mesh vertices.
+
+    Uploaded OBJ Fill (Job B) always uses this mesh's vertices. Catalog
+    ``parts`` matched by filename would apply another cube's box.
+    """
+    if not uploaded_obj:
+        part = match_checkpoint_part(ckpt, npz_name, mesh_path)
+        if part is not None:
+            center = np.asarray(part["center"], dtype=np.float32).reshape(3)
+            scale = float(part["scale"])
+            return center, scale, "checkpoint"
+    if vertices is not None and int(np.asarray(vertices).shape[0]) > 0:
+        center, scale = compute_center_scale(np.asarray(vertices, dtype=np.float32))
+        return center, scale, "mesh"
+    if mesh_path and data_dir is not None:
+        try:
+            resolved = resolve_viewer_mesh(mesh_path, data_dir)
+            vertices, _faces = load_obj_triangles(resolved)
+            center, scale = compute_center_scale(vertices)
+            return center, scale, "mesh"
+        except (PermissionError, FileNotFoundError, ValueError):
+            pass
+    center, scale = compute_center_scale(points)
+    return center, scale, "points"
+
+
+def _ckpt_shape_encoder(ckpt: dict[str, Any]) -> str:
+    """
+    Encoder stored on ``best.pt``, not live YAML.
+
+    Missing ``shape_encoder`` on an occupancy-encoder checkpoint is the
+    original envelope head.
+    """
+    raw = str(ckpt.get("shape_encoder") or "").strip().lower()
+    if raw in ("surface", "none"):
+        return raw
+    if raw == "mesh":
+        raise ValueError(
+            "face-token occupancy checkpoints (shape_encoder='mesh') "
+            "are no longer supported"
+        )
+    kind = str(ckpt.get("kind") or "")
+    if kind == ENCODER_KIND:
+        return "surface"
+    return "none"
+
+
+def _runtime_cfg(cfg: OccupancyConfig | None):
+    """Use the caller cfg (tests) or load repo YAML for device / batch / seed."""
+    if cfg is not None:
+        return cfg
+    from scatteringnet.config import load_config
+
+    return load_config()
+
+
+def _forward_logits(model, cfg, xyz, geom, shape_id):
+    """Batched occupancy logits. ``geom`` is envelope ``(1, N, 3)`` or ``None``."""
+    import torch
+
+    n = int(xyz.shape[0])
+    logits_rows: list[Any] = []
+    with torch.no_grad():
+        for start in range(0, n, int(cfg.batch_size)):
+            sl = slice(start, start + int(cfg.batch_size))
+            batch_xyz = xyz[sl].to(cfg.device)
+            if geom is None:
+                logits_rows.append(model(batch_xyz).cpu())
+            else:
+                b = int(batch_xyz.shape[0])
+                geom_b = geom.expand(b, -1, -1).to(cfg.device)
+                sid = shape_id.reshape(()).expand(b).to(cfg.device)
+                logits_rows.append(model(batch_xyz, geom_b, sid).cpu())
+    return torch.cat(logits_rows, dim=0)
+
+
+def _geom_from_mesh(ckpt, cfg, vertices, faces, center, scale, cache_key: str):
+    """
+    Build the envelope this checkpoint was trained with.
+
+    ``surface`` → ``(1, n_surface, C)`` envelope (C from checkpoint).
+    ``none`` → no geometry (xyz-only MLP).
+    Count comes from the checkpoint. Sampling is always area-weighted
+    (old ``envelope_mix`` on ``best.pt`` is ignored).
+    """
+    import torch
+
+    enc = _ckpt_shape_encoder(ckpt)
+    seed = envelope_seed_from_ckpt(ckpt)
+    if enc == "surface":
+        n_surface = (
+            int(ckpt["n_surface"]) if ckpt.get("n_surface") is not None else 1024
+        )
+        world = sample_surface_points(
+            vertices,
+            faces,
+            n_surface,
+            seed=seed,
+            cache_key=cache_key,
+        )
+        env = apply_envelope_aabb(world, center, scale)
+        env = project_envelope_dim(env, envelope_dim_from_ckpt(ckpt))
+        geom = torch.from_numpy(env).unsqueeze(0)
+        shape_id = torch.zeros(1, dtype=torch.long)
+        return geom, shape_id
+    return None, None
+
+
+def decode_points_b64(text: str) -> np.ndarray:
+    """Little-endian float32 XYZ from standard base64."""
+    raw = base64.b64decode(text)
+    pts = np.frombuffer(raw, dtype=np.float32)
+    if pts.size % 3 != 0:
+        raise ValueError("points buffer length is not a multiple of 3")
+    return np.ascontiguousarray(pts.reshape(-1, 3))
+
+
+def decode_labels_b64(text: str, n: int) -> np.ndarray:
+    """uint8 {0,1} labels, length ``n``."""
+    raw = base64.b64decode(text)
+    labels = np.frombuffer(raw, dtype=np.uint8)
+    if int(labels.shape[0]) != int(n):
+        raise ValueError(
+            f"labels length {labels.shape[0]} does not match points {n}"
+        )
+    return np.ascontiguousarray(labels)
+
+
+def infer_uploaded_npz(
+    *,
+    run_id: str,
+    models_root: Path,
+    data_dir: Path | None,
+    npz_name: str,
+    mesh_path: str,
+    points: np.ndarray,
+    labels: np.ndarray,
+    cfg: OccupancyConfig | None = None,
+) -> dict[str, Any]:
+    """
+    Classify ``points`` with ``best.pt``. Returns pred bytes (base64) and scores.
+
+    Envelope rebuild follows ``ckpt['shape_encoder']``.
+    """
+    import torch
+
+    n = int(points.shape[0])
+    if n < 1:
+        raise ValueError("no query points")
+    if n > MAX_POINTS:
+        raise ValueError(f"too many points ({n}; max {MAX_POINTS})")
+    if points.ndim != 2 or points.shape[1] != 3:
+        raise ValueError(f"points must be (N, 3), got {tuple(points.shape)}")
+    if int(labels.shape[0]) != n:
+        raise ValueError("labels length does not match points")
+
+    t_all = time.perf_counter()
+    t0 = time.perf_counter()
+    cfg = _runtime_cfg(cfg)
+    model, ckpt, ckpt_path, cache_hit = load_cached_occupancy(
+        run_id, models_root, cfg.device
+    )
+    _sync_if_cuda(cfg.device)
+    load_s = _round_s(t0)
+    center, scale, aabb_src = aabb_for_viewer(
+        ckpt,
+        npz_name=npz_name,
+        mesh_path=mesh_path,
+        points=points,
+        data_dir=data_dir,
+    )
+    enc = _ckpt_shape_encoder(ckpt)
+    geom = None
+    shape_id = None
+    parse_s = 0.0
+    envelope_s = 0.0
+    if enc in ("surface", "mesh"):
+        if not mesh_path:
+            raise ValueError("this checkpoint needs a mesh_path for the geometry encoder")
+        if data_dir is None:
+            raise ValueError("helper has no data_dir; cannot load the OBJ for the encoder")
+        t0 = time.perf_counter()
+        mesh_file = resolve_viewer_mesh(mesh_path, data_dir)
+        vertices, faces = load_obj_triangles(mesh_file)
+        parse_s = _round_s(t0)
+        t0 = time.perf_counter()
+        geom, shape_id = _geom_from_mesh(
+            ckpt, cfg, vertices, faces, center, scale, str(mesh_file.resolve())
+        )
+        envelope_s = _round_s(t0)
+        if geom is None:
+            raise ValueError(f"checkpoint shape_encoder={enc!r} built no geometry tokens")
+
+    t0 = time.perf_counter()
+    xyz = torch.from_numpy(apply_normalization(points, center, scale))
+    y = torch.from_numpy(labels.astype(np.float32)).unsqueeze(1)
+    logits = _forward_logits(model, cfg, xyz, geom, shape_id)
+    _sync_if_cuda(cfg.device)
+    forward_s = _round_s(t0)
+    scores = occupancy_metrics(logits, y)
+    probs, pred = _sigmoid_probs_and_pred(logits)
+    timings = {
+        "parse_obj": parse_s,
+        "load_model": load_s,
+        "envelope": envelope_s,
+        "forward": forward_s,
+        "server_total": _round_s(t_all),
+        "load_cached": cache_hit,
+        "device": str(cfg.device),
+    }
+    print(
+        "viewer infer-npz timings (s) n=%s parse=%.3f load=%.3f envelope=%.3f "
+        "forward=%.3f total=%.3f cached=%s device=%s"
+        % (
+            n,
+            parse_s,
+            load_s,
+            envelope_s,
+            forward_s,
+            timings["server_total"],
+            cache_hit,
+            cfg.device,
+        ),
+        flush=True,
+    )
+    gt = labels > 0
+    pred_bool = pred > 0
+    n_fn = int(np.count_nonzero(gt & ~pred_bool))
+    n_fp = int(np.count_nonzero(~gt & pred_bool))
+    return {
+        "pred_b64": base64.b64encode(np.ascontiguousarray(pred)).decode("ascii"),
+        "prob_b64": base64.b64encode(np.ascontiguousarray(probs)).decode("ascii"),
+        "n": n,
+        "accuracy": float(scores.accuracy),
+        "inside_iou": float(scores.inside_iou),
+        "inside_f1": float(scores.inside_f1),
+        "kind": str(ckpt.get("kind") or ""),
+        "shape_encoder": enc,
+        "aabb": aabb_src,
+        "n_error": n_fn + n_fp,
+        "n_fn": n_fn,
+        "n_fp": n_fp,
+        "run_id": Path(ckpt_path).parent.name,
+        "timings": timings,
+    }
+
+
+def infer_uploaded_obj(
+    *,
+    run_id: str,
+    models_root: Path,
+    data_dir: Path | None,
+    obj_name: str,
+    obj_text: str,
+    points: np.ndarray,
+    cfg: OccupancyConfig | None = None,
+) -> dict[str, Any]:
+    """
+    Classify fill-lattice XYZ with ``best.pt``.
+
+    Envelope tokens are built from the uploaded OBJ when the
+    checkpoint is ``surface``. No file labels (Job B): metrics are omitted.
+    """
+    import torch
+
+    n = int(points.shape[0])
+    if n < 1:
+        raise ValueError("no query points; Fill points first")
+    if n > MAX_POINTS:
+        raise ValueError(f"too many points ({n}; max {MAX_POINTS})")
+    if points.ndim != 2 or points.shape[1] != 3:
+        raise ValueError(f"points must be (N, 3), got {tuple(points.shape)}")
+
+    t_all = time.perf_counter()
+    t0 = time.perf_counter()
+    vertices, faces = triangles_from_obj_text(obj_text)
+    parse_s = _round_s(t0)
+    t0 = time.perf_counter()
+    cfg = _runtime_cfg(cfg)
+    model, ckpt, ckpt_path, cache_hit = load_cached_occupancy(
+        run_id, models_root, cfg.device
+    )
+    _sync_if_cuda(cfg.device)
+    load_s = _round_s(t0)
+    center, scale, aabb_src = aabb_for_viewer(
+        ckpt,
+        npz_name="",
+        mesh_path=str(obj_name or ""),
+        points=points,
+        data_dir=data_dir,
+        vertices=vertices,
+        uploaded_obj=True,
+    )
+    enc = _ckpt_shape_encoder(ckpt)
+    t0 = time.perf_counter()
+    geom, shape_id = _geom_from_mesh(
+        ckpt, cfg, vertices, faces, center, scale, "upload:" + str(obj_name or "obj")
+    )
+    envelope_s = _round_s(t0)
+    if enc in ("surface", "mesh") and geom is None:
+        raise ValueError(f"checkpoint shape_encoder={enc!r} built no geometry tokens")
+    t0 = time.perf_counter()
+    xyz = torch.from_numpy(apply_normalization(points, center, scale))
+    logits = _forward_logits(model, cfg, xyz, geom, shape_id)
+    _sync_if_cuda(cfg.device)
+    forward_s = _round_s(t0)
+    probs, pred = _sigmoid_probs_and_pred(logits)
+    n_in = int(np.count_nonzero(pred > 0))
+    timings = {
+        "parse_obj": parse_s,
+        "load_model": load_s,
+        "envelope": envelope_s,
+        "forward": forward_s,
+        "server_total": _round_s(t_all),
+        "load_cached": cache_hit,
+        "device": str(cfg.device),
+    }
+    print(
+        "viewer infer-obj timings (s) n=%s parse=%.3f load=%.3f envelope=%.3f "
+        "forward=%.3f total=%.3f cached=%s device=%s"
+        % (
+            n,
+            parse_s,
+            load_s,
+            envelope_s,
+            forward_s,
+            timings["server_total"],
+            cache_hit,
+            cfg.device,
+        ),
+        flush=True,
+    )
+    return {
+        "pred_b64": base64.b64encode(np.ascontiguousarray(pred)).decode("ascii"),
+        "prob_b64": base64.b64encode(np.ascontiguousarray(probs)).decode("ascii"),
+        "n": n,
+        "n_inside": n_in,
+        "n_outside": n - n_in,
+        "kind": str(ckpt.get("kind") or ""),
+        "shape_encoder": enc,
+        "aabb": aabb_src,
+        "run_id": Path(ckpt_path).parent.name,
+        "timings": timings,
+    }
+
+
+_WARM_OBJ = (
+    "v 0 0 0\nv 1 0 0\nv 0 1 0\nv 0 0 1\n"
+    "f 1 2 3\nf 1 2 4\nf 1 3 4\nf 2 3 4\n"
+)
+
+
+def warmup_viewer_helper(models_root: Path) -> None:
+    """
+    Pay first-click costs before the browser opens: torch, CUDA, trimesh
+    fill, load the INSPECT ``best.pt`` (else newest), tiny envelope + forward.
+    """
+    t0 = time.perf_counter()
+    print("warmup: torch / CUDA…", flush=True)
+    import torch
+
+    from scatteringnet.config import load_config
+    from scatteringnet.viewer.obj_fill import fill_aabb_lattice
+
+    cfg = load_config()
+    print("warmup: occupancy device=" + str(cfg.device), flush=True)
+    if str(cfg.device.type) == "cuda":
+        torch.zeros(1, device=cfg.device)
+        torch.cuda.synchronize()
+        print("warmup: CUDA " + str(cfg.device), flush=True)
+    else:
+        print("warmup: CPU only", flush=True)
+
+    print("warmup: tiny fill…", flush=True)
+    verts, faces = triangles_from_obj_text(_WARM_OBJ)
+    points, _used, _grid = fill_aabb_lattice(verts, 0.40)
+    if int(points.shape[0]) < 1:
+        points = np.array([[0.2, 0.2, 0.2], [0.8, 0.2, 0.2]], dtype=np.float32)
+
+    from scatteringnet.viewer.model_access import inspect_run_id, list_viewer_models
+
+    rows = list_viewer_models(models_root)
+    if not rows:
+        print("warmup: no models/; skip infer", flush=True)
+        print("warmup: done in %.1fs" % (time.perf_counter() - t0), flush=True)
+        return
+    ids = [str(row["id"]) for row in rows]
+    wanted = inspect_run_id()
+    # Warm the inspect alias when that folder exists; otherwise newest.
+    run_id = wanted if wanted in ids else ids[0]
+    print("warmup: infer " + run_id + "…", flush=True)
+    infer_uploaded_obj(
+        run_id=run_id,
+        models_root=models_root,
+        data_dir=None,
+        obj_name="warmup.obj",
+        obj_text=_WARM_OBJ,
+        points=points,
+        cfg=cfg,
+    )
+    print("warmup: done in %.1fs" % (time.perf_counter() - t0), flush=True)

scatteringnet/viewer/mesh_access.py

@@ -0,0 +1,52 @@
+"""Resolve NPZ ``mesh_path`` for the occupancy viewer helper.
+
+Uses :func:`data_npz.resolve_mesh_path` and then requires the file to sit
+under ``data_dir`` (no arbitrary filesystem reads).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from scatteringnet.data_npz import resolve_mesh_path
+
+
+def resolve_viewer_mesh(stored: str, data_dir: Path | str) -> Path:
+    """
+    Return an existing ``.obj`` under ``data_dir`` for a stored mesh_path.
+
+    Parameters
+    ----------
+    stored:
+        Relative or absolute path from the NPZ ``mesh_path`` array.
+    data_dir:
+        Dataset root (``config.yaml`` ``data_dir``).
+
+    Returns
+    -------
+    Path
+        Resolved OBJ path.
+
+    Raises
+    ------
+    ValueError
+        Empty path or not an OBJ.
+    FileNotFoundError
+        Mesh does not exist (from :func:`resolve_mesh_path`).
+    PermissionError
+        Resolved path is outside ``data_dir``.
+    """
+    text = str(stored).strip()
+    if not text:
+        raise ValueError("mesh_path is empty")
+    root = Path(data_dir).resolve()
+    resolved = resolve_mesh_path(text, root)
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise PermissionError(
+            f"mesh is outside data_dir: {resolved} (stored={text!r})"
+        ) from exc
+    if resolved.suffix.lower() != ".obj":
+        raise ValueError(f"mesh is not an OBJ: {resolved}")
+    return resolved

scatteringnet/viewer/model_access.py

@@ -0,0 +1,183 @@
+"""List and resolve ``models/<run_id>/best.pt`` for the occupancy viewer.
+
+Read-only: paths must stay under the repo ``models/`` folder.
+Does not import torch.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+# Repo root: this file lives at src/viewer/model_access.py.
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+# Pointers (YAML). Occupancy train / infer math does not read these.
+INSPECT_POINTER = _REPO_ROOT / "docs" / "inspect_checkpoint.yaml"
+HOLDOUT_POINTER = _REPO_ROOT / "docs" / "locked_holdout_objs.yaml"
+# Same id as the committed pointer; used if that file is missing.
+_INSPECT_FALLBACK = "2026-09-14_07-43-34_prim_extruded_nr45_knn24_n2048_n6"
+
+
+def inspect_run_id() -> str:
+    """INSPECT alias: ``run_id`` in ``docs/inspect_checkpoint.yaml``.
+
+    Viewers use this as the default ``models/<id>/best.pt`` when that file
+    exists. Occupancy train / infer math is unchanged.
+    """
+    try:
+        raw = yaml.safe_load(INSPECT_POINTER.read_text(encoding="utf-8"))
+    except OSError:
+        return _INSPECT_FALLBACK
+    if not isinstance(raw, dict):
+        return _INSPECT_FALLBACK
+    token = str(raw.get("run_id") or "").strip()
+    return token[:200] if token else _INSPECT_FALLBACK
+
+
+def locked_holdout_objs() -> list[str]:
+    """OBJ basenames from ``docs/locked_holdout_objs.yaml``.
+
+    Train / catalog construction does not consult this list. It is the
+    locked inspect set for humans and for tests.
+    """
+    try:
+        raw = yaml.safe_load(HOLDOUT_POINTER.read_text(encoding="utf-8"))
+    except OSError:
+        return []
+    if not isinstance(raw, dict):
+        return []
+    objs = raw.get("objs") or []
+    if not isinstance(objs, list):
+        return []
+    names: list[str] = []
+    for item in objs:
+        name = str(item or "").strip()
+        if name:
+            names.append(name)
+    return names
+
+
+def _shape_encoder_from_run(runs_root: Path | None, run_id: str) -> str:
+    """Read ``shape_encoder`` from ``runs/<id>/config.yaml`` (no torch)."""
+    if runs_root is None:
+        return ""
+    path = Path(runs_root) / run_id / "config.yaml"
+    try:
+        if not path.is_file():
+            return ""
+        for line in path.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#") or not stripped.startswith("shape_encoder:"):
+                continue
+            raw = stripped.split(":", 1)[1].split("#", 1)[0].strip().strip("\"'")
+            kind = raw.lower()
+            if kind in ("surface", "mesh", "none"):
+                return kind
+            return ""
+    except OSError:
+        return ""
+    return ""
+
+
+def list_viewer_models(
+    models_root: Path | str,
+    *,
+    runs_root: Path | str | None = None,
+) -> list[dict[str, str | int]]:
+    """
+    Return ``best.pt`` checkpoints one level under ``models_root``.
+
+    Each item: ``id`` (folder name), ``path`` (repo-relative), ``mtime``,
+    and ``shape_encoder`` when ``runs/<id>/config.yaml`` is present.
+    Newest first. Missing folder → empty list.
+    """
+    root = Path(models_root)
+    try:
+        root = root.resolve()
+    except OSError:
+        return []
+    if not root.is_dir():
+        return []
+    runs = Path(runs_root) if runs_root is not None else None
+    items: list[dict[str, str | int]] = []
+    for best in root.glob("*/best.pt"):
+        if not best.is_file():
+            continue
+        run_id = best.parent.name
+        try:
+            mtime = int(best.stat().st_mtime)
+        except OSError:
+            mtime = 0
+        enc = _shape_encoder_from_run(runs, run_id)
+        row: dict[str, str | int] = {
+            "id": run_id,
+            "path": "models/" + run_id + "/best.pt",
+            "mtime": mtime,
+        }
+        if enc:
+            row["shape_encoder"] = enc
+        items.append(row)
+    items.sort(key=lambda row: (-int(row["mtime"]), str(row["id"])))
+    return items
+
+
+def resolve_viewer_checkpoint(run_id: str, models_root: Path | str) -> Path:
+    """
+    Return ``models_root / <run_id> / best.pt``.
+
+    ``run_id`` is a single folder name (no slashes). Also accepts
+    ``models/<run_id>/best.pt`` and strips it down to the folder name.
+
+    Raises
+    ------
+    ValueError
+        Empty or unsafe id.
+    FileNotFoundError
+        ``best.pt`` is missing.
+    PermissionError
+        Resolved path is outside ``models_root``.
+    """
+    raw = str(run_id or "").strip().replace("\\", "/")
+    if raw.endswith("/best.pt"):
+        raw = raw[: -len("/best.pt")]
+    if raw.startswith("models/"):
+        raw = raw[len("models/") :]
+    name = raw.strip("/")
+    if not name or "/" in name or name in (".", "..") or ".." in name:
+        raise ValueError("invalid model id")
+    root = Path(models_root).resolve()
+    best = (root / name / "best.pt").resolve()
+    try:
+        best.relative_to(root)
+    except ValueError as exc:
+        raise PermissionError(
+            f"checkpoint is outside models/: {best} (id={run_id!r})"
+        ) from exc
+    if not best.is_file():
+        raise FileNotFoundError(f"best.pt not found for {name!r}")
+    return best
+
+
+def match_checkpoint_part(ckpt: dict, npz_name: str, mesh_path: str) -> dict | None:
+    """
+    Catalog AABB from ``ckpt['parts']``.
+
+    NPZ: full stored path or the occupancy filename (those stems are unique).
+    Mesh: exact stored path only. Basename matches (``cube.obj``) steal a
+    catalog box for an OOD upload of the same name — Job B must not do that.
+    """
+    parts = ckpt.get("parts") or []
+    name = Path(str(npz_name or "")).name
+    mesh = str(mesh_path or "").replace("\\", "/").strip()
+    if name:
+        for part in parts:
+            stored = str(part.get("npz") or "").replace("\\", "/")
+            if stored == name or Path(stored).name == name:
+                return part
+    if mesh:
+        for part in parts:
+            stored_m = str(part.get("mesh") or "").replace("\\", "/").strip()
+            if stored_m and stored_m == mesh:
+                return part
+    return None

scatteringnet/viewer/obj_fill.py

@@ -0,0 +1,138 @@
+"""Job B: unlabeled AABB lattice inside an uploaded OBJ (no occupancy GT).
+
+Lattice math matches ``scatter_generation.raycast_scatter`` occupancy grid
+(``_padded_bounds`` / ``_uniform_grid_points``) without importing that module
+(Open3D / package ``__init__``). Does not import torch and does not raycast-label.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+
+from scatteringnet.geometry.mesh_io import load_obj_triangles  # noqa: E402
+
+MAX_FILL_POINTS = 200_000
+SPACING_MIN = 0.04
+SPACING_MAX = 0.50
+# Slider 0 = coarse (0.40), 100 = dense (0.05). Training occupancy often uses 0.15.
+SPACING_COARSE = 0.40
+SPACING_FINE = 0.05
+
+
+def spacing_from_slider(value: float) -> float:
+    """Map UI density 0–100 to lattice spacing (higher = denser = smaller step)."""
+    t = min(1.0, max(0.0, float(value) / 100.0))
+    return float(SPACING_COARSE + (SPACING_FINE - SPACING_COARSE) * t)
+
+
+def clamp_spacing(spacing: float) -> float:
+    s = float(spacing)
+    if s < SPACING_MIN or s > SPACING_MAX:
+        raise ValueError(
+            f"spacing must be between {SPACING_MIN} and {SPACING_MAX}, got {s}"
+        )
+    return s
+
+
+def _padded_bounds(bounds: np.ndarray, pad: float) -> np.ndarray:
+    """Expand AABB by ``pad`` on every side (same as occupancy lattice)."""
+    bounds = np.asarray(bounds, dtype=np.float64)
+    out = bounds.copy()
+    out[0] -= pad
+    out[1] += pad
+    return out
+
+
+def _uniform_grid_points(
+    bounds: np.ndarray,
+    spacing: float,
+    *,
+    max_points: int = MAX_FILL_POINTS,
+) -> tuple[np.ndarray, float, tuple[int, int, int]]:
+    """Regular XYZ lattice; coarsen spacing by 1.25 until under ``max_points``."""
+    if spacing <= 0:
+        raise ValueError("point_spacing must be > 0")
+    bmin = bounds[0].astype(np.float64)
+    bmax = bounds[1].astype(np.float64)
+    extents = np.maximum(bmax - bmin, 1e-12)
+    used = float(spacing)
+
+    def counts(step: float) -> tuple[int, int, int]:
+        return tuple(max(2, int(np.floor(extents[i] / step)) + 1) for i in range(3))
+
+    nx, ny, nz = counts(used)
+    while nx * ny * nz > max_points:
+        used *= 1.25
+        nx, ny, nz = counts(used)
+
+    xs = np.linspace(bmin[0], bmax[0], nx, dtype=np.float64)
+    ys = np.linspace(bmin[1], bmax[1], ny, dtype=np.float64)
+    zs = np.linspace(bmin[2], bmax[2], nz, dtype=np.float64)
+    xx, yy, zz = np.meshgrid(xs, ys, zs, indexing="ij")
+    points = np.column_stack([xx.ravel(), yy.ravel(), zz.ravel()])
+    return points, used, (nx, ny, nz)
+
+
+def triangles_from_obj_text(text: str) -> tuple[np.ndarray, np.ndarray]:
+    """Parse Wavefront text via a temp file (same loader as training)."""
+    raw = str(text or "")
+    if not raw.strip():
+        raise ValueError("OBJ is empty")
+    fd, path = tempfile.mkstemp(suffix=".obj")
+    try:
+        os.write(fd, raw.encode("utf-8"))
+        os.close(fd)
+        fd = -1
+        return load_obj_triangles(path, cache=False)
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+
+
+def fill_aabb_lattice(
+    vertices: np.ndarray,
+    spacing: float,
+    *,
+    max_points: int = MAX_FILL_POINTS,
+) -> tuple[np.ndarray, float, tuple[int, int, int]]:
+    """
+    Regular grid in a padded mesh AABB. Pad = spacing (outside shell), no jitter.
+    """
+    step = clamp_spacing(spacing)
+    verts = np.asarray(vertices, dtype=np.float64)
+    if verts.ndim != 2 or verts.shape[1] != 3 or verts.shape[0] < 1:
+        raise ValueError(f"vertices must be (V, 3), got {tuple(verts.shape)}")
+    bounds = np.stack([verts.min(axis=0), verts.max(axis=0)])
+    sample_bounds = _padded_bounds(bounds, step)
+    points, used, grid = _uniform_grid_points(
+        sample_bounds, step, max_points=int(max_points)
+    )
+    return np.ascontiguousarray(points, dtype=np.float32), float(used), grid
+
+
+def fill_from_obj_text(
+    obj_text: str,
+    spacing: float,
+) -> dict:
+    """Return lattice points (float32) and grid metadata."""
+    vertices, _faces = triangles_from_obj_text(obj_text)
+    points, used, grid = fill_aabb_lattice(vertices, spacing)
+    return {
+        "n": int(points.shape[0]),
+        "used_spacing": used,
+        "grid": [int(grid[0]), int(grid[1]), int(grid[2])],
+        "points_b64": base64.b64encode(np.ascontiguousarray(points)).decode("ascii"),
+    }

src/__init__.py

@@ -0,0 +1 @@
+"""Occupancy fill: catalog training, encoder, and inspect helper."""

src/config.py

@@ -0,0 +1,611 @@
+"""Hybrid config loader for catalog occupancy training.
+
+Static experiment knobs live in ``config.yaml``. ``device`` is resolved
+here from CUDA availability. Training knobs (epochs, lr, batch_size,
+optimizer, catalog, val split) are YAML-owned so ``train_multi_npz``
+does not hardcode them.
+
+This module does not read ``.env`` and does not open NPZ files.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, TypedDict
+
+import torch
+import yaml
+
+# Repo root: src/config.py → parents[1].
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+_DEFAULT_YAML = _REPO_ROOT / "config.yaml"
+
+_REQUIRED_YAML_KEYS = (
+    "hidden",
+    "depth",
+    "seed",
+    "data_dir",
+    "epochs",
+    "lr",
+)
+
+
+class YamlKnobs(TypedDict):
+    """Subset of OccupancyConfig that is stored in YAML (paths as strings)."""
+
+    hidden: int
+    depth: int
+    seed: int
+    data_dir: str
+    epochs: int
+    lr: float
+    val_fraction: float
+    latent_dim: int | None
+    npz_glob: str
+    npz_paths: tuple[str, ...]
+    npz_catalog: tuple[tuple[str, int | None], ...]
+    max_files_per_shape: int | None
+    run_name: str
+    checkpoint_metric: str
+    batch_size: int
+    optimizer: str
+    n_surface: int
+    knn_k: int
+    knn_local_dim: int | None
+    shape_encoder: str
+    # Explicit BCE pos_weight; None when omitted or when auto is set.
+    pos_weight: float | None
+    pos_weight_auto: bool
+
+
+def get_device() -> torch.device:
+    """
+    CUDA when a GPU is visible; otherwise CPU.
+
+    Hugging Face CPU Spaces have no CUDA: infer still runs (slower).
+    ``SCATTERINGNET_DEVICE=cpu`` forces CPU even if a GPU exists.
+    ``SCATTERINGNET_DEVICE=cuda`` uses CUDA only when ``is_available()``;
+    otherwise it falls back to CPU (no crash).
+
+    Training scripts should still warn on a long catalog run on CPU.
+    """
+    forced = os.environ.get("SCATTERINGNET_DEVICE", "").strip().lower()
+    if forced == "cpu":
+        return torch.device("cpu")
+    if forced == "cuda":
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        return torch.device("cpu")
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    return torch.device("cpu")
+
+
+def repo_root() -> Path:
+    """Git / project root (folder that contains ``src/`` and ``config.yaml``)."""
+    return _REPO_ROOT
+
+
+def gpu_name(device: torch.device | None = None) -> str | None:
+    """
+    Human GPU name for the run snapshot (``None`` on CPU).
+
+    Uses ``cfg.device`` when given so a forced-CPU train does not stamp a
+    card that was not used.
+    """
+    dev = device if device is not None else get_device()
+    if dev.type != "cuda" or not torch.cuda.is_available():
+        return None
+    index = 0 if dev.index is None else int(dev.index)
+    if index < 0 or index >= torch.cuda.device_count():
+        return None
+    name = str(torch.cuda.get_device_name(index)).strip()
+    return name or None
+
+
+def _as_positive_int(name: str, value: Any) -> int:
+    """YAML may yield int or (rarely) str; occupancy dims must be int >= 1."""
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be an integer, got {value!r}") from exc
+    if parsed < 1:
+        raise ValueError(f"{name} must be >= 1, got {parsed}")
+    return parsed
+
+
+def _as_int_in_range(name: str, value: Any, lo: int, hi: int) -> int:
+    """Inclusive integer range (YAML ``knn_k`` is 0–4096)."""
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be an integer, got {value!r}") from exc
+    if parsed < lo or parsed > hi:
+        raise ValueError(f"{name} must be in [{lo}, {hi}], got {parsed}")
+    return parsed
+
+
+def _as_positive_float(name: str, value: Any) -> float:
+    """Learning-rate style knobs must be a finite float > 0."""
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a float, got {value!r}") from exc
+    if parsed <= 0.0 or parsed != parsed:
+        raise ValueError(f"{name} must be > 0, got {parsed}")
+    return parsed
+
+
+def _as_pos_weight_pair(raw: Mapping[str, Any]) -> tuple[float | None, bool]:
+    """
+    YAML ``pos_weight``: omit / null → unweighted BCE.
+
+    ``auto`` → compute n_outside / n_inside on the train split at train time.
+    A finite float > 0 is used as-is (1.0 is unweighted).
+    """
+    if "pos_weight" not in raw:
+        return None, False
+    value = raw["pos_weight"]
+    if value is None or value is False:
+        return None, False
+    if isinstance(value, str):
+        text = value.strip().lower()
+        if text in ("", "none", "off", "false"):
+            return None, False
+        if text == "auto":
+            return None, True
+    parsed = _as_positive_float("pos_weight", value)
+    return parsed, False
+
+
+def _as_open_unit_interval(name: str, value: Any) -> float:
+    """Hold-out fractions must be in (0, 1) so both splits are non-empty."""
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a float, got {value!r}") from exc
+    if parsed != parsed or parsed <= 0.0 or parsed >= 1.0:
+        raise ValueError(f"{name} must be in (0, 1), got {parsed}")
+    return parsed
+
+
+def _as_nonempty_path_string(name: str, value: Any) -> str:
+    if value is None or (isinstance(value, str) and not value.strip()):
+        raise ValueError(f"{name} must be a non-empty path string in config.yaml")
+    return str(value).strip()
+
+
+def _as_data_dir_string(value: Any) -> str:
+    return _as_nonempty_path_string("data_dir", value)
+
+
+def _as_optional_positive_int(name: str, value: Any) -> int | None:
+    """YAML null → unlimited catalog cap; otherwise int >= 1."""
+    if value is None:
+        return None
+    return _as_positive_int(name, value)
+
+
+def _as_run_name(value: Any) -> str:
+    """Optional YAML suffix for ``runs/<timestamp>_<name>/``; empty → ``run``."""
+    if value is None:
+        return "run"
+    text = str(value).strip()
+    return text if text else "run"
+
+
+_CHECKPOINT_METRIC_ALIASES = {
+    "test_acc": "val_acc",
+    "test_iou": "val_iou",
+}
+
+
+def _as_checkpoint_metric(value: Any) -> str:
+    """Name of the scalar used to decide ``best.pt`` (strict improve)."""
+    if value is None or (isinstance(value, str) and not value.strip()):
+        raise ValueError("checkpoint_metric must be a non-empty string")
+    name = str(value).strip()
+    return _CHECKPOINT_METRIC_ALIASES.get(name, name)
+
+
+def _as_val_fraction(raw: Mapping[str, Any]) -> float:
+    """Prefer ``val_fraction``; accept legacy ``test_fraction``."""
+    if "val_fraction" in raw:
+        return _as_open_unit_interval("val_fraction", raw["val_fraction"])
+    if "test_fraction" in raw:
+        return _as_open_unit_interval("test_fraction", raw["test_fraction"])
+    raise ValueError("Config YAML missing keys: val_fraction")
+
+
+def _as_optional_latent_dim(raw: Mapping[str, Any]) -> int | None:
+    """YAML omit / null → use ``hidden`` at train time."""
+    if "latent_dim" not in raw or raw["latent_dim"] is None:
+        return None
+    return _as_positive_int("latent_dim", raw["latent_dim"])
+
+
+# Names accepted in config.yaml ``optimizer``. Used by train_multi_npz.
+_ALLOWED_OPTIMIZERS = ("adam", "adamw", "sgd")
+# ``none`` = OccupancyMLP (xyz only). ``surface`` = envelope encoder.
+_ALLOWED_SHAPE_ENCODERS = ("none", "surface")
+
+
+def _as_optimizer(value: Any) -> str:
+    """Optimizer family for multi-NPZ train; default Adam."""
+    if value is None or (isinstance(value, str) and not str(value).strip()):
+        return "adam"
+    name = str(value).strip().lower()
+    if name not in _ALLOWED_OPTIMIZERS:
+        allowed = ", ".join(_ALLOWED_OPTIMIZERS)
+        raise ValueError(f"optimizer must be one of {allowed}, got {value!r}")
+    return name
+
+
+def _as_shape_encoder(value: Any) -> str:
+    """Occupancy head family; default xyz-only so older YAML still loads."""
+    if value is None or (isinstance(value, str) and not str(value).strip()):
+        return "none"
+    name = str(value).strip().lower()
+    if name not in _ALLOWED_SHAPE_ENCODERS:
+        allowed = ", ".join(_ALLOWED_SHAPE_ENCODERS)
+        raise ValueError(f"shape_encoder must be one of {allowed}, got {value!r}")
+    return name
+
+
+def _as_npz_paths(value: Any) -> tuple[str, ...]:
+    """Explicit NPZ list relative to data_dir (empty → use glob)."""
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        item = value.strip()
+        return (item,) if item else ()
+    if not isinstance(value, list):
+        raise ValueError(f"npz_paths must be a list of strings or null, got {type(value).__name__}")
+    out: list[str] = []
+    for i, raw in enumerate(value):
+        text = _as_nonempty_path_string(f"npz_paths[{i}]", raw)
+        out.append(text)
+    return tuple(out)
+
+
+def _as_npz_catalog(value: Any) -> tuple[tuple[str, int | None], ...]:
+    """Union of globs; optional ``max_shapes`` is unique meshes per glob."""
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise ValueError(
+            f"npz_catalog must be a list or null, got {type(value).__name__}"
+        )
+    out: list[tuple[str, int | None]] = []
+    for i, raw in enumerate(value):
+        if isinstance(raw, str):
+            glob_s = _as_nonempty_path_string(f"npz_catalog[{i}]", raw)
+            out.append((glob_s, None))
+            continue
+        if not isinstance(raw, Mapping):
+            raise ValueError(
+                f"npz_catalog[{i}] must be a glob string or mapping, "
+                f"got {type(raw).__name__}"
+            )
+        if "glob" not in raw:
+            raise ValueError(f"npz_catalog[{i}] missing glob")
+        glob_s = _as_nonempty_path_string(f"npz_catalog[{i}].glob", raw["glob"])
+        max_shapes: int | None = None
+        if "max_shapes" in raw and raw["max_shapes"] is not None:
+            max_shapes = _as_positive_int(
+                f"npz_catalog[{i}].max_shapes", raw["max_shapes"]
+            )
+        out.append((glob_s, max_shapes))
+    return tuple(out)
+
+
+def as_repo_relative(path: Path | str, *, root: Path | None = None) -> str:
+    """
+    POSIX string relative to the git repo when ``path`` is inside it.
+
+    Already-relative inputs are returned as POSIX. Absolute paths on another
+    drive (the dataset disk) cannot be repo-relative and stay absolute POSIX.
+    """
+    text = str(path).strip()
+    if not text:
+        return text
+    parsed = Path(text)
+    if not parsed.is_absolute():
+        return parsed.as_posix()
+    base = (root or _REPO_ROOT).resolve()
+    try:
+        return parsed.resolve().relative_to(base).as_posix()
+    except ValueError:
+        return parsed.resolve().as_posix()
+
+
+def as_data_relative(path: Path | str, data_dir: Path | str) -> str:
+    """
+    POSIX string relative to ``data_dir`` (``exports/...``, not ``E:/...``).
+
+    Already-relative inputs are returned as POSIX. Paths outside ``data_dir``
+    (unit-test temp trees) fall back to absolute POSIX.
+    """
+    text = str(path).strip()
+    if not text:
+        return text
+    parsed = Path(text)
+    if not parsed.is_absolute():
+        return parsed.as_posix()
+    root = Path(data_dir).expanduser().resolve()
+    resolved = parsed.expanduser().resolve()
+    try:
+        return resolved.relative_to(root).as_posix()
+    except ValueError:
+        return resolved.as_posix()
+
+
+def load_yaml_knobs(path: Path) -> YamlKnobs:
+    """
+    Read YAML settings. Does not check that data_dir exists on disk.
+
+    Parameters
+    ----------
+    path:
+        Path to ``config.yaml``.
+
+    Returns
+    -------
+    YamlKnobs
+        Typed dict of experiment knobs (paths still strings).
+    """
+    if not path.is_file():
+        raise FileNotFoundError(f"Config YAML not found: {path}")
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, Mapping):
+        raise ValueError(f"Config YAML must be a mapping, got {type(raw).__name__}")
+    missing = [k for k in _REQUIRED_YAML_KEYS if k not in raw]
+    if missing:
+        raise ValueError(f"Config YAML missing keys: {', '.join(missing)}")
+    pos_weight, pos_weight_auto = _as_pos_weight_pair(raw)
+    return {
+        "hidden": _as_positive_int("hidden", raw["hidden"]),
+        "depth": _as_positive_int("depth", raw["depth"]),
+        "seed": _as_positive_int("seed", raw["seed"]),
+        "data_dir": _as_data_dir_string(raw["data_dir"]),
+        "epochs": _as_positive_int("epochs", raw["epochs"]),
+        "lr": _as_positive_float("lr", raw["lr"]),
+        "val_fraction": _as_val_fraction(raw),
+        "latent_dim": _as_optional_latent_dim(raw),
+        "npz_glob": (
+            _as_nonempty_path_string("npz_glob", raw["npz_glob"])
+            if "npz_glob" in raw
+            else "exports/dataset/*.npz"
+        ),
+        "npz_paths": _as_npz_paths(raw.get("npz_paths")),
+        "npz_catalog": _as_npz_catalog(raw.get("npz_catalog")),
+        "max_files_per_shape": (
+            _as_optional_positive_int("max_files_per_shape", raw["max_files_per_shape"])
+            if "max_files_per_shape" in raw
+            else 2
+        ),
+        "run_name": (
+            _as_run_name(raw["run_name"]) if "run_name" in raw else "run"
+        ),
+        "checkpoint_metric": (
+            _as_checkpoint_metric(raw["checkpoint_metric"])
+            if "checkpoint_metric" in raw
+            else "val_acc"
+        ),
+        "batch_size": (
+            _as_positive_int("batch_size", raw["batch_size"])
+            if "batch_size" in raw
+            else 1024
+        ),
+        "optimizer": (
+            _as_optimizer(raw["optimizer"]) if "optimizer" in raw else "adam"
+        ),
+        "n_surface": (
+            _as_positive_int("n_surface", raw["n_surface"])
+            if "n_surface" in raw
+            else 1024
+        ),
+        "knn_k": (
+            _as_int_in_range("knn_k", raw["knn_k"], 0, 4096)
+            if "knn_k" in raw
+            else 0
+        ),
+        "knn_local_dim": (
+            _as_positive_int("knn_local_dim", raw["knn_local_dim"])
+            if "knn_local_dim" in raw
+            else None
+        ),
+        "shape_encoder": (
+            _as_shape_encoder(raw["shape_encoder"])
+            if "shape_encoder" in raw
+            else "none"
+        ),
+        "pos_weight": pos_weight,
+        "pos_weight_auto": pos_weight_auto,
+    }
+
+
+def _warn_missing_data_dir(data_dir: Path, yaml_path: Path) -> None:
+    """Print a terminal hint so the user can fix config.yaml (no .env involved)."""
+    print(
+        "\n"
+        "Dataset folder not found.\n"
+        f"  Looked for: {data_dir}\n"
+        "\n"
+        "Update `data_dir` in config.yaml to the folder that contains "
+        "`exports/` and `meshes/`.\n"
+        f"  Config file: {yaml_path}\n"
+    )
+
+
+def require_data_dir(data_dir: Path, *, yaml_path: Path) -> None:
+    """Validate the dataset root before training or NPZ loading."""
+    if data_dir.is_dir():
+        return
+    _warn_missing_data_dir(data_dir, yaml_path)
+    raise FileNotFoundError(
+        f"Dataset directory does not exist: {data_dir}. "
+        f"Set data_dir in {yaml_path}."
+    )
+
+
+@dataclass(frozen=True)
+class OccupancyConfig:
+    """Resolved experiment settings from YAML plus detected device."""
+
+    data_dir: Path
+    device: torch.device
+    hidden: int
+    depth: int
+    seed: int
+    epochs: int
+    lr: float
+    # Fraction of catalog **meshes** held out as val (selection split, not a locked test).
+    val_fraction: float
+    # Catalog knobs (optional in YAML; omitted keys keep these defaults).
+    npz_glob: str = "exports/dataset/*.npz"
+    npz_paths: tuple[str, ...] = ()
+    # ``(glob, max_shapes)`` rows. Empty → use ``npz_glob``. ``max_shapes``
+    # None keeps every mesh that glob hits (after ``max_files_per_shape``).
+    npz_catalog: tuple[tuple[str, int | None], ...] = ()
+    max_files_per_shape: int | None = 2
+    # Suffix for runs/<timestamp>_<name>/ (device stays runtime-only).
+    run_name: str = "run"
+    # Which logged scalar selects best.pt (strict improve).
+    checkpoint_metric: str = "val_acc"
+    # Encoder latent width; None → use ``hidden`` at train / infer time.
+    latent_dim: int | None = None
+    # Mini-batch size and optimizer family (train_multi_npz).
+    batch_size: int = 1024
+    optimizer: str = "adam"
+    # Envelope sample count (YAML). Used when ``shape_encoder`` is ``surface``.
+    n_surface: int = 1024
+    # 0 = global envelope z only. >0 = that many nearest envelope dots per query.
+    knn_k: int = 0
+    # Width of z_local; None → same as occupancy latent_dim / hidden.
+    knn_local_dim: int | None = None
+    # ``none`` keeps OccupancyMLP; ``surface`` uses the envelope PointNet.
+    shape_encoder: str = "none"
+    # BCE inside-class weight. None + auto=False = unweighted (legacy).
+    pos_weight: float | None = None
+    pos_weight_auto: bool = False
+
+
+def load_config(
+    yaml_path: Path | None = None,
+    *,
+    require_existing_data_dir: bool = True,
+) -> OccupancyConfig:
+    """
+    Compose OccupancyConfig from ``config.yaml`` (not from ``.env``).
+
+    When ``require_existing_data_dir`` is True (default), a missing folder
+    prints a short instruction and then raises FileNotFoundError — used for
+    training and data loading.
+
+    Parameters
+    ----------
+    yaml_path:
+        Config file; default is repo-root ``config.yaml``.
+    require_existing_data_dir:
+        If True, refuse to return a config whose ``data_dir`` is missing.
+
+    Returns
+    -------
+    OccupancyConfig
+        YAML knobs plus detected ``device``.
+    """
+    cfg_path = yaml_path or _DEFAULT_YAML
+    knobs = load_yaml_knobs(cfg_path)
+    data_dir = Path(knobs["data_dir"])
+    if require_existing_data_dir:
+        require_data_dir(data_dir, yaml_path=cfg_path)
+    return OccupancyConfig(
+        data_dir=data_dir,
+        device=get_device(),
+        hidden=knobs["hidden"],
+        depth=knobs["depth"],
+        seed=knobs["seed"],
+        epochs=knobs["epochs"],
+        lr=knobs["lr"],
+        val_fraction=knobs["val_fraction"],
+        latent_dim=knobs["latent_dim"],
+        npz_glob=knobs["npz_glob"],
+        npz_paths=knobs["npz_paths"],
+        npz_catalog=knobs["npz_catalog"],
+        max_files_per_shape=knobs["max_files_per_shape"],
+        run_name=knobs["run_name"],
+        checkpoint_metric=knobs["checkpoint_metric"],
+        batch_size=knobs["batch_size"],
+        optimizer=knobs["optimizer"],
+        n_surface=knobs["n_surface"],
+        knn_k=knobs["knn_k"],
+        knn_local_dim=knobs["knn_local_dim"],
+        shape_encoder=knobs["shape_encoder"],
+        pos_weight=knobs["pos_weight"],
+        pos_weight_auto=knobs["pos_weight_auto"],
+    )
+
+
+def encoder_latent_dim(cfg: OccupancyConfig) -> int:
+    """OccupancyEncoder ``z`` width: YAML ``latent_dim`` or ``hidden``."""
+    if cfg.latent_dim is None:
+        return int(cfg.hidden)
+    return int(cfg.latent_dim)
+
+
+def encoder_knn_local_dim(cfg: OccupancyConfig) -> int:
+    """Local envelope code width: YAML ``knn_local_dim`` or global latent."""
+    if cfg.knn_local_dim is None:
+        return encoder_latent_dim(cfg)
+    return int(cfg.knn_local_dim)
+
+
+def format_config(cfg: OccupancyConfig) -> str:
+    """
+    Pretty-print for CLI smoke checks.
+
+    Parameters
+    ----------
+    cfg:
+        Resolved config.
+
+    Returns
+    -------
+    str
+        Multi-line ``OccupancyConfig(...)`` dump.
+    """
+    return (
+        f"OccupancyConfig(\n"
+        f"  data_dir={cfg.data_dir}\n"
+        f"  device={cfg.device}\n"
+        f"  gpu={gpu_name(cfg.device)}\n"
+        f"  hidden={cfg.hidden}\n"
+        f"  depth={cfg.depth}\n"
+        f"  seed={cfg.seed}\n"
+        f"  epochs={cfg.epochs}\n"
+        f"  lr={cfg.lr}\n"
+        f"  val_fraction={cfg.val_fraction}\n"
+        f"  latent_dim={cfg.latent_dim}\n"
+        f"  npz_glob={cfg.npz_glob}\n"
+        f"  npz_paths={list(cfg.npz_paths)}\n"
+        f"  npz_catalog={list(cfg.npz_catalog)}\n"
+        f"  max_files_per_shape={cfg.max_files_per_shape}\n"
+        f"  run_name={cfg.run_name}\n"
+        f"  checkpoint_metric={cfg.checkpoint_metric}\n"
+        f"  batch_size={cfg.batch_size}\n"
+        f"  optimizer={cfg.optimizer}\n"
+        f"  n_surface={cfg.n_surface}\n"
+        f"  knn_k={cfg.knn_k}\n"
+        f"  knn_local_dim={cfg.knn_local_dim}\n"
+        f"  shape_encoder={cfg.shape_encoder}\n"
+        f"  pos_weight={cfg.pos_weight}\n"
+        f"  pos_weight_auto={cfg.pos_weight_auto}\n"
+        f")"
+    )
+
+
+if __name__ == "__main__":
+    print(format_config(load_config()))

src/data_npz.py

@@ -0,0 +1,460 @@
+"""Load occupancy query points and labels from scatter NPZ files.
+
+:func:`load_points_labels` reads **one** file. A catalog resolver lists
+many NPZs (glob or explicit paths) without training.
+
+``load_points_labels`` still returns only ``points`` and ``labels``.
+``load_points_labels_mesh`` also resolves ``mesh_path`` against ``data_dir``.
+"""
+
+from __future__ import annotations
+
+import glob as globlib
+import random
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+# Labels are converted here (not deferred to the Dataset) so every caller gets
+# the same dtypes: float32 XYZ and float32 {0, 1} occupancy.
+PointsArray = NDArray[np.float32]
+LabelsArray = NDArray[np.float32]
+
+
+def load_points_labels(path: Path) -> tuple[PointsArray, LabelsArray]:
+    """
+    Read query coordinates and inside/outside labels from one NPZ file.
+
+    Parameters
+    ----------
+    path:
+        Path to a ``.npz`` with arrays ``points`` ``(N, 3)`` and
+        ``labels`` ``(N,)`` (typically uint8 0/1).
+
+    Returns
+    -------
+    points:
+        ``float32`` array of shape ``(N, 3)``.
+    labels:
+        ``float32`` array of shape ``(N,)`` with values in ``{0.0, 1.0}``
+        (0 = outside, 1 = inside).
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+
+    # allow_pickle=False: we only need numeric arrays, not object payloads.
+    with np.load(npz_path, allow_pickle=False) as raw:
+        files = set(raw.files)
+        if "points" not in files or "labels" not in files:
+            raise KeyError(
+                f"NPZ must contain 'points' and 'labels', got {sorted(files)} "
+                f"in {npz_path}"
+            )
+        points = np.asarray(raw["points"])
+        labels = np.asarray(raw["labels"])
+
+    if points.ndim != 2 or points.shape[1] != 3:
+        raise ValueError(
+            f"points must have shape (N, 3), got {tuple(points.shape)} in {npz_path}"
+        )
+    n = int(points.shape[0])
+    if labels.shape != (n,):
+        raise ValueError(
+            f"labels must have shape (N,) with N={n}, got {tuple(labels.shape)} "
+            f"in {npz_path}"
+        )
+
+    points_f32 = np.asarray(points, dtype=np.float32)
+    labels_f32 = np.asarray(labels, dtype=np.float32)
+    unique = np.unique(labels_f32)
+    if not np.all((unique == 0.0) | (unique == 1.0)):
+        raise ValueError(
+            f"labels must be in {{0, 1}}, got unique={unique.tolist()} in {npz_path}"
+        )
+    return points_f32, labels_f32
+
+
+def count_npz_points(path: Path | str) -> int:
+    """
+    Query count in one NPZ without keeping the arrays.
+
+    Catalog construct uses this so ``len(part)`` / ``n_points`` do not
+    require loading every lattice into RAM.
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+    with np.load(npz_path, allow_pickle=False) as raw:
+        files = set(raw.files)
+        if "points" not in files or "labels" not in files:
+            raise KeyError(
+                f"NPZ must contain 'points' and 'labels', got {sorted(files)} "
+                f"in {npz_path}"
+            )
+        n = int(np.asarray(raw["points"]).shape[0])
+        n_y = int(np.asarray(raw["labels"]).shape[0])
+    if n_y != n:
+        raise ValueError(
+            f"labels must have shape (N,) with N={n}, got N={n_y} in {npz_path}"
+        )
+    return n
+
+
+def count_npz_labels(path: Path | str) -> tuple[int, int]:
+    """
+    Outside / inside counts in one NPZ without keeping the point cloud.
+
+    Used for ``pos_weight: auto`` (n_outside / n_inside on the train split).
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+    with np.load(npz_path, allow_pickle=False) as raw:
+        if "labels" not in set(raw.files):
+            raise KeyError(f"NPZ must contain 'labels', got {sorted(raw.files)} in {npz_path}")
+        labels = np.asarray(raw["labels"]).reshape(-1)
+    # Labels are 0/1 occupancy; nonzero is inside.
+    n_in = int(np.count_nonzero(labels))
+    n_out = int(labels.size) - n_in
+    return n_out, n_in
+
+
+def read_npz_mesh_path(path: Path | str) -> str:
+    """
+    Read the stored ``mesh_path`` string from one occupancy NPZ.
+
+    Step 2 writes a ``data_dir``-relative POSIX path (for example
+    ``meshes/Primitives/Sphere/sphere_r0p5_sa16_sh16.obj``).
+
+    Parameters
+    ----------
+    path:
+        Occupancy ``.npz`` that contains ``mesh_path``.
+
+    Returns
+    -------
+    str
+        Stored path string (relative or absolute). Not resolved here.
+    """
+    npz_path = Path(path)
+    if not npz_path.is_file():
+        raise FileNotFoundError(f"NPZ not found: {npz_path}")
+    # allow_pickle=True: some exports store a 0-d string / object array.
+    with np.load(npz_path, allow_pickle=True) as raw:
+        if "mesh_path" not in raw.files:
+            raise KeyError(f"NPZ has no 'mesh_path' in {npz_path}")
+        stored = str(np.asarray(raw["mesh_path"]).item()).strip()
+    if not stored:
+        raise ValueError(f"mesh_path is empty in {npz_path}")
+    return stored
+
+
+def resolve_mesh_path(stored: str, data_dir: Path | str) -> Path:
+    """
+    Resolve a stored ``mesh_path`` against ``data_dir``.
+
+    Relative entries are joined to ``data_dir``. Absolute entries are
+    used as-is. Missing files raise ``FileNotFoundError``.
+
+    Parameters
+    ----------
+    stored:
+        Value from :func:`read_npz_mesh_path`.
+    data_dir:
+        Dataset root (``config.yaml`` ``data_dir``).
+
+    Returns
+    -------
+    Path
+        Existing resolved mesh file.
+    """
+    text = str(stored).strip()
+    if not text:
+        raise ValueError("mesh_path is empty")
+    item = Path(text)
+    root = Path(data_dir)
+    resolved = item if item.is_absolute() else (root / item)
+    resolved = resolved.resolve()
+    if not resolved.is_file():
+        raise FileNotFoundError(f"mesh not found: {resolved} (stored={text!r})")
+    return resolved
+
+
+def load_points_labels_mesh(
+    path: Path | str,
+    data_dir: Path | str,
+) -> tuple[PointsArray, LabelsArray, Path]:
+    """
+    Read occupancy arrays and resolve the source OBJ.
+
+    Keeps :func:`load_points_labels` unchanged (xyz + labels only).
+
+    Parameters
+    ----------
+    path:
+        Occupancy ``.npz`` with ``points``, ``labels``, and ``mesh_path``.
+    data_dir:
+        Root used to resolve a relative ``mesh_path``.
+
+    Returns
+    -------
+    points, labels, mesh_path:
+        Same arrays as :func:`load_points_labels`, plus the existing OBJ.
+    """
+    npz_path = Path(path)
+    points, labels = load_points_labels(npz_path)
+    stored = read_npz_mesh_path(npz_path)
+    mesh_path = resolve_mesh_path(stored, data_dir)
+    return points, labels, mesh_path
+
+
+def _is_combo_npz(path: Path) -> bool:
+    """True when the filename looks like a combo dump (excluded from the catalog)."""
+    return "combo" in path.name.lower()
+
+
+def shape_key(path: Path) -> str:
+    """
+    Group NPZs that belong to the same mesh.
+
+    Uses the stem before ``__`` (dataset_builder tag), else the full stem.
+
+    Parameters
+    ----------
+    path:
+        NPZ path.
+
+    Returns
+    -------
+    str
+        Stable key for ``max_files_per_shape``.
+    """
+    stem = Path(path).stem
+    if "__" in stem:
+        return stem.split("__", 1)[0]
+    return stem
+
+
+def _cap_per_shape(
+    paths: Sequence[Path],
+    max_files_per_shape: int | None,
+) -> list[Path]:
+    """Keep at most ``max_files_per_shape`` files per :func:`shape_key` (sorted order)."""
+    if max_files_per_shape is None:
+        return list(paths)
+    if max_files_per_shape < 1:
+        raise ValueError(f"max_files_per_shape must be >= 1 or None, got {max_files_per_shape}")
+    counts: dict[str, int] = {}
+    out: list[Path] = []
+    for path in paths:
+        key = shape_key(path)
+        taken = counts.get(key, 0)
+        if taken >= max_files_per_shape:
+            continue
+        counts[key] = taken + 1
+        out.append(path)
+    return out
+
+
+def _glob_npz(root: Path, pattern: str) -> list[Path]:
+    """Match ``pattern`` under ``root`` (``*`` / ``**``)."""
+    full = str(root / pattern)
+    recursive = "**" in pattern.replace("\\", "/")
+    found = globlib.glob(full, recursive=recursive)
+    return [Path(p).resolve() for p in found if Path(p).is_file()]
+
+
+def _is_parameterized_stem(path: Path) -> bool:
+    """
+    Maya catalog names are ``family_param_...``. Varied one-off stems
+    (``Cone.obj`` → ``Cone__occupancy.npz``) have no ``_`` in the shape key
+    and must not ride along when Windows glob is case-insensitive.
+    """
+    return "_" in shape_key(path)
+
+
+def _subsample_shapes(
+    paths: Sequence[Path],
+    max_shapes: int,
+    seed: int,
+) -> list[Path]:
+    """Keep NPZs for at most ``max_shapes`` unique :func:`shape_key` values."""
+    if max_shapes < 1:
+        raise ValueError(f"max_shapes must be >= 1, got {max_shapes}")
+    keys: list[str] = []
+    seen: set[str] = set()
+    for path in paths:
+        key = shape_key(path)
+        if key in seen:
+            continue
+        seen.add(key)
+        keys.append(key)
+    if max_shapes >= len(keys):
+        return list(paths)
+    # Sort then sample so the same seed always picks the same meshes.
+    chosen_keys = set(random.Random(int(seed)).sample(sorted(keys), max_shapes))
+    return [path for path in paths if shape_key(path) in chosen_keys]
+
+
+def resolve_npz_catalog(
+    data_dir: Path | str,
+    *,
+    npz_glob: str = "exports/dataset/*.npz",
+    npz_paths: Sequence[str | Path] | None = None,
+    npz_catalog: Sequence[tuple[str, int | None]] | None = None,
+    max_files_per_shape: int | None = 2,
+    exclude_combo: bool = True,
+    seed: int = 1,
+) -> list[Path]:
+    """
+    Resolve occupancy NPZ paths under ``data_dir`` (no point loading).
+
+    Priority: explicit ``npz_paths``, else ``npz_catalog`` (union of globs),
+    else ``npz_glob``. Relative entries are joined to ``data_dir``.
+    Missing files in ``npz_paths`` raise ``FileNotFoundError``.
+
+    Parameters
+    ----------
+    data_dir:
+        Dataset root (``config.yaml`` ``data_dir``).
+    npz_glob:
+        Single glob relative to ``data_dir`` (``*`` and ``**`` allowed).
+    npz_paths:
+        Explicit relative or absolute NPZ paths. Empty / None → use glob(s).
+    npz_catalog:
+        ``(glob, max_shapes)`` rows. ``max_shapes`` is unique meshes after
+        the per-shape file cap; ``None`` keeps every mesh the glob hits.
+    max_files_per_shape:
+        Cap per :func:`shape_key` after sort. ``None`` = no cap.
+    exclude_combo:
+        Drop filenames containing ``combo``.
+    seed:
+        RNG for ``max_shapes`` subsampling (YAML ``seed``).
+
+    Returns
+    -------
+    list[Path]
+        Sorted existing ``.npz`` files.
+    """
+    root = Path(data_dir)
+    chosen: list[Path]
+    if npz_paths:
+        chosen = []
+        for raw in npz_paths:
+            item = Path(raw)
+            resolved = item if item.is_absolute() else (root / item)
+            if not resolved.is_file():
+                raise FileNotFoundError(f"NPZ not found: {resolved}")
+            chosen.append(resolved.resolve())
+    elif npz_catalog:
+        # Union in YAML order. Same file from two globs is kept once.
+        seen: set[Path] = set()
+        chosen = []
+        for pattern, max_shapes in npz_catalog:
+            hit = _glob_npz(root, str(pattern))
+            if exclude_combo:
+                hit = [p for p in hit if not _is_combo_npz(p)]
+            hit = [
+                p
+                for p in hit
+                if p.suffix.lower() == ".npz" and _is_parameterized_stem(p)
+            ]
+            hit = sorted(hit)
+            hit = _cap_per_shape(hit, max_files_per_shape)
+            if max_shapes is not None:
+                hit = _subsample_shapes(hit, int(max_shapes), int(seed))
+            for path in hit:
+                if path in seen:
+                    continue
+                seen.add(path)
+                chosen.append(path)
+    else:
+        chosen = _glob_npz(root, npz_glob)
+
+    npz_only = [p for p in chosen if p.suffix.lower() == ".npz"]
+    if exclude_combo:
+        npz_only = [p for p in npz_only if not _is_combo_npz(p)]
+    if npz_catalog and not npz_paths:
+        # Already capped per glob; keep YAML union order (not a global sort).
+        capped = npz_only
+    else:
+        npz_only = sorted(npz_only)
+        capped = _cap_per_shape(npz_only, max_files_per_shape)
+    if not capped:
+        raise FileNotFoundError(
+            f"No occupancy NPZ files matched under {root} "
+            f"(glob={npz_glob!r}, catalog={bool(npz_catalog)}, "
+            f"explicit={bool(npz_paths)})"
+        )
+    return capped
+
+
+def _summarize(points: PointsArray, labels: LabelsArray) -> str:
+    n = int(points.shape[0])
+    inside = float(labels.mean()) if n else float("nan")
+    xyz_min = points.min(axis=0) if n else np.full(3, np.nan, dtype=np.float32)
+    xyz_max = points.max(axis=0) if n else np.full(3, np.nan, dtype=np.float32)
+    return (
+        f"N={n}\n"
+        f"inside_fraction={inside:.6f}\n"
+        f"xyz_min={xyz_min.tolist()}\n"
+        f"xyz_max={xyz_max.tolist()}"
+    )
+
+
+# Default smoke-check file from the v2 plan (dataset_test sphere).
+_SAMPLE_RELATIVE = Path("exports") / "dataset_test" / "sphere__raycast_z_raut_s0.15_inout.npz"
+
+
+if __name__ == "__main__":
+    import sys
+
+    from scatteringnet.config import load_config
+
+    cfg = load_config()
+    if "--catalog" in sys.argv:
+        paths = resolve_npz_catalog(
+            cfg.data_dir,
+            npz_glob=cfg.npz_glob,
+            npz_paths=cfg.npz_paths or None,
+            npz_catalog=cfg.npz_catalog or None,
+            max_files_per_shape=cfg.max_files_per_shape,
+            seed=cfg.seed,
+        )
+        print(f"data_dir={cfg.data_dir}")
+        print(f"npz_glob={cfg.npz_glob}")
+        print(f"npz_catalog={list(cfg.npz_catalog)}")
+        print(f"max_files_per_shape={cfg.max_files_per_shape}")
+        print(f"files={len(paths)}")
+        # Load a few files only — the full catalog can be thousands of NPZs.
+        preview = paths[:3]
+        n_all = 0
+        n_in = 0
+        for path in preview:
+            pts, labs = load_points_labels(path)
+            n = int(pts.shape[0])
+            inside = int((labs == 1.0).sum())
+            n_all += n
+            n_in += inside
+            print(
+                f"  {path.name} N={n} inside={inside} outside={n - inside}"
+            )
+        print(
+            f"preview_files={len(preview)} preview_N={n_all} "
+            f"preview_inside={n_in} preview_outside={n_all - n_in}"
+        )
+        from scatteringnet.dataset import OccupancyMultiNpzDataset, make_dataloader
+
+        ds = OccupancyMultiNpzDataset(paths)
+        loader = make_dataloader(ds.parts[0], batch_size=8, shuffle=False)
+        xyz, y = next(iter(loader))
+        print(f"files={len(ds)} n_points={ds.n_points} parts={len(ds.parts)}")
+        print(f"batch xyz={tuple(xyz.shape)} y={tuple(y.shape)}")
+    else:
+        sample = cfg.data_dir / _SAMPLE_RELATIVE
+        pts, labs = load_points_labels(sample)
+        print(f"file={sample}")
+        print(_summarize(pts, labs))

src/geometry/__init__.py

@@ -0,0 +1,10 @@
+"""Training-side geometry: OBJ triangles and envelope samples."""
+
+from scatteringnet.geometry.mesh_io import clear_triangle_cache
+from scatteringnet.geometry.surface import clear_envelope_cache
+
+
+def clear_geometry_caches() -> None:
+    """Drop OBJ triangle and envelope process caches."""
+    clear_triangle_cache()
+    clear_envelope_cache()

src/geometry/mesh_io.py

@@ -0,0 +1,80 @@
+"""Load OBJ triangle meshes for the NPZ ↔ mesh join.
+
+This module only returns ``vertices (V, 3)`` and ``faces (T, 3)``.
+It does **not** sample the envelope.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import numpy as np
+import trimesh
+from numpy.typing import NDArray
+
+from scatteringnet.geometry.trimesh_util import as_trimesh
+
+VerticesArray = NDArray[np.float32]
+FacesArray = NDArray[np.int32]
+
+# Same resolved OBJ can back several NPZs (``max_files_per_shape``). Cache
+# the triangle arrays so catalog load does not re-parse the file.
+_TRIANGLE_CACHE: dict[str, tuple[VerticesArray, FacesArray]] = {}
+
+
+def clear_triangle_cache() -> None:
+    """Drop cached OBJ arrays (tests / long-lived notebooks)."""
+    _TRIANGLE_CACHE.clear()
+
+
+def load_obj_triangles(
+    path: Path | str,
+    *,
+    cache: bool = True,
+) -> tuple[VerticesArray, FacesArray]:
+    """
+    Read one OBJ as triangle vertices and face indices.
+
+    Parameters
+    ----------
+    path:
+        Existing ``.obj`` file.
+    cache:
+        Reuse arrays for the same resolved path (catalog load).
+
+    Returns
+    -------
+    vertices:
+        ``float32`` array of shape ``(V, 3)``.
+    faces:
+        ``int32`` array of shape ``(T, 3)`` (0-based vertex indices).
+    """
+    obj_path = Path(path)
+    if not obj_path.is_file():
+        raise FileNotFoundError(f"OBJ not found: {obj_path}")
+    if obj_path.suffix.lower() != ".obj":
+        raise ValueError(f"expected .obj, got {obj_path.suffix!r} ({obj_path})")
+
+    cache_key = str(obj_path.resolve())
+    if cache and cache_key in _TRIANGLE_CACHE:
+        return _TRIANGLE_CACHE[cache_key]
+
+    # process=False keeps the authored vertices; we only need the join.
+    loaded = trimesh.load(obj_path, force=None, process=False)
+    mesh = as_trimesh(loaded)
+    vertices = np.asarray(mesh.vertices, dtype=np.float32)
+    faces = np.asarray(mesh.faces, dtype=np.int32)
+    if vertices.ndim != 2 or vertices.shape[1] != 3:
+        raise ValueError(
+            f"vertices must have shape (V, 3), got {tuple(vertices.shape)} in {obj_path}"
+        )
+    if faces.ndim != 2 or faces.shape[1] != 3:
+        raise ValueError(
+            f"faces must have shape (T, 3), got {tuple(faces.shape)} in {obj_path}"
+        )
+    if int(faces.shape[0]) < 1:
+        raise ValueError(f"OBJ has no triangles: {obj_path}")
+
+    arrays = (vertices, faces)
+    if cache:
+        _TRIANGLE_CACHE[cache_key] = arrays
+    return arrays

src/geometry/surface.py

@@ -0,0 +1,154 @@
+"""Surface envelope samples from a triangle mesh.
+
+Area-weighted face darts (larger triangles get more samples). Each
+sample is ``(x, y, z, nx, ny, nz)``: position plus the unit normal of
+the triangle it sits on. World clouds are cached per
+``(mesh_key, n_surface, seed)``. AABB is applied to XYZ only.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import trimesh
+from numpy.typing import NDArray
+from trimesh.sample import sample_surface
+
+from scatteringnet.normalize import apply_normalization
+
+PointsArray = NDArray[np.float32]
+ENVELOPE_XYZ_DIM = 3
+ENVELOPE_FEAT_DIM = 6
+
+# Same OBJ + count + seed → same world samples (always 6-D).
+_ENVELOPE_CACHE: dict[tuple[str, int, int], PointsArray] = {}
+
+
+def clear_envelope_cache() -> None:
+    """Drop cached world-space envelopes (tests / long-lived notebooks)."""
+    _ENVELOPE_CACHE.clear()
+
+
+def _triangle_normals(verts: np.ndarray, faces: np.ndarray) -> NDArray[np.float64]:
+    v0 = verts[faces[:, 0]]
+    v1 = verts[faces[:, 1]]
+    v2 = verts[faces[:, 2]]
+    cross = np.cross(v1 - v0, v2 - v0)
+    length = np.linalg.norm(cross, axis=1, keepdims=True)
+    ok = length[:, 0] > 1e-12
+    normals = np.zeros_like(cross)
+    normals[ok] = cross[ok] / length[ok]
+    return normals
+
+
+def _pack_xyz_normal(xyz: np.ndarray, normals: np.ndarray) -> PointsArray:
+    """Concatenate XYZ with unit face normals → ``(N, 6)``."""
+    pos = np.asarray(xyz, dtype=np.float32)
+    nrm = np.asarray(normals, dtype=np.float32)
+    if pos.shape != nrm.shape or pos.ndim != 2 or pos.shape[1] != 3:
+        raise ValueError(
+            f"xyz/normals must be (N, 3), got {tuple(pos.shape)} / {tuple(nrm.shape)}"
+        )
+    length = np.linalg.norm(nrm, axis=1, keepdims=True)
+    ok = length[:, 0] > 1e-12
+    unit = np.zeros_like(nrm)
+    unit[ok] = nrm[ok] / length[ok]
+    return np.concatenate([pos, unit], axis=1)
+
+
+def apply_envelope_aabb(
+    env: np.ndarray, center: np.ndarray, scale: float
+) -> PointsArray:
+    """AABB-normalize XYZ; leave normals as unit directions."""
+    arr = np.asarray(env, dtype=np.float32)
+    if arr.ndim != 2 or arr.shape[1] not in (ENVELOPE_XYZ_DIM, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"envelope must be (N, 3) or (N, 6), got {tuple(arr.shape)}"
+        )
+    out = arr.copy()
+    out[:, :3] = apply_normalization(out[:, :3], center, scale)
+    return out
+
+
+def undo_envelope_aabb(
+    env: np.ndarray, center: np.ndarray, scale: float
+) -> PointsArray:
+    """Undo AABB on XYZ only."""
+    arr = np.asarray(env, dtype=np.float32)
+    if arr.ndim != 2 or arr.shape[1] not in (ENVELOPE_XYZ_DIM, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"envelope must be (N, 3) or (N, 6), got {tuple(arr.shape)}"
+        )
+    out = arr.copy()
+    c = np.asarray(center, dtype=np.float32).reshape(3)
+    out[:, :3] = out[:, :3] * np.float32(scale) + c
+    return out
+
+
+def project_envelope_dim(env: np.ndarray, dim: int) -> PointsArray:
+    """Keep XYZ+normal or drop to XYZ for an older checkpoint."""
+    arr = np.asarray(env, dtype=np.float32)
+    want = int(dim)
+    if want == ENVELOPE_FEAT_DIM:
+        if arr.ndim != 2 or arr.shape[1] != ENVELOPE_FEAT_DIM:
+            raise ValueError(f"expected (N, 6) envelope, got {tuple(arr.shape)}")
+        return arr
+    if want == ENVELOPE_XYZ_DIM:
+        if arr.ndim != 2 or arr.shape[1] not in (ENVELOPE_XYZ_DIM, ENVELOPE_FEAT_DIM):
+            raise ValueError(f"expected (N, 3|6) envelope, got {tuple(arr.shape)}")
+        return arr[:, :3]
+    raise ValueError(f"envelope dim must be 3 or 6, got {want}")
+
+
+def _sample_area(
+    verts: np.ndarray, tris: np.ndarray, count: int, seed: int
+) -> PointsArray:
+    mesh = trimesh.Trimesh(vertices=verts, faces=tris, process=False)
+    points, face_idx = sample_surface(mesh, count, seed=int(seed))
+    nrm = _triangle_normals(verts, tris)[np.asarray(face_idx, dtype=np.int64)]
+    out = _pack_xyz_normal(points, nrm)
+    if out.shape != (count, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"expected envelope shape {(count, ENVELOPE_FEAT_DIM)}, got {tuple(out.shape)}"
+        )
+    return out
+
+
+def sample_surface_points(
+    vertices: np.ndarray,
+    faces: np.ndarray,
+    n_surface: int,
+    *,
+    seed: int = 1,
+    cache_key: str | None = None,
+) -> PointsArray:
+    """
+    Sample ``n_surface`` envelope points as ``(N, 6)`` XYZ + unit normal.
+
+    Face-area weighted: larger triangles receive more darts. No crease
+    or fold path — unused ``envelope_mix`` on old checkpoints is ignored.
+    """
+    count = int(n_surface)
+    if count < 1:
+        raise ValueError(f"n_surface must be >= 1, got {count}")
+    verts = np.asarray(vertices, dtype=np.float64)
+    tris = np.asarray(faces, dtype=np.int64)
+    if verts.ndim != 2 or verts.shape[1] != 3:
+        raise ValueError(f"vertices must have shape (V, 3), got {tuple(verts.shape)}")
+    if tris.ndim != 2 or tris.shape[1] != 3:
+        raise ValueError(f"faces must have shape (T, 3), got {tuple(tris.shape)}")
+
+    key: tuple[str, int, int] | None = None
+    if cache_key is not None:
+        key = (str(cache_key), count, int(seed))
+        cached = _ENVELOPE_CACHE.get(key)
+        if cached is not None:
+            return cached
+
+    out = _sample_area(verts, tris, count, int(seed))
+    if out.shape != (count, ENVELOPE_FEAT_DIM):
+        raise ValueError(
+            f"expected envelope shape {(count, ENVELOPE_FEAT_DIM)}, got {tuple(out.shape)}"
+        )
+    if key is not None:
+        _ENVELOPE_CACHE[key] = out
+    return out

src/geometry/trimesh_util.py

@@ -0,0 +1,19 @@
+"""Shared trimesh flatten. No Open3D — safe for train-side mesh_io."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import trimesh
+
+
+def as_trimesh(mesh: Any) -> trimesh.Trimesh:
+    """Flatten a Trimesh or a Scene of triangle meshes to one Trimesh."""
+    if isinstance(mesh, trimesh.Scene):
+        geoms = [g for g in mesh.geometry.values() if isinstance(g, trimesh.Trimesh)]
+        if not geoms:
+            raise ValueError("Scene contains no triangle meshes")
+        mesh = trimesh.util.concatenate(geoms)
+    if not isinstance(mesh, trimesh.Trimesh):
+        raise TypeError(f"Unsupported mesh type: {type(mesh)!r}")
+    return mesh

src/gradio/app.py

@@ -0,0 +1,503 @@
+"""Gradio occupancy demo: upload an OBJ, fill the AABB, classify with best.pt.
+
+The 3D pane is a persistent Babylon canvas (``orbit.js`` via ``launch(js=)``).
+Gradio ``Model3D`` remounts WebGL on every new GLB — that is the gray flash
+and the camera snap. ``gr.HTML`` scripts are stripped, so the viewer JS is
+not put in the HTML component. The inspect tool remains ``src/viewer``.
+
+Launch (conda env scatteringNet):
+
+    python src/gradio/app.py
+"""
+
+from __future__ import annotations
+
+import html
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# ZeroGPU scans for ``@spaces.GPU`` at import. Import this before torch.
+try:
+    import spaces
+except ImportError:
+    spaces = None
+
+import numpy as np
+
+# Pip package first — this directory must not shadow it.
+import gradio as gr
+
+_HERE = Path(__file__).resolve().parent
+# Repo root (Space ships ``scatteringnet/`` here; local uses pip ``-e .``).
+_ROOT = _HERE.parents[1]
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+if str(_HERE) not in sys.path:
+    sys.path.insert(0, str(_HERE))
+
+from figure import (  # noqa: E402
+    DEFAULT_MESH_OPACITY,
+    DEFAULT_POINT_SIZE,
+    empty_figure,
+    occupancy_figure,
+)
+from pipeline import (  # noqa: E402
+    DEFAULT_CUT,
+    DEFAULT_DENSITY,
+    apply_cut,
+    default_run_id,
+    fill_and_infer,
+)
+from scatteringnet.viewer.obj_fill import triangles_from_obj_text  # noqa: E402
+
+# Shipped sample meshes in examples/ (not in the training catalog).
+_EXAMPLE_OBJS = (
+    "Obese.obj",
+    "horse.obj",
+    "Player.obj",
+    "dog.obj",
+    "Helix_bend.obj",
+    "TorusX3_box.obj",
+)
+
+# Inspect viewer: scene.background = 0x2a2a32 (not near-black).
+_BG_HEX = "#2a2a32"
+_ORBIT_JS = _HERE / "orbit.js"
+# Host never goes in event outputs — remounting it would flash again.
+_ORBIT_HOST = (
+    f'<div id="sn-orbit-host" style="position:relative;width:100%;height:640px;'
+    f'background:{_BG_HEX};border-radius:8px;overflow:hidden;">'
+    '<canvas id="sn-orbit" style="width:100%;height:100%;display:block;"></canvas>'
+    '<div id="sn-drop-hint">Drop an OBJ file here</div>'
+    "</div>"
+)
+# Shared by Blocks (Hugging Face finds ``demo``) and local launch().
+_ORBIT_CSS = (
+    "#sn-cmd-wrap { display: none !important; }"
+    "#sn-obj-file-slot {"
+    " position: fixed !important; left: -100vw !important; top: 0 !important;"
+    " width: 8px !important; height: 8px !important; overflow: hidden !important;"
+    " opacity: 0 !important; pointer-events: none !important;"
+    "}"
+    "#sn-obj-file-slot .file-preview-holder, #sn-obj-file-slot table,"
+    " #sn-obj-file-slot .filename { display: none !important; }"
+    "#sn-orbit-host.sn-drop-over { outline: 2px solid #f5a623; outline-offset: -2px; }"
+    "#sn-drop-hint {"
+    " position: absolute; left: 0; right: 0; top: 12px;"
+    " text-align: center; pointer-events: none; z-index: 2;"
+    " font-size: 13px; line-height: 1.3; color: #aabbcc;"
+    " text-shadow: 0 1px 2px #1a1a20;"
+    "}"
+)
+
+
+def _make_blocks() -> gr.Blocks:
+    """Gradio 6 moved ``js`` / ``css`` off Blocks onto ``launch()``."""
+    return gr.Blocks(title="scatteringNet occupancy")
+
+
+def _patch_launch(blocks: gr.Blocks) -> None:
+    """HF calls ``demo.launch()`` with no kwargs; inject orbit JS / CSS."""
+    orbit_js = _ORBIT_JS.read_text(encoding="utf-8")
+    orig = blocks.launch
+
+    def launch(*args, **kwargs):
+        kwargs.setdefault("js", orbit_js)
+        kwargs.setdefault("css", _ORBIT_CSS)
+        kwargs.setdefault("allowed_paths", [str(_glb_dir())])
+        try:
+            return orig(*args, **kwargs)
+        except TypeError:
+            kwargs.pop("js", None)
+            return orig(*args, **kwargs)
+
+    blocks.launch = launch
+
+
+def _glb_dir() -> Path:
+    """Same folder ``figure._export_glb`` writes; ``allowed_paths`` serves it."""
+    folder = Path(tempfile.gettempdir()) / "scatteringnet_gradio"
+    folder.mkdir(parents=True, exist_ok=True)
+    return folder
+
+
+def _cmd_html(
+    glb: str,
+    reset_n: int,
+    point_size: float = DEFAULT_POINT_SIZE,
+    wire: bool = False,
+    force_default: bool = False,
+) -> str:
+    """Tiny span orbit.js polls. Remounting this does not remount the canvas.
+
+    ``force_default`` (last field) is **Reset view** only. Sample / drop /
+    Load OBJ / Run keep the current orbit — same as the original load fix.
+    """
+    path = html.escape(str(Path(glb).resolve()))
+    px = max(1, min(24, int(round(float(point_size)))))
+    w = 1 if wire else 0
+    d = 1 if force_default else 0
+    return f'<span id="sn-cmd">{path}|{int(reset_n)}|{px}|{w}|{d}</span>'
+
+
+def _held_path(file_obj) -> str | None:
+    """File widget / UploadButton → filepath string for later Run / restyle."""
+    if file_obj is None:
+        return None
+    return str(getattr(file_obj, "name", None) or file_obj)
+
+
+def _read_upload(file_obj) -> tuple[str, str]:
+    """Gradio File (filepath) → (basename, OBJ text)."""
+    if file_obj is None:
+        raise ValueError("upload an .obj")
+    path = Path(getattr(file_obj, "name", None) or str(file_obj))
+    if path.suffix.lower() != ".obj":
+        raise ValueError("file must be an .obj")
+    return path.name, path.read_text(encoding="utf-8", errors="replace")
+
+
+def _status_md(result: dict, *, cut: float, shown_out: bool) -> str:
+    """Short inspect-style summary under the view."""
+    t = result.get("timings") or {}
+    extra = " (outside hidden)" if not shown_out else ""
+    return (
+        f"**{result.get('obj_name', 'OBJ')}** · `{result.get('run_id', '')}`  \n"
+        f"Inside **{result['n_inside']}** / outside **{result['n_outside']}** "
+        f"(cut {cut:.2f}){extra}  \n"
+        f"Lattice `{result['n']}` pts · spacing `{result['used_spacing']:.3f}` · "
+        f"grid `{result['grid']}`  \n"
+        f"Times s: fill+forward total `{t.get('server_total', 0):.3f}` · "
+        f"envelope `{t.get('envelope', 0):.3f}` · run `{t.get('forward', 0):.3f}` · "
+        f"device `{t.get('device', '?')}`"
+    )
+
+
+def _view(result: dict | None, cut: float, show_outside: bool, mesh_opacity: float):
+    """Rebuild the occupancy GLB. The canvas stays; only the cmd span changes."""
+    if not result:
+        return str(empty_figure()), "Upload an OBJ, then **Run model**."
+    pred, n_in, n_out = apply_cut(result["probs"], float(cut))
+    view = dict(result)
+    view["pred"] = pred
+    view["n_inside"] = n_in
+    view["n_outside"] = n_out
+    glb = occupancy_figure(
+        view["vertices"],
+        view["faces"],
+        view["points"],
+        pred,
+        show_outside=bool(show_outside),
+        title=str(view.get("obj_name") or "occupancy fill"),
+        mesh_opacity=float(mesh_opacity),
+    )
+    return str(glb), _status_md(view, cut=float(cut), shown_out=bool(show_outside))
+
+
+def run_model(file_obj, obj_held, density, cut, show_outside, mesh_opacity):
+    """Fill + infer with the single default checkpoint (no model picker)."""
+    src = file_obj or obj_held
+    held = _held_path(src)
+    try:
+        obj_name, obj_text = _read_upload(src)
+        result = fill_and_infer(
+            obj_text,
+            obj_name=obj_name,
+            run_id=default_run_id(),
+            density=float(density),
+        )
+        glb, md = _view(result, float(cut), bool(show_outside), float(mesh_opacity))
+        return result, glb, md, None, held
+    except Exception as exc:
+        return None, str(empty_figure(str(exc))), f"**Error:** {exc}", None, held
+
+
+def preview_upload(file_obj, mesh_opacity=DEFAULT_MESH_OPACITY):
+    """Show the uploaded mesh on the floor immediately (no occupancy yet)."""
+    if file_obj is None:
+        return None, str(empty_figure()), "Upload an OBJ, then click **Run model**."
+    try:
+        obj_name, obj_text = _read_upload(file_obj)
+        vertices, faces = triangles_from_obj_text(obj_text)
+        glb = occupancy_figure(
+            vertices,
+            faces,
+            np.zeros((0, 3), dtype=np.float32),
+            np.zeros((0,), dtype=np.uint8),
+            title=obj_name,
+            mesh_opacity=float(mesh_opacity),
+        )
+        return (
+            None,
+            str(glb),
+            f"**{obj_name}** is on the floor. Click **Run model** to classify the fill.",
+        )
+    except Exception as exc:
+        return None, str(empty_figure(str(exc))), f"**Error:** {exc}"
+
+
+def accept_obj(
+    file_obj,
+    mesh_opacity=DEFAULT_MESH_OPACITY,
+    reset_n=0,
+    current_glb=None,
+):
+    """
+    Load an OBJ, then clear the File box so the next drop can fire change.
+
+    Keep ``reset_n`` so orbit.js does not reframe. Clearing the picker
+    (``file_obj is None``) must not write a new empty GLB — that changed
+    the cmd path and made the camera reload. **Reset view** is the only bump.
+    """
+    keep = int(reset_n or 0)
+    if file_obj is None:
+        glb = current_glb or str(empty_figure())
+        yield None, str(glb), keep, "Upload an OBJ, then click **Run model**.", None, None
+        return
+    held = _held_path(file_obj)
+    state, glb, md = preview_upload(file_obj, mesh_opacity)
+    yield state, str(glb), keep, md, None, held
+
+
+def restyle(result, file_obj, obj_held, cut, show_outside, mesh_opacity):
+    """Rebuild GLB after cut / opacity / outside. Reset counter is not touched."""
+    try:
+        if result:
+            return _view(result, float(cut), bool(show_outside), float(mesh_opacity))
+        src = file_obj or obj_held
+        if src is None:
+            return str(empty_figure()), "Upload an OBJ, then **Run model**."
+        _, glb, md = preview_upload(src, mesh_opacity)
+        return str(glb), md
+    except Exception as exc:
+        return str(empty_figure(str(exc))), f"**Error:** {exc}"
+
+
+def bump_reset(glb_held, reset_n, point_size, wire):
+    """Reset view: same GLB, increment token so JS frames 45° / 70°."""
+    nxt = int(reset_n or 0) + 1
+    path = glb_held or str(empty_figure())
+    return nxt, _cmd_html(path, nxt, point_size, wire, force_default=True)
+
+
+def accept_obj_ui(
+    file_obj,
+    mesh_opacity=DEFAULT_MESH_OPACITY,
+    reset_n=0,
+    point_size=DEFAULT_POINT_SIZE,
+    wire=False,
+    glb_held=None,
+):
+    """accept_obj plus the #sn-cmd span orbit.js reads."""
+    for state, glb, nxt, md, cleared, held in accept_obj(
+        file_obj, mesh_opacity, reset_n, current_glb=glb_held
+    ):
+        yield state, glb, nxt, _cmd_html(glb, nxt, point_size, wire), md, cleared, held
+
+
+def _maybe_gpu(fn):
+    """ZeroGPU requires at least one ``@spaces.GPU`` at startup. No-op locally."""
+    if spaces is None:
+        return fn
+    return spaces.GPU(duration=30)(fn)
+
+
+@_maybe_gpu
+def run_model_ui(
+    file_obj, obj_held, density, cut, show_outside, mesh_opacity, reset_n, point_size, wire
+):
+    """Run: new GLB, same reset token, so the canvas keeps the orbit."""
+    result, glb, md, cleared, held = run_model(
+        file_obj, obj_held, density, cut, show_outside, mesh_opacity
+    )
+    return result, glb, _cmd_html(glb, int(reset_n or 0), point_size, wire), md, cleared, held
+
+
+def restyle_ui(
+    result, file_obj, obj_held, cut, show_outside, mesh_opacity, reset_n, point_size, wire
+):
+    """Restyle: new GLB, same reset token."""
+    glb, md = restyle(result, file_obj, obj_held, cut, show_outside, mesh_opacity)
+    return glb, _cmd_html(glb, int(reset_n or 0), point_size, wire), md
+
+
+def set_view_flags(glb_held, reset_n, point_size, wire):
+    """Dot size / wireframe — no new GLB, orbit.js applies both."""
+    path = glb_held or str(empty_figure())
+    return _cmd_html(path, int(reset_n or 0), point_size, wire)
+
+
+def build_demo() -> gr.Blocks:
+    """One-page Gradio occupancy fill."""
+    # Only list files that are actually on disk (partial checkout still launches).
+    example_list = [
+        str(path)
+        for name in _EXAMPLE_OBJS
+        if (path := _HERE / "examples" / name).is_file()
+    ] or None
+    empty_glb = empty_figure()
+
+    with _make_blocks() as demo:
+        gr.Markdown(
+            """
+# scatteringNet — occupancy fill
+
+A trained occupancy network that fills a 3D mesh with points it labels
+**inside** the solid (not outside).
+
+[Code](https://github.com/PerryGu/scatteringNet)
+
+[Video](https://youtu.be/vU45O0Mu0o4)
+            """.strip()
+        )
+        state = gr.State(None)
+        obj_held = gr.State(None)
+        glb_held = gr.State(str(Path(empty_glb).resolve()))
+        reset_n = gr.State(0)
+        with gr.Row():
+            with gr.Column(scale=1):
+                load_btn = gr.Button("Load OBJ", elem_id="sn-load-obj")
+                density_in = gr.Slider(
+                    0,
+                    100,
+                    value=DEFAULT_DENSITY,
+                    step=1,
+                    label="Density (higher = denser lattice)",
+                )
+                cut_in = gr.Slider(
+                    0.05,
+                    0.95,
+                    value=DEFAULT_CUT,
+                    step=0.01,
+                    label="Inside cut",
+                )
+                opacity_in = gr.Slider(
+                    0,
+                    100,
+                    value=DEFAULT_MESH_OPACITY,
+                    step=1,
+                    label="Mesh opacity",
+                    info="Default 50% so occupancy points show through the shell.",
+                )
+                psize_in = gr.Slider(
+                    1,
+                    24,
+                    value=DEFAULT_POINT_SIZE,
+                    step=1,
+                    label="Dot size",
+                    info="Occupancy points in the 3D view (pixels).",
+                )
+                with gr.Row():
+                    show_out = gr.Checkbox(label="Show outside points", value=False)
+                    wire_in = gr.Checkbox(label="Wireframe", value=False)
+                with gr.Row():
+                    run_btn = gr.Button("Run model", variant="primary")
+                    reset_btn = gr.Button("Reset view")
+                status = gr.Markdown(
+                    "Drop an OBJ on the **3D view**, or click **Load OBJ**. "
+                    "**Run model** fills the volume."
+                )
+            with gr.Column(scale=2):
+                # Never list this HTML in outputs — a new value remounts the canvas.
+                gr.HTML(value=_ORBIT_HOST, elem_id="sn-orbit-wrap")
+        # Plumbing only. The cmd span is a temp GLB path; if it sits in the
+        # layout it paints through Load OBJ (even with height:0).
+        with gr.Column(elem_id="sn-obj-file-slot"):
+            cmd = gr.HTML(
+                value=_cmd_html(str(empty_glb), 0, DEFAULT_POINT_SIZE),
+                elem_id="sn-cmd-wrap",
+                visible="hidden",
+                container=False,
+            )
+            obj_in = gr.File(
+                label="OBJ",
+                file_types=[".obj"],
+                type="filepath",
+                show_label=False,
+                container=False,
+                elem_id="sn-obj-file",
+            )
+        _accept_out = [state, glb_held, reset_n, cmd, status, obj_in, obj_held]
+        _run_out = [state, glb_held, cmd, status, obj_in, obj_held]
+        _style_out = [glb_held, cmd, status]
+        if example_list:
+            # One file column; the other inputs keep the live sliders / Wireframe.
+            # inputs=obj_in alone called accept_obj_ui with wire=False.
+            gr.Markdown(
+                "These geometries were not in the model's training catalog."
+            )
+            gr.Examples(
+                examples=[[p] for p in example_list],
+                inputs=[obj_in, opacity_in, reset_n, psize_in, wire_in, glb_held],
+                outputs=_accept_out,
+                fn=accept_obj_ui,
+                run_on_click=True,
+                cache_examples=False,
+                label="Sample OBJ",
+            )
+        # Picker is a plain Button: UploadButton paints the path over the label.
+        # orbit.js clicks #sn-obj-file's input; File.upload runs accept.
+        # Do not bind File.clear — we empty the box on purpose so DND stays.
+        obj_in.upload(
+            accept_obj_ui,
+            inputs=[obj_in, opacity_in, reset_n, psize_in, wire_in, glb_held],
+            outputs=_accept_out,
+        )
+        run_btn.click(
+            run_model_ui,
+            inputs=[
+                obj_in,
+                obj_held,
+                density_in,
+                cut_in,
+                show_out,
+                opacity_in,
+                reset_n,
+                psize_in,
+                wire_in,
+            ],
+            outputs=_run_out,
+        )
+        reset_btn.click(
+            bump_reset,
+            inputs=[glb_held, reset_n, psize_in, wire_in],
+            outputs=[reset_n, cmd],
+        )
+        _style_in = [
+            state,
+            obj_in,
+            obj_held,
+            cut_in,
+            show_out,
+            opacity_in,
+            reset_n,
+            psize_in,
+            wire_in,
+        ]
+        cut_in.release(restyle_ui, inputs=_style_in, outputs=_style_out)
+        opacity_in.release(restyle_ui, inputs=_style_in, outputs=_style_out)
+        show_out.change(restyle_ui, inputs=_style_in, outputs=_style_out)
+        _flag_in = [glb_held, reset_n, psize_in, wire_in]
+        psize_in.release(set_view_flags, inputs=_flag_in, outputs=cmd)
+        wire_in.change(set_view_flags, inputs=_flag_in, outputs=cmd)
+    return demo
+
+
+# HF / ZeroGPU look for a module-level ``demo`` and for ``@spaces.GPU``.
+demo = build_demo()
+demo.queue()
+_patch_launch(demo)
+
+
+def main() -> None:
+    """Local binds localhost; Spaces set ``PORT`` and need ``0.0.0.0``."""
+    on_space = bool(os.environ.get("SPACE_ID") or os.environ.get("PORT"))
+    port = int(os.environ["PORT"]) if os.environ.get("PORT") else 7860
+    host = "0.0.0.0" if on_space else "127.0.0.1"
+    demo.launch(server_name=host, server_port=port)
+
+
+if __name__ == "__main__":
+    main()

src/gradio/figure.py

@@ -0,0 +1,255 @@
+"""GLB scene for Gradio ``Model3D`` (Babylon.js orbit, Y-up).
+
+Plotly 3D was the wrong tool: its camera is a unit-cube, not world Y-up, so
+the floor never sat on the ground. This writes a real mesh (floor grid +
+OBJ + occupancy points) and lets Gradio's 3D viewer frame it.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import uuid
+from pathlib import Path
+
+import numpy as np
+import trimesh
+from trimesh.path.entities import Line
+from trimesh.path.path import Path3D
+from trimesh.visual.material import PBRMaterial
+from trimesh.visual.texture import TextureVisuals
+
+# Inspect COLOR_INSIDE is 0xffaa00. Babylon treats GLB vertex colors as
+# linear, so that same RGB reads as lemon-yellow. Drop the green channel
+# so the on-screen fill matches the inspect orange.
+COLOR_INSIDE = np.array([255, 136, 0, 255], dtype=np.uint8)
+COLOR_OUTSIDE = np.array([74, 109, 140, 220], dtype=np.uint8)
+COLOR_MESH_RGB = (0.60, 0.64, 0.70)
+# THREE.GridHelper(span, 20, 0xaabbcc, 0x556677) — center vs cells.
+COLOR_GRID = np.array([85, 102, 119, 255], dtype=np.uint8)
+COLOR_GRID_CENTER = np.array([170, 187, 204, 255], dtype=np.uint8)
+DEFAULT_MESH_OPACITY = 50
+# Babylon POINTS are 1 px in the GLB; orbit.js applies this pixel size.
+DEFAULT_POINT_SIZE = 8
+# Match pipeline.MAX_FILL_POINTS so the GLB is not a random subset of the lattice.
+MAX_PLOT_POINTS = 80_000
+FLOOR_DIVS = 20
+
+
+def _floor_bounds(vertices: np.ndarray | None) -> tuple[float, float, float, float, float]:
+    """XZ rectangle and Y of the floor (content ymin, else y=0)."""
+    if vertices is None or int(np.asarray(vertices).size) == 0:
+        return -2.0, 2.0, -2.0, 2.0, 0.0
+    verts = np.asarray(vertices, dtype=np.float64)
+    vmin = verts.min(axis=0)
+    vmax = verts.max(axis=0)
+    radius = 0.5 * float(np.max(vmax - vmin))
+    span = max(radius * 4.0, 4.0)
+    cx = 0.5 * float(vmin[0] + vmax[0])
+    cz = 0.5 * float(vmin[2] + vmax[2])
+    y = float(vmin[1])
+    half = 0.5 * span
+    return cx - half, cx + half, cz - half, cz + half, y
+
+
+def _clamp_opacity(value: float) -> float:
+    """Slider 0–100 → 0–1. Missing / NaN → default 50%."""
+    try:
+        t = float(value)
+    except (TypeError, ValueError):
+        t = float(DEFAULT_MESH_OPACITY)
+    if not np.isfinite(t):
+        t = float(DEFAULT_MESH_OPACITY)
+    return min(1.0, max(0.0, t / 100.0))
+
+
+def _shell_mesh(vertices: np.ndarray, faces: np.ndarray, opacity: float) -> trimesh.Trimesh:
+    """
+    OBJ shell with a GLTF BLEND material.
+
+    Vertex-color alpha is ignored by Babylon Model3D (that is why the
+    torus looked solid). ``alphaMode=BLEND`` + baseColorFactor.a is the
+    channel the viewer actually uses.
+    """
+    mesh = trimesh.Trimesh(vertices=vertices, faces=faces, process=False)
+    alpha = _clamp_opacity(opacity)
+    mesh.visual = TextureVisuals(
+        material=PBRMaterial(
+            name="shell",
+            baseColorFactor=[COLOR_MESH_RGB[0], COLOR_MESH_RGB[1], COLOR_MESH_RGB[2], alpha],
+            metallicFactor=0.0,
+            roughnessFactor=0.85,
+            alphaMode="BLEND",
+            doubleSided=True,
+        )
+    )
+    mesh.metadata["name"] = "occ_shell"
+    return mesh
+
+
+def _grid_mesh(vertices: np.ndarray | None, *, n: int = FLOOR_DIVS) -> Path3D:
+    """
+    XZ floor as GL_LINES (1 px in Babylon), not extruded boxes.
+
+    Boxes read as a thick waffle. The inspect viewer uses
+    ``THREE.GridHelper(span, 20, 0xaabbcc, 0x556677)`` — same count
+    and the lighter centre cross.
+    """
+    x0, x1, z0, z1, y = _floor_bounds(vertices)
+    n = max(2, int(n))
+    mid = n // 2
+    verts: list[list[float]] = []
+    entities: list[Line] = []
+    colors: list[np.ndarray] = []
+    for i in range(n + 1):
+        t = i / n
+        x = x0 + (x1 - x0) * t
+        z = z0 + (z1 - z0) * t
+        color = COLOR_GRID_CENTER if i == mid else COLOR_GRID
+        i0 = len(verts)
+        verts.extend(([x, y, z0], [x, y, z1]))
+        entities.append(Line(points=[i0, i0 + 1]))
+        colors.append(color)
+        i1 = len(verts)
+        verts.extend(([x0, y, z], [x1, y, z]))
+        entities.append(Line(points=[i1, i1 + 1]))
+        colors.append(color)
+    return Path3D(
+        entities=entities,
+        vertices=np.asarray(verts, dtype=np.float64),
+        colors=np.asarray(colors, dtype=np.uint8),
+        process=False,
+    )
+
+
+def _axis_mesh(vertices: np.ndarray | None) -> Path3D:
+    """
+    RGB triad as GL_LINES — same idea as ``THREE.AxesHelper``.
+
+    Length is ``max(radius * 0.45, 1)`` with ``span = 4 * radius``,
+    matching the inspect helper. Boxes looked like fat sticks.
+    """
+    x0, x1, z0, z1, y = _floor_bounds(vertices)
+    span = max(x1 - x0, z1 - z0, 1.0)
+    length = max(0.45 * (span / 4.0), 1.0)
+    origin = np.array([0.5 * (x0 + x1), y, 0.5 * (z0 + z1)], dtype=np.float64)
+    # AxesHelper: +X red, +Y green, +Z blue.
+    specs = (
+        (np.array([length, 0.0, 0.0]), (255, 0, 0, 255)),
+        (np.array([0.0, length, 0.0]), (0, 255, 0, 255)),
+        (np.array([0.0, 0.0, length]), (0, 0, 255, 255)),
+    )
+    verts: list[np.ndarray] = []
+    entities: list[Line] = []
+    colors: list[tuple[int, int, int, int]] = []
+    for delta, rgba in specs:
+        i0 = len(verts)
+        verts.extend((origin, origin + delta))
+        entities.append(Line(points=[i0, i0 + 1]))
+        colors.append(rgba)
+    return Path3D(
+        entities=entities,
+        vertices=np.asarray(verts, dtype=np.float64),
+        colors=np.asarray(colors, dtype=np.uint8),
+        process=False,
+    )
+
+
+def _points_mesh(xyz: np.ndarray, rgba: np.ndarray) -> trimesh.Trimesh | None:
+    """Occupancy dots as a vertex cloud (GLB point primitive)."""
+    if xyz.ndim != 2 or xyz.shape[0] < 1:
+        return None
+    cloud = trimesh.points.PointCloud(xyz.astype(np.float64), colors=rgba)
+    # Node name survives GLB import so orbit.js can set pointSize.
+    cloud.metadata["name"] = "occ_points"
+    return cloud
+
+
+def _subsample(points: np.ndarray, pred: np.ndarray, cap: int) -> tuple[np.ndarray, np.ndarray]:
+    n = int(points.shape[0])
+    if n <= cap:
+        return points, pred
+    rng = np.random.default_rng(0)
+    inside = np.flatnonzero(pred > 0)
+    outside = np.flatnonzero(pred == 0)
+    n_in = min(int(inside.shape[0]), cap)
+    take_in = rng.choice(inside, size=n_in, replace=False) if n_in else np.empty(0, dtype=int)
+    remain = cap - n_in
+    n_out = min(int(outside.shape[0]), remain)
+    take_out = (
+        rng.choice(outside, size=n_out, replace=False) if n_out else np.empty(0, dtype=int)
+    )
+    idx = np.concatenate([take_in, take_out])
+    return points[idx], pred[idx]
+
+
+def _placeholder_geom() -> trimesh.Trimesh:
+    """Tiny triangle so trimesh can export when the draw list is empty."""
+    dummy = trimesh.Trimesh(
+        vertices=np.array([[0.0, 0.0, 0.0], [1e-4, 0.0, 0.0], [0.0, 0.0, 1e-4]]),
+        faces=np.array([[0, 1, 2]], dtype=np.int64),
+        process=False,
+    )
+    dummy.metadata["name"] = "occ_empty"
+    return dummy
+
+
+def _export_glb(geoms: list) -> Path:
+    """Write a unique GLB so the orbit fetch is not served from a stale cache."""
+    folder = Path(tempfile.gettempdir()) / "scatteringnet_gradio"
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / f"view_{uuid.uuid4().hex[:10]}.glb"
+    scene = trimesh.Scene()
+    added = 0
+    for i, geom in enumerate(geoms):
+        if geom is None:
+            continue
+        meta = getattr(geom, "metadata", None) or {}
+        name = str(meta["name"]) if isinstance(meta, dict) and meta.get("name") else f"g{i}"
+        scene.add_geometry(geom, node_name=name)
+        added += 1
+    if added < 1:
+        scene.add_geometry(_placeholder_geom(), node_name="occ_empty")
+    scene.export(path)
+    return path
+
+
+def empty_figure(message: str = "", **_kwargs) -> Path:
+    """
+    Placeholder GLB so the cmd path can change. The visible floor lives
+    in orbit.js and is never replaced (a per-mesh grid was the camera jump).
+    """
+    _ = message
+    return _export_glb([])
+
+
+def occupancy_figure(
+    vertices: np.ndarray,
+    faces: np.ndarray,
+    points: np.ndarray,
+    pred: np.ndarray,
+    *,
+    show_outside: bool = False,
+    title: str = "",
+    mesh_opacity: float = DEFAULT_MESH_OPACITY,
+    **_kwargs,
+) -> Path:
+    """Mesh + occupancy points as one GLB. Floor stays in orbit.js."""
+    _ = title
+    verts = np.asarray(vertices, dtype=np.float32) if vertices is not None else np.zeros((0, 3), np.float32)
+    tris = np.asarray(faces, dtype=np.int32) if faces is not None else np.zeros((0, 3), np.int32)
+    geoms: list = []
+    if verts.ndim == 2 and verts.shape[0] > 0:
+        if tris.ndim == 2 and tris.shape[0] > 0 and tris.shape[1] == 3:
+            geoms.append(_shell_mesh(verts, tris, mesh_opacity))
+    xyz = np.asarray(points, dtype=np.float32)
+    if xyz.ndim == 2 and xyz.shape[0] > 0:
+        labels = np.asarray(pred, dtype=np.uint8).reshape(-1)
+        if not show_outside:
+            keep = labels > 0
+            xyz = xyz[keep]
+            labels = labels[keep]
+        xyz, labels = _subsample(xyz, labels, MAX_PLOT_POINTS)
+        if xyz.shape[0] > 0:
+            colors = np.where(labels[:, None] > 0, COLOR_INSIDE, COLOR_OUTSIDE)
+            geoms.append(_points_mesh(xyz, colors))
+    return _export_glb(geoms)

src/gradio/orbit.js

@@ -0,0 +1,564 @@
+/**
+ * Persistent occupancy orbit (Y-up). Gradio Model3D remounts the whole
+ * WebGL context on every new GLB — that is the gray flash + camera snap.
+ * This script owns one Engine for the page lifetime and only replaces meshes.
+ *
+ * Gradio 6 strips <script> inside gr.HTML. This file is passed to launch(js=)
+ * so it actually runs. Python writes a tiny #sn-cmd span (path + reset).
+ * The canvas host HTML is never updated, so the Engine is not remounted.
+ */
+(async function () {
+  /* Gradio can re-run launch(js=) when the cmd span updates. A second
+     Engine would start at 45°/70° and snapshotCam() would wipe the orbit. */
+  if (window.__snOrbit && window.__snOrbit.alive && window.__snOrbit.alive()) {
+    return;
+  }
+  const BG = [42 / 255, 42 / 255, 50 / 255, 1];
+  const START_ALPHA = 45;
+  const START_BETA = 70;
+  /* Pull back so samples (dog / horse / torus) fit in frame. Load still
+     does not move the camera; Reset view returns here. */
+  const START_RADIUS = 60;
+  const GRID_HALF = 16;
+  const GRID_DIVS = 20;
+  const AXIS_LEN = 4;
+  const BABYLON_SRCS = [
+    [
+      "https://cdn.babylonjs.com/babylon.js",
+      "https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js",
+    ],
+    [
+      "https://cdn.jsdelivr.net/npm/babylonjs@7/babylon.js",
+      "https://cdn.jsdelivr.net/npm/babylonjs@7/babylonjs.loaders.min.js",
+    ],
+  ];
+
+  function loadScript(src) {
+    return new Promise(function (resolve, reject) {
+      const el = document.createElement("script");
+      el.src = src;
+      el.async = true;
+      el.onload = function () {
+        resolve();
+      };
+      el.onerror = function () {
+        reject(new Error(src));
+      };
+      document.head.appendChild(el);
+    });
+  }
+
+  async function loadBabylon() {
+    if (window.BABYLON && window.BABYLON.SceneLoader) {
+      return;
+    }
+    let last = null;
+    for (let i = 0; i < BABYLON_SRCS.length; i += 1) {
+      try {
+        await loadScript(BABYLON_SRCS[i][0]);
+        await loadScript(BABYLON_SRCS[i][1]);
+        if (window.BABYLON && window.BABYLON.SceneLoader) {
+          return;
+        }
+      } catch (err) {
+        last = err;
+      }
+    }
+    throw last || new Error("Babylon.js failed to load");
+  }
+
+  function waitFor(id) {
+    return new Promise(function (resolve) {
+      function tick() {
+        const el = document.getElementById(id);
+        if (el) {
+          resolve(el);
+          return;
+        }
+        window.setTimeout(tick, 50);
+      }
+      tick();
+    });
+  }
+
+  function cmdSpan() {
+    const direct = document.getElementById("sn-cmd");
+    if (direct) {
+      return direct;
+    }
+    const wrap = document.getElementById("sn-cmd-wrap");
+    return wrap ? wrap.querySelector("span") : null;
+  }
+
+  const DEFAULT_PSIZE = 8;
+
+  function cmdParts() {
+    const el = cmdSpan();
+    if (!el) {
+      return ["", 0, DEFAULT_PSIZE, 0, 0];
+    }
+    const bits = String(el.textContent || "").trim().split("|");
+    const path = bits[0] || "";
+    const reset = bits.length > 1 ? Number(bits[1]) : 0;
+    const psize = bits.length > 2 ? Number(bits[2]) : DEFAULT_PSIZE;
+    const wire = bits.length > 3 ? Number(bits[3]) : 0;
+    const forceDefault = bits.length > 4 ? Number(bits[4]) : 0;
+    return [path, reset, psize, wire, forceDefault];
+  }
+
+  function fieldPath() {
+    return cmdParts()[0];
+  }
+
+  function fieldReset() {
+    return cmdParts()[1] || 0;
+  }
+
+  function fieldPsize() {
+    const n = cmdParts()[2];
+    if (!Number.isFinite(n) || n < 1) {
+      return DEFAULT_PSIZE;
+    }
+    return Math.max(1, Math.min(24, n));
+  }
+
+  function fieldWire() {
+    return cmdParts()[3] ? 1 : 0;
+  }
+
+  function fieldForceDefault() {
+    return cmdParts()[4] ? 1 : 0;
+  }
+
+  function fileUrl(absPath) {
+    const posix = String(absPath).replace(/\\/g, "/");
+    return "/gradio_api/file=" + posix;
+  }
+
+  function pickObj(fileList) {
+    if (!fileList) {
+      return null;
+    }
+    for (let i = 0; i < fileList.length; i += 1) {
+      if (fileList[i] && /\.obj$/i.test(fileList[i].name || "")) {
+        return fileList[i];
+      }
+    }
+    return null;
+  }
+
+  function objFileInput() {
+    const root = document.getElementById("sn-obj-file");
+    return root ? root.querySelector("input[type=file]") : null;
+  }
+
+  function sendObjToGradio(file) {
+    const input = objFileInput();
+    if (!input || !file) {
+      return;
+    }
+    const dt = new DataTransfer();
+    dt.items.add(file);
+    input.value = "";
+    input.files = dt.files;
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    input.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+
+  function bindLoadBtn(wrap) {
+    if (!wrap || wrap.dataset.snLoadBound === "1") {
+      return;
+    }
+    wrap.dataset.snLoadBound = "1";
+    wrap.addEventListener(
+      "click",
+      function () {
+        const input = objFileInput();
+        if (input) {
+          input.click();
+        }
+      },
+      true
+    );
+  }
+
+  function bindViewDrop(host) {
+    if (!host || host.dataset.snDropBound === "1") {
+      return;
+    }
+    host.dataset.snDropBound = "1";
+    host.addEventListener(
+      "dragover",
+      function (e) {
+        if (!e.dataTransfer) {
+          return;
+        }
+        e.preventDefault();
+        e.dataTransfer.dropEffect = "copy";
+        host.classList.add("sn-drop-over");
+      },
+      true
+    );
+    host.addEventListener(
+      "dragleave",
+      function (e) {
+        if (!host.contains(e.relatedTarget)) {
+          host.classList.remove("sn-drop-over");
+        }
+      },
+      true
+    );
+    host.addEventListener(
+      "drop",
+      function (e) {
+        e.preventDefault();
+        host.classList.remove("sn-drop-over");
+        sendObjToGradio(pickObj(e.dataTransfer && e.dataTransfer.files));
+      },
+      true
+    );
+  }
+
+  waitFor("sn-orbit-host").then(bindViewDrop);
+  waitFor("sn-load-obj").then(bindLoadBtn);
+  await loadBabylon();
+  if (window.BABYLON && window.BABYLON.SceneLoader) {
+    window.BABYLON.SceneLoader.OnPluginActivatedObservable.add(function (plugin) {
+      if (plugin && String(plugin.name || "").toLowerCase() === "gltf") {
+        plugin.loadCameras = false;
+      }
+    });
+  }
+  let canvas = document.getElementById("sn-orbit");
+  if (!canvas) {
+    /* Gradio may strip <canvas> from HTML; the host div is enough. */
+    let host = document.getElementById("sn-orbit-host");
+    if (!host) {
+      const wrap = await waitFor("sn-orbit-wrap");
+      host = document.createElement("div");
+      host.id = "sn-orbit-host";
+      host.style.cssText =
+        "width:100%;height:640px;background:#2a2a32;border-radius:8px;overflow:hidden;";
+      wrap.appendChild(host);
+    }
+    bindViewDrop(host);
+    canvas = document.createElement("canvas");
+    canvas.id = "sn-orbit";
+    canvas.style.cssText = "width:100%;height:100%;display:block;";
+    host.appendChild(canvas);
+  }
+  if (canvas && canvas.parentElement && !document.getElementById("sn-drop-hint")) {
+    const hint = document.createElement("div");
+    hint.id = "sn-drop-hint";
+    hint.textContent = "Drop an OBJ file here";
+    canvas.parentElement.appendChild(hint);
+  }
+  const BABYLON = window.BABYLON;
+
+  const engine = new BABYLON.Engine(canvas, true, { preserveDrawingBuffer: true }, true);
+  const scene = new BABYLON.Scene(engine);
+  scene.useRightHandedSystem = true;
+  scene.clearColor = new BABYLON.Color4(BG[0], BG[1], BG[2], BG[3]);
+  scene.ambientColor = new BABYLON.Color3(0.35, 0.35, 0.38);
+
+  const camera = new BABYLON.ArcRotateCamera(
+    "cam",
+    BABYLON.Tools.ToRadians(START_ALPHA),
+    BABYLON.Tools.ToRadians(START_BETA),
+    START_RADIUS,
+    BABYLON.Vector3.Zero(),
+    scene
+  );
+  camera.lowerRadiusLimit = 0.05;
+  camera.minZ = 0.01;
+  camera.wheelPrecision = 40;
+  camera.attachControl(canvas, true);
+
+  const light = new BABYLON.HemisphericLight("hemi", new BABYLON.Vector3(0.2, 1, 0.15), scene);
+  light.intensity = 0.95;
+
+  /* Fixed world floor. Not part of the GLB — a per-mesh grid is what
+     made the camera look like it jumped when a new OBJ loaded. */
+  (function addWorldHelpers() {
+    const half = GRID_HALF;
+    const n = GRID_DIVS;
+    const mid = n / 2;
+    const cell = new BABYLON.Color3(85 / 255, 102 / 255, 119 / 255);
+    const center = new BABYLON.Color3(170 / 255, 187 / 255, 204 / 255);
+    for (let i = 0; i <= n; i += 1) {
+      const t = -half + (2 * half * i) / n;
+      const col = i === mid ? center : cell;
+      const gx = BABYLON.MeshBuilder.CreateLines(
+        "sn_gx_" + i,
+        { points: [new BABYLON.Vector3(t, 0, -half), new BABYLON.Vector3(t, 0, half)] },
+        scene
+      );
+      gx.color = col;
+      const gz = BABYLON.MeshBuilder.CreateLines(
+        "sn_gz_" + i,
+        { points: [new BABYLON.Vector3(-half, 0, t), new BABYLON.Vector3(half, 0, t)] },
+        scene
+      );
+      gz.color = col;
+    }
+    const axis = [
+      [new BABYLON.Vector3(AXIS_LEN, 0, 0), new BABYLON.Color3(1, 0, 0)],
+      [new BABYLON.Vector3(0, AXIS_LEN, 0), new BABYLON.Color3(0, 1, 0)],
+      [new BABYLON.Vector3(0, 0, AXIS_LEN), new BABYLON.Color3(0, 0, 1)],
+    ];
+    for (let i = 0; i < axis.length; i += 1) {
+      const line = BABYLON.MeshBuilder.CreateLines(
+        "sn_ax_" + i,
+        { points: [BABYLON.Vector3.Zero(), axis[i][0]] },
+        scene
+      );
+      line.color = axis[i][1];
+    }
+  })();
+
+  let imported = [];
+  let lastPath = "";
+  let lastReset = null;
+  let lastPsize = null;
+  let lastWire = null;
+  let loadGen = 0;
+  let loadBusy = false;
+
+  function applyCam(shot) {
+    if (!shot) {
+      return;
+    }
+    if (camera.inertialAlphaOffset !== undefined) {
+      camera.inertialAlphaOffset = 0;
+      camera.inertialBetaOffset = 0;
+      camera.inertialRadiusOffset = 0;
+    }
+    if (camera.inertialPanningX !== undefined) {
+      camera.inertialPanningX = 0;
+      camera.inertialPanningY = 0;
+    }
+    camera.alpha = shot.a;
+    camera.beta = shot.b;
+    camera.radius = shot.r;
+    camera.setTarget(new BABYLON.Vector3(shot.tx, shot.ty, shot.tz));
+    scene.activeCamera = camera;
+  }
+
+  function applyDefaultCam() {
+    applyCam({
+      a: BABYLON.Tools.ToRadians(START_ALPHA),
+      b: BABYLON.Tools.ToRadians(START_BETA),
+      r: START_RADIUS,
+      tx: 0,
+      ty: 0,
+      tz: 0,
+    });
+  }
+
+  function frameDefault() {
+    applyDefaultCam();
+  }
+
+  function isOccPoints(mesh) {
+    /* Grid/axes are GL_LINES with idx.length === vert count. Treating those
+       as a point cloud turns the floor into dots. Only occupancy points. */
+    if (!mesh) {
+      return false;
+    }
+    return String(mesh.name || "").indexOf("occ_points") >= 0;
+  }
+
+  function isOccShell(mesh) {
+    if (!mesh) {
+      return false;
+    }
+    return String(mesh.name || "").indexOf("occ_shell") >= 0;
+  }
+
+  function applyWireframe(on) {
+    /* Inspect viewer: THREE.EdgesGeometry(geom, 25) on the solid, not
+       material.wireframe (that draws every triangle). Babylon's epsilon is
+       cos(threshold): draw an edge when adjacent face normals diverge. */
+    const want = !!on;
+    const epsilon = Math.cos((25 * Math.PI) / 180);
+    const edgeColor = new BABYLON.Color4(228 / 255, 232 / 255, 238 / 255, 0.9);
+    for (let i = 0; i < imported.length; i += 1) {
+      const mesh = imported[i];
+      if (!isOccShell(mesh)) {
+        continue;
+      }
+      const mats = mesh.material
+        ? Array.isArray(mesh.material)
+          ? mesh.material
+          : [mesh.material]
+        : [];
+      for (let m = 0; m < mats.length; m += 1) {
+        if (mats[m]) {
+          mats[m].wireframe = false;
+        }
+      }
+      if (want) {
+        mesh.enableEdgesRendering(epsilon);
+        mesh.edgesWidth = 1.5;
+        mesh.edgesColor = edgeColor;
+      } else if (mesh.disableEdgesRendering) {
+        mesh.disableEdgesRendering();
+      }
+    }
+  }
+  function applyPointSize(px) {
+    const size = Math.max(1, Math.min(24, Number(px) || DEFAULT_PSIZE));
+    for (let i = 0; i < imported.length; i += 1) {
+      const mesh = imported[i];
+      if (!isOccPoints(mesh)) {
+        continue;
+      }
+      const mats = mesh.material
+        ? Array.isArray(mesh.material)
+          ? mesh.material
+          : [mesh.material]
+        : [];
+      for (let m = 0; m < mats.length; m += 1) {
+        const mat = mats[m];
+        if (!mat) {
+          continue;
+        }
+        mat.pointsCloud = true;
+        mat.pointSize = size;
+        mat.disableLighting = true;
+        if (mat.unlit !== undefined) {
+          mat.unlit = true;
+        }
+      }
+    }
+  }
+
+  function clearImported() {
+    for (let i = 0; i < imported.length; i += 1) {
+      if (imported[i] && imported[i].dispose) {
+        imported[i].dispose(false, true);
+      }
+    }
+    imported = [];
+  }
+
+  async function loadGlb(url, px, wire) {
+    /* Freeze the orbit. Import must not frame, target, or replace the camera. */
+    const pose = {
+      a: camera.alpha,
+      b: camera.beta,
+      r: camera.radius,
+      tx: camera.target.x,
+      ty: camera.target.y,
+      tz: camera.target.z,
+    };
+    const gen = (loadGen += 1);
+    let result;
+    try {
+      result = await BABYLON.SceneLoader.ImportMeshAsync("", url, "", scene);
+    } catch (err) {
+      applyCam(pose);
+      throw err;
+    }
+    if (gen !== loadGen) {
+      (result.meshes || []).forEach(function (m) {
+        m.dispose(false, true);
+      });
+      applyCam(pose);
+      return;
+    }
+    clearImported();
+    imported = [];
+    (result.meshes || []).forEach(function (m) {
+      const n = String(m.name || "");
+      if (n.indexOf("occ_empty") >= 0) {
+        m.dispose(false, true);
+        return;
+      }
+      imported.push(m);
+    });
+    (result.cameras || []).forEach(function (cam) {
+      if (cam && cam.dispose) {
+        cam.dispose();
+      }
+    });
+    scene.activeCamera = camera;
+    applyPointSize(px);
+    applyWireframe(wire);
+    applyCam(pose);
+  }
+
+  async function tick() {
+    if (loadBusy) {
+      return;
+    }
+    const path = fieldPath();
+    const resetN = fieldReset();
+    const px = fieldPsize();
+    const wire = fieldWire();
+    if (!path) {
+      return;
+    }
+    const pathChanged = path !== lastPath;
+    const resetChanged = lastReset !== null && resetN !== lastReset;
+    const sizeChanged = lastPsize !== null && px !== lastPsize;
+    const wireChanged = lastWire !== null && wire !== lastWire;
+    if (!pathChanged && !resetChanged && !sizeChanged && !wireChanged) {
+      lastReset = resetN;
+      lastPsize = px;
+      lastWire = wire;
+      return;
+    }
+    if (pathChanged) {
+      lastPath = path;
+      lastReset = resetN;
+      lastPsize = px;
+      lastWire = wire;
+      loadBusy = true;
+      try {
+        await loadGlb(fileUrl(path), px, wire);
+      } catch (err) {
+        console.error("sn-orbit load", err);
+      } finally {
+        loadBusy = false;
+      }
+      return;
+    }
+    lastReset = resetN;
+    lastPsize = px;
+    lastWire = wire;
+    if (resetChanged) {
+      applyDefaultCam();
+    }
+    if (sizeChanged || resetChanged) {
+      applyPointSize(px);
+    }
+    if (wireChanged || resetChanged) {
+      applyWireframe(wire);
+    }
+  }
+
+  window.addEventListener("resize", function () {
+    engine.resize();
+  });
+  engine.runRenderLoop(function () {
+    scene.render();
+  });
+
+  applyDefaultCam();
+
+  window.__snOrbit = {
+    alive: function () {
+      return !!(
+        engine &&
+        !engine.isDisposed &&
+        canvas &&
+        canvas.isConnected &&
+        engine.getRenderingCanvas() === canvas
+      );
+    },
+  };
+
+  await tick();
+  window.setInterval(tick, 200);
+})();

src/gradio/pipeline.py

@@ -0,0 +1,133 @@
+"""Gradio occupancy loop: fill an OBJ AABB, then classify with ``best.pt``.
+
+Reuses the viewer helper (``obj_fill``, ``infer_job``, ``model_access``).
+Does not import Gradio and does not change the Three.js viewer.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+# Occupancy is the installed ``scatteringnet`` package (``pip install -e .``).
+# This folder is not a package so it cannot shadow pip ``gradio``.
+_GRADIO_DIR = Path(__file__).resolve().parent
+_REPO = _GRADIO_DIR.parents[1]
+
+from scatteringnet.config import load_config
+from scatteringnet.viewer.infer_job import infer_uploaded_obj, pred_from_probs  # noqa: E402
+from scatteringnet.viewer.model_access import inspect_run_id, list_viewer_models  # noqa: E402
+from scatteringnet.viewer.obj_fill import (  # noqa: E402
+    fill_aabb_lattice,
+    spacing_from_slider,
+    triangles_from_obj_text,
+)
+
+# INSPECT alias from docs/inspect_checkpoint.yaml (not the newest best.pt).
+INSPECT_RUN_ID = inspect_run_id()
+# Viewer allows 200k; Plotly + Spaces need a tighter lattice.
+MAX_FILL_POINTS = 80_000
+MAX_OBJ_BYTES = 32 * 1024 * 1024
+# Slider default matches the Three.js Density control (spacing ~0.15).
+DEFAULT_DENSITY = 71
+DEFAULT_CUT = 0.50
+
+
+def models_root() -> Path:
+    """Repo ``models/`` (``models/<run_id>/best.pt``)."""
+    return _REPO / "models"
+
+
+def list_run_ids(root: Path | None = None) -> list[str]:
+    """Newest-first run folder names that have a ``best.pt``."""
+    rows = list_viewer_models(root or models_root())
+    return [str(row["id"]) for row in rows]
+
+
+def default_run_id(root: Path | None = None) -> str:
+    """INSPECT pointer if that ``best.pt`` exists, else newest, else empty."""
+    ids = list_run_ids(root)
+    wanted = inspect_run_id()
+    if wanted and wanted in ids:
+        return wanted
+    return ids[0] if ids else ""
+
+
+def runtime_cfg(cfg: Any | None = None):
+    """
+    Device / batch from YAML. ``data_dir`` is not required (uploaded OBJ).
+    """
+    if cfg is not None:
+        return cfg
+    return load_config(require_existing_data_dir=False)
+
+
+def apply_cut(probs: np.ndarray, threshold: float) -> tuple[np.ndarray, int, int]:
+    """Hard labels from stored sigmoid probs (no extra GPU pass)."""
+    pred = pred_from_probs(probs, threshold)
+    n_in = int(np.count_nonzero(pred > 0))
+    return pred, n_in, int(pred.shape[0]) - n_in
+
+
+def fill_and_infer(
+    obj_text: str,
+    *,
+    obj_name: str,
+    run_id: str,
+    density: float,
+    models: Path | None = None,
+    cfg: Any | None = None,
+) -> dict[str, Any]:
+    """
+    Job B for Gradio: AABB lattice + occupancy forward.
+
+    Returns vertices/faces (for the Plotly mesh), query XYZ, sigmoid
+    probs, timings, and the run id. The UI recuts ``probs`` locally.
+    """
+    raw = str(obj_text or "")
+    if not raw.strip():
+        raise ValueError("OBJ is empty")
+    if len(raw.encode("utf-8")) > MAX_OBJ_BYTES:
+        raise ValueError(f"OBJ too large (max {MAX_OBJ_BYTES} bytes)")
+    name = str(run_id or "").strip()
+    if not name:
+        raise ValueError("select a checkpoint under models/<run_id>/best.pt")
+
+    vertices, faces = triangles_from_obj_text(raw)
+    spacing = spacing_from_slider(density)
+    points, used, grid = fill_aabb_lattice(
+        vertices, spacing, max_points=MAX_FILL_POINTS
+    )
+    ckpt_root = Path(models) if models is not None else models_root()
+    out = infer_uploaded_obj(
+        run_id=name,
+        models_root=ckpt_root,
+        data_dir=None,
+        obj_name=str(obj_name or "upload.obj"),
+        obj_text=raw,
+        points=points,
+        cfg=runtime_cfg(cfg),
+    )
+    probs = np.frombuffer(base64.b64decode(out["prob_b64"]), dtype=np.float32).reshape(
+        -1
+    )
+    pred, n_in, n_out = apply_cut(probs, DEFAULT_CUT)
+    return {
+        "vertices": np.ascontiguousarray(vertices, dtype=np.float32),
+        "faces": np.ascontiguousarray(faces, dtype=np.int32),
+        "points": np.ascontiguousarray(points, dtype=np.float32),
+        "probs": np.ascontiguousarray(probs, dtype=np.float32),
+        "pred": pred,
+        "n": int(out["n"]),
+        "n_inside": n_in,
+        "n_outside": n_out,
+        "used_spacing": float(used),
+        "grid": [int(grid[0]), int(grid[1]), int(grid[2])],
+        "run_id": str(out["run_id"]),
+        "shape_encoder": str(out["shape_encoder"]),
+        "timings": dict(out["timings"]),
+        "obj_name": str(obj_name or "upload.obj"),
+    }

src/infer_multi_npz.py

@@ -0,0 +1,202 @@
+"""Classify occupancy NPZs from ``models/<run_id>/best.pt``.
+
+Rebuilds ``OccupancyMLP`` or ``OccupancyEncoder`` from the checkpoint
+``kind``. Query XYZ (and envelope, when conditioned) use the stored
+per-mesh AABB, not a fresh map. Face-token checkpoints are rejected.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+
+from scatteringnet.config import OccupancyConfig, as_data_relative, load_config, repo_root
+from scatteringnet.data_npz import load_points_labels, load_points_labels_mesh
+from scatteringnet.geometry.mesh_io import load_obj_triangles
+from scatteringnet.geometry.surface import apply_envelope_aabb, project_envelope_dim, sample_surface_points
+from scatteringnet.metrics import occupancy_metrics
+from scatteringnet.normalize import apply_normalization
+from scatteringnet.occupancy_encoder import (
+    OccupancyEncoder,
+    envelope_dim_from_ckpt,
+    envelope_seed_from_ckpt,
+)
+from scatteringnet.occupancy_encoder import CHECKPOINT_KIND as ENCODER_KIND
+from scatteringnet.occupancy_mlp import OccupancyMLP
+from scatteringnet.occupancy_mlp import CHECKPOINT_KIND as MLP_KIND
+
+
+def resolve_best_pt(
+    *,
+    checkpoint: Path | str | None = None,
+    run_id: str | None = None,
+    root: Path | None = None,
+) -> Path:
+    """Resolve ``best.pt`` from an explicit path or ``runs/<id>/checkpoint_dir.txt``."""
+    base = (root or repo_root()).resolve()
+    if checkpoint is not None:
+        path = Path(checkpoint)
+        if not path.is_absolute():
+            path = base / path
+        if not path.is_file():
+            raise FileNotFoundError(f"checkpoint not found: {path}")
+        return path
+    if not run_id:
+        raise ValueError("pass checkpoint= or run_id=")
+    pointer = base / "runs" / str(run_id) / "checkpoint_dir.txt"
+    if not pointer.is_file():
+        raise FileNotFoundError(f"run pointer not found: {pointer}")
+    rel = pointer.read_text(encoding="utf-8").strip()
+    path = Path(rel)
+    if not path.is_absolute():
+        path = base / path
+    best = path / "best.pt" if path.is_dir() else path
+    if not best.is_file():
+        raise FileNotFoundError(f"best.pt not found: {best}")
+    return best
+
+
+def load_occupancy_model(
+    ckpt: dict[str, Any],
+    device: torch.device,
+) -> OccupancyMLP | OccupancyEncoder:
+    """Rebuild the head recorded in ``ckpt['kind']`` and load weights."""
+    hidden = int(ckpt["hidden"])
+    depth = int(ckpt["depth"])
+    kind = str(ckpt["kind"])
+    if kind == MLP_KIND:
+        model: OccupancyMLP | OccupancyEncoder = OccupancyMLP(hidden=hidden, depth=depth)
+    elif kind == ENCODER_KIND:
+        latent = int(ckpt["latent_dim"]) if ckpt.get("latent_dim") is not None else hidden
+        enc = str(ckpt.get("shape_encoder") or "surface").strip().lower()
+        if enc == "mesh":
+            raise ValueError(
+                "face-token occupancy checkpoints (shape_encoder='mesh') "
+                "are no longer supported"
+            )
+        knn_k = int(ckpt["knn_k"]) if ckpt.get("knn_k") is not None else 0
+        knn_local = None
+        if knn_k > 0 and ckpt.get("knn_local_dim") is not None:
+            knn_local = int(ckpt["knn_local_dim"])
+        model = OccupancyEncoder(
+            hidden=hidden,
+            depth=depth,
+            latent_dim=latent,
+            shape_encoder=enc,
+            knn_k=knn_k,
+            knn_local_dim=knn_local,
+            envelope_dim=envelope_dim_from_ckpt(ckpt),
+        )
+    else:
+        raise ValueError(f"unsupported checkpoint kind {kind!r}")
+    model.load_state_dict(ckpt["state_dict"])
+    return model.to(device).eval()
+
+
+def _part_for_npz(ckpt: dict[str, Any], npz_path: Path, data_dir: Path) -> dict[str, Any]:
+    rel = as_data_relative(npz_path, data_dir)
+    name = npz_path.name
+    for part in ckpt.get("parts") or []:
+        stored = str(part.get("npz", ""))
+        if stored == rel or Path(stored).name == name:
+            return part
+    raise KeyError(f"no AABB part for {npz_path.name} in checkpoint")
+
+
+def infer_npz(
+    cfg: OccupancyConfig,
+    *,
+    checkpoint: Path | str | None = None,
+    run_id: str | None = None,
+    npz_path: Path | str | None = None,
+    root: Path | None = None,
+) -> dict[str, float]:
+    """
+    Score one NPZ with ``best.pt``. Returns accuracy / IoU / F1.
+    """
+    ckpt_path = resolve_best_pt(checkpoint=checkpoint, run_id=run_id, root=root)
+    ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+    model = load_occupancy_model(ckpt, cfg.device)
+    if npz_path is None:
+        rels = ckpt.get("npz_paths") or []
+        if not rels:
+            raise ValueError("checkpoint has no npz_paths; pass npz_path=")
+        npz = cfg.data_dir / str(rels[0])
+    else:
+        npz = Path(npz_path)
+        if not npz.is_absolute():
+            npz = cfg.data_dir / npz
+    part = _part_for_npz(ckpt, npz, cfg.data_dir)
+    center = np.asarray(part["center"], dtype=np.float32)
+    scale = float(part["scale"])
+    geom = None
+    shape_id = None
+    enc = str(ckpt.get("shape_encoder", "none")).strip().lower()
+    if enc == "mesh":
+        raise ValueError(
+            "face-token occupancy checkpoints (shape_encoder='mesh') "
+            "are no longer supported"
+        )
+    if enc == "surface":
+        points, labels, mesh_path = load_points_labels_mesh(npz, cfg.data_dir)
+        vertices, faces = load_obj_triangles(mesh_path)
+        cache_key = str(mesh_path.resolve())
+        n_surface = int(ckpt.get("n_surface") or cfg.n_surface)
+        world = sample_surface_points(
+            vertices,
+            faces,
+            n_surface,
+            seed=envelope_seed_from_ckpt(ckpt),
+            cache_key=cache_key,
+        )
+        arr = apply_envelope_aabb(world, center, scale)
+        arr = project_envelope_dim(arr, envelope_dim_from_ckpt(ckpt))
+        geom = torch.from_numpy(arr).unsqueeze(0)
+        shape_id = torch.zeros((), dtype=torch.long)
+    else:
+        points, labels = load_points_labels(npz)
+    xyz = torch.from_numpy(apply_normalization(points, center, scale))
+    y = torch.from_numpy(np.asarray(labels, dtype=np.float32)).unsqueeze(1)
+    logits_rows: list[torch.Tensor] = []
+    with torch.no_grad():
+        for start in range(0, int(xyz.shape[0]), int(cfg.batch_size)):
+            sl = slice(start, start + int(cfg.batch_size))
+            batch_xyz = xyz[sl].to(cfg.device)
+            if geom is None:
+                logits_rows.append(model(batch_xyz).cpu())
+            else:
+                b = int(batch_xyz.shape[0])
+                geom_b = geom.expand(b, -1, -1).to(cfg.device)
+                sid = shape_id.expand(b).to(cfg.device)
+                logits_rows.append(model(batch_xyz, geom_b, sid).cpu())
+    logits = torch.cat(logits_rows, dim=0)
+    scores = occupancy_metrics(logits, y)
+    print(
+        f"checkpoint={ckpt_path} npz={npz.name} "
+        f"acc={scores.accuracy:.4f} iou={scores.inside_iou:.4f} "
+        f"f1={scores.inside_f1:.4f}"
+    )
+    return {
+        "accuracy": scores.accuracy,
+        "inside_iou": scores.inside_iou,
+        "inside_f1": scores.inside_f1,
+    }
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Infer occupancy from models/<id>/best.pt")
+    parser.add_argument("--checkpoint", default=None, help="Path to best.pt")
+    parser.add_argument("--run-id", default=None, help="runs/<id> folder name")
+    parser.add_argument("--npz", default=None, help="NPZ path (data_dir-relative or absolute)")
+    args = parser.parse_args()
+    infer_npz(
+        load_config(),
+        checkpoint=args.checkpoint,
+        run_id=args.run_id,
+        npz_path=args.npz,
+    )

src/metrics.py

@@ -0,0 +1,156 @@
+"""Occupancy classification metrics from logits vs labels.
+
+The model emits raw logits (no sigmoid in ``forward``). Metrics apply
+sigmoid only at decision time so they stay consistent with
+``BCEWithLogitsLoss`` and with inference (threshold ``0.5``).
+
+Inside (label ``1``) is the product-relevant class: points that belong
+in the interior. Precision / recall are therefore reported for that
+class only. No extra packages (sklearn, etc.).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+from torch import Tensor
+
+
+@dataclass(frozen=True)
+class OccupancyMetrics:
+    """Pointwise occupancy scores for one batch or a full set of queries."""
+
+    accuracy: float
+    inside_precision: float
+    inside_recall: float
+    inside_iou: float
+    inside_f1: float
+
+
+def _safe_div(numerator: float, denominator: float) -> float:
+    """Return ``0.0`` when the count in the denominator is zero (no sklearn)."""
+    if denominator <= 0.0:
+        return 0.0
+    return numerator / denominator
+
+
+def _flatten_pair(logits: Tensor, labels: Tensor) -> tuple[Tensor, Tensor]:
+    """
+    Collapse ``(B, 1)`` or ``(B,)`` logits / labels to a shared 1-D view.
+
+    Last dim of logits is 1 when it comes from ``OccupancyMLP``; labels from
+    the Dataset match that. A 1-D label vector is accepted so callers do not
+    have to unsqueeze.
+    """
+    if logits.numel() != labels.numel():
+        raise ValueError(
+            f"logits and labels must have the same number of elements, "
+            f"got logits={tuple(logits.shape)} labels={tuple(labels.shape)}"
+        )
+    return logits.reshape(-1), labels.reshape(-1)
+
+
+def occupancy_metrics(
+    logits: Tensor,
+    labels: Tensor,
+    *,
+    threshold: float = 0.5,
+) -> OccupancyMetrics:
+    """
+    Accuracy plus inside precision / recall from occupancy logits.
+
+    Parameters
+    ----------
+    logits:
+        Unnormalized scores, shape ``(B, 1)`` or ``(B,)``. Positive → inside.
+    labels:
+        Float ``{0, 1}`` with the same number of elements as ``logits``.
+    threshold:
+        Decision cut on ``sigmoid(logit)``. Default ``0.5`` matches inference.
+
+    Returns
+    -------
+    OccupancyMetrics
+        Scalar floats on CPU (safe to print or average across batches).
+    """
+    # Sigmoid here only: training still uses BCE-with-logits on raw logits.
+    tp, fp, fn, correct, n = occupancy_counts(logits, labels, threshold=threshold)
+    return occupancy_metrics_from_counts(tp=tp, fp=fp, fn=fn, correct=correct, n=n)
+
+
+def occupancy_counts(
+    logits: Tensor,
+    labels: Tensor,
+    *,
+    threshold: float = 0.5,
+) -> tuple[float, float, float, float, float]:
+    """Return ``(tp, fp, fn, correct, n)`` for a micro-average over points."""
+    logits_flat, labels_flat = _flatten_pair(logits, labels)
+    pred_inside = logits_flat.sigmoid() >= threshold
+    true_inside = labels_flat > 0.5
+    pred_f = pred_inside.to(dtype=torch.float32)
+    true_f = true_inside.to(dtype=torch.float32)
+    tp = float((pred_f * true_f).sum().item())
+    fp = float((pred_f * (1.0 - true_f)).sum().item())
+    fn = float(((1.0 - pred_f) * true_f).sum().item())
+    correct = float((pred_inside == true_inside).to(dtype=torch.float32).sum().item())
+    n = float(pred_inside.numel())
+    return tp, fp, fn, correct, n
+
+
+def occupancy_metrics_from_counts(
+    *,
+    tp: float,
+    fp: float,
+    fn: float,
+    correct: float,
+    n: float,
+) -> OccupancyMetrics:
+    """Build metrics from accumulated confusion counts (point micro-average)."""
+    precision = _safe_div(tp, tp + fp)
+    recall = _safe_div(tp, tp + fn)
+    return OccupancyMetrics(
+        accuracy=_safe_div(correct, n),
+        inside_precision=precision,
+        inside_recall=recall,
+        inside_iou=_safe_div(tp, tp + fp + fn),
+        inside_f1=_safe_div(2.0 * precision * recall, precision + recall),
+    )
+
+
+def accuracy_from_logits(
+    logits: Tensor,
+    labels: Tensor,
+    *,
+    threshold: float = 0.5,
+) -> float:
+    """Fraction of points whose thresholded sigmoid matches the 0/1 label.
+
+    Parameters
+    ----------
+    logits, labels, threshold:
+        Same meaning as :func:`occupancy_metrics`.
+
+    Returns
+    -------
+    float
+        Accuracy in ``[0, 1]``.
+    """
+    return occupancy_metrics(logits, labels, threshold=threshold).accuracy
+
+
+if __name__ == "__main__":
+    # Deterministic 8-point batch: 4 true insides, 4 true outsides, all correct.
+    demo_logits = torch.tensor(
+        [[4.0], [3.0], [2.0], [1.0], [-1.0], [-2.0], [-3.0], [-4.0]]
+    )
+    demo_labels = torch.tensor(
+        [[1.0], [1.0], [1.0], [1.0], [0.0], [0.0], [0.0], [0.0]]
+    )
+    scores = occupancy_metrics(demo_logits, demo_labels)
+    print(f"accuracy={scores.accuracy:.4f}")
+    print(f"inside_precision={scores.inside_precision:.4f}")
+    print(f"inside_recall={scores.inside_recall:.4f}")
+    print(f"inside_iou={scores.inside_iou:.4f}")
+    print(f"inside_f1={scores.inside_f1:.4f}")

src/normalize.py

@@ -0,0 +1,104 @@
+"""AABB normalization for occupancy XYZ.
+
+Maps a point cloud into a roughly ``[-1, 1]^3`` cube so the MLP sees
+comparable coordinates across differently sized meshes.
+
+  center = midpoint of the axis-aligned bounding box
+  scale  = maximum half-extent (longest AABB side / 2)
+
+Normalized point: ``(xyz - center) / scale``.
+This module does not touch the occupancy model.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+PointsArray = NDArray[np.float32]
+
+
+def compute_center_scale(points: np.ndarray) -> tuple[PointsArray, float]:
+    """
+    AABB center and max half-extent for an ``(N, 3)`` point array.
+
+    Parameters
+    ----------
+    points:
+        Query XYZ, shape ``(N, 3)``, at least one row.
+
+    Returns
+    -------
+    center:
+        ``float32`` vector of shape ``(3,)``.
+    scale:
+        Positive float (max half-extent). Raises if the cloud has no extent.
+    """
+    pts = np.asarray(points, dtype=np.float32)
+    if pts.ndim != 2 or pts.shape[1] != 3:
+        raise ValueError(f"points must have shape (N, 3), got {tuple(pts.shape)}")
+    if pts.shape[0] == 0:
+        raise ValueError("points must contain at least one row")
+
+    xyz_min = pts.min(axis=0)
+    xyz_max = pts.max(axis=0)
+    center = 0.5 * (xyz_min + xyz_max)
+    half_extents = 0.5 * (xyz_max - xyz_min)
+    scale = float(np.max(half_extents))
+    if scale <= 0.0:
+        raise ValueError(
+            "scale must be > 0; all points appear to share the same location"
+        )
+    return center.astype(np.float32, copy=False), scale
+
+
+def apply_normalization(
+    points: np.ndarray,
+    center: np.ndarray,
+    scale: float,
+) -> PointsArray:
+    """
+    Return ``(points - center) / scale`` as ``float32 (N, 3)``.
+
+    Parameters
+    ----------
+    points:
+        Query XYZ, shape ``(N, 3)``.
+    center:
+        AABB midpoint, shape ``(3,)``.
+    scale:
+        Positive max half-extent.
+
+    Returns
+    -------
+    ndarray
+        Normalized points, ``float32 (N, 3)``.
+    """
+    if scale <= 0.0:
+        raise ValueError(f"scale must be > 0, got {scale}")
+    pts = np.asarray(points, dtype=np.float32)
+    if pts.ndim != 2 or pts.shape[1] != 3:
+        raise ValueError(f"points must have shape (N, 3), got {tuple(pts.shape)}")
+    c = np.asarray(center, dtype=np.float32).reshape(3)
+    return (pts - c) / np.float32(scale)
+
+
+if __name__ == "__main__":
+    from scatteringnet.config import load_config
+    from scatteringnet.data_npz import load_points_labels
+
+    sample = (
+        load_config().data_dir
+        / "exports"
+        / "dataset_test"
+        / "sphere__raycast_z_raut_s0.15_inout.npz"
+    )
+    points, _labels = load_points_labels(sample)
+    center, scale = compute_center_scale(points)
+    normed = apply_normalization(points, center, scale)
+    recovered = normed[:3] * np.float32(scale) + center
+    print(f"file={sample}")
+    print(f"center={center.tolist()} scale={scale:.6f}")
+    print(f"normed_min={normed.min(axis=0).tolist()}")
+    print(f"normed_max={normed.max(axis=0).tolist()}")
+    print(f"inverse_ok={np.allclose(recovered, points[:3], rtol=1e-5, atol=1e-5)}")

src/occupancy_encoder.py

@@ -0,0 +1,248 @@
+"""Geometry-conditioned occupancy: query XYZ plus a shape latent.
+
+``OccupancyMLP`` stays xyz-only. ``shape_encoder: surface`` is the
+envelope PointNet over ``(N, 6)`` XYZ + face normal (or ``(N, 3)``
+for older checkpoints). ``knn_k > 0`` adds per-query nearest-neighbor
+features (XYZ offset, plus the neighbor normal when the cloud is 6-D).
+The face-token head (``shape_encoder: mesh``) was removed.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from torch import Tensor
+
+from scatteringnet.occupancy_mlp import build_mlp
+
+# Distinct from OccupancyMLP so infer can tell the checkpoint apart.
+CHECKPOINT_KIND = "occupancy_encoder"
+
+
+class SurfaceEncoder(nn.Module):
+    """
+    Per-point MLP + max-pool (PointNet) over an envelope cloud.
+
+    Shapes
+    ------
+    envelope: ``(U, N, C)`` unique meshes; ``C`` is 3 (XYZ) or 6 (XYZ+n)
+    output:   ``(U, D)``    one latent per mesh
+    """
+
+    def __init__(
+        self, latent_dim: int = 64, hidden: int = 64, *, in_dim: int = 3
+    ) -> None:
+        super().__init__()
+        if latent_dim < 1:
+            raise ValueError(f"latent_dim must be >= 1, got {latent_dim}")
+        if hidden < 1:
+            raise ValueError(f"hidden must be >= 1, got {hidden}")
+        dim = int(in_dim)
+        if dim not in (3, 6):
+            raise ValueError(f"in_dim must be 3 or 6, got {dim}")
+        self.latent_dim = latent_dim
+        self.hidden = hidden
+        self.in_dim = dim
+        self.point_mlp = nn.Sequential(
+            nn.Linear(dim, hidden),
+            nn.ReLU(inplace=True),
+            nn.Linear(hidden, latent_dim),
+        )
+
+    def forward(self, envelope: Tensor) -> Tensor:
+        """Max-pool per-point features → one vector per unique mesh."""
+        if envelope.ndim != 3 or envelope.shape[-1] != self.in_dim:
+            raise ValueError(
+                f"envelope must have shape (U, N, {self.in_dim}), "
+                f"got {tuple(envelope.shape)}"
+            )
+        features = self.point_mlp(envelope)
+        return features.max(dim=1).values
+
+
+def knn_offsets(xyz: Tensor, envelope: Tensor, k: int) -> Tensor:
+    """
+    Offsets from each query to its ``k`` nearest envelope points.
+
+    Distances use XYZ only (AABB Euclidean). ``k`` is clamped to N.
+    If the cloud is ``(B, N, 6)``, each neighbor is
+    ``(dx, dy, dz, nx, ny, nz)`` — relative position plus that
+    neighbor's stored normal. Query points have no normal.
+
+    Shapes: ``xyz (B, 3)``, ``envelope (B, N, 3|6)`` → ``(B, k, 3|6)``.
+    """
+    if xyz.ndim != 2 or xyz.shape[-1] != 3:
+        raise ValueError(f"xyz must have shape (B, 3), got {tuple(xyz.shape)}")
+    if envelope.ndim != 3 or envelope.shape[-1] not in (3, 6):
+        raise ValueError(
+            f"envelope must have shape (B, N, 3 or 6), got {tuple(envelope.shape)}"
+        )
+    if int(xyz.shape[0]) != int(envelope.shape[0]):
+        raise ValueError(
+            f"xyz/envelope batch mismatch: {tuple(xyz.shape)} vs {tuple(envelope.shape)}"
+        )
+    n_env = int(envelope.shape[1])
+    if n_env < 1:
+        raise ValueError("envelope length N must be >= 1")
+    take = min(int(k), n_env)
+    if take < 1:
+        raise ValueError(f"k must be >= 1, got {k}")
+    feat = int(envelope.shape[-1])
+    # k-NN is position-only; extras (normals) ride along after the gather.
+    pos = envelope[..., :3]
+    dist = torch.linalg.norm(pos - xyz.unsqueeze(1), dim=-1)
+    idx = dist.topk(take, dim=-1, largest=False).indices
+    nbrs = torch.gather(envelope, 1, idx.unsqueeze(-1).expand(-1, -1, feat))
+    rel_xyz = nbrs[..., :3] - xyz.unsqueeze(1)
+    if feat == 3:
+        return rel_xyz
+    return torch.cat([rel_xyz, nbrs[..., 3:]], dim=-1)
+
+
+# Catalog trains used YAML seed 1. Old best.pt files omit ``seed``.
+DEFAULT_ENVELOPE_SEED = 1
+
+
+def envelope_seed_from_ckpt(ckpt: dict) -> int:
+    """
+    Envelope RNG seed this checkpoint was trained with.
+
+    New trains store ``seed`` on ``best.pt``. Older files omit it; do
+    not fall back to live YAML (that knob may have changed since train).
+    """
+    raw = ckpt.get("seed")
+    if raw is None:
+        return DEFAULT_ENVELOPE_SEED
+    return int(raw)
+
+
+def envelope_dim_from_ckpt(ckpt: dict) -> int:
+    """
+    Envelope channel count this checkpoint was trained with.
+
+    New trains store ``envelope_dim``. Older XYZ-only ``best.pt`` files
+    omit it; the first SurfaceEncoder Linear in-features is then 3.
+    """
+    raw = ckpt.get("envelope_dim")
+    if raw is not None:
+        dim = int(raw)
+        if dim not in (3, 6):
+            raise ValueError(f"envelope_dim must be 3 or 6, got {dim}")
+        return dim
+    weight = (ckpt.get("state_dict") or {}).get("surface.point_mlp.0.weight")
+    if weight is not None:
+        dim = int(weight.shape[1])
+        if dim in (3, 6):
+            return dim
+    return 3
+
+
+class OccupancyEncoder(nn.Module):
+    """
+    Occupancy logits from query XYZ and an envelope code.
+
+    Unique ``shape_id`` values are encoded **once** per batch, then
+    broadcast. ``knn_k > 0`` concatenates a local envelope code.
+
+    Shapes
+    ------
+    xyz:      ``(B, 3)``
+    geom:     ``(B, N, C)`` envelope; ``C`` is ``envelope_dim`` (3 or 6)
+    shape_id: ``(B,)`` long
+    output:   ``(B, 1)`` logits
+    """
+
+    def __init__(
+        self,
+        hidden: int = 64,
+        depth: int = 4,
+        latent_dim: int = 64,
+        *,
+        shape_encoder: str = "surface",
+        knn_k: int = 0,
+        knn_local_dim: int | None = None,
+        envelope_dim: int = 6,
+    ) -> None:
+        super().__init__()
+        if hidden < 1:
+            raise ValueError(f"hidden must be >= 1, got {hidden}")
+        if depth < 1:
+            raise ValueError(f"depth must be >= 1, got {depth}")
+        if latent_dim < 1:
+            raise ValueError(f"latent_dim must be >= 1, got {latent_dim}")
+        kind = str(shape_encoder).strip().lower()
+        if kind != "surface":
+            raise ValueError(
+                "OccupancyEncoder only supports shape_encoder='surface' "
+                f"(face-token 'mesh' was removed), got {shape_encoder!r}"
+            )
+        k = int(knn_k)
+        if k < 0:
+            raise ValueError(f"knn_k must be >= 0, got {k}")
+        local_dim = int(knn_local_dim) if knn_local_dim is not None else int(latent_dim)
+        if k > 0 and local_dim < 1:
+            raise ValueError(f"knn_local_dim must be >= 1, got {local_dim}")
+        ed = int(envelope_dim)
+        if ed not in (3, 6):
+            raise ValueError(f"envelope_dim must be 3 or 6, got {ed}")
+        self.hidden = hidden
+        self.depth = depth
+        self.latent_dim = latent_dim
+        self.shape_encoder = kind
+        self.knn_k = k
+        self.knn_local_dim = local_dim if k > 0 else 0
+        self.envelope_dim = ed
+        # Name ``surface`` is load-stable for existing envelope checkpoints.
+        self.surface = SurfaceEncoder(latent_dim=latent_dim, hidden=hidden, in_dim=ed)
+        self.token_dim = ed
+        head_in = 3 + latent_dim
+        if k > 0:
+            # Same PointNet block as the global envelope, over k neighbor features.
+            self.local = SurfaceEncoder(latent_dim=local_dim, hidden=hidden, in_dim=ed)
+            head_in += local_dim
+        self.head = build_mlp(head_in, hidden, depth)
+
+    def encode_unique(self, geom: Tensor, shape_id: Tensor) -> Tensor:
+        """
+        Encode each distinct ``shape_id`` once and scatter back to ``(B, D)``.
+
+        Parameters
+        ----------
+        geom, shape_id:
+            Batched envelope clouds and integer mesh ids (same length B).
+        """
+        if shape_id.ndim != 1 or int(shape_id.shape[0]) != int(geom.shape[0]):
+            raise ValueError(
+                f"shape_id must be (B,), got {tuple(shape_id.shape)} "
+                f"for geom {tuple(geom.shape)}"
+            )
+        unique_ids, inverse = torch.unique(shape_id, sorted=True, return_inverse=True)
+        hits = shape_id.unsqueeze(0) == unique_ids.unsqueeze(1)
+        first = hits.to(dtype=torch.int64).argmax(dim=1)
+        z_unique = self.surface(geom[first])
+        return z_unique[inverse]
+
+    def forward(
+        self,
+        xyz: Tensor,
+        geom: Tensor,
+        shape_id: Tensor,
+    ) -> Tensor:
+        """``cat(xyz, z_global[, z_local])`` → occupancy logit."""
+        if xyz.ndim != 2 or xyz.shape[-1] != 3:
+            raise ValueError(f"xyz must have shape (B, 3), got {tuple(xyz.shape)}")
+        if geom.ndim != 3 or geom.shape[-1] != self.token_dim:
+            raise ValueError(
+                f"geom must have shape (B, K, {self.token_dim}), got {tuple(geom.shape)}"
+            )
+        if int(xyz.shape[0]) != int(geom.shape[0]):
+            raise ValueError(
+                f"xyz/geom batch mismatch: {tuple(xyz.shape)} vs {tuple(geom.shape)}"
+            )
+        ids = shape_id.reshape(-1)
+        z_shape = self.encode_unique(geom, ids)
+        pieces = [xyz, z_shape]
+        if self.knn_k > 0:
+            rel = knn_offsets(xyz, geom, self.knn_k)
+            pieces.append(self.local(rel))
+        return self.head(torch.cat(pieces, dim=-1))

src/occupancy_mlp.py

@@ -0,0 +1,87 @@
+"""Occupancy MLP: raw XYZ → inside/outside logit."""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from torch import Tensor
+
+# Checkpoint schema tag (not a YAML knob).
+CHECKPOINT_KIND = "occupancy_mlp"
+
+
+def build_mlp(in_dim: int, hidden: int, depth: int) -> nn.Sequential:
+    """Linear→ReLU × ``depth`` then a 1-logit head. Shared by OccupancyMLP."""
+    if in_dim < 1:
+        raise ValueError(f"in_dim must be >= 1, got {in_dim}")
+    if hidden < 1:
+        raise ValueError(f"hidden must be >= 1, got {hidden}")
+    if depth < 1:
+        raise ValueError(f"depth must be >= 1, got {depth}")
+    layers: list[nn.Module] = []
+    dim = in_dim
+    for _ in range(depth):
+        layers.append(nn.Linear(dim, hidden))
+        layers.append(nn.ReLU(inplace=True))
+        dim = hidden
+    layers.append(nn.Linear(dim, 1))
+    return nn.Sequential(*layers)
+
+
+class OccupancyMLP(nn.Module):
+    """
+    Tiny fully-connected occupancy field.
+
+    Maps a batch of 3D query coordinates to a single unnormalized logit per
+    point. A later training step will apply ``binary_cross_entropy_with_logits``
+    (do not softmax / sigmoid inside ``forward``).
+
+    Shapes
+    ------
+    xyz:    ``(B, 3)``  batch of query points (device follows the caller)
+    output: ``(B, 1)``  logits; positive → inside, negative → outside
+
+    Device
+    ------
+    Parameters live on whatever device the module was moved to
+    (``.to(device)`` / ``.cuda()``). ``xyz`` must already be on that same
+    device; this module does not copy tensors.
+    """
+
+    def __init__(self, hidden: int = 64, depth: int = 4) -> None:
+        """
+        Build Linear→ReLU blocks then a 1-logit head.
+
+        Parameters
+        ----------
+        hidden:
+            Channel width of each hidden Linear (must be ``>= 1``).
+        depth:
+            Number of hidden Linear+ReLU blocks (must be ``>= 1``).
+        """
+        super().__init__()
+        self.hidden = hidden
+        self.depth = depth
+        # First Linear is 3 → H; remaining blocks are H → H.
+        self.net = build_mlp(3, hidden, depth)
+
+    def forward(self, xyz: Tensor) -> Tensor:
+        """
+        Evaluate occupancy logits at query coordinates.
+
+        Parameters
+        ----------
+        xyz:
+            Float tensor of shape ``(B, 3)``. Last dim is Cartesian XYZ.
+
+        Returns
+        -------
+        Tensor
+            Float tensor of shape ``(B, 1)`` on the same device as ``xyz``.
+        """
+        if xyz.ndim != 2 or xyz.shape[-1] != 3:
+            raise ValueError(
+                f"xyz must have shape (B, 3), got {tuple(xyz.shape)}"
+            )
+        # Sequential Linear layers require matching dtype/device with parameters.
+        return self.net(xyz)

src/viewer/__init__.py

@@ -0,0 +1 @@
+"""Three.js inspect helper (HTTP + Job A / Job B)."""

src/viewer/infer_job.py

@@ -0,0 +1,536 @@
+"""Job A / B: classify uploaded points with a ``models/*/best.pt``.
+
+Reuses ``load_occupancy_model`` and AABB helpers. Envelope tokens follow
+the **checkpoint**, not live ``config.yaml``. Face-token checkpoints
+are rejected. Does not modify occupancy train/infer modules.
+"""
+
+from __future__ import annotations
+
+import base64
+import threading
+import time
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from scatteringnet.config import OccupancyConfig
+
+import numpy as np
+
+
+from scatteringnet.infer_multi_npz import load_occupancy_model  # noqa: E402
+from scatteringnet.geometry.mesh_io import load_obj_triangles  # noqa: E402
+from scatteringnet.geometry.surface import (  # noqa: E402
+    apply_envelope_aabb,
+    project_envelope_dim,
+    sample_surface_points,
+)
+from scatteringnet.metrics import occupancy_metrics  # noqa: E402
+from scatteringnet.normalize import apply_normalization, compute_center_scale  # noqa: E402
+from scatteringnet.occupancy_encoder import CHECKPOINT_KIND as ENCODER_KIND  # noqa: E402
+from scatteringnet.occupancy_encoder import envelope_dim_from_ckpt  # noqa: E402
+from scatteringnet.occupancy_encoder import envelope_seed_from_ckpt  # noqa: E402
+
+from scatteringnet.viewer.mesh_access import resolve_viewer_mesh  # noqa: E402
+from scatteringnet.viewer.model_access import match_checkpoint_part, resolve_viewer_checkpoint  # noqa: E402
+from scatteringnet.viewer.obj_fill import triangles_from_obj_text  # noqa: E402
+
+MAX_POINTS = 2_000_000
+
+# One occupancy head in this process. Same checkpoint + device → skip torch.load.
+_CACHE_LOCK = threading.Lock()
+_MODEL_CACHE: tuple[tuple[str, int, str], Any, dict[str, Any]] | None = None
+
+
+def clear_model_cache() -> None:
+    """Drop the cached head (tests / swapped GPU)."""
+    global _MODEL_CACHE
+    with _CACHE_LOCK:
+        _MODEL_CACHE = None
+
+
+def _model_cache_key(ckpt_path: Path, device: Any) -> tuple[str, int, str]:
+    stat = ckpt_path.stat()
+    return (str(ckpt_path.resolve()), int(stat.st_mtime_ns), str(device))
+
+
+def load_cached_occupancy(
+    run_id: str,
+    models_root: Path,
+    device: Any,
+) -> tuple[Any, dict[str, Any], Path, bool]:
+    """
+    Load ``best.pt`` once per (path, mtime, device).
+
+    Returns ``(model, ckpt, path, cache_hit)``. Switching run_id replaces
+    the slot so GPU RAM does not keep every inspect checkpoint.
+    """
+    import torch
+
+    ckpt_path = resolve_viewer_checkpoint(run_id, models_root)
+    key = _model_cache_key(ckpt_path, device)
+    global _MODEL_CACHE
+    with _CACHE_LOCK:
+        slot = _MODEL_CACHE
+        if slot is not None and slot[0] == key:
+            return slot[1], slot[2], ckpt_path, True
+    ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+    model = load_occupancy_model(ckpt, device)
+    with _CACHE_LOCK:
+        _MODEL_CACHE = (key, model, ckpt)
+    return model, ckpt, ckpt_path, False
+
+
+def _sync_if_cuda(device) -> None:
+    """Wait for GPU work so lap times are not just the CPU launch."""
+    import torch
+
+    dev = device if hasattr(device, "type") else torch.device(str(device))
+    if str(dev.type) == "cuda":
+        torch.cuda.synchronize()
+
+
+def _round_s(t0: float) -> float:
+    return round(time.perf_counter() - t0, 3)
+
+
+def pred_from_probs(probs: np.ndarray, threshold: float = 0.5) -> np.ndarray:
+    """Hard inside labels: 1 iff sigmoid probability is at least ``threshold``."""
+    t = float(threshold)
+    if not np.isfinite(t):
+        t = 0.5
+    t = min(1.0, max(0.0, t))
+    return (np.asarray(probs, dtype=np.float32).reshape(-1) >= t).astype(np.uint8)
+
+
+def _sigmoid_probs_and_pred(logits: Any) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Float32 sigmoid of a 1-D logit tensor, plus a 0.5-cut pred for tests/compat.
+
+    The inspect page re-cuts from ``prob_b64``; occupancy train metrics stay at 0.5.
+    """
+    import torch
+
+    probs = (
+        torch.sigmoid(logits.reshape(-1))
+        .detach()
+        .cpu()
+        .numpy()
+        .astype(np.float32, copy=False)
+    )
+    return probs, pred_from_probs(probs, 0.5)
+
+
+def aabb_for_viewer(
+    ckpt: dict[str, Any],
+    *,
+    npz_name: str,
+    mesh_path: str,
+    points: np.ndarray,
+    data_dir: Path | None,
+    vertices: np.ndarray | None = None,
+    uploaded_obj: bool = False,
+) -> tuple[np.ndarray, float, str]:
+    """
+    Checkpoint AABB when this catalog NPZ/mesh was trained; else mesh vertices.
+
+    Uploaded OBJ Fill (Job B) always uses this mesh's vertices. Catalog
+    ``parts`` matched by filename would apply another cube's box.
+    """
+    if not uploaded_obj:
+        part = match_checkpoint_part(ckpt, npz_name, mesh_path)
+        if part is not None:
+            center = np.asarray(part["center"], dtype=np.float32).reshape(3)
+            scale = float(part["scale"])
+            return center, scale, "checkpoint"
+    if vertices is not None and int(np.asarray(vertices).shape[0]) > 0:
+        center, scale = compute_center_scale(np.asarray(vertices, dtype=np.float32))
+        return center, scale, "mesh"
+    if mesh_path and data_dir is not None:
+        try:
+            resolved = resolve_viewer_mesh(mesh_path, data_dir)
+            vertices, _faces = load_obj_triangles(resolved)
+            center, scale = compute_center_scale(vertices)
+            return center, scale, "mesh"
+        except (PermissionError, FileNotFoundError, ValueError):
+            pass
+    center, scale = compute_center_scale(points)
+    return center, scale, "points"
+
+
+def _ckpt_shape_encoder(ckpt: dict[str, Any]) -> str:
+    """
+    Encoder stored on ``best.pt``, not live YAML.
+
+    Missing ``shape_encoder`` on an occupancy-encoder checkpoint is the
+    original envelope head.
+    """
+    raw = str(ckpt.get("shape_encoder") or "").strip().lower()
+    if raw in ("surface", "none"):
+        return raw
+    if raw == "mesh":
+        raise ValueError(
+            "face-token occupancy checkpoints (shape_encoder='mesh') "
+            "are no longer supported"
+        )
+    kind = str(ckpt.get("kind") or "")
+    if kind == ENCODER_KIND:
+        return "surface"
+    return "none"
+
+
+def _runtime_cfg(cfg: OccupancyConfig | None):
+    """Use the caller cfg (tests) or load repo YAML for device / batch / seed."""
+    if cfg is not None:
+        return cfg
+    from scatteringnet.config import load_config
+
+    return load_config()
+
+
+def _forward_logits(model, cfg, xyz, geom, shape_id):
+    """Batched occupancy logits. ``geom`` is envelope ``(1, N, 3)`` or ``None``."""
+    import torch
+
+    n = int(xyz.shape[0])
+    logits_rows: list[Any] = []
+    with torch.no_grad():
+        for start in range(0, n, int(cfg.batch_size)):
+            sl = slice(start, start + int(cfg.batch_size))
+            batch_xyz = xyz[sl].to(cfg.device)
+            if geom is None:
+                logits_rows.append(model(batch_xyz).cpu())
+            else:
+                b = int(batch_xyz.shape[0])
+                geom_b = geom.expand(b, -1, -1).to(cfg.device)
+                sid = shape_id.reshape(()).expand(b).to(cfg.device)
+                logits_rows.append(model(batch_xyz, geom_b, sid).cpu())
+    return torch.cat(logits_rows, dim=0)
+
+
+def _geom_from_mesh(ckpt, cfg, vertices, faces, center, scale, cache_key: str):
+    """
+    Build the envelope this checkpoint was trained with.
+
+    ``surface`` → ``(1, n_surface, C)`` envelope (C from checkpoint).
+    ``none`` → no geometry (xyz-only MLP).
+    Count comes from the checkpoint. Sampling is always area-weighted
+    (old ``envelope_mix`` on ``best.pt`` is ignored).
+    """
+    import torch
+
+    enc = _ckpt_shape_encoder(ckpt)
+    seed = envelope_seed_from_ckpt(ckpt)
+    if enc == "surface":
+        n_surface = (
+            int(ckpt["n_surface"]) if ckpt.get("n_surface") is not None else 1024
+        )
+        world = sample_surface_points(
+            vertices,
+            faces,
+            n_surface,
+            seed=seed,
+            cache_key=cache_key,
+        )
+        env = apply_envelope_aabb(world, center, scale)
+        env = project_envelope_dim(env, envelope_dim_from_ckpt(ckpt))
+        geom = torch.from_numpy(env).unsqueeze(0)
+        shape_id = torch.zeros(1, dtype=torch.long)
+        return geom, shape_id
+    return None, None
+
+
+def decode_points_b64(text: str) -> np.ndarray:
+    """Little-endian float32 XYZ from standard base64."""
+    raw = base64.b64decode(text)
+    pts = np.frombuffer(raw, dtype=np.float32)
+    if pts.size % 3 != 0:
+        raise ValueError("points buffer length is not a multiple of 3")
+    return np.ascontiguousarray(pts.reshape(-1, 3))
+
+
+def decode_labels_b64(text: str, n: int) -> np.ndarray:
+    """uint8 {0,1} labels, length ``n``."""
+    raw = base64.b64decode(text)
+    labels = np.frombuffer(raw, dtype=np.uint8)
+    if int(labels.shape[0]) != int(n):
+        raise ValueError(
+            f"labels length {labels.shape[0]} does not match points {n}"
+        )
+    return np.ascontiguousarray(labels)
+
+
+def infer_uploaded_npz(
+    *,
+    run_id: str,
+    models_root: Path,
+    data_dir: Path | None,
+    npz_name: str,
+    mesh_path: str,
+    points: np.ndarray,
+    labels: np.ndarray,
+    cfg: OccupancyConfig | None = None,
+) -> dict[str, Any]:
+    """
+    Classify ``points`` with ``best.pt``. Returns pred bytes (base64) and scores.
+
+    Envelope rebuild follows ``ckpt['shape_encoder']``.
+    """
+    import torch
+
+    n = int(points.shape[0])
+    if n < 1:
+        raise ValueError("no query points")
+    if n > MAX_POINTS:
+        raise ValueError(f"too many points ({n}; max {MAX_POINTS})")
+    if points.ndim != 2 or points.shape[1] != 3:
+        raise ValueError(f"points must be (N, 3), got {tuple(points.shape)}")
+    if int(labels.shape[0]) != n:
+        raise ValueError("labels length does not match points")
+
+    t_all = time.perf_counter()
+    t0 = time.perf_counter()
+    cfg = _runtime_cfg(cfg)
+    model, ckpt, ckpt_path, cache_hit = load_cached_occupancy(
+        run_id, models_root, cfg.device
+    )
+    _sync_if_cuda(cfg.device)
+    load_s = _round_s(t0)
+    center, scale, aabb_src = aabb_for_viewer(
+        ckpt,
+        npz_name=npz_name,
+        mesh_path=mesh_path,
+        points=points,
+        data_dir=data_dir,
+    )
+    enc = _ckpt_shape_encoder(ckpt)
+    geom = None
+    shape_id = None
+    parse_s = 0.0
+    envelope_s = 0.0
+    if enc in ("surface", "mesh"):
+        if not mesh_path:
+            raise ValueError("this checkpoint needs a mesh_path for the geometry encoder")
+        if data_dir is None:
+            raise ValueError("helper has no data_dir; cannot load the OBJ for the encoder")
+        t0 = time.perf_counter()
+        mesh_file = resolve_viewer_mesh(mesh_path, data_dir)
+        vertices, faces = load_obj_triangles(mesh_file)
+        parse_s = _round_s(t0)
+        t0 = time.perf_counter()
+        geom, shape_id = _geom_from_mesh(
+            ckpt, cfg, vertices, faces, center, scale, str(mesh_file.resolve())
+        )
+        envelope_s = _round_s(t0)
+        if geom is None:
+            raise ValueError(f"checkpoint shape_encoder={enc!r} built no geometry tokens")
+
+    t0 = time.perf_counter()
+    xyz = torch.from_numpy(apply_normalization(points, center, scale))
+    y = torch.from_numpy(labels.astype(np.float32)).unsqueeze(1)
+    logits = _forward_logits(model, cfg, xyz, geom, shape_id)
+    _sync_if_cuda(cfg.device)
+    forward_s = _round_s(t0)
+    scores = occupancy_metrics(logits, y)
+    probs, pred = _sigmoid_probs_and_pred(logits)
+    timings = {
+        "parse_obj": parse_s,
+        "load_model": load_s,
+        "envelope": envelope_s,
+        "forward": forward_s,
+        "server_total": _round_s(t_all),
+        "load_cached": cache_hit,
+        "device": str(cfg.device),
+    }
+    print(
+        "viewer infer-npz timings (s) n=%s parse=%.3f load=%.3f envelope=%.3f "
+        "forward=%.3f total=%.3f cached=%s device=%s"
+        % (
+            n,
+            parse_s,
+            load_s,
+            envelope_s,
+            forward_s,
+            timings["server_total"],
+            cache_hit,
+            cfg.device,
+        ),
+        flush=True,
+    )
+    gt = labels > 0
+    pred_bool = pred > 0
+    n_fn = int(np.count_nonzero(gt & ~pred_bool))
+    n_fp = int(np.count_nonzero(~gt & pred_bool))
+    return {
+        "pred_b64": base64.b64encode(np.ascontiguousarray(pred)).decode("ascii"),
+        "prob_b64": base64.b64encode(np.ascontiguousarray(probs)).decode("ascii"),
+        "n": n,
+        "accuracy": float(scores.accuracy),
+        "inside_iou": float(scores.inside_iou),
+        "inside_f1": float(scores.inside_f1),
+        "kind": str(ckpt.get("kind") or ""),
+        "shape_encoder": enc,
+        "aabb": aabb_src,
+        "n_error": n_fn + n_fp,
+        "n_fn": n_fn,
+        "n_fp": n_fp,
+        "run_id": Path(ckpt_path).parent.name,
+        "timings": timings,
+    }
+
+
+def infer_uploaded_obj(
+    *,
+    run_id: str,
+    models_root: Path,
+    data_dir: Path | None,
+    obj_name: str,
+    obj_text: str,
+    points: np.ndarray,
+    cfg: OccupancyConfig | None = None,
+) -> dict[str, Any]:
+    """
+    Classify fill-lattice XYZ with ``best.pt``.
+
+    Envelope tokens are built from the uploaded OBJ when the
+    checkpoint is ``surface``. No file labels (Job B): metrics are omitted.
+    """
+    import torch
+
+    n = int(points.shape[0])
+    if n < 1:
+        raise ValueError("no query points; Fill points first")
+    if n > MAX_POINTS:
+        raise ValueError(f"too many points ({n}; max {MAX_POINTS})")
+    if points.ndim != 2 or points.shape[1] != 3:
+        raise ValueError(f"points must be (N, 3), got {tuple(points.shape)}")
+
+    t_all = time.perf_counter()
+    t0 = time.perf_counter()
+    vertices, faces = triangles_from_obj_text(obj_text)
+    parse_s = _round_s(t0)
+    t0 = time.perf_counter()
+    cfg = _runtime_cfg(cfg)
+    model, ckpt, ckpt_path, cache_hit = load_cached_occupancy(
+        run_id, models_root, cfg.device
+    )
+    _sync_if_cuda(cfg.device)
+    load_s = _round_s(t0)
+    center, scale, aabb_src = aabb_for_viewer(
+        ckpt,
+        npz_name="",
+        mesh_path=str(obj_name or ""),
+        points=points,
+        data_dir=data_dir,
+        vertices=vertices,
+        uploaded_obj=True,
+    )
+    enc = _ckpt_shape_encoder(ckpt)
+    t0 = time.perf_counter()
+    geom, shape_id = _geom_from_mesh(
+        ckpt, cfg, vertices, faces, center, scale, "upload:" + str(obj_name or "obj")
+    )
+    envelope_s = _round_s(t0)
+    if enc in ("surface", "mesh") and geom is None:
+        raise ValueError(f"checkpoint shape_encoder={enc!r} built no geometry tokens")
+    t0 = time.perf_counter()
+    xyz = torch.from_numpy(apply_normalization(points, center, scale))
+    logits = _forward_logits(model, cfg, xyz, geom, shape_id)
+    _sync_if_cuda(cfg.device)
+    forward_s = _round_s(t0)
+    probs, pred = _sigmoid_probs_and_pred(logits)
+    n_in = int(np.count_nonzero(pred > 0))
+    timings = {
+        "parse_obj": parse_s,
+        "load_model": load_s,
+        "envelope": envelope_s,
+        "forward": forward_s,
+        "server_total": _round_s(t_all),
+        "load_cached": cache_hit,
+        "device": str(cfg.device),
+    }
+    print(
+        "viewer infer-obj timings (s) n=%s parse=%.3f load=%.3f envelope=%.3f "
+        "forward=%.3f total=%.3f cached=%s device=%s"
+        % (
+            n,
+            parse_s,
+            load_s,
+            envelope_s,
+            forward_s,
+            timings["server_total"],
+            cache_hit,
+            cfg.device,
+        ),
+        flush=True,
+    )
+    return {
+        "pred_b64": base64.b64encode(np.ascontiguousarray(pred)).decode("ascii"),
+        "prob_b64": base64.b64encode(np.ascontiguousarray(probs)).decode("ascii"),
+        "n": n,
+        "n_inside": n_in,
+        "n_outside": n - n_in,
+        "kind": str(ckpt.get("kind") or ""),
+        "shape_encoder": enc,
+        "aabb": aabb_src,
+        "run_id": Path(ckpt_path).parent.name,
+        "timings": timings,
+    }
+
+
+_WARM_OBJ = (
+    "v 0 0 0\nv 1 0 0\nv 0 1 0\nv 0 0 1\n"
+    "f 1 2 3\nf 1 2 4\nf 1 3 4\nf 2 3 4\n"
+)
+
+
+def warmup_viewer_helper(models_root: Path) -> None:
+    """
+    Pay first-click costs before the browser opens: torch, CUDA, trimesh
+    fill, load the INSPECT ``best.pt`` (else newest), tiny envelope + forward.
+    """
+    t0 = time.perf_counter()
+    print("warmup: torch / CUDA…", flush=True)
+    import torch
+
+    from scatteringnet.config import load_config
+    from scatteringnet.viewer.obj_fill import fill_aabb_lattice
+
+    cfg = load_config()
+    print("warmup: occupancy device=" + str(cfg.device), flush=True)
+    if str(cfg.device.type) == "cuda":
+        torch.zeros(1, device=cfg.device)
+        torch.cuda.synchronize()
+        print("warmup: CUDA " + str(cfg.device), flush=True)
+    else:
+        print("warmup: CPU only", flush=True)
+
+    print("warmup: tiny fill…", flush=True)
+    verts, faces = triangles_from_obj_text(_WARM_OBJ)
+    points, _used, _grid = fill_aabb_lattice(verts, 0.40)
+    if int(points.shape[0]) < 1:
+        points = np.array([[0.2, 0.2, 0.2], [0.8, 0.2, 0.2]], dtype=np.float32)
+
+    from scatteringnet.viewer.model_access import inspect_run_id, list_viewer_models
+
+    rows = list_viewer_models(models_root)
+    if not rows:
+        print("warmup: no models/; skip infer", flush=True)
+        print("warmup: done in %.1fs" % (time.perf_counter() - t0), flush=True)
+        return
+    ids = [str(row["id"]) for row in rows]
+    wanted = inspect_run_id()
+    # Warm the inspect alias when that folder exists; otherwise newest.
+    run_id = wanted if wanted in ids else ids[0]
+    print("warmup: infer " + run_id + "…", flush=True)
+    infer_uploaded_obj(
+        run_id=run_id,
+        models_root=models_root,
+        data_dir=None,
+        obj_name="warmup.obj",
+        obj_text=_WARM_OBJ,
+        points=points,
+        cfg=cfg,
+    )
+    print("warmup: done in %.1fs" % (time.perf_counter() - t0), flush=True)

src/viewer/mesh_access.py

@@ -0,0 +1,52 @@
+"""Resolve NPZ ``mesh_path`` for the occupancy viewer helper.
+
+Uses :func:`data_npz.resolve_mesh_path` and then requires the file to sit
+under ``data_dir`` (no arbitrary filesystem reads).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from scatteringnet.data_npz import resolve_mesh_path
+
+
+def resolve_viewer_mesh(stored: str, data_dir: Path | str) -> Path:
+    """
+    Return an existing ``.obj`` under ``data_dir`` for a stored mesh_path.
+
+    Parameters
+    ----------
+    stored:
+        Relative or absolute path from the NPZ ``mesh_path`` array.
+    data_dir:
+        Dataset root (``config.yaml`` ``data_dir``).
+
+    Returns
+    -------
+    Path
+        Resolved OBJ path.
+
+    Raises
+    ------
+    ValueError
+        Empty path or not an OBJ.
+    FileNotFoundError
+        Mesh does not exist (from :func:`resolve_mesh_path`).
+    PermissionError
+        Resolved path is outside ``data_dir``.
+    """
+    text = str(stored).strip()
+    if not text:
+        raise ValueError("mesh_path is empty")
+    root = Path(data_dir).resolve()
+    resolved = resolve_mesh_path(text, root)
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise PermissionError(
+            f"mesh is outside data_dir: {resolved} (stored={text!r})"
+        ) from exc
+    if resolved.suffix.lower() != ".obj":
+        raise ValueError(f"mesh is not an OBJ: {resolved}")
+    return resolved

src/viewer/model_access.py

@@ -0,0 +1,183 @@
+"""List and resolve ``models/<run_id>/best.pt`` for the occupancy viewer.
+
+Read-only: paths must stay under the repo ``models/`` folder.
+Does not import torch.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+# Repo root: this file lives at src/viewer/model_access.py.
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+# Pointers (YAML). Occupancy train / infer math does not read these.
+INSPECT_POINTER = _REPO_ROOT / "docs" / "inspect_checkpoint.yaml"
+HOLDOUT_POINTER = _REPO_ROOT / "docs" / "locked_holdout_objs.yaml"
+# Same id as the committed pointer; used if that file is missing.
+_INSPECT_FALLBACK = "2026-09-14_07-43-34_prim_extruded_nr45_knn24_n2048_n6"
+
+
+def inspect_run_id() -> str:
+    """INSPECT alias: ``run_id`` in ``docs/inspect_checkpoint.yaml``.
+
+    Viewers use this as the default ``models/<id>/best.pt`` when that file
+    exists. Occupancy train / infer math is unchanged.
+    """
+    try:
+        raw = yaml.safe_load(INSPECT_POINTER.read_text(encoding="utf-8"))
+    except OSError:
+        return _INSPECT_FALLBACK
+    if not isinstance(raw, dict):
+        return _INSPECT_FALLBACK
+    token = str(raw.get("run_id") or "").strip()
+    return token[:200] if token else _INSPECT_FALLBACK
+
+
+def locked_holdout_objs() -> list[str]:
+    """OBJ basenames from ``docs/locked_holdout_objs.yaml``.
+
+    Train / catalog construction does not consult this list. It is the
+    locked inspect set for humans and for tests.
+    """
+    try:
+        raw = yaml.safe_load(HOLDOUT_POINTER.read_text(encoding="utf-8"))
+    except OSError:
+        return []
+    if not isinstance(raw, dict):
+        return []
+    objs = raw.get("objs") or []
+    if not isinstance(objs, list):
+        return []
+    names: list[str] = []
+    for item in objs:
+        name = str(item or "").strip()
+        if name:
+            names.append(name)
+    return names
+
+
+def _shape_encoder_from_run(runs_root: Path | None, run_id: str) -> str:
+    """Read ``shape_encoder`` from ``runs/<id>/config.yaml`` (no torch)."""
+    if runs_root is None:
+        return ""
+    path = Path(runs_root) / run_id / "config.yaml"
+    try:
+        if not path.is_file():
+            return ""
+        for line in path.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#") or not stripped.startswith("shape_encoder:"):
+                continue
+            raw = stripped.split(":", 1)[1].split("#", 1)[0].strip().strip("\"'")
+            kind = raw.lower()
+            if kind in ("surface", "mesh", "none"):
+                return kind
+            return ""
+    except OSError:
+        return ""
+    return ""
+
+
+def list_viewer_models(
+    models_root: Path | str,
+    *,
+    runs_root: Path | str | None = None,
+) -> list[dict[str, str | int]]:
+    """
+    Return ``best.pt`` checkpoints one level under ``models_root``.
+
+    Each item: ``id`` (folder name), ``path`` (repo-relative), ``mtime``,
+    and ``shape_encoder`` when ``runs/<id>/config.yaml`` is present.
+    Newest first. Missing folder → empty list.
+    """
+    root = Path(models_root)
+    try:
+        root = root.resolve()
+    except OSError:
+        return []
+    if not root.is_dir():
+        return []
+    runs = Path(runs_root) if runs_root is not None else None
+    items: list[dict[str, str | int]] = []
+    for best in root.glob("*/best.pt"):
+        if not best.is_file():
+            continue
+        run_id = best.parent.name
+        try:
+            mtime = int(best.stat().st_mtime)
+        except OSError:
+            mtime = 0
+        enc = _shape_encoder_from_run(runs, run_id)
+        row: dict[str, str | int] = {
+            "id": run_id,
+            "path": "models/" + run_id + "/best.pt",
+            "mtime": mtime,
+        }
+        if enc:
+            row["shape_encoder"] = enc
+        items.append(row)
+    items.sort(key=lambda row: (-int(row["mtime"]), str(row["id"])))
+    return items
+
+
+def resolve_viewer_checkpoint(run_id: str, models_root: Path | str) -> Path:
+    """
+    Return ``models_root / <run_id> / best.pt``.
+
+    ``run_id`` is a single folder name (no slashes). Also accepts
+    ``models/<run_id>/best.pt`` and strips it down to the folder name.
+
+    Raises
+    ------
+    ValueError
+        Empty or unsafe id.
+    FileNotFoundError
+        ``best.pt`` is missing.
+    PermissionError
+        Resolved path is outside ``models_root``.
+    """
+    raw = str(run_id or "").strip().replace("\\", "/")
+    if raw.endswith("/best.pt"):
+        raw = raw[: -len("/best.pt")]
+    if raw.startswith("models/"):
+        raw = raw[len("models/") :]
+    name = raw.strip("/")
+    if not name or "/" in name or name in (".", "..") or ".." in name:
+        raise ValueError("invalid model id")
+    root = Path(models_root).resolve()
+    best = (root / name / "best.pt").resolve()
+    try:
+        best.relative_to(root)
+    except ValueError as exc:
+        raise PermissionError(
+            f"checkpoint is outside models/: {best} (id={run_id!r})"
+        ) from exc
+    if not best.is_file():
+        raise FileNotFoundError(f"best.pt not found for {name!r}")
+    return best
+
+
+def match_checkpoint_part(ckpt: dict, npz_name: str, mesh_path: str) -> dict | None:
+    """
+    Catalog AABB from ``ckpt['parts']``.
+
+    NPZ: full stored path or the occupancy filename (those stems are unique).
+    Mesh: exact stored path only. Basename matches (``cube.obj``) steal a
+    catalog box for an OOD upload of the same name — Job B must not do that.
+    """
+    parts = ckpt.get("parts") or []
+    name = Path(str(npz_name or "")).name
+    mesh = str(mesh_path or "").replace("\\", "/").strip()
+    if name:
+        for part in parts:
+            stored = str(part.get("npz") or "").replace("\\", "/")
+            if stored == name or Path(stored).name == name:
+                return part
+    if mesh:
+        for part in parts:
+            stored_m = str(part.get("mesh") or "").replace("\\", "/").strip()
+            if stored_m and stored_m == mesh:
+                return part
+    return None