reverse3d 0.4.0__py3-none-any.whl

reverse3d/config.py

@@ -0,0 +1,167 @@
+"""Runtime settings.
+
+Precedence (lowest → highest): built-in defaults → user config file
+(``~/.reverse3d/config.json``, managed with ``reverse3d config``) → environment
+variables. :meth:`Settings.load` applies all three; :meth:`Settings.from_env`
+reads only the given mapping (useful in tests).
+
+All resource limits exist to bound the work an AI agent (or a malicious input
+file) can trigger: OWASP LLM10 "Unbounded Consumption". Every value is parsed
+and range-checked; invalid values fail loudly instead of silently falling back
+to "unlimited".
+
+==============================  =====================================  ============
+Variable                        Meaning                                Default
+==============================  =====================================  ============
+REVERSE3D_WORKSPACE             Sandbox root for the agent tool layer  current dir
+REVERSE3D_DEVICE                auto | cpu | gpu                       auto
+REVERSE3D_PROFILE               fast | balanced | quality              balanced
+REVERSE3D_VERBOSITY             compact | full (agent tool output)     compact
+REVERSE3D_TOOLSET               full | lean (tools exposed to agents)  full
+REVERSE3D_OFFLINE               auto | on | off (internet use)         auto
+REVERSE3D_THREADS               CPU threads, 0 = automatic             0
+REVERSE3D_MAX_INPUT_MB          Max size of any input file             512
+REVERSE3D_MAX_IMAGE_PIXELS      Max pixels per decoded image           100000000
+REVERSE3D_MAX_IMAGES            Max images per photogrammetry job      500
+REVERSE3D_MAX_MESH_FACES        Max faces of a loaded mesh             5000000
+REVERSE3D_TIMEOUT_S             Timeout per external process (s)       3600
+REVERSE3D_BLENDER               Explicit path to the Blender binary    (PATH)
+REVERSE3D_COLMAP                Explicit path to the COLMAP binary     (PATH)
+REVERSE3D_LOG_LEVEL             DEBUG | INFO | WARNING | ERROR         INFO
+REVERSE3D_LOG_JSON              1 to emit JSON log lines on stderr     0
+REVERSE3D_HOME                  Folder of config.json                  ~/.reverse3d
+==============================  =====================================  ============
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Literal
+
+from reverse3d.errors import InputValidationError
+
+_MB = 1024 * 1024
+_LOG_LEVELS = {"DEBUG", "INFO", "WARNING", "ERROR"}
+
+Device = Literal["auto", "cpu", "gpu"]
+Profile = Literal["fast", "balanced", "quality"]
+Verbosity = Literal["compact", "full"]
+Toolset = Literal["full", "lean"]
+OfflineMode = Literal["auto", "on", "off"]
+
+_CHOICES: dict[str, tuple[str, ...]] = {
+    "REVERSE3D_DEVICE": ("auto", "cpu", "gpu"),
+    "REVERSE3D_PROFILE": ("fast", "balanced", "quality"),
+    "REVERSE3D_VERBOSITY": ("compact", "full"),
+    "REVERSE3D_TOOLSET": ("full", "lean"),
+    "REVERSE3D_OFFLINE": ("auto", "on", "off"),
+}
+
+
+def _int_env(env: Mapping[str, str], name: str, default: int, lo: int, hi: int) -> int:
+    raw = env.get(name)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        value = int(str(raw).strip())
+    except ValueError as exc:
+        raise InputValidationError(f"{name} must be an integer, got {raw!r}") from exc
+    if not lo <= value <= hi:
+        raise InputValidationError(f"{name} must be between {lo} and {hi}, got {value}")
+    return value
+
+
+def _choice_env(env: Mapping[str, str], name: str, default: str) -> str:
+    raw = str(env.get(name, "") or "").strip().lower()
+    if not raw:
+        return default
+    if raw not in _CHOICES[name]:
+        raise InputValidationError(f"{name} must be one of {list(_CHOICES[name])}, got {raw!r}")
+    return raw
+
+
+def _optional_path(env: Mapping[str, str], name: str) -> Path | None:
+    raw = env.get(name)
+    return Path(raw).expanduser() if raw and str(raw).strip() else None
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable runtime configuration. Build it with :meth:`load`."""
+
+    workspace: Path = field(default_factory=Path.cwd)
+    device: Device = "auto"
+    profile: Profile = "balanced"
+    verbosity: Verbosity = "compact"
+    toolset: Toolset = "full"
+    offline: OfflineMode = "auto"
+    threads: int = 0
+    max_input_bytes: int = 512 * _MB
+    max_image_pixels: int = 100_000_000
+    max_images: int = 500
+    max_mesh_faces: int = 5_000_000
+    subprocess_timeout_s: int = 3600
+    blender_path: Path | None = None
+    colmap_path: Path | None = None
+    log_level: str = "INFO"
+    log_json: bool = False
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Settings:
+        """Build settings from ``env`` only (defaults to ``os.environ``).
+
+        Raises:
+            InputValidationError: if a variable is malformed or out of range.
+        """
+        env = os.environ if env is None else env
+        workspace_raw = env.get("REVERSE3D_WORKSPACE")
+        workspace = Path(workspace_raw).expanduser() if workspace_raw else Path.cwd()
+
+        log_level = str(env.get("REVERSE3D_LOG_LEVEL", "INFO")).strip().upper()
+        if log_level not in _LOG_LEVELS:
+            raise InputValidationError(f"REVERSE3D_LOG_LEVEL must be one of {sorted(_LOG_LEVELS)}")
+
+        return cls(
+            workspace=workspace.resolve(),
+            device=_choice_env(env, "REVERSE3D_DEVICE", "auto"),  # type: ignore[arg-type]
+            profile=_choice_env(env, "REVERSE3D_PROFILE", "balanced"),  # type: ignore[arg-type]
+            verbosity=_choice_env(env, "REVERSE3D_VERBOSITY", "compact"),  # type: ignore[arg-type]
+            toolset=_choice_env(env, "REVERSE3D_TOOLSET", "full"),  # type: ignore[arg-type]
+            offline=_choice_env(env, "REVERSE3D_OFFLINE", "auto"),  # type: ignore[arg-type]
+            threads=_int_env(env, "REVERSE3D_THREADS", 0, 0, 1024),
+            max_input_bytes=_int_env(env, "REVERSE3D_MAX_INPUT_MB", 512, 1, 16_384) * _MB,
+            max_image_pixels=_int_env(
+                env, "REVERSE3D_MAX_IMAGE_PIXELS", 100_000_000, 1_000, 1_000_000_000
+            ),
+            max_images=_int_env(env, "REVERSE3D_MAX_IMAGES", 500, 1, 10_000),
+            max_mesh_faces=_int_env(env, "REVERSE3D_MAX_MESH_FACES", 5_000_000, 100, 200_000_000),
+            subprocess_timeout_s=_int_env(env, "REVERSE3D_TIMEOUT_S", 3600, 10, 172_800),
+            blender_path=_optional_path(env, "REVERSE3D_BLENDER"),
+            colmap_path=_optional_path(env, "REVERSE3D_COLMAP"),
+            log_level=log_level,
+            log_json=str(env.get("REVERSE3D_LOG_JSON", "0")).strip() in {"1", "true", "yes"},
+        )
+
+    @classmethod
+    def load(
+        cls, env: Mapping[str, str] | None = None, *, config_file: Path | None = None
+    ) -> Settings:
+        """Defaults ← user config file ← environment variables."""
+        from reverse3d.userconfig import config_as_env, read_config
+
+        env = os.environ if env is None else env
+        merged = {**config_as_env(read_config(config_file)), **env}
+        return cls.from_env(merged)
+
+    def with_workspace(self, workspace: Path) -> Settings:
+        """Return a copy with a different (resolved) sandbox root."""
+        return replace(self, workspace=workspace.expanduser().resolve())
+
+    def with_device(self, device: Device) -> Settings:
+        """Return a copy with another compute device preference."""
+        if device not in ("auto", "cpu", "gpu"):
+            raise InputValidationError("device must be auto, cpu or gpu")
+        return replace(self, device=device)

