reverse3d 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.6.0
+Version: 0.7.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>

reverse3d-0.7.0/reverse3d/_version.py

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

{reverse3d-0.6.0 → reverse3d-0.7.0}/reverse3d/offline.py

@@ -54,6 +54,7 @@ MODEL_REVISIONS: dict[str, str] = {
     "depth-anything/Depth-Anything-V2-Small-hf": "5426e4f0f36572d16453bbda7a8389317b1bef99",
     "depth-anything/Depth-Anything-V2-Base-hf": "b1958afc87fb45a9e3746cb387596094de553ed8",
     "depth-anything/Depth-Anything-V2-Large-hf": "7581137eff8d4e94f6e796d3baea0e9fa79b22d2",
+    "facebook/sam-vit-base": "70c1a07f894ebb5b307fd9eaaee97b9dfc16068f",
 }
 
 
@@ -100,8 +101,9 @@ def is_offline(settings: Settings) -> bool:
 
 def _allowed_models() -> dict[str, tuple[str, str]]:
     from reverse3d.reconstruction.depth_estimation import ALLOWED_MODELS
+    from reverse3d.vision.segmenter import ALLOWED_SEGMENTERS
 
-    return dict(ALLOWED_MODELS)
+    return {**ALLOWED_MODELS, **ALLOWED_SEGMENTERS}
 
 
 def _default_model() -> str:
@@ -177,7 +179,7 @@ def resolve_model(model_id: str, settings: Settings) -> Path:
         return local
     if is_offline(settings):
         raise DependencyMissingError(
-            "The AI depth model is not on this computer and there is no internet connection.",
+            "The AI model is not on this computer and there is no internet connection.",
             hint="Connect to the internet once and run: reverse3d offline prepare",
         )
     try:
@@ -190,7 +192,7 @@ def resolve_model(model_id: str, settings: Settings) -> Path:
     except Exception as exc:  # network errors come in many shapes; report them plainly
         has_internet(refresh=True)
         raise DependencyMissingError(
-            f"Could not download the AI depth model ({exc.__class__.__name__}).",
+            f"Could not download the AI model ({exc.__class__.__name__}).",
             hint="Check your connection and run: reverse3d offline prepare",
         ) from exc
 
@@ -201,7 +203,10 @@ def prepare(settings: Settings, *, include_non_commercial: bool = False) -> dict
     Safe to run any time: models already on disk are skipped. It never raises
     for a missing optional stack; that is reported in the result instead.
     """
-    models = [_default_model()]
+    from reverse3d.vision.segmenter import DEFAULT_SEGMENTER
+
+    # Depth (reliefs) and segmentation (object silhouettes), both commercial-friendly.
+    models = [_default_model(), DEFAULT_SEGMENTER]
     if include_non_commercial:
         models += [m for m in _allowed_models() if m not in models]
 

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

@@ -36,6 +36,7 @@ from reverse3d.errors import (
     DependencyMissingError,
     InputValidationError,
     ProcessingError,
+    Reverse3DError,
 )
 from reverse3d.hardware import torch_device, wants_gpu
 from reverse3d.profiles import profile_values
@@ -262,6 +263,19 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
     upright = False
     if silhouette:
         from reverse3d.reconstruction.silhouette import visual_hull
+        from reverse3d.vision.segmenter import ObjectSegmenter
+
+        def load_segmenter() -> ObjectSegmenter | None:
+            # The AI segmenter keeps dark caps, handles and thin parts; without it
+            # (no AI extra, or offline before the first download) GrabCut is used.
+            try:
+                return ObjectSegmenter(run.settings, device=torch_device(run.settings))
+            except Reverse3DError as exc:
+                logger.info("AI segmentation unavailable (%s); using GrabCut", exc.message)
+                run.warnings.append(
+                    "AI segmentation unavailable: thin or dark parts may be missing."
+                )
+                return None
 
         try:
             hull = run.step(
@@ -270,6 +284,7 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
                     Path(photo.images_dir or ""),
                     Path(photo.sparse_text_dir or ""),
                     run.out / "reconstruction" / "object_hull.ply",
+                    segmenter=load_segmenter,
                 ),
             )
         except ProcessingError as exc:

{reverse3d-0.6.0 → reverse3d-0.7.0}/reverse3d/reconstruction/silhouette.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 import logging
 from dataclasses import asdict, dataclass
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import cv2
 import numpy as np
@@ -30,6 +31,11 @@ import trimesh
 
 from reverse3d.errors import DependencyMissingError, ProcessingError
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from reverse3d.vision.segmenter import ObjectSegmenter
+
 logger = logging.getLogger(__name__)
 
 _WORK_SIDE = 640
@@ -62,6 +68,7 @@ class HullResult:
     voxels: int
     faces: int
     support_plane: bool
+    ai_segmentation: bool = False
 
     def to_dict(self) -> dict[str, object]:
         return asdict(self)
@@ -191,6 +198,7 @@ def visual_hull(
     *,
     resolution: int = 176,
     refinements: int = 3,
+    segmenter: Callable[[], ObjectSegmenter | None] | None = None,
 ) -> HullResult:
     """Carve the object seen by every photo; writes a watertight, upright mesh.
 
