reverse3d 0.4.0__py3-none-any.whl

reverse3d/mesh_io.py

@@ -0,0 +1,152 @@
+"""Safe mesh / point-cloud I/O on top of trimesh.
+
+Security notes:
+
+* Only allowlisted formats are parsed (no pickle-based or executable formats).
+* ``.gltf`` and ``.obj`` may reference sibling files (buffers, textures, .mtl).
+  :class:`SandboxedResolver` only serves files located inside the model's own
+  directory, so a crafted model cannot read ``../../secrets`` (CWE-22).
+* Face counts are bounded by ``Settings.max_mesh_faces`` after loading.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+
+import numpy as np
+import trimesh
+from trimesh.resolvers import FilePathResolver
+
+from reverse3d.config import Settings
+from reverse3d.errors import InputValidationError, SecurityViolationError
+from reverse3d.security import (
+    MESH_EXTENSIONS,
+    POINT_CLOUD_EXTENSIONS,
+    prepare_output_file,
+    validate_input_file,
+)
+
+logger = logging.getLogger(__name__)
+
+Geometry = trimesh.Trimesh | trimesh.PointCloud
+
+
+class SandboxedResolver(FilePathResolver):
+    """A trimesh resolver that refuses to read or write outside its directory."""
+
+    def __init__(self, source: str | Path) -> None:
+        super().__init__(str(source))
+        self._root = Path(self.parent).resolve()
+
+    def _check(self, name: str) -> None:
+        for variant in {name, unquote(name)}:
+            target = (self._root / variant.strip()).resolve()
+            if target != self._root and not target.is_relative_to(self._root):
+                raise SecurityViolationError("Model references a file outside its own directory.")
+
+    def get(self, name: str) -> bytes:
+        self._check(name)
+        return super().get(name)
+
+    def write(self, name: str, data: bytes | str) -> None:
+        self._check(name)
+        super().write(name, data)
+
+
+def _check_faces(mesh: trimesh.Trimesh, settings: Settings) -> None:
+    if len(mesh.faces) > settings.max_mesh_faces:
+        raise InputValidationError(
+            f"Mesh has too many faces ({len(mesh.faces):,} > {settings.max_mesh_faces:,}).",
+            hint="Decimate it first or raise REVERSE3D_MAX_MESH_FACES.",
+        )
+
+
+def load_geometry(path: str | Path, settings: Settings) -> Geometry:
+    """Load a mesh or point cloud from an allowlisted format.
+
+    Scenes (glTF/GLB with many nodes) are flattened into a single mesh with
+    node transforms applied.
+
+    Raises:
+        InputValidationError: unsupported, unreadable, empty or oversize input.
+    """
+    allowed = MESH_EXTENSIONS | POINT_CLOUD_EXTENSIONS
+    resolved = validate_input_file(
+        path, allowed_extensions=allowed, max_bytes=settings.max_input_bytes
+    )
+    loaded: Any
+    try:
+        loaded = trimesh.load(
+            str(resolved),
+            file_type=resolved.suffix.lower().lstrip("."),
+            resolver=SandboxedResolver(resolved),
+            # Merge duplicated vertices: STL stores unshared triangle soups and
+            # topology metrics (watertight, volume, holes) would be meaningless.
+            process=True,
+        )
+    except SecurityViolationError:
+        raise
+    except Exception as exc:  # trimesh raises many exception types for bad files
+        raise InputValidationError(f"Could not parse geometry file: {resolved.name}") from exc
+
+    if isinstance(loaded, trimesh.Scene):
+        if not loaded.geometry:
+            raise InputValidationError(f"Scene contains no geometry: {resolved.name}")
+        loaded = loaded.to_mesh() if hasattr(loaded, "to_mesh") else loaded.dump(concatenate=True)
+
+    if isinstance(loaded, trimesh.Trimesh):
+        if len(loaded.faces) == 0:
+            # A PLY with vertices only is a point cloud.
+            if len(loaded.vertices) == 0:
+                raise InputValidationError(f"Empty geometry: {resolved.name}")
+            return trimesh.PointCloud(loaded.vertices)
+        _check_faces(loaded, settings)
+        return loaded
+    if isinstance(loaded, trimesh.PointCloud):
+        if len(loaded.vertices) == 0:
+            raise InputValidationError(f"Empty point cloud: {resolved.name}")
+        return loaded
+    raise InputValidationError(f"Unsupported geometry type in {resolved.name}")
+
+
+def load_mesh(path: str | Path, settings: Settings) -> trimesh.Trimesh:
+    """Like :func:`load_geometry` but requires a triangle mesh."""
+    geometry = load_geometry(path, settings)
+    if not isinstance(geometry, trimesh.Trimesh):
+        raise InputValidationError(
+            "File contains a point cloud, not a mesh.",
+            hint="Use the photogrammetry/meshing tools to build a surface first.",
+        )
+    return geometry
+
+
+def save_mesh(mesh: trimesh.Trimesh, path: str | Path, *, overwrite: bool = False) -> Path:
+    """Export ``mesh`` to an allowlisted format inferred from the extension."""
+    out = prepare_output_file(path, allowed_extensions=MESH_EXTENSIONS, overwrite=overwrite)
+    file_type = out.suffix.lower().lstrip(".")
+    if file_type == "gltf":
+        # Embed buffers so the export is a single self-contained file.
+        data = trimesh.exchange.gltf.export_gltf(mesh.scene(), embed_buffers=True)
+        out.write_bytes(data["model.gltf"])
+    else:
+        mesh.export(str(out), file_type=file_type)
+    logger.info("Saved mesh %s (%d faces)", out.name, len(mesh.faces))
+    return out
+
+
+def sample_points(
+    geometry: Geometry, count: int, *, seed: int = 0
+) -> tuple[np.ndarray, np.ndarray | None]:
+    """Sample up to ``count`` points (and normals for meshes) from ``geometry``."""
+    if isinstance(geometry, trimesh.Trimesh):
+        points, face_idx = trimesh.sample.sample_surface(geometry, count, seed=seed)
+        normals = geometry.face_normals[face_idx]
+        return np.asarray(points, dtype=np.float64), np.asarray(normals, dtype=np.float64)
+    vertices = np.asarray(geometry.vertices, dtype=np.float64)
+    if len(vertices) > count:
+        rng = np.random.default_rng(seed)
+        vertices = vertices[rng.choice(len(vertices), count, replace=False)]
+    return vertices, None

reverse3d/offline.py

@@ -0,0 +1,313 @@
+"""Offline mode: keep working without internet and switch to it automatically.
+
+Everything reverse3d computes runs locally (OpenCV, COLMAP, Open3D, trimesh,
+Blender). The only part that ever needs the network is the AI depth model,
+downloaded from Hugging Face the first time it is used. This module removes
+that dependency:
+
+* :func:`has_internet` is a cheap, cached TCP probe (no HTTP, no data sent).
+* Models live in ``~/.reverse3d/models``. :func:`prepare` downloads the
+  allowlisted ones in advance (``reverse3d offline prepare``; the installer runs
+  it too), fetching only ``*.safetensors`` weights and small config files.
+* :func:`resolve_model` always prefers the local copy, so a prepared machine
+  never touches the network, and fails with a clear hint when a model is
+  missing and there is no connection.
+* :func:`offline_status` tells the user, in one call, what works offline.
+
+``Settings.offline`` (``REVERSE3D_OFFLINE`` / ``reverse3d config set offline``):
+``auto`` (default) detects the connection, ``on`` never uses the network,
+``off`` skips the probe and assumes the network is available.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import os
+import socket
+import time
+from pathlib import Path
+from typing import Any
+
+from reverse3d.config import Settings
+from reverse3d.errors import DependencyMissingError, InputValidationError, Reverse3DError
+from reverse3d.userconfig import home_dir
+
+logger = logging.getLogger(__name__)
+
+#: Hosts probed to decide whether the machine is online. Hugging Face is the
+#: only service reverse3d downloads from at run time; 1.1.1.1 covers networks
+#: where it is blocked but the internet works.
+_PROBE_HOSTS: tuple[tuple[str, int], ...] = (("huggingface.co", 443), ("1.1.1.1", 443))
+_PROBE_TIMEOUT_S = 1.5
+_CACHE_TTL_S = 60.0
+_cache: tuple[float, bool] | None = None
+
+#: Only these files are downloaded: safetensors weights and small configs.
+#: Pickled ``*.bin`` checkpoints (code execution on load) are never fetched.
+MODEL_FILE_PATTERNS = ["*.json", "*.safetensors", "*.txt"]
+
+#: Pinned Hugging Face commit of every allowlisted model: only this exact
+#: revision is downloaded or accepted from disk, so a changed upstream
+#: repository cannot alter what runs (bump together with a review).
+MODEL_REVISIONS: dict[str, str] = {
+    "depth-anything/Depth-Anything-V2-Small-hf": "5426e4f0f36572d16453bbda7a8389317b1bef99",
+    "depth-anything/Depth-Anything-V2-Base-hf": "b1958afc87fb45a9e3746cb387596094de553ed8",
+    "depth-anything/Depth-Anything-V2-Large-hf": "7581137eff8d4e94f6e796d3baea0e9fa79b22d2",
+}
+
+
+def models_dir() -> Path:
+    """Folder that holds the downloaded AI models (``~/.reverse3d/models``)."""
+    return home_dir() / "models"
+
+
+def _reachable(hosts: tuple[tuple[str, int], ...]) -> bool:
+    for host, port in hosts:
+        try:
+            with socket.create_connection((host, port), timeout=_PROBE_TIMEOUT_S):
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def _probe() -> bool:
+    return _reachable(_PROBE_HOSTS)
+
+
+def has_internet(*, refresh: bool = False) -> bool:
+    """Return True if the internet is reachable. The answer is cached for a minute."""
+    global _cache
+    now = time.monotonic()
+    if not refresh and _cache is not None and now - _cache[0] < _CACHE_TTL_S:
+        return _cache[1]
+    online = _probe()
+    _cache = (now, online)
+    if not online:
+        logger.info("No internet connection detected: working offline.")
+    return online
+
+
+def is_offline(settings: Settings) -> bool:
+    """Whether reverse3d must avoid the network right now."""
+    if settings.offline == "on":
+        return True
+    if settings.offline == "off":
+        return False
+    return not has_internet()
+
+
+def _allowed_models() -> dict[str, tuple[str, str]]:
+    from reverse3d.reconstruction.depth_estimation import ALLOWED_MODELS
+
+    return dict(ALLOWED_MODELS)
+
+
+def _default_model() -> str:
+    from reverse3d.reconstruction.depth_estimation import DEFAULT_MODEL
+
+    return DEFAULT_MODEL
+
+
+def _cache_folder(model_id: str) -> Path:
+    return models_dir() / ("models--" + model_id.replace("/", "--"))
+
+
+def local_model_path(model_id: str) -> Path | None:
+    """Return the local snapshot folder of ``model_id`` if its weights are on disk.
+
+    Pure filesystem check: it never imports Hugging Face nor touches the network.
+    """
+    revision = MODEL_REVISIONS.get(model_id)
+    if revision is None:
+        return None
+    snapshot = _cache_folder(model_id) / "snapshots" / revision
+    return snapshot if snapshot.is_dir() and any(snapshot.glob("*.safetensors")) else None
+
+
+def _folder_mb(path: Path) -> float:
+    total = 0
+    for file in path.rglob("*"):
+        try:
+            if file.is_file():
+                total += file.stat().st_size  # resolves the symlinked blobs
+        except OSError:
+            continue
+    return round(total / (1024 * 1024), 1)
+
+
+def _depth_stack_installed() -> bool:
+    return all(
+        importlib.util.find_spec(m) is not None
+        for m in ("torch", "transformers", "huggingface_hub")
+    )
+
+
+def _download(model_id: str) -> Path:
+    from huggingface_hub import snapshot_download
+
+    path = snapshot_download(
+        model_id,
+        revision=MODEL_REVISIONS[model_id],
+        cache_dir=str(models_dir()),
+        allow_patterns=MODEL_FILE_PATTERNS,
+    )
+    return Path(path)
+
+
+def resolve_model(model_id: str, settings: Settings) -> Path:
+    """Return a local folder with the files of an allowlisted model.
+
+    Uses the local copy when there is one (no network at all). Otherwise it
+    downloads the model if the machine is online.
+
+    Raises:
+        InputValidationError: the model is not in the allowlist.
+        DependencyMissingError: the model is not on disk and cannot be downloaded
+            (offline, or the download failed).
+    """
+    if model_id not in _allowed_models() or model_id not in MODEL_REVISIONS:
+        raise InputValidationError(
+            f"Model '{model_id}' is not in the allowlist.",
+            hint=f"Allowed: {', '.join(_allowed_models())}",
+        )
+    local = local_model_path(model_id)
+    if local is not None:
+        return local
+    if is_offline(settings):
+        raise DependencyMissingError(
+            "The AI depth model is not on this computer and there is no internet connection.",
+            hint="Connect to the internet once and run: reverse3d offline prepare",
+        )
+    try:
+        return _download(model_id)
+    except ImportError as exc:
+        raise DependencyMissingError(
+            "huggingface_hub is required to download AI models.",
+            hint='pip install "reverse3d[depth]"',
+        ) from exc
+    except Exception as exc:  # network errors come in many shapes; report them plainly
+        has_internet(refresh=True)
+        raise DependencyMissingError(
+            f"Could not download the AI depth model ({exc.__class__.__name__}).",
+            hint="Check your connection and run: reverse3d offline prepare",
+        ) from exc
+
+
+def prepare(settings: Settings, *, include_non_commercial: bool = False) -> dict[str, Any]:
+    """Download the allowlisted AI models so reverse3d works without internet.
+
+    Safe to run any time: models already on disk are skipped. It never raises
+    for a missing optional stack; that is reported in the result instead.
+    """
+    models = [_default_model()]
+    if include_non_commercial:
+        models += [m for m in _allowed_models() if m not in models]
+
+    if not _depth_stack_installed():
+        return {
+            "ready": True,
+            "models_dir": str(models_dir()),
+            "models": [
+                {"model": m, "status": "skipped", "detail": "AI depth extra not installed"}
+                for m in models
+            ],
+            "message": "Nothing to download: AI depth is not installed and everything else "
+            "already works offline.",
+        }
+
+    results: list[dict[str, Any]] = []
+    online = not is_offline(settings)
+    for model_id in models:
+        local = local_model_path(model_id)
+        if local is not None:
+            results.append(
+                {
+                    "model": model_id,
+                    "status": "ready",
+                    "path": str(local),
+                    "size_mb": _folder_mb(local),
+                }
+            )
+            continue
+        if not online:
+            results.append(
+                {
+                    "model": model_id,
+                    "status": "missing",
+                    "detail": "No internet connection: connect and run this again.",
+                }
+            )
+            continue
+        try:
+            path = resolve_model(model_id, settings)
+        except Reverse3DError as exc:
+            results.append({"model": model_id, "status": "failed", "detail": exc.message})
+            continue
+        results.append(
+            {
+                "model": model_id,
+                "status": "downloaded",
+                "path": str(path),
+                "size_mb": _folder_mb(path),
+            }
+        )
+
+    ready = all(r["status"] in ("ready", "downloaded") for r in results)
+    return {
+        "ready": ready,
+        "models_dir": str(models_dir()),
+        "models": results,
+        "message": (
+            "Ready: reverse3d now works without internet."
+            if ready
+            else "Some models are missing: connect to the internet and run "
+            "`reverse3d offline prepare`."
+        ),
+    }
+
+
+def offline_status(settings: Settings) -> dict[str, Any]:
+    """Report what works right now and what would work without internet."""
+    from reverse3d.doctor import environment_report
+
+    env = environment_report(settings, include_offline=False)
+    caps: dict[str, bool] = env["capabilities"]  # type: ignore[assignment]
+    depth_installed = bool(caps.get("depth_estimation"))
+    model_on_disk = local_model_path(_default_model()) is not None
+    internet = None if settings.offline != "auto" else has_internet()
+
+    components = {
+        "measure_repair_cad": {"available": True, "offline": True},
+        "plan_to_part": {"available": True, "offline": True},
+        "photogrammetry": {"available": caps.get("photogrammetry", False), "offline": True},
+        "dense_meshing": {"available": caps.get("dense_meshing", False), "offline": True},
+        "render": {
+            "available": caps.get("render_blender", False) or caps.get("render_pyvista", False),
+            "offline": True,
+        },
+        "ai_depth": {"available": depth_installed, "offline": depth_installed and model_on_disk},
+    }
+    missing = []
+    if depth_installed and not model_on_disk:
+        missing.append(
+            "AI depth model not downloaded yet: run `reverse3d offline prepare` while online."
+        )
+    working_offline = is_offline(settings)
+    return {
+        "mode": settings.offline,
+        "internet": internet,
+        "working_offline": working_offline,
+        "ready_for_offline": not missing,
+        "models_dir": str(models_dir()),
+        "components": components,
+        "missing": missing,
+        "message": ("Everything installed works without internet." if not missing else missing[0]),
+    }
+
+
+def force_offline_env() -> None:
+    """Tell Hugging Face libraries not to reach the network in this process."""
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"

reverse3d/profiles.py

@@ -0,0 +1,33 @@
+"""Performance profiles: one knob that trades speed for quality everywhere.
+
+``fast`` is for previews and weak machines, ``balanced`` is the default and
+``quality`` is for final deliverables. Explicit tool arguments always win over
+the profile.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from reverse3d.config import Settings
+
+
+@dataclass(frozen=True)
+class ProfileValues:
+    photo_quality: str
+    render_samples: int
+    render_width: int
+    render_height: int
+    depth_stride: int
+    fit_samples: int
+
+
+PROFILES: dict[str, ProfileValues] = {
+    "fast": ProfileValues("low", 16, 960, 720, 4, 8_000),
+    "balanced": ProfileValues("medium", 64, 1600, 1200, 2, 20_000),
+    "quality": ProfileValues("high", 256, 2400, 1800, 1, 50_000),
+}
+
+
+def profile_values(settings: Settings) -> ProfileValues:
+    return PROFILES[settings.profile]