reverse3d 0.5.1__tar.gz → 0.6.0__tar.gz

{reverse3d-0.5.1/reverse3d.egg-info → reverse3d-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.5.1
+Version: 0.6.0
 Summary: AI-agent-ready toolkit for 3D reverse engineering: image analysis, photogrammetry, mesh repair, primitive fitting and headless rendering.
 Author-email: Voxel Enterprise <info@voxel.lat>
 Maintainer-email: Voxel Enterprise <info@voxel.lat>
@@ -31,6 +31,7 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: numpy>=1.26
 Requires-Dist: scipy>=1.11
+Requires-Dist: scikit-image>=0.22
 Requires-Dist: opencv-python-headless>=4.9
 Requires-Dist: pillow>=10.3
 Requires-Dist: pillow-heif>=1.1
@@ -425,6 +426,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 
 **Formatos:** imágenes `png jpg jpeg tif tiff bmp webp`, y fotos de iPhone `heic heif` (se convierten a JPEG conservando el EXIF) · mallas `stl obj ply glb gltf off` · nubes `ply xyz pcd`.
 
+**Perfiles de escena:** reverse3d predice si las fotos son de un objeto, un personaje, arquitectura o un paisaje (`reverse3d scene detect <carpeta>`) y ajusta la reconstrucción; también puedes elegirlo con `reverse3d auto <carpeta> --scene architecture`.
+
 **¿Cómo tomar las fotos?** Mínimo 20, recomendadas 40-60, en 4 perfiles (anillos a 10-20°, 35-45° y 60-70°, y 4 desde arriba), sin mover el objeto, con luz pareja y sin reflejos. Guía completa: [docs/captura.md](docs/captura.md).
 
 ---

{reverse3d-0.5.1 → reverse3d-0.6.0}/README.md

@@ -358,6 +358,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 
 **Formatos:** imágenes `png jpg jpeg tif tiff bmp webp`, y fotos de iPhone `heic heif` (se convierten a JPEG conservando el EXIF) · mallas `stl obj ply glb gltf off` · nubes `ply xyz pcd`.
 
+**Perfiles de escena:** reverse3d predice si las fotos son de un objeto, un personaje, arquitectura o un paisaje (`reverse3d scene detect <carpeta>`) y ajusta la reconstrucción; también puedes elegirlo con `reverse3d auto <carpeta> --scene architecture`.
+
 **¿Cómo tomar las fotos?** Mínimo 20, recomendadas 40-60, en 4 perfiles (anillos a 10-20°, 35-45° y 60-70°, y 4 desde arriba), sin mover el objeto, con luz pareja y sin reflejos. Guía completa: [docs/captura.md](docs/captura.md).
 
 ---

{reverse3d-0.5.1 → reverse3d-0.6.0}/pyproject.toml

@@ -39,6 +39,7 @@ classifiers = [
 dependencies = [
     "numpy>=1.26",
     "scipy>=1.11",
+    "scikit-image>=0.22",
     "opencv-python-headless>=4.9",
     "pillow>=10.3",
     "pillow-heif>=1.1",

reverse3d-0.6.0/reverse3d/_version.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

{reverse3d-0.5.1 → reverse3d-0.6.0}/reverse3d/agent/tools.py

@@ -240,6 +240,11 @@ class RunRecipeArgs(_Args):
     force_analysis: bool = Field(
         False, description="photos_to_model: continue even if the photo check fails."
     )
+    scene: Literal["auto", "object", "character", "architecture", "landscape"] = Field(
+        "auto",
+        description="Photo sets: auto predicts it. object=part/product, character=person "
+        "for games, architecture=building/interior, landscape=terrain/drone flight.",
+    )
     overwrite: bool = _OVERWRITE
 
 
@@ -471,6 +476,7 @@ def _run_recipe(a: RunRecipeArgs, s: Settings) -> dict[str, Any]:
             render=a.render,
             quality=a.quality,
             force_analysis=a.force_analysis,
+            scene=a.scene,
             overwrite=a.overwrite,
         ),
     )

{reverse3d-0.5.1 → reverse3d-0.6.0}/reverse3d/autopilot.py

@@ -299,6 +299,8 @@ def _relief_fallback(
 ) -> dict[str, Any]:
     """Photogrammetry was not possible: build an approximate model from the best photo."""
     photo, mask = _best_photo(source, out, settings)
+    if base.scene in ("architecture", "landscape"):
+        mask = None  # an open scene: keep the whole view as a relief
     logger.info("Photogrammetry not possible; building an AI-depth relief from %s", photo.name)
     summary = run_recipe(
         "photo_to_relief",
@@ -352,6 +354,16 @@ def auto_run(
         source = _mesh_from_points(detection, out, settings, base.overwrite)
 
     history: list[dict[str, Any]] = []
+    scene_info: dict[str, Any] | None = None
+    if detection.kind == "photos":
+        from reverse3d.scenes import SCENE_PRESETS, detect_scene
+
+        if base.scene == "auto":
+            predicted = detect_scene(source, settings)
+            scene_info = predicted.to_dict()
+            base = replace(base, scene=predicted.kind)
+        elif base.scene in SCENE_PRESETS:
+            scene_info = {"kind": base.scene, "confidence": 1.0, "reasons": ["chosen"]}
     summary: dict[str, Any] | None = None
     last_error: Reverse3DError | None = None
     capture_advice: list[str] = []
@@ -396,7 +408,14 @@ def auto_run(
 
     if summary is None and detection.kind == "photos" and last_error is not None:
         reason = last_error.message.split(":", 1)[0].rstrip(".")
-        capture_advice = [CAPTURE_ADVICE_ES]
+        from reverse3d.scenes import scene_advice
+
+        photos = len(
+            list_images(source, max_images=settings.max_images, max_bytes=settings.max_input_bytes)
+        )
+        capture_advice = (
+            scene_advice(base.scene, photos) if base.scene != "auto" else [CAPTURE_ADVICE_ES]
+        )
         try:
             summary = _relief_fallback(source, out, settings, base, reason, history)
         except Reverse3DError as exc:
@@ -409,6 +428,8 @@ def auto_run(
         raise last_error or ProcessingError("No processing attempt could run.")
 
     summary["auto"] = {"detected": detection.to_dict(), "attempts": history}
+    if scene_info is not None:
+        summary["auto"]["scene"] = scene_info
     summary["next_steps"] = capture_advice + next_steps(detection, summary, base)
     summary["outputs"]["summary"] = str(write_summary(out, detection, summary))
     return summary

{reverse3d-0.5.1 → reverse3d-0.6.0}/reverse3d/cli.py

@@ -67,6 +67,10 @@ app.add_typer(vision_app, name="vision")
 app.add_typer(recon_app, name="recon")
 app.add_typer(mesh_app, name="mesh")
 app.add_typer(agent_app, name="agent")
+scene_app = typer.Typer(
+    help="Scene profiles: object, character, architecture, landscape.", no_args_is_help=True
+)
+app.add_typer(scene_app, name="scene")
 
 
 @dataclass
@@ -757,6 +761,10 @@ def auto_cmd(
     units_per_pixel: float | None = typer.Option(None, min=0, help="Drawing scale (mm/px)."),
     scale: float = typer.Option(1.0, min=1e-9, help="Final uniform scale (m→mm: 1000)."),
     render: bool = typer.Option(True, help="Render a PNG preview at the end."),
+    scene: str = typer.Option(
+        "auto",
+        help="Photo sets: auto (predicted), object, character, architecture or landscape.",
+    ),
     force: bool = typer.Option(False, "--force", "-f", help="Overwrite outputs."),
 ) -> None:
     """Detect what INPUT is and process it automatically (no recipe to choose)."""
@@ -769,6 +777,7 @@ def auto_cmd(
         units_per_pixel=units_per_pixel,
         scale=scale,
         render=render,
+        scene=scene,
         overwrite=force,
     )
 
@@ -780,6 +789,22 @@ def auto_cmd(
     _run(ctx, job)
 
 
+@scene_app.command("detect")
+def scene_detect_cmd(
+    ctx: typer.Context,
+    folder: Path = typer.Argument(..., help="Folder with the photos."),
+) -> None:
+    """Predict the scene of a photo set (object, character, architecture, landscape)."""
+    from reverse3d.imaging import prepare_heic_input
+    from reverse3d.scenes import detect_scene
+
+    def job(s: Settings) -> Any:
+        work = s.workspace / ".scene"
+        return detect_scene(prepare_heic_input(folder, work), s).to_dict()
+
+    _run(ctx, job)
+
+
 _WATCH_TEXT = {
     "detected": "📥 Nuevo: {item} (esperando a que termine de copiarse…)",
     "processing": "⚙️  Procesando {item}…",

{reverse3d-0.5.1 → reverse3d-0.6.0}/reverse3d/recipes.py

@@ -24,7 +24,6 @@ from __future__ import annotations
 import json
 import logging
 import math
-import shutil
 import time
 from collections.abc import Callable
 from dataclasses import dataclass, field
@@ -73,6 +72,8 @@ class RecipeOptions:
     overwrite: bool = False
     #: plan_to_part: how the drawing is separated from the background.
     mask_method: MaskMethod = "otsu"
+    #: photos_to_model: scene profile (object, character, architecture, landscape) or "auto".
+    scene: str = "auto"
     #: photo_to_relief: object mask (white = keep), e.g. from the autopilot fallback.
     mask_path: str | None = None
     #: mesh repair strength; "strong" closes much larger holes.
@@ -193,27 +194,37 @@ _MIN_GROUP = 8
 
 
 def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
-    from reverse3d.reconstruction.photogrammetry import PhotogrammetryOptions, run_photogrammetry
+    from reverse3d.reconstruction.photogrammetry import (
+        PhotogrammetryOptions,
+        PhotogrammetryResult,
+        run_photogrammetry,
+    )
+    from reverse3d.scenes import SCENE_LABEL_ES, SCENE_PRESETS, detect_scene
     from reverse3d.vision.feature_matcher import analyze_image_set
 
+    scene: str
+    if opt.scene == "auto":
+        detection = run.step("scene", lambda: detect_scene(src, run.settings))
+        scene, confidence, predicted = detection.kind, detection.confidence, True
+    elif opt.scene in SCENE_PRESETS:
+        scene, confidence, predicted = opt.scene, 1.0, False
+    else:
+        raise InputValidationError(
+            f"Unknown scene '{opt.scene}'.", hint=f"Use auto or one of: {', '.join(SCENE_PRESETS)}"
+        )
+    preset = SCENE_PRESETS[scene]
+    run.details["scene"] = {
+        "kind": scene,
+        "label": SCENE_LABEL_ES[scene],
+        "confidence": confidence,
+        "predicted": predicted,
+    }
     analysis = run.step("analyze", lambda: analyze_image_set(src, run.settings))
     run.details["analysis"] = analysis.to_dict()
     if not analysis.suitable_for_photogrammetry and analysis.connected_images >= _MIN_GROUP:
-        # Part of the set overlaps well: reconstruct from that group only.
-        dropped = set(analysis.weak_links)
-        group_dir = run.out / "photos_used"
-        group_dir.mkdir(parents=True, exist_ok=True)
-        for image in sorted(src.iterdir()):
-            if image.is_file() and image.name not in dropped and not image.name.startswith("."):
-                target = group_dir / image.name
-                if not target.exists():
-                    shutil.copy2(image, target)
-        run.warnings.append(
-            f"Used the {analysis.connected_images} photos that overlap; skipped "
-            f"{len(dropped)} that do not match the rest."
-        )
-        run.details["photos_used"] = analysis.connected_images
-        src = group_dir
+        # COLMAP places cameras far better than this quick check (it often uses
+        # the whole room), so every photo goes in; the check is only advice.
+        run.warnings.extend(analysis.recommendations)
     elif not analysis.suitable_for_photogrammetry:
         if not opt.force_analysis:
             raise CaptureQualityError(
@@ -223,21 +234,63 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
             )
         run.warnings.extend(analysis.recommendations)
 
-    quality = opt.quality or profile_values(run.settings).photo_quality
-    photo = run.step(
-        "photogrammetry",
-        lambda: run_photogrammetry(
+    quality = opt.quality or preset.quality or profile_values(run.settings).photo_quality
+    # Objects and characters: COLMAP only places the cameras (fast, no dense stage)
+    # and the shape is carved from the silhouettes, which also works on plain,
+    # white or glossy surfaces. Open scenes keep classic dense reconstruction.
+    silhouette = scene in ("object", "character")
+
+    def photogrammetry(classic: bool) -> PhotogrammetryResult:
+        return run_photogrammetry(
             src,
             run.out / "reconstruction",
             run.settings,
-            PhotogrammetryOptions(quality=quality, use_gpu=wants_gpu(run.settings)),  # type: ignore[arg-type]
-            overwrite=opt.overwrite,
-        ),
-    )
+            PhotogrammetryOptions(
+                quality=quality,  # type: ignore[arg-type]
+                matcher=preset.matcher,
+                dense="auto" if classic else "off",
+                use_gpu=wants_gpu(run.settings),
+                build_mesh=classic,
+                poisson_depth=preset.poisson_depth,
+                density_quantile=preset.density_quantile,
+            ),
+            overwrite=opt.overwrite or not classic,
+        )
+
+    photo = run.step("photogrammetry", lambda: photogrammetry(classic=not silhouette))
+    mesh_path: str | None = photo.mesh_path
+    upright = False
+    if silhouette:
+        from reverse3d.reconstruction.silhouette import visual_hull
+
+        try:
+            hull = run.step(
+                "silhouette",
+                lambda: visual_hull(
+                    Path(photo.images_dir or ""),
+                    Path(photo.sparse_text_dir or ""),
+                    run.out / "reconstruction" / "object_hull.ply",
+                ),
+            )
+        except ProcessingError as exc:
+            logger.info("Silhouette carving failed (%s); using dense reconstruction", exc.message)
+            run.warnings.append(
+                f"Silhouette carving failed ({exc.message}); used dense reconstruction."
+            )
+            photo = run.step("photogrammetry", lambda: photogrammetry(classic=True))
+            mesh_path = photo.mesh_path
+        else:
+            run.details["silhouette"] = hull.to_dict()
+            mesh_path = hull.mesh_path
+            upright = True
+    if photo.registered_images >= 0.9 * max(photo.total_images, 1):
+        # COLMAP placed (almost) every photo: the quick pre-check's capture advice
+        # would only confuse.
+        run.warnings[:] = [w for w in run.warnings if w not in analysis.recommendations]
     run.warnings.extend(photo.warnings)
     run.details["photogrammetry"] = photo.to_dict()
     run.outputs["point_cloud"] = photo.dense_points_path or photo.sparse_points_path
-    if not photo.mesh_path:
+    if not mesh_path:
         raise ProcessingError(
             "Point cloud created but no mesh could be built.",
             hint='Install the meshing extra: pip install "reverse3d[recon]" (Python ≤ 3.12).',
@@ -245,11 +298,13 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
     model = run.out / "model.stl"
     _clean(
         run,
-        Path(photo.mesh_path),
+        Path(mesh_path),
         model,
         scale=opt.scale,
         overwrite=opt.overwrite,
-        keep_largest=True,
+        fill_holes=preset.fill_holes,
+        align="none" if upright else "obb",
+        keep_largest=preset.keep_largest,
         repair=opt.repair,
     )
     return _measure(run, model)
@@ -452,6 +507,8 @@ def run_recipe(
         "steps": [f"{s['step']}:{s['s']}s" for s in run.steps],
         "warnings": run.warnings,
     }
+    if "scene" in run.details:
+        summary["scene"] = run.details["scene"]
     if "primitive_summary" in run.details:
         summary["primitives"] = run.details["primitive_summary"]
 

{reverse3d-0.5.1 → reverse3d-0.6.0}/reverse3d/reconstruction/photogrammetry.py

@@ -46,7 +46,7 @@ from reverse3d.security import (
 logger = logging.getLogger(__name__)
 
 Quality = Literal["low", "medium", "high"]
-MatcherKind = Literal["auto", "exhaustive", "sequential"]
+MatcherKind = Literal["auto", "exhaustive", "sequential", "spatial"]
 DenseMode = Literal["auto", "on", "off"]
 
 CAMERA_MODELS = frozenset(
@@ -68,7 +68,15 @@ _MIN_SPARSE_POINTS = 1000
 _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")
+_ARTIFACTS = (
+    "database.db",
+    "images",
+    "sparse",
+    "sparse_txt",
+    "dense",
+    "sparse_points.ply",
+    "mesh.ply",
+)
 
 
 @dataclass
@@ -82,12 +90,20 @@ class PhotogrammetryOptions:
     camera_model: str = "SIMPLE_RADIAL"
     single_camera: bool = True
     build_mesh: bool = True
+    #: Poisson octree depth; None uses the quality preset (scene profiles raise it).
+    poisson_depth: int | None = None
+    #: share of the least supported surface trimmed after Poisson.
+    density_quantile: float = 0.02
 
     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.matcher not in ("auto", "exhaustive", "sequential", "spatial"):
+            raise InputValidationError("matcher must be auto, exhaustive, sequential or spatial")
+        if self.poisson_depth is not None and not 5 <= self.poisson_depth <= 13:
+            raise InputValidationError("poisson_depth must be in [5, 13]")
+        if not 0 <= self.density_quantile < 0.5:
+            raise InputValidationError("density_quantile must be in [0, 0.5)")
         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:
@@ -114,6 +130,9 @@ class PhotogrammetryResult:
     sparse_points: int
     stages: list[StageTiming] = field(default_factory=list)
     warnings: list[str] = field(default_factory=list)
+    #: the photos as COLMAP saw them, and the chosen model as text (silhouette carving).
+    images_dir: str | None = None
+    sparse_text_dir: str | None = None
 
     def to_dict(self) -> dict[str, object]:
         return asdict(self)
@@ -296,18 +315,38 @@ class ColmapPipeline:
 
         # 2. Matching
         matcher = options.matcher
+        if matcher == "spatial":
+            from reverse3d.scenes import has_gps
+
+            # GPS-guided matching (drone / large outdoor sets); without GPS, sequential.
+            matcher = "spatial" if has_gps(staged) else "sequential"
         if matcher == "auto":
             matcher = "exhaustive" if len(images) <= _EXHAUSTIVE_LIMIT else "sequential"
         command = f"{matcher}_matcher"
-        self._stage(
-            result,
-            command,
-            self._with_options(
+        extra: dict[tuple[str, ...], str] = {
+            ("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu
+        }
+        if matcher == "spatial":
+            extra[("SpatialMatching.is_gps",)] = "1"
+        try:
+            self._stage(
+                result,
                 command,
-                [command, "--database_path", str(db)],
-                {("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu},
-            ),
-        )
+                self._with_options(command, [command, "--database_path", str(db)], extra),
+            )
+        except ExternalToolError:
+            if matcher != "spatial":
+                raise
+            result.warnings.append("GPS matching failed; used sequential matching instead.")
+            self._stage(
+                result,
+                "sequential_matcher",
+                self._with_options(
+                    "sequential_matcher",
+                    ["sequential_matcher", "--database_path", str(db)],
+                    {("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu},
+                ),
+            )
 
         # 3. Sparse reconstruction (SfM)
         self._stage(
@@ -366,6 +405,23 @@ class ColmapPipeline:
             ],
         )
         result.sparse_points_path = str(sparse_ply)
+        result.images_dir = str(staged)
+        text_dir = out / "sparse_txt"
+        text_dir.mkdir(parents=True, exist_ok=True)
+        self._stage(
+            result,
+            "model_converter_txt",
+            [
+                "model_converter",
+                "--input_path",
+                str(best),
+                "--output_path",
+                str(text_dir),
+                "--output_type",
+                "TXT",
+            ],
+        )
+        result.sparse_text_dir = str(text_dir)
 
         # 4. Dense reconstruction (MVS) — CUDA only
         run_dense = options.dense == "on" or (options.dense == "auto" and options.use_gpu)
@@ -389,7 +445,8 @@ class ColmapPipeline:
                     cloud,
                     out / "mesh.ply",
                     self.settings,
-                    depth=preset["poisson_depth"],
+                    depth=options.poisson_depth or preset["poisson_depth"],
+                    density_quantile=options.density_quantile,
                     overwrite=True,
                 )
                 result.mesh_path = meshing.mesh_path