reverse3d/doctor.py

@@ -0,0 +1,113 @@
+"""Environment diagnostics: which optional stacks and external tools are usable."""
+
+from __future__ import annotations
+
+import importlib.util
+import platform
+import sys
+from importlib import metadata
+
+from reverse3d._version import __version__
+from reverse3d.config import Settings
+from reverse3d.errors import Reverse3DError
+from reverse3d.security import resolve_executable
+
+_PACKAGES = {
+    "numpy": "core",
+    "opencv-python-headless": "core",
+    "trimesh": "core",
+    "shapely": "core",
+    "fast-simplification": "core",
+    "open3d": "recon",
+    "torch": "depth",
+    "transformers": "depth",
+    "pyvista": "render",
+    "mcp": "mcp",
+    "anthropic": "agents",
+}
+_MODULES = {
+    "opencv-python-headless": "cv2",
+    "fast-simplification": "fast_simplification",
+}
+
+
+def _package_version(dist: str) -> str | None:
+    module = _MODULES.get(dist, dist.replace("-", "_"))
+    if importlib.util.find_spec(module) is None:
+        return None
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "installed"
+
+
+def environment_report(settings: Settings, *, include_offline: bool = True) -> dict[str, object]:
+    """Return a JSON-serialisable description of the runtime environment.
+
+    Never raises for missing optional components; they are reported as absent.
+    """
+    packages = {
+        name: {"extra": extra, "version": _package_version(name)}
+        for name, extra in _PACKAGES.items()
+    }
+    tools: dict[str, dict[str, object]] = {}
+    for tool, names, override in (
+        ("colmap", ["colmap", "COLMAP", "colmap.exe", "COLMAP.bat"], settings.colmap_path),
+        ("blender", ["blender", "blender.exe"], settings.blender_path),
+    ):
+        try:
+            tools[tool] = {
+                "available": True,
+                "path": str(resolve_executable(names, override, tool=tool)),
+            }
+        except Reverse3DError as exc:
+            tools[tool] = {"available": False, "hint": exc.hint}
+
+    from reverse3d._about import AUTHOR, AUTHOR_URL, OFFICIAL_REPOSITORY
+    from reverse3d.hardware import hardware_report
+
+    report: dict[str, object] = {
+        "reverse3d": __version__,
+        "author": f"{AUTHOR} ({AUTHOR_URL})",
+        "official_source": OFFICIAL_REPOSITORY,
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "workspace": str(settings.workspace),
+        "settings": {
+            "device": settings.device,
+            "profile": settings.profile,
+            "verbosity": settings.verbosity,
+            "toolset": settings.toolset,
+        },
+        "hardware": hardware_report(settings),
+        "limits": {
+            "max_input_mb": settings.max_input_bytes // (1024 * 1024),
+            "max_image_pixels": settings.max_image_pixels,
+            "max_images": settings.max_images,
+            "max_mesh_faces": settings.max_mesh_faces,
+            "timeout_s": settings.subprocess_timeout_s,
+        },
+        "packages": packages,
+        "external_tools": tools,
+        "capabilities": {
+            "vision": True,
+            "mesh_repair": True,
+            "primitive_fitting": True,
+            "photogrammetry": bool(tools["colmap"]["available"]),
+            "dense_meshing": packages["open3d"]["version"] is not None,
+            "depth_estimation": packages["torch"]["version"] is not None
+            and packages["transformers"]["version"] is not None,
+            "render_blender": bool(tools["blender"]["available"]),
+            "render_pyvista": packages["pyvista"]["version"] is not None,
+            "mcp_server": packages["mcp"]["version"] is not None,
+        },
+    }
+    if include_offline:
+        from reverse3d.offline import offline_status
+
+        status = offline_status(settings)
+        report["offline"] = {
+            k: status[k]
+            for k in ("mode", "internet", "working_offline", "ready_for_offline", "missing")
+        }
+    return report