@@ -269,6 +277,36 @@ def visual_hull(
         return (seen >= 3) & (votes >= seen - tolerance)
 
     keep = carve(masks, 2)
+    # The AI segmenter is only loaded (or downloaded) once the photos proved usable.
+    ai = segmenter() if segmenter is not None else None
+    if ai is not None:
+        # AI segmentation: a box around the projected hull (taller upwards, where caps
+        # and handles get lost) and a point on it. Two rounds, each from the new hull.
+        states = [ai.embed(cv2.cvtColor(small, cv2.COLOR_BGR2RGB)) for small, _ in images]
+        for _ in range(2):
+            ai_masks: list[np.ndarray] = []
+            for state, (small, _), (u, v, inside), old in zip(
+                states, images, projections, masks, strict=True
+            ):
+                sel = keep & inside
+                if not sel.any():
+                    ai_masks.append(old)
+                    continue
+                us, vs = u[sel], v[sel]
+                x0, x1 = int(us.min()), int(us.max())
+                y0, y1 = int(vs.min()), int(vs.max())
+                pad_x, pad_y = 0.15 * (x1 - x0 + 1), 0.15 * (y1 - y0 + 1)
+                box = (
+                    max(0, int(x0 - pad_x)),
+                    max(0, int(y0 - 2.5 * pad_y)),
+                    min(small.shape[1] - 1, int(x1 + pad_x)),
+                    min(small.shape[0] - 1, int(y1 + pad_y)),
+                )
+                point = (int(np.median(us)), int(np.median(vs)))
+                ai_masks.append(ai.segment(state, box, point))
+            masks = ai_masks
+            keep = carve(masks, 1)
+        refinements = 0
     for _ in range(refinements):
         refined: list[np.ndarray] = []
         for (small, _), (u, v, inside), old in zip(images, projections, masks, strict=True):
@@ -333,4 +371,6 @@ def visual_hull(
     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)
+    return HullResult(
+        str(output_path), len(views), voxels, len(mesh.faces), plane is not None, ai is not None
+    )

reverse3d-0.7.0/reverse3d/vision/segmenter.py

@@ -0,0 +1,136 @@
+"""AI object segmentation (Segment Anything) for silhouette carving.
+
+GrabCut only compares colours, so a dark cap or handle in front of a dark
+background is cut off. Segment Anything (Meta, Apache-2.0) understands what
+"the object" is: given a box and a point on it, it returns the whole object,
+cap and handle included.
+
+The model is allowlisted, pinned to an exact commit and loaded from
+safetensors only (see :mod:`reverse3d.offline`); after the first download it
+works without internet. Everything degrades gracefully: without the AI extra
+or the model, callers fall back to GrabCut.
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any
+
+import numpy as np
+
+from reverse3d.config import Settings
+from reverse3d.errors import DependencyMissingError
+
+logger = logging.getLogger(__name__)
+
+#: Allowlisted segmentation models: id -> (kind, license).
+ALLOWED_SEGMENTERS: dict[str, tuple[str, str]] = {
+    "facebook/sam-vit-base": ("sam", "Apache-2.0"),
+}
+DEFAULT_SEGMENTER = "facebook/sam-vit-base"
+
+
+def segmenter_available() -> bool:
+    """True when the AI stack (torch + transformers) is installed."""
+    try:
+        import torch  # noqa: F401
+        import transformers  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+@lru_cache(maxsize=2)
+def _load(model_id: str, device: str, model_dir: str) -> tuple[Any, Any]:
+    from transformers import SamModel, SamProcessor
+
+    try:  # keep CLI/agent output clean: no loading progress bars
+        from transformers.utils import logging as hf_logging
+
+        hf_logging.disable_progress_bar()
+        hf_logging.set_verbosity_error()
+    except ImportError:  # pragma: no cover - very old transformers
+        pass
+    # model_dir is the local snapshot of a commit-pinned, allowlisted model
+    # (reverse3d.offline.resolve_model): nothing is fetched here.
+    model: Any = SamModel.from_pretrained(  # nosec B615
+        model_dir, local_files_only=True, use_safetensors=True, trust_remote_code=False
+    )
+    processor = SamProcessor.from_pretrained(model_dir, local_files_only=True)  # nosec B615
+    model.to(device).eval()
+    logger.info("Loaded %s on %s", model_id, device)
+    return model, processor
+
+
+class ObjectSegmenter:
+    """Segments the object inside a box (plus a point on it) in RGB images.
+
+    Raises:
+        DependencyMissingError: the AI extra or the model is not available.
+    """
+
+    def __init__(self, settings: Settings, device: str = "cpu", model_id: str = DEFAULT_SEGMENTER):
+        if not segmenter_available():
+            raise DependencyMissingError(
+                "The AI segmentation stack is not installed.",
+                hint='pip install "reverse3d[depth]"',
+            )
+        from reverse3d.offline import force_offline_env, is_offline, resolve_model
+
+        self.device = device
+        model_dir = resolve_model(model_id, settings)
+        if is_offline(settings):
+            force_offline_env()
+        self.model, self.processor = _load(model_id, device, str(model_dir))
+
+    def embed(self, rgb: np.ndarray) -> dict[str, Any]:
+        """Run the heavy image encoder once; reuse the result for several prompts."""
+        import torch
+
+        inputs = self.processor(rgb, return_tensors="pt").to(self.device)
+        with torch.no_grad():
+            embeddings = self.model.get_image_embeddings(inputs["pixel_values"])
+        return {
+            "rgb": rgb,
+            "embeddings": embeddings,
+            "original_sizes": inputs["original_sizes"],
+            "reshaped_input_sizes": inputs["reshaped_input_sizes"],
+        }
+
+    def segment(
+        self,
+        image: np.ndarray | dict[str, Any],
+        box: tuple[int, int, int, int],
+        point: tuple[int, int],
+    ) -> np.ndarray:
+        """Object mask (uint8, 255 = object) for a box ``(x0, y0, x1, y1)`` and a point.
+
+        ``image`` is an RGB array or the result of :meth:`embed` (much faster).
+        """
+        import torch
+
+        state = image if isinstance(image, dict) else self.embed(image)
+        prompts = self.processor(
+            state["rgb"],
+            input_boxes=[[[float(v) for v in box]]],
+            input_points=[[[[float(point[0]), float(point[1])]]]],
+            input_labels=[[[1]]],
+            return_tensors="pt",
+        ).to(self.device)
+        with torch.no_grad():
+            outputs = self.model(
+                image_embeddings=state["embeddings"],
+                input_boxes=prompts["input_boxes"],
+                input_points=prompts["input_points"],
+                input_labels=prompts["input_labels"],
+                multimask_output=True,
+            )
+        masks = self.processor.image_processor.post_process_masks(
+            outputs.pred_masks.cpu(),
+            state["original_sizes"].cpu(),
+            state["reshaped_input_sizes"].cpu(),
+        )[0][0]
+        scores = outputs.iou_scores.cpu()[0, 0]
+        best = int(torch.argmax(scores))
+        return np.where(masks[best].numpy(), 255, 0).astype(np.uint8)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.6.0
+Version: 0.7.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>

{reverse3d-0.6.0 → reverse3d-0.7.0}/reverse3d.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ reverse3d/reverse_eng/parametric.py
 reverse3d/vision/__init__.py
 reverse3d/vision/feature_matcher.py
 reverse3d/vision/mask_extractor.py
+reverse3d/vision/segmenter.py
 tests/test_agent_tools.py
 tests/test_authorship.py
 tests/test_automation.py

{reverse3d-0.6.0 → reverse3d-0.7.0}/tests/test_offline_autopilot.py

@@ -125,8 +125,9 @@ class TestModels:
 
     def test_every_allowlisted_model_is_pinned(self, tmp_path: Path) -> None:
         from reverse3d.reconstruction.depth_estimation import ALLOWED_MODELS
+        from reverse3d.vision.segmenter import ALLOWED_SEGMENTERS
 
-        assert set(ALLOWED_MODELS) == set(offline.MODEL_REVISIONS)
+        assert set(ALLOWED_MODELS) | set(ALLOWED_SEGMENTERS) == set(offline.MODEL_REVISIONS)
         assert all(len(sha) == 40 for sha in offline.MODEL_REVISIONS.values())
         other = tmp_path / "_r3d_home" / "models" / ("models--" + SMALL.replace("/", "--"))
         (other / "snapshots" / "unreviewed").mkdir(parents=True)

{reverse3d-0.6.0 → reverse3d-0.7.0}/tests/test_silhouette.py

@@ -104,3 +104,55 @@ def test_too_few_photos(tmp_path: Path) -> None:
     (text / "images.txt").write_text("\n\n".join(rows[:5]) + "\n\n")
     with pytest.raises(ProcessingError, match="at least"):
         visual_hull(images, text, tmp_path / "hull.ply", resolution=48, refinements=0)
+
+
+class _FakeSegmenter:
+    """Stands in for Segment Anything: the object is the bright part inside the box."""
+
+    def __init__(self) -> None:
+        self.calls = 0
+
+    def embed(self, rgb: np.ndarray) -> dict[str, np.ndarray]:
+        return {"rgb": rgb}
+
+    def segment(
+        self, state: dict[str, np.ndarray], box: tuple[int, int, int, int], point: tuple[int, int]
+    ) -> np.ndarray:
+        self.calls += 1
+        gray = state["rgb"].mean(axis=2)
+        mask = np.zeros(gray.shape, np.uint8)
+        x0, y0, x1, y1 = box
+        mask[y0 : y1 + 1, x0 : x1 + 1] = np.where(gray[y0 : y1 + 1, x0 : x1 + 1] > 200, 255, 0)
+        return mask
+
+
+def test_ai_segmenter_is_loaded_lazily_and_used(tmp_path: Path) -> None:
+    images, text = _scene(tmp_path)
+    fake = _FakeSegmenter()
+    loads: list[int] = []
+
+    def factory() -> _FakeSegmenter:
+        loads.append(1)
+        return fake
+
+    result = visual_hull(
+        images,
+        text,
+        tmp_path / "hull.ply",
+        resolution=64,
+        refinements=1,
+        segmenter=factory,  # type: ignore[arg-type]
+    )
+    assert loads == [1] and fake.calls == 2 * 30  # two AI rounds over the 30 photos
+    assert result.ai_segmentation
+    mesh = trimesh.load(result.mesh_path)
+    width = (mesh.extents[0] + mesh.extents[1]) / 2
+    assert mesh.is_watertight and 1.3 < mesh.extents[2] / width < 2.2
+
+
+def test_without_ai_segmenter_grabcut_is_used(tmp_path: Path) -> None:
+    images, text = _scene(tmp_path)
+    result = visual_hull(
+        images, text, tmp_path / "hull.ply", resolution=48, refinements=1, segmenter=lambda: None
+    )
+    assert not result.ai_segmentation

reverse3d-0.6.0/reverse3d/_version.py

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