reverse3d 0.4.0__py3-none-any.whl

reverse3d/reconstruction/photogrammetry.py

@@ -0,0 +1,460 @@
+"""Photogrammetry pipeline built on the COLMAP command-line interface.
+
+Stages::
+
+    stage images → feature_extractor → (exhaustive|sequential)_matcher → mapper
+      → model_analyzer (pick largest model) → model_converter (sparse PLY)
+      → [dense: image_undistorter → patch_match_stereo → stereo_fusion]  (CUDA)
+      → [mesh: Poisson via Open3D]                                        ([recon])
+
+Design notes:
+
+* COLMAP option names changed across releases (e.g. ``SiftExtraction.use_gpu``
+  became ``FeatureExtraction.use_gpu`` in 3.12). Instead of pinning a version,
+  each stage probes ``<command> -h`` once and uses whichever option exists.
+* Input images are validated and **copied** into ``<output>/images`` so COLMAP
+  only ever reads files that passed the allowlist and size checks.
+* Dense MVS requires CUDA. With ``dense="auto"`` a dense failure degrades
+  gracefully to the sparse cloud and is reported as a warning.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import time
+from dataclasses import asdict, dataclass, field, replace
+from pathlib import Path
+from typing import Literal
+
+from reverse3d.config import Settings
+from reverse3d.errors import (
+    DependencyMissingError,
+    ExternalToolError,
+    InputValidationError,
+    ProcessingError,
+)
+from reverse3d.security import (
+    list_images,
+    prepare_output_dir,
+    resolve_executable,
+    run_command,
+    validate_input_dir,
+)
+
+logger = logging.getLogger(__name__)
+
+Quality = Literal["low", "medium", "high"]
+MatcherKind = Literal["auto", "exhaustive", "sequential"]
+DenseMode = Literal["auto", "on", "off"]
+
+CAMERA_MODELS = frozenset(
+    {"SIMPLE_PINHOLE", "PINHOLE", "SIMPLE_RADIAL", "RADIAL", "OPENCV", "FULL_OPENCV"}
+)
+
+_PRESETS: dict[str, dict[str, int]] = {
+    "low": {"max_image_size": 1000, "max_features": 4096, "poisson_depth": 8},
+    "medium": {"max_image_size": 1600, "max_features": 8192, "poisson_depth": 9},
+    "high": {"max_image_size": 3200, "max_features": 16384, "poisson_depth": 10},
+}
+
+# Above this many images exhaustive matching (O(n²)) becomes impractical.
+_EXHAUSTIVE_LIMIT = 150
+
+# Names of the artifacts this pipeline creates; only these are removed on overwrite.
+_ARTIFACTS = ("database.db", "images", "sparse", "dense", "sparse_points.ply", "mesh.ply")
+
+
+@dataclass
+class PhotogrammetryOptions:
+    """User-facing options of :meth:`ColmapPipeline.run`."""
+
+    quality: Quality = "medium"
+    matcher: MatcherKind = "auto"
+    dense: DenseMode = "auto"
+    use_gpu: bool = False
+    camera_model: str = "SIMPLE_RADIAL"
+    single_camera: bool = True
+    build_mesh: bool = True
+
+    def validate(self) -> None:
+        if self.quality not in _PRESETS:
+            raise InputValidationError(f"quality must be one of {sorted(_PRESETS)}")
+        if self.matcher not in ("auto", "exhaustive", "sequential"):
+            raise InputValidationError("matcher must be auto, exhaustive or sequential")
+        if self.dense not in ("auto", "on", "off"):
+            raise InputValidationError("dense must be auto, on or off")
+        if self.camera_model not in CAMERA_MODELS:
+            raise InputValidationError(f"camera_model must be one of {sorted(CAMERA_MODELS)}")
+
+
+@dataclass
+class StageTiming:
+    name: str
+    seconds: float
+
+
+@dataclass
+class PhotogrammetryResult:
+    """Outputs of a photogrammetry run (paths are absolute strings)."""
+
+    output_dir: str
+    sparse_model_dir: str
+    sparse_points_path: str
+    dense_points_path: str | None
+    mesh_path: str | None
+    total_images: int
+    registered_images: int
+    sparse_points: int
+    stages: list[StageTiming] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+class ColmapPipeline:
+    """Thin, safe wrapper around the ``colmap`` executable."""
+
+    def __init__(self, settings: Settings, executable: Path | None = None) -> None:
+        self.settings = settings
+        self.executable = executable or resolve_executable(
+            ["colmap", "COLMAP", "colmap.exe", "COLMAP.bat"], settings.colmap_path, tool="colmap"
+        )
+        self._help_cache: dict[str, str] = {}
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+
+    def _help(self, command: str) -> str:
+        if command not in self._help_cache:
+            proc = run_command(
+                self.executable, [command, "-h"], timeout_s=60, tool="colmap", allow_nonzero=True
+            )
+            self._help_cache[command] = (proc.stdout or "") + (proc.stderr or "")
+        return self._help_cache[command]
+
+    def _pick_option(self, command: str, candidates: tuple[str, ...]) -> str | None:
+        help_text = self._help(command)
+        for option in candidates:
+            if f"--{option}" in help_text:
+                return option
+        return None
+
+    def _with_options(
+        self, command: str, args: list[str], options: dict[tuple[str, ...], str]
+    ) -> list[str]:
+        for candidates, value in options.items():
+            name = self._pick_option(command, candidates)
+            if name:
+                args += [f"--{name}", value]
+            else:
+                logger.debug("COLMAP %s: none of %s supported, skipping", command, candidates)
+        return args
+
+    def _stage(self, result: PhotogrammetryResult, name: str, args: list[str]) -> str:
+        start = time.perf_counter()
+        logger.info("COLMAP stage: %s", name)
+        proc = run_command(
+            self.executable,
+            args,
+            timeout_s=self.settings.subprocess_timeout_s,
+            tool=f"colmap {name}",
+        )
+        result.stages.append(StageTiming(name, round(time.perf_counter() - start, 2)))
+        return (proc.stdout or "") + (proc.stderr or "")
+
+    def version(self) -> str:
+        """Return the COLMAP version banner (first line of ``colmap help``)."""
+        proc = run_command(
+            self.executable, ["help"], timeout_s=60, tool="colmap", allow_nonzero=True
+        )
+        text = (proc.stdout or proc.stderr or "").strip()
+        return text.splitlines()[0] if text else "unknown"
+
+    def has_cuda(self) -> bool:
+        """False only when COLMAP's banner states it was built ``without CUDA``."""
+        proc = run_command(
+            self.executable, ["help"], timeout_s=60, tool="colmap", allow_nonzero=True
+        )
+        return "without cuda" not in ((proc.stdout or "") + (proc.stderr or "")).lower()
+
+    # ── pipeline ──────────────────────────────────────────────────────────────
+
+    def _prepare_workspace(self, image_dir: Path, output_dir: Path, overwrite: bool) -> list[Path]:
+        images = list_images(
+            image_dir, max_images=self.settings.max_images, max_bytes=self.settings.max_input_bytes
+        )
+        if len(images) < 3:
+            raise InputValidationError("Photogrammetry needs at least 3 images.")
+        existing = [name for name in _ARTIFACTS if (output_dir / name).exists()]
+        if existing and not overwrite:
+            raise InputValidationError(
+                "Output directory already contains a reconstruction.",
+                hint="Use another output_dir or pass overwrite=true.",
+            )
+        for name in existing:
+            target = output_dir / name
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+        staged = output_dir / "images"
+        staged.mkdir()
+        for img in images:
+            shutil.copy2(img, staged / img.name)
+        return images
+
+    @staticmethod
+    def _parse_model_stats(text: str) -> tuple[int, int]:
+        def grab(label: str) -> int:
+            match = re.search(rf"{label}\s*:\s*(\d+)", text)
+            return int(match.group(1)) if match else 0
+
+        return grab("Registered images"), grab("Points")
+
+    def run(
+        self,
+        image_dir: str | Path,
+        output_dir: str | Path,
+        options: PhotogrammetryOptions | None = None,
+        *,
+        overwrite: bool = False,
+    ) -> PhotogrammetryResult:
+        """Run the full pipeline and return paths and statistics.
+
+        Raises:
+            InputValidationError: invalid options or image folder.
+            ExternalToolError: a COLMAP stage failed.
+            ProcessingError: no model could be reconstructed.
+        """
+        options = options or PhotogrammetryOptions()
+        options.validate()
+        preset = _PRESETS[options.quality]
+        src = validate_input_dir(image_dir)
+        out = prepare_output_dir(output_dir)
+        # Overwrite deletes our artifact folders; never let that touch the source photos.
+        if any(src.is_relative_to(out / name) for name in _ARTIFACTS):
+            raise InputValidationError(
+                "image_dir must not be inside the reconstruction artifacts of output_dir."
+            )
+        images = self._prepare_workspace(src, out, overwrite)
+
+        db = out / "database.db"
+        staged = out / "images"
+        sparse_root = out / "sparse"
+        sparse_root.mkdir()
+        result = PhotogrammetryResult(
+            output_dir=str(out),
+            sparse_model_dir="",
+            sparse_points_path="",
+            dense_points_path=None,
+            mesh_path=None,
+            total_images=len(images),
+            registered_images=0,
+            sparse_points=0,
+        )
+        if options.use_gpu and not self.has_cuda():
+            # A CPU-only COLMAP build fails (or uses headless-incompatible OpenGL)
+            # with use_gpu=1, so degrade instead of failing the whole job.
+            options = replace(options, use_gpu=False)
+            result.warnings.append("COLMAP was built without CUDA; running on CPU.")
+        gpu = "1" if options.use_gpu else "0"
+
+        # 1. Features
+        args = [
+            "feature_extractor",
+            "--database_path",
+            str(db),
+            "--image_path",
+            str(staged),
+            "--ImageReader.camera_model",
+            options.camera_model,
+            "--ImageReader.single_camera",
+            "1" if options.single_camera else "0",
+        ]
+        self._stage(
+            result,
+            "feature_extractor",
+            self._with_options(
+                "feature_extractor",
+                args,
+                {
+                    ("FeatureExtraction.use_gpu", "SiftExtraction.use_gpu"): gpu,
+                    ("FeatureExtraction.max_image_size", "SiftExtraction.max_image_size"): str(
+                        preset["max_image_size"]
+                    ),
+                    ("SiftExtraction.max_num_features",): str(preset["max_features"]),
+                },
+            ),
+        )
+
+        # 2. Matching
+        matcher = options.matcher
+        if matcher == "auto":
+            matcher = "exhaustive" if len(images) <= _EXHAUSTIVE_LIMIT else "sequential"
+        command = f"{matcher}_matcher"
+        self._stage(
+            result,
+            command,
+            self._with_options(
+                command,
+                [command, "--database_path", str(db)],
+                {("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu},
+            ),
+        )
+
+        # 3. Sparse reconstruction (SfM)
+        self._stage(
+            result,
+            "mapper",
+            [
+                "mapper",
+                "--database_path",
+                str(db),
+                "--image_path",
+                str(staged),
+                "--output_path",
+                str(sparse_root),
+            ],
+        )
+        models = sorted(p for p in sparse_root.iterdir() if p.is_dir())
+        if not models:
+            raise ProcessingError(
+                "COLMAP could not register the images into a 3D model.",
+                hint="Run the image analysis tool: more overlap, texture and sharpness are needed.",
+            )
+        best, best_stats = models[0], (0, 0)
+        for model in models:
+            stats = self._parse_model_stats(
+                self._stage(
+                    result, f"model_analyzer:{model.name}", ["model_analyzer", "--path", str(model)]
+                )
+            )
+            if stats[0] > best_stats[0]:
+                best, best_stats = model, stats
+        result.sparse_model_dir = str(best)
+        result.registered_images, result.sparse_points = best_stats
+        if result.registered_images and result.registered_images < len(images) * 0.5:
+            result.warnings.append(
+                f"Only {result.registered_images}/{len(images)} images were registered."
+            )
+
+        sparse_ply = out / "sparse_points.ply"
+        self._stage(
+            result,
+            "model_converter",
+            [
+                "model_converter",
+                "--input_path",
+                str(best),
+                "--output_path",
+                str(sparse_ply),
+                "--output_type",
+                "PLY",
+            ],
+        )
+        result.sparse_points_path = str(sparse_ply)
+
+        # 4. Dense reconstruction (MVS) — CUDA only
+        run_dense = options.dense == "on" or (options.dense == "auto" and options.use_gpu)
+        if run_dense:
+            try:
+                result.dense_points_path = str(self._dense(result, staged, best, out, preset))
+            except ExternalToolError as exc:
+                if options.dense == "on":
+                    raise
+                result.warnings.append(f"Dense stage skipped ({exc.message}); using sparse cloud.")
+        elif options.dense == "auto":
+            result.warnings.append("Dense MVS skipped (requires use_gpu=true and CUDA COLMAP).")
+
+        # 5. Surface
+        if options.build_mesh:
+            from reverse3d.reconstruction.pointcloud import poisson_mesh
+
+            cloud = result.dense_points_path or result.sparse_points_path
+            try:
+                meshing = poisson_mesh(
+                    cloud,
+                    out / "mesh.ply",
+                    self.settings,
+                    depth=preset["poisson_depth"],
+                    overwrite=True,
+                )
+                result.mesh_path = meshing.mesh_path
+            except (DependencyMissingError, ProcessingError) as exc:
+                result.warnings.append(f"Meshing skipped: {exc.message}")
+
+        logger.info(
+            "Photogrammetry done: %d/%d images registered", result.registered_images, len(images)
+        )
+        return result
+
+    def _dense(
+        self,
+        result: PhotogrammetryResult,
+        staged: Path,
+        model: Path,
+        out: Path,
+        preset: dict[str, int],
+    ) -> Path:
+        dense = out / "dense"
+        self._stage(
+            result,
+            "image_undistorter",
+            [
+                "image_undistorter",
+                "--image_path",
+                str(staged),
+                "--input_path",
+                str(model),
+                "--output_path",
+                str(dense),
+                "--output_type",
+                "COLMAP",
+                "--max_image_size",
+                str(preset["max_image_size"]),
+            ],
+        )
+        self._stage(
+            result,
+            "patch_match_stereo",
+            [
+                "patch_match_stereo",
+                "--workspace_path",
+                str(dense),
+                "--workspace_format",
+                "COLMAP",
+                "--PatchMatchStereo.geom_consistency",
+                "true",
+            ],
+        )
+        fused = dense / "fused.ply"
+        self._stage(
+            result,
+            "stereo_fusion",
+            [
+                "stereo_fusion",
+                "--workspace_path",
+                str(dense),
+                "--workspace_format",
+                "COLMAP",
+                "--input_type",
+                "geometric",
+                "--output_path",
+                str(fused),
+            ],
+        )
+        return fused
+
+
+def run_photogrammetry(
+    image_dir: str | Path,
+    output_dir: str | Path,
+    settings: Settings,
+    options: PhotogrammetryOptions | None = None,
+    *,
+    overwrite: bool = False,
+) -> PhotogrammetryResult:
+    """Convenience wrapper: locate COLMAP and run :class:`ColmapPipeline`."""
+    return ColmapPipeline(settings).run(image_dir, output_dir, options, overwrite=overwrite)

reverse3d/reconstruction/pointcloud.py

@@ -0,0 +1,120 @@
+"""Point cloud → surface meshing with Open3D (optional ``[recon]`` extra)."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from reverse3d.config import Settings
+from reverse3d.errors import DependencyMissingError, InputValidationError, ProcessingError
+from reverse3d.security import (
+    MESH_EXTENSIONS,
+    POINT_CLOUD_EXTENSIONS,
+    prepare_output_file,
+    validate_input_file,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def require_open3d() -> Any:
+    """Import Open3D or raise a helpful :class:`DependencyMissingError`."""
+    try:
+        import open3d as o3d
+    except ImportError as exc:
+        raise DependencyMissingError(
+            "Open3D is required for point-cloud meshing.",
+            hint='pip install "reverse3d[recon]" (Open3D wheels exist for Python 3.10-3.12).',
+        ) from exc
+    return o3d
+
+
+@dataclass
+class MeshingResult:
+    """Outputs of :func:`poisson_mesh`."""
+
+    mesh_path: str
+    input_points: int
+    filtered_points: int
+    vertices: int
+    faces: int
+    poisson_depth: int
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def poisson_mesh(
+    cloud_path: str | Path,
+    output_path: str | Path,
+    settings: Settings,
+    *,
+    depth: int = 9,
+    voxel_size: float | None = None,
+    density_quantile: float = 0.02,
+    outlier_std_ratio: float = 2.0,
+    overwrite: bool = False,
+) -> MeshingResult:
+    """Reconstruct a watertight-ish surface from a point cloud (screened Poisson).
+
+    Steps: optional voxel downsampling → statistical outlier removal → normal
+    estimation and consistent orientation → Poisson → removal of low-density
+    vertices (the "balloon" Poisson extrapolates into empty space) → crop to the
+    input bounding box.
+
+    Raises:
+        DependencyMissingError: Open3D not installed.
+        ProcessingError: too few points or empty result.
+    """
+    if not 5 <= depth <= 12:
+        raise InputValidationError("depth must be in [5, 12].")
+    if not 0 <= density_quantile < 0.5:
+        raise InputValidationError("density_quantile must be in [0, 0.5).")
+    o3d = require_open3d()
+
+    src = validate_input_file(
+        cloud_path, allowed_extensions=POINT_CLOUD_EXTENSIONS, max_bytes=settings.max_input_bytes
+    )
+    out = prepare_output_file(output_path, allowed_extensions=MESH_EXTENSIONS, overwrite=overwrite)
+
+    pcd = o3d.io.read_point_cloud(str(src))
+    n_input = len(pcd.points)
+    if n_input < 100:
+        raise ProcessingError(f"Point cloud too small for meshing ({n_input} points).")
+
+    if voxel_size:
+        pcd = pcd.voxel_down_sample(voxel_size)
+    pcd, _ = pcd.remove_statistical_outlier(nb_neighbors=20, std_ratio=outlier_std_ratio)
+    extent = float(np.linalg.norm(pcd.get_axis_aligned_bounding_box().get_extent()))
+    radius = max(extent * 0.01, 1e-6)
+    if not pcd.has_normals():
+        pcd.estimate_normals(o3d.geometry.KDTreeSearchParamHybrid(radius=radius * 3, max_nn=30))
+    pcd.orient_normals_consistent_tangent_plane(15)
+
+    mesh, densities = o3d.geometry.TriangleMesh.create_from_point_cloud_poisson(pcd, depth=depth)
+    densities = np.asarray(densities)
+    if density_quantile > 0 and len(densities):
+        mesh.remove_vertices_by_mask(densities < np.quantile(densities, density_quantile))
+    mesh = mesh.crop(pcd.get_axis_aligned_bounding_box())
+    mesh.remove_degenerate_triangles()
+    mesh.remove_unreferenced_vertices()
+    if len(mesh.triangles) == 0:
+        raise ProcessingError("Poisson reconstruction produced an empty mesh.")
+    if len(mesh.triangles) > settings.max_mesh_faces:
+        mesh = mesh.simplify_quadric_decimation(settings.max_mesh_faces)
+
+    if not o3d.io.write_triangle_mesh(str(out), mesh):
+        raise ProcessingError(f"Open3D could not write {out.name}")
+    logger.info("Poisson mesh %s: %d faces", out.name, len(mesh.triangles))
+    return MeshingResult(
+        mesh_path=str(out),
+        input_points=n_input,
+        filtered_points=len(pcd.points),
+        vertices=len(mesh.vertices),
+        faces=len(mesh.triangles),
+        poisson_depth=depth,
+    )

reverse3d/rendering/__init__.py

@@ -0,0 +1,10 @@
+"""Automated rendering: headless Blender (Cycles/Eevee/Workbench) or PyVista."""
+
+from reverse3d.rendering.blender_render import (
+    RenderOptions,
+    RenderResult,
+    render_mesh,
+    render_with_blender,
+)
+
+__all__ = ["RenderOptions", "RenderResult", "render_mesh", "render_with_blender"]