reverse3d/errors.py

@@ -0,0 +1,83 @@
+"""Exception hierarchy.
+
+Every error raised intentionally by reverse3d derives from :class:`Reverse3DError`
+and carries a stable machine-readable ``code`` so that CLI ``--json`` output and
+the agent tool layer can report failures without leaking stack traces.
+"""
+
+from __future__ import annotations
+
+
+class Reverse3DError(Exception):
+    """Base class for all reverse3d errors."""
+
+    code: str = "reverse3d_error"
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+    def to_dict(self) -> dict[str, str]:
+        data = {"code": self.code, "message": self.message}
+        if self.hint:
+            data["hint"] = self.hint
+        return data
+
+
+class InputValidationError(Reverse3DError):
+    """An argument or input file is invalid (missing, wrong type, too large...)."""
+
+    code = "invalid_input"
+
+
+class SecurityViolationError(Reverse3DError):
+    """A request tried to escape the sandbox or violate a security limit."""
+
+    code = "security_violation"
+
+
+class DependencyMissingError(Reverse3DError):
+    """An optional Python extra or an external binary is not available."""
+
+    code = "dependency_missing"
+
+
+class ExternalToolError(Reverse3DError):
+    """An external binary (COLMAP, Blender) failed or timed out."""
+
+    code = "external_tool_failed"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        returncode: int | None = None,
+        stderr_tail: str = "",
+    ) -> None:
+        super().__init__(message, hint=hint)
+        self.returncode = returncode
+        self.stderr_tail = stderr_tail
+
+    def to_dict(self) -> dict[str, str]:
+        data = super().to_dict()
+        if self.returncode is not None:
+            data["returncode"] = str(self.returncode)
+        if self.stderr_tail:
+            data["stderr_tail"] = self.stderr_tail
+        return data
+
+
+class ProcessingError(Reverse3DError):
+    """An algorithm could not produce a valid result for the given data."""
+
+    code = "processing_failed"
+
+
+class CaptureQualityError(ProcessingError):
+    """The input capture (e.g. a photo set) is not good enough to process.
+
+    Retrying with other parameters will not help: the user has to improve the
+    capture. Kept under ``processing_failed`` so existing clients see the same code.
+    """

