reverse3d 0.8.1__tar.gz → 0.10.0__tar.gz

{reverse3d-0.8.1/reverse3d.egg-info → reverse3d-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.8.1
+Version: 0.10.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>
@@ -32,6 +32,7 @@ License-File: NOTICE
 Requires-Dist: numpy>=1.26
 Requires-Dist: scipy>=1.11
 Requires-Dist: scikit-image>=0.22
+Requires-Dist: xatlas>=0.0.9
 Requires-Dist: opencv-python-headless>=4.9
 Requires-Dist: pillow>=10.3
 Requires-Dist: pillow-heif>=1.1
@@ -219,7 +220,7 @@ Cada archivo modificado se **respalda antes** (`*.reverse3d-backup-<fecha>`). So
 | `--lite` | `-Lite` | Todo, con la IA local en la CPU (PyTorch CPU, ~250 MB en vez de ~2.5 GB) |
 | `--minimal` | `-Minimal` | Núcleo + MCP + IA local, sin herramientas externas |
 | `--no-tools` | `-NoTools` | No instalar Blender ni COLMAP |
-| *(en todos los modos)* | *(en todos los modos)* | **La IA local se instala y se descarga siempre** (clasificador, segmentación y profundidad, unos 750 MB) para que todo funcione sin internet |
+| *(en todos los modos)* | *(en todos los modos)* | **La IA local se instala y se descarga siempre** (clasificador, segmentación, profundidad y puntos con IA, unos 800 MB) para que todo funcione sin internet |
 | `--no-auto-approve` | `-NoAutoApprove` | Que los agentes pregunten antes de cada herramienta |
 | `--with recon,depth` | `-With recon,depth` | Extras a elección |
 | `--device auto\|cpu\|gpu` | `-Device …` | Dispositivo por defecto |
@@ -358,7 +359,7 @@ reverse3d config set verbosity full     # si alguna vez necesitas el detalle com
 
 ## 🔌 Sin internet (modo offline)
 
-reverse3d **funciona sin conexión**. Todo el cálculo es local (OpenCV, COLMAP, Open3D, trimesh, Blender). Lo único que se descarga es el modelo de IA de profundidad, y **el instalador lo deja descargado**.
+reverse3d **funciona sin conexión**. Todo el cálculo es local (OpenCV, COLMAP, Open3D, trimesh, Blender). Lo único que se descarga son los modelos de IA local (sujeto, recorte, profundidad y los puntos ALIKED + LightGlue), y **el instalador los deja descargados**.
 
 - **Cambio automático:** si el equipo no detecta internet, reverse3d pasa solo a modo offline. No tienes que hacer nada.
 - **Comprobar:** `reverse3d offline status` dice si hay conexión y qué funciona sin ella. `reverse3d doctor` lo incluye en su informe.
@@ -416,6 +417,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 | 🧱 **Plano → pieza** | Extrusión de contornos a sólido 3D con escala real | Shapely + trimesh |
 | 📷 **Fotogrametría** | Fotos → SfM → MVS denso → nube → malla | COLMAP + Open3D |
 | 🌊 **Profundidad con IA** | Una foto → mapa de profundidad → relieve 2.5D | Depth Anything V2 |
+| 🎨 **Texturas** | Textura fotográfica 2048² desde las propias fotos (UV, visibilidad, sin costuras) en `model.glb` | xatlas + OpenCV |
+| 🧠 **Puntos con IA** | Rescate automático de capturas difíciles con puntos y emparejamiento aprendidos | ALIKED + LightGlue (ONNX) |
 | 🛠️ **Reparación de mallas** | Limpieza, restos sueltos, agujeros, normales, Taubin, decimación, alineación OBB/PCA, escala | trimesh |
 | 📏 **Metrología** | Cotas AABB/OBB, área, volumen, centro de masa, estanqueidad | trimesh |
 | 📐 **Primitivas** | Planos, cilindros y esferas con RANSAC (radios, ejes, normales) | NumPy |

{reverse3d-0.8.1 → reverse3d-0.10.0}/README.md

@@ -151,7 +151,7 @@ Cada archivo modificado se **respalda antes** (`*.reverse3d-backup-<fecha>`). So
 | `--lite` | `-Lite` | Todo, con la IA local en la CPU (PyTorch CPU, ~250 MB en vez de ~2.5 GB) |
 | `--minimal` | `-Minimal` | Núcleo + MCP + IA local, sin herramientas externas |
 | `--no-tools` | `-NoTools` | No instalar Blender ni COLMAP |
-| *(en todos los modos)* | *(en todos los modos)* | **La IA local se instala y se descarga siempre** (clasificador, segmentación y profundidad, unos 750 MB) para que todo funcione sin internet |
+| *(en todos los modos)* | *(en todos los modos)* | **La IA local se instala y se descarga siempre** (clasificador, segmentación, profundidad y puntos con IA, unos 800 MB) para que todo funcione sin internet |
 | `--no-auto-approve` | `-NoAutoApprove` | Que los agentes pregunten antes de cada herramienta |
 | `--with recon,depth` | `-With recon,depth` | Extras a elección |
 | `--device auto\|cpu\|gpu` | `-Device …` | Dispositivo por defecto |
@@ -290,7 +290,7 @@ reverse3d config set verbosity full     # si alguna vez necesitas el detalle com
 
 ## 🔌 Sin internet (modo offline)
 
-reverse3d **funciona sin conexión**. Todo el cálculo es local (OpenCV, COLMAP, Open3D, trimesh, Blender). Lo único que se descarga es el modelo de IA de profundidad, y **el instalador lo deja descargado**.
+reverse3d **funciona sin conexión**. Todo el cálculo es local (OpenCV, COLMAP, Open3D, trimesh, Blender). Lo único que se descarga son los modelos de IA local (sujeto, recorte, profundidad y los puntos ALIKED + LightGlue), y **el instalador los deja descargados**.
 
 - **Cambio automático:** si el equipo no detecta internet, reverse3d pasa solo a modo offline. No tienes que hacer nada.
 - **Comprobar:** `reverse3d offline status` dice si hay conexión y qué funciona sin ella. `reverse3d doctor` lo incluye en su informe.
@@ -348,6 +348,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 | 🧱 **Plano → pieza** | Extrusión de contornos a sólido 3D con escala real | Shapely + trimesh |
 | 📷 **Fotogrametría** | Fotos → SfM → MVS denso → nube → malla | COLMAP + Open3D |
 | 🌊 **Profundidad con IA** | Una foto → mapa de profundidad → relieve 2.5D | Depth Anything V2 |
+| 🎨 **Texturas** | Textura fotográfica 2048² desde las propias fotos (UV, visibilidad, sin costuras) en `model.glb` | xatlas + OpenCV |
+| 🧠 **Puntos con IA** | Rescate automático de capturas difíciles con puntos y emparejamiento aprendidos | ALIKED + LightGlue (ONNX) |
 | 🛠️ **Reparación de mallas** | Limpieza, restos sueltos, agujeros, normales, Taubin, decimación, alineación OBB/PCA, escala | trimesh |
 | 📏 **Metrología** | Cotas AABB/OBB, área, volumen, centro de masa, estanqueidad | trimesh |
 | 📐 **Primitivas** | Planos, cilindros y esferas con RANSAC (radios, ejes, normales) | NumPy |

{reverse3d-0.8.1 → reverse3d-0.10.0}/pyproject.toml

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

reverse3d-0.10.0/reverse3d/_version.py

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

{reverse3d-0.8.1 → reverse3d-0.10.0}/reverse3d/offline.py

@@ -59,6 +59,55 @@ MODEL_REVISIONS: dict[str, str] = {
 }
 
 
+#: Learned feature models COLMAP runs through ONNX (ALIKED, BSD-3; LightGlue,
+#: Apache-2.0): (download URL, pinned SHA-256). Used to rescue hard photo sets.
+COLMAP_MODELS: dict[str, tuple[str, str]] = {
+    "aliked-n16rot.onnx": (
+        "https://github.com/colmap/colmap/releases/download/3.13.0/aliked-n16rot.onnx",
+        "39c423d0a6f03d39ec89d3d1d61853765c2fb6a8b8381376c703e5758778a547",
+    ),
+    "aliked-lightglue.onnx": (
+        "https://github.com/colmap/colmap/releases/download/3.13.0/aliked-lightglue.onnx",
+        "b9a5de7204648b18a8cf5dcac819f9d30de1a5961ef03756803c8b86c2dceb8d",
+    ),
+}
+
+
+def colmap_model_path(name: str) -> Path | None:
+    """Local copy of a COLMAP ONNX model, if downloaded (filesystem check only)."""
+    path = models_dir() / "colmap" / name
+    return path if path.is_file() else None
+
+
+def download_colmap_models() -> dict[str, str]:
+    """Download the learned-feature models, verifying their pinned SHA-256."""
+    import hashlib
+    import urllib.request
+
+    status: dict[str, str] = {}
+    folder = models_dir() / "colmap"
+    folder.mkdir(parents=True, exist_ok=True)
+    for name, (url, sha) in COLMAP_MODELS.items():
+        target = folder / name
+        if target.is_file() and hashlib.sha256(target.read_bytes()).hexdigest() == sha:
+            status[name] = "ready"
+            continue
+        try:
+            with urllib.request.urlopen(url, timeout=120) as response:  # noqa: S310  # nosec B310 - pinned https URL, SHA-256 checked
+                data = response.read()
+        except Exception as exc:  # network errors come in many shapes
+            status[name] = f"failed ({exc.__class__.__name__})"
+            continue
+        if hashlib.sha256(data).hexdigest() != sha:
+            status[name] = "failed (checksum mismatch)"
+            continue
+        tmp = target.with_suffix(".part")
+        tmp.write_bytes(data)
+        tmp.replace(target)
+        status[name] = "downloaded"
+    return status
+
+
 def models_dir() -> Path:
     """Folder that holds the downloaded AI models (``~/.reverse3d/models``)."""
     return home_dir() / "models"
@@ -263,6 +312,15 @@ def prepare(settings: Settings, *, include_non_commercial: bool = False) -> dict
             }
         )
 