reverse3d/hardware.py

@@ -0,0 +1,115 @@
+"""Compute-device detection and resolution (CPU / NVIDIA CUDA / Apple MPS).
+
+``Settings.device`` expresses a *preference* (auto | cpu | gpu). These helpers
+turn it into concrete choices per backend, falling back to CPU when the
+requested accelerator is not usable, so a GPU preference never breaks a job.
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+import shutil
+from dataclasses import asdict, dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from reverse3d.config import Settings
+from reverse3d.errors import Reverse3DError
+from reverse3d.security import run_command
+
+logger = logging.getLogger(__name__)
+
+TorchDevice = Literal["cpu", "cuda", "mps"]
+
+
+@dataclass(frozen=True)
+class GpuInfo:
+    """What accelerators this machine exposes."""
+
+    cuda: bool
+    name: str | None
+    vram_mb: int | None
+    driver: str | None
+    mps: bool
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@lru_cache(maxsize=1)
+def detect_gpu() -> GpuInfo:
+    """Detect NVIDIA GPUs (via ``nvidia-smi``) and Apple Silicon (MPS). Cached."""
+    mps = platform.system() == "Darwin" and platform.machine() in {"arm64", "aarch64"}
+    smi = shutil.which("nvidia-smi")
+    if not smi:
+        return GpuInfo(cuda=False, name=None, vram_mb=None, driver=None, mps=mps)
+    try:
+        proc = run_command(
+            Path(smi),
+            ["--query-gpu=name,memory.total,driver_version", "--format=csv,noheader,nounits"],
+            timeout_s=15,
+            tool="nvidia-smi",
+        )
+    except Reverse3DError:
+        return GpuInfo(cuda=False, name=None, vram_mb=None, driver=None, mps=mps)
+    first = (proc.stdout or "").strip().splitlines()[:1]
+    if not first:
+        return GpuInfo(cuda=False, name=None, vram_mb=None, driver=None, mps=mps)
+    parts = [p.strip() for p in first[0].split(",")]
+    vram = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else None
+    return GpuInfo(
+        cuda=True,
+        name=parts[0] or None,
+        vram_mb=vram,
+        driver=parts[2] if len(parts) > 2 else None,
+        mps=mps,
+    )
+
+
+def wants_gpu(settings: Settings) -> bool:
+    """Should GPU-capable external tools (COLMAP, Blender Cycles) use the GPU?"""
+    if settings.device == "cpu":
+        return False
+    if settings.device == "gpu":
+        return True
+    return detect_gpu().cuda
+
+
+def torch_device(settings: Settings) -> TorchDevice:
+    """Best PyTorch device for the preference; CPU if torch/accelerator is missing."""
+    if settings.device == "cpu":
+        return "cpu"
+    try:
+        import torch
+    except ImportError:
+        return "cpu"
+    if torch.cuda.is_available():
+        return "cuda"
+    mps = getattr(torch.backends, "mps", None)
+    if mps is not None and mps.is_available():
+        return "mps"
+    if settings.device == "gpu":
+        logger.warning("GPU requested but PyTorch has no CUDA/MPS support; using CPU")
+    return "cpu"
+
+
+def apply_threads(settings: Settings) -> None:
+    """Apply the CPU thread budget to in-process libraries (OpenCV; PyTorch lazily)."""
+    if settings.threads <= 0:
+        return
+    import cv2
+
+    cv2.setNumThreads(settings.threads)
+
+
+def hardware_report(settings: Settings) -> dict[str, object]:
+    """JSON-friendly summary used by doctor / environment_check / configure."""
+    gpu = detect_gpu()
+    return {
+        "device_preference": settings.device,
+        "external_tools_use_gpu": wants_gpu(settings),
+        "gpu": gpu.to_dict(),
+        "threads": settings.threads or "auto",
+    }

reverse3d/imaging.py

@@ -0,0 +1,79 @@
+"""Safe image I/O.
+
+Images are size-checked from their header with Pillow *before* OpenCV decodes
+the full pixel buffer, which prevents decompression bombs from exhausting
+memory. Decoding goes through ``np.fromfile`` + ``cv2.imdecode`` so non-ASCII
+paths work on Windows (``cv2.imread`` does not support them).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+from reverse3d.config import Settings
+from reverse3d.errors import InputValidationError, ProcessingError
+from reverse3d.security import IMAGE_EXTENSIONS, prepare_output_file, validate_input_file
+
+
+def check_image_header(path: Path, max_pixels: int) -> tuple[int, int]:
+    """Return ``(width, height)`` from the image header, enforcing ``max_pixels``."""
+    # Pillow's own bomb guard would raise a warning/error at ~2x its default;
+    # we apply our explicit, configurable limit instead.
+    try:
+        with Image.open(path) as img:
+            width, height = img.size
+    except (OSError, Image.DecompressionBombError) as exc:
+        raise InputValidationError(f"Unreadable or unsafe image: {path.name}") from exc
+    if width * height > max_pixels:
+        raise InputValidationError(
+            f"Image too large ({width}x{height} px).",
+            hint="Raise REVERSE3D_MAX_IMAGE_PIXELS if this is expected.",
+        )
+    return width, height
+
+
+def load_image(
+    path: str | Path,
+    settings: Settings,
+    *,
+    flags: int = cv2.IMREAD_COLOR,
+) -> np.ndarray:
+    """Validate and decode an image into a NumPy array (BGR / grayscale / BGRA).
+
+    Raises:
+        InputValidationError: invalid file, type, or size.
+    """
+    resolved = validate_input_file(
+        path, allowed_extensions=IMAGE_EXTENSIONS, max_bytes=settings.max_input_bytes
+    )
+    check_image_header(resolved, settings.max_image_pixels)
+    buffer = np.fromfile(resolved, dtype=np.uint8)
+    image = cv2.imdecode(buffer, flags)
+    if image is None:
+        raise InputValidationError(f"OpenCV could not decode image: {resolved.name}")
+    return image
+
+
+def save_image(image: np.ndarray, path: str | Path, *, overwrite: bool = False) -> Path:
+    """Encode and write ``image`` to ``path`` (format inferred from extension)."""
+    out = prepare_output_file(path, allowed_extensions=IMAGE_EXTENSIONS, overwrite=overwrite)
+    ok, encoded = cv2.imencode(out.suffix, image)
+    if not ok:
+        raise ProcessingError(f"Could not encode image as {out.suffix}")
+    encoded.tofile(out)
+    return out
+
+
+def downscale(image: np.ndarray, max_dim: int) -> tuple[np.ndarray, float]:
+    """Downscale so the longest side is ``max_dim``. Returns ``(image, scale)``."""
+    h, w = image.shape[:2]
+    longest = max(h, w)
+    if longest <= max_dim:
+        return image, 1.0
+    scale = max_dim / longest
+    resized = cv2.resize(image, (round(w * scale), round(h * scale)), interpolation=cv2.INTER_AREA)
+    return resized, scale

reverse3d/logging_utils.py

@@ -0,0 +1,41 @@
+"""Logging setup.
+
+Logs always go to **stderr**: stdout is reserved for command results (``--json``)
+and for the MCP stdio transport, which would be corrupted by stray log lines.
+Logged messages never include file contents, credentials or full absolute paths
+supplied by agents; modules log file *names* only.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, str | None] = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exc_type"] = record.exc_info[0].__name__ if record.exc_info[0] else None
+        return json.dumps(payload, ensure_ascii=False)
+
+
+def configure_logging(level: str = "INFO", *, json_lines: bool = False) -> None:
+    """Configure the ``reverse3d`` logger hierarchy (idempotent)."""
+    root = logging.getLogger("reverse3d")
+    root.setLevel(level)
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        _JsonFormatter() if json_lines else logging.Formatter("%(levelname)s %(name)s: %(message)s")
+    )
+    root.addHandler(handler)
+    root.propagate = False