+    if online or all(colmap_model_path(n) for n in COLMAP_MODELS):
+        for name, state in download_colmap_models().items():
+            results.append({"model": f"colmap/{name}", "status": state.split(" ")[0]})
+    else:
+        results += [
+            {"model": f"colmap/{n}", "status": "missing", "detail": "No internet connection."}
+            for n in COLMAP_MODELS
+            if not colmap_model_path(n)
+        ]
     ready = all(r["status"] in ("ready", "downloaded") for r in results)
     return {
         "ready": ready,
@@ -294,6 +352,7 @@ def offline_status(settings: Settings) -> dict[str, Any]:
         "ai_segmentation": DEFAULT_SEGMENTER,
         "ai_depth": _default_model(),
     }
+    features_ready = all(colmap_model_path(n) for n in COLMAP_MODELS)
     on_disk = {key: local_model_path(model) is not None for key, model in ai_models.items()}
     internet = None if settings.offline != "auto" else has_internet()
 
@@ -310,6 +369,7 @@ def offline_status(settings: Settings) -> dict[str, Any]:
             key: {"available": depth_installed, "offline": depth_installed and on_disk[key]}
             for key in ai_models
         },
+        "ai_features": {"available": True, "offline": features_ready},
     }
     missing = []
     names = {
@@ -321,6 +381,11 @@ def offline_status(settings: Settings) -> dict[str, Any]:
         missing.append(
             "AI depth model not downloaded yet: run `reverse3d offline prepare` while online."
         )
+    if not features_ready:
+        missing.append(
+            "AI feature models (ALIKED + LightGlue) not downloaded yet: "
+            "run `reverse3d offline prepare` while online."
+        )
     for key in ("ai_subject", "ai_segmentation"):
         if depth_installed and not on_disk[key]:
             missing.append(

{reverse3d-0.8.1 → reverse3d-0.10.0}/reverse3d/recipes.py

@@ -36,6 +36,7 @@ from reverse3d.config import Settings
 from reverse3d.errors import (
     CaptureQualityError,
     DependencyMissingError,
+    ExternalToolError,
     InputValidationError,
     ProcessingError,
     Reverse3DError,
@@ -161,7 +162,7 @@ def _clean(
             import trimesh
 
             glb = dst.with_name("model.glb")
-            trimesh.load(color_ply, process=False, force="mesh").export(glb)
+            _export_glb(trimesh.load(color_ply, process=False, force="mesh"), glb)
             run.outputs["model_color"] = str(color_ply)
             run.outputs["model_glb"] = str(glb)
         except Exception as exc:  # colour is a bonus: never fail the model for it
@@ -169,6 +170,20 @@ def _clean(
     return report.after
 
 
+def _export_glb(mesh: Any, path: Path) -> None:
+    """Write a GLB that stands up in any viewer: glTF is Y-up, our models are Z-up.
+
+    The geometry keeps its Z-up coordinates and a root node rotates it, so
+    Blender, game engines and web viewers show it upright.
+    """
+    import trimesh
+
+    scene = trimesh.Scene()
+    up = trimesh.transformations.rotation_matrix(-np.pi / 2, [1, 0, 0])
+    scene.add_geometry(mesh, node_name="model", transform=up)
+    scene.export(path)
+
+
 def _has_vertex_colors(path: Path) -> bool:
     import trimesh
 
@@ -253,6 +268,30 @@ _DEFAULT_LOOK = {
 }
 
 
+def _texture(run: _Run, model: Path, photo: Any, to_world: list[list[float]], scale: float) -> None:
+    """Bake a photo texture onto the final model: model.glb gets real detail."""
+    try:
+        import trimesh
+
+        from reverse3d.reconstruction.texture import bake_texture
+
+        mesh: Any = trimesh.load(model, process=False, force="mesh")
+        # The cleaned model is the carved hull scaled by ``scale``.
+        world = np.asarray(to_world) @ np.diag([1 / scale, 1 / scale, 1 / scale, 1.0])
+        textured = run.step(
+            "texture",
+            lambda: bake_texture(
+                mesh, Path(photo.images_dir), Path(photo.sparse_text_dir), to_world=world
+            ),
+        )
+        glb = model.with_name("model.glb")
+        _export_glb(textured, glb)
+        run.outputs["model_glb"] = str(glb)
+        run.details["texture"] = {"size": 2048, "faces": len(textured.faces)}
+    except Exception as exc:  # the texture is a bonus: never fail the model for it
+        logger.info("Texture skipped: %s", exc)
+
+
 def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
     from reverse3d.reconstruction.photogrammetry import (
         PhotogrammetryOptions,
@@ -304,7 +343,7 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
     # white or glossy surfaces. Open scenes keep classic dense reconstruction.
     silhouette = scene in ("object", "character")
 
-    def photogrammetry(classic: bool) -> PhotogrammetryResult:
+    def photogrammetry(classic: bool, features: str = "sift") -> PhotogrammetryResult:
         return run_photogrammetry(
             src,
             run.out / "reconstruction",
@@ -317,13 +356,28 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
                 build_mesh=classic,
                 poisson_depth=preset.poisson_depth,
                 density_quantile=preset.density_quantile,
+                features=features,  # type: ignore[arg-type]
             ),
-            overwrite=opt.overwrite or not classic,
+            overwrite=opt.overwrite or not classic or features != "sift",
         )
 
-    photo = run.step("photogrammetry", lambda: photogrammetry(classic=not silhouette))
+    try:
+        photo = run.step("photogrammetry", lambda: photogrammetry(classic=not silhouette))
+    except ProcessingError as exc:
+        # Rescue for hard sets: learned AI features (ALIKED + LightGlue) place
+        # photos that SIFT cannot. Slower (CPU), so only when SIFT fell short.
+        logger.info("SIFT could not place the photos (%s); retrying with AI features", exc.message)
+        try:
+            photo = run.step(
+                "photogrammetry_ai",
+                lambda: photogrammetry(classic=not silhouette, features="aliked"),
+            )
+        except (ProcessingError, DependencyMissingError, ExternalToolError):
+            raise exc from None
+        run.warnings.append("Photos placed with AI features (ALIKED + LightGlue).")
     mesh_path: str | None = photo.mesh_path
     upright = False
+    hull_world: list[list[float]] | None = None
     if silhouette:
         from reverse3d.reconstruction.silhouette import visual_hull
         from reverse3d.vision.segmenter import ObjectSegmenter
@@ -340,6 +394,18 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
                 )
                 return None
 
+        def load_depth() -> Callable[[np.ndarray], np.ndarray] | None:
+            # AI depth reveals concavities and holes (cup insides, handle loops).
+            from reverse3d.reconstruction.depth_estimation import predict_depth
+
+            device = torch_device(run.settings)
+            try:
+                predict_depth(np.zeros((32, 32, 3), np.uint8), device=device, settings=run.settings)
+            except Reverse3DError as exc:
+                logger.info("AI depth unavailable (%s); concavities stay filled", exc.message)
+                return None
+            return lambda rgb: predict_depth(rgb, device=device, settings=run.settings)
+
         try:
             hull = run.step(
                 "silhouette",
@@ -348,6 +414,7 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
                     Path(photo.sparse_text_dir or ""),
                     run.out / "reconstruction" / "object_hull.ply",
                     segmenter=load_segmenter,
+                    depth=load_depth,
                 ),
             )
         except ProcessingError as exc:
@@ -361,6 +428,7 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
             run.details["silhouette"] = hull.to_dict()
             mesh_path = hull.mesh_path
             upright = True
+            hull_world = hull.to_world
     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.
@@ -374,14 +442,29 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
             hint='Install the meshing extra: pip install "reverse3d[recon]" (Python ≤ 3.12).',
         )
     cloud = photo.dense_points_path or photo.sparse_points_path
-    if not upright and cloud:
+    if not upright:
+        # Dense scenes: colour from the photos themselves (sharp, independent of how
+        # dense the cloud is); the cloud's colours are the fallback.
+        colored_path = run.out / "reconstruction" / "mesh_color.ply"
+        colored: Path | None = None
         try:
-            colored = _color_from_cloud(
-                Path(mesh_path), Path(cloud), run.out / "reconstruction" / "mesh_color.ply"
-            )
-            mesh_path = str(colored) if colored else mesh_path
+            from reverse3d.reconstruction.silhouette import colorize_from_photos
+
+            if photo.images_dir and photo.sparse_text_dir:
+                colored = colorize_from_photos(
+                    Path(mesh_path),
+                    Path(photo.images_dir),
+                    Path(photo.sparse_text_dir),
+                    colored_path,
+                )
         except Exception as exc:  # colour is a bonus
-            logger.info("Colouring from the point cloud skipped: %s", exc)
+            logger.info("Colouring from the photos skipped: %s", exc)
+        if colored is None and cloud:
+            try:
+                colored = _color_from_cloud(Path(mesh_path), Path(cloud), colored_path)
+            except Exception as exc:  # colour is a bonus
+                logger.info("Colouring from the point cloud skipped: %s", exc)
+        mesh_path = str(colored) if colored else mesh_path
     model = run.out / "model.stl"
     _clean(
         run,
@@ -394,6 +477,8 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
         keep_largest=preset.keep_largest,
         repair=opt.repair,
     )
+    if upright and hull_world is not None:
+        _texture(run, model, photo, hull_world, opt.scale)
     return _measure(run, model)
 
 
@@ -582,7 +667,12 @@ def run_recipe(
         source = prepare_heic_input(source, out)  # iPhone HEIC photos -> JPEG
     stats = _RECIPES[recipe](run, source, opt)
     if opt.render:
-        _render(run, Path(run.outputs.get("model_color") or run.outputs["model"]), opt.overwrite)
+        textured = run.details.get("texture") and run.outputs.get("model_glb")
+        _render(
+            run,
+            Path(textured or run.outputs.get("model_color") or run.outputs["model"]),
+            opt.overwrite,
+        )
 
     summary: dict[str, Any] = {
         "recipe": recipe,

{reverse3d-0.8.1 → reverse3d-0.10.0}/reverse3d/reconstruction/photogrammetry.py

@@ -94,6 +94,9 @@ class PhotogrammetryOptions:
     poisson_depth: int | None = None
     #: share of the least supported surface trimmed after Poisson.
     density_quantile: float = 0.02
+    #: "sift" (fast, GPU) or "aliked": learned ALIKED features + LightGlue matching,
+    #: which places photos of hard sets SIFT cannot (CPU, much slower).
+    features: Literal["sift", "aliked"] = "sift"
 
     def validate(self) -> None:
         if self.quality not in _PRESETS:
@@ -297,13 +300,36 @@ class ColmapPipeline:
             "--ImageReader.single_camera",
             "1" if options.single_camera else "0",
         ]
+        learned = options.features == "aliked"
+        if learned:
+            from reverse3d.offline import colmap_model_path, download_colmap_models
+
+            if not colmap_model_path("aliked-n16rot.onnx"):
+                download_colmap_models()
+            aliked = colmap_model_path("aliked-n16rot.onnx")
+            if aliked is None:
+                raise DependencyMissingError(
+                    "The AI feature model (ALIKED) is not on this computer.",
+                    hint="Connect to the internet once and run: reverse3d offline prepare",
+                )
+            # ONNX on the CPU: the CUDA runtime it needs is not bundled with COLMAP.
+            args += [
+                "--FeatureExtraction.type",
+                "ALIKED_N16ROT",
+                "--FeatureExtraction.use_gpu",
+                "0",
+                "--AlikedExtraction.n16rot_model_path",
+                str(aliked),
+            ]
         self._stage(
             result,
             "feature_extractor",
             self._with_options(
                 "feature_extractor",
                 args,
-                {
+                {}
+                if learned
+                else {
                     ("FeatureExtraction.use_gpu", "SiftExtraction.use_gpu"): gpu,
                     ("FeatureExtraction.max_image_size", "SiftExtraction.max_image_size"): str(
                         preset["max_image_size"]
@@ -324,8 +350,19 @@ class ColmapPipeline:
             matcher = "exhaustive" if len(images) <= _EXHAUSTIVE_LIMIT else "sequential"
         command = f"{matcher}_matcher"
         extra: dict[tuple[str, ...], str] = {
-            ("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): gpu
+            ("FeatureMatching.use_gpu", "SiftMatching.use_gpu"): "0" if learned else gpu
         }
+        if learned:
+            from reverse3d.offline import colmap_model_path
+
+            glue = colmap_model_path("aliked-lightglue.onnx")
+            if glue is None:
+                raise DependencyMissingError(
+                    "The AI matching model (LightGlue) is not on this computer.",
+                    hint="Connect to the internet once and run: reverse3d offline prepare",
+                )
+            extra[("FeatureMatching.type",)] = "ALIKED_LIGHTGLUE"
+            extra[("AlikedMatching.lightglue_model_path",)] = str(glue)
         if matcher == "spatial":
             extra[("SpatialMatching.is_gps",)] = "1"
         try:

{reverse3d-0.8.1 → reverse3d-0.10.0}/reverse3d/reconstruction/silhouette.py

@@ -69,6 +69,9 @@ class HullResult:
     faces: int
     support_plane: bool
     ai_segmentation: bool = False
+    depth_carved_voxels: int = 0
+    #: 4x4 matrix from the model's coordinates back to the COLMAP world (textures).
+    to_world: list[list[float]] | None = None
 
     def to_dict(self) -> dict[str, object]:
         return asdict(self)
@@ -250,6 +253,102 @@ def _vertex_colors(
     return colors
 
 
+def _fit_inverse_depth(disparity: np.ndarray, depth: np.ndarray) -> tuple[float, float] | None:
+    """Robust fit 1/depth ≈ s·disparity + t (relative AI disparity → metric-like depth)."""
+    inv = 1.0 / depth
+    keep = np.ones(len(inv), bool)
+    for _ in range(3):
+        if keep.sum() < 50:
+            return None
+        a = np.column_stack([disparity[keep], np.ones(int(keep.sum()))])
+        (s, t), *_ = np.linalg.lstsq(a, inv[keep], rcond=None)
+        residual = np.abs(s * disparity + t - inv)
+        mad = float(np.median(residual[keep])) or 1e-9
+        keep = residual < 3 * 1.4826 * mad
+    return (float(s), float(t)) if s > 0 else None
+
+
+def _depth_carve(
+    keep: np.ndarray,
+    grid: np.ndarray,
+    views: list[_View],
+    images: list[tuple[np.ndarray, float]],
+    projections: list[tuple[np.ndarray, np.ndarray, np.ndarray]],
+    masks: list[np.ndarray],
+    estimator: Callable[[np.ndarray], np.ndarray],
+    *,
+    tolerance: float = 0.05,
+    min_votes: int = 3,
+    min_share: float = 0.5,
+) -> np.ndarray:
+    """Empty the voxels that sit clearly in front of the surface the AI depth sees,
+    in at least ``min_votes`` photos *and* in most (``min_share``) of the photos
+    that actually see them. A photo where the voxel lies on the surface votes
+    solid; one where it is hidden behind the surface abstains. A few wrong depth
+    maps therefore cannot carve real material.
+
+    The relative AI depth is calibrated per photo against the carved hull itself
+    (a robust fit on the object's pixels), so only real disagreements carve.
+    """
+    votes = np.zeros(len(grid), np.int32)
+    seen = np.zeros(len(grid), np.int32)
+    for (small, _), view, (u, v, inside), mask in zip(
+        images, views, projections, masks, strict=True
+    ):
+        sel = keep & inside
+        if sel.sum() < 100:
+            continue
+        h, w = small.shape[:2]
+        z = (grid[sel] @ view.rotation.T + view.translation)[:, 2]
+        us, vs = u[sel], v[sel]
+        # Depth of the hull's visible surface per pixel (z-buffer of kept voxels).
+        hull_depth = np.full((h, w), np.inf)
+        np.minimum.at(hull_depth, (vs, us), z)
+        object_px = (mask > 0) & np.isfinite(hull_depth)
+        if object_px.sum() < 100:
+            continue
+        disparity = np.asarray(estimator(cv2.cvtColor(small, cv2.COLOR_BGR2RGB)), np.float64)
+        if disparity.shape != (h, w):
+            disparity = cv2.resize(disparity, (w, h), interpolation=cv2.INTER_LINEAR)
+        fit = _fit_inverse_depth(disparity[object_px], hull_depth[object_px])
+        if fit is None:
+            continue
+        s, t = fit
+        with np.errstate(divide="ignore", invalid="ignore"):
+            observed = 1.0 / np.maximum(s * disparity + t, 1e-9)
+        # A voxel strictly in front of the observed surface, on an object pixel, is air.
+        in_mask = mask[vs, us] > 0
+        front = z < observed[vs, us] * (1.0 - tolerance)
+        on_surface = np.abs(z - observed[vs, us]) <= tolerance * observed[vs, us]
+        idx = np.flatnonzero(sel)
+        seen[idx[in_mask & (front | on_surface)]] += 1  # hidden voxels abstain
+        votes[idx[in_mask & front]] += 1
+    air = (votes >= min_votes) & (votes >= min_share * np.maximum(seen, 1))
+    return keep & ~air
+
+
+def colorize_from_photos(
+    mesh_path: Path, image_dir: Path, model_text_dir: Path, output_path: Path
+) -> Path:
+    """Paint any mesh in COLMAP coordinates with the photos that see it (dense scenes)."""
+    views, _ = read_colmap_text(model_text_dir)
+    images: list[tuple[np.ndarray, float]] = []
+    for view in views:
+        bgr = cv2.imread(str(image_dir / view.name))
+        if bgr is None:
+            raise ProcessingError(f"Could not read {view.name} for colouring.")
+        h, w = bgr.shape[:2]
+        scale = 1280 / max(h, w)
+        size = (round(w * scale), round(h * scale))
+        images.append((cv2.resize(bgr, size, interpolation=cv2.INTER_AREA), scale))
+    mesh: trimesh.Trimesh = trimesh.load(mesh_path, process=False, force="mesh")  # type: ignore[assignment]
+    mesh.visual = trimesh.visual.ColorVisuals(
+        mesh, vertex_colors=_vertex_colors(mesh, views, images)
+    )
+    mesh.export(output_path)
+    return output_path
+
+
 def visual_hull(
     image_dir: Path,
     model_text_dir: Path,
@@ -258,6 +357,7 @@ def visual_hull(
     resolution: int = 176,
     refinements: int = 3,
     segmenter: Callable[[], ObjectSegmenter | None] | None = None,
+    depth: Callable[[], Callable[[np.ndarray], np.ndarray] | None] | None = None,
 ) -> HullResult:
     """Carve the object seen by every photo; writes a watertight, upright mesh.
 
@@ -385,6 +485,16 @@ def visual_hull(
         masks = refined
         keep = carve(masks, 1)
 
+    # Concavities and through-holes (a handle loop, the inside of a cup) never
+    # show in a silhouette: the AI depth of each photo reveals them.
+    estimator = depth() if depth is not None else None
+    carved_by_depth = 0
+    if estimator is not None:
+        before = int(keep.sum())
+        keep = _depth_carve(keep, grid, views, images, projections, masks, estimator)
+        carved_by_depth = before - int(keep.sum())
+        logger.info("AI depth carved %d voxel(s) of concavities", carved_by_depth)
+
     volume = keep.reshape(n, n, n).astype(np.float32)
     plane = _support_plane(points, center, radius, cameras)
     if plane is not None:
@@ -432,11 +542,20 @@ def visual_hull(
     transform = np.eye(4)
     transform[:3, :3] = basis
     mesh.apply_transform(transform)
-    mesh.apply_translation([-mesh.centroid[0], -mesh.centroid[1], -mesh.bounds[0][2]])
+    shift = np.array([-mesh.centroid[0], -mesh.centroid[1], -mesh.bounds[0][2]])
+    mesh.apply_translation(shift)
+    world_to_model = trimesh.transformations.translation_matrix(shift) @ transform
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
     mesh.export(output_path)
     logger.info("Silhouette model: %d views, %d faces", len(views), len(mesh.faces))
     return HullResult(
-        str(output_path), len(views), voxels, len(mesh.faces), plane is not None, ai is not None
+        str(output_path),
+        len(views),
+        voxels,
+        len(mesh.faces),
+        plane is not None,
+        ai is not None,
+        carved_by_depth,
+        np.linalg.inv(world_to_model).tolist(),
     )