reverse3d 0.11.3__tar.gz → 0.13.0__tar.gz

{reverse3d-0.11.3/reverse3d.egg-info → reverse3d-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.11.3
+Version: 0.13.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>
@@ -421,6 +421,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 |---|---|---|
 | Recortes perfectos | 0,943 | 0,941 |
 | 15 % de recortes defectuosos | 0,000 (pierde el objeto) | **0,921** |
+| Concavidad invisible a las siluetas (error en la ranura) | 0,154 | **0,091** (refinamiento por fotos, Core 0.3) |
+| Mapa de confianza y consejos de captura | — | ✅ Core 0.4 (`model_quality.glb`) |
 
 *(Coincidencia volumétrica, IoU: 1 = idéntico.)*
 

{reverse3d-0.11.3 → reverse3d-0.13.0}/README.md

@@ -352,6 +352,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 |---|---|---|
 | Recortes perfectos | 0,943 | 0,941 |
 | 15 % de recortes defectuosos | 0,000 (pierde el objeto) | **0,921** |
+| Concavidad invisible a las siluetas (error en la ranura) | 0,154 | **0,091** (refinamiento por fotos, Core 0.3) |
+| Mapa de confianza y consejos de captura | — | ✅ Core 0.4 (`model_quality.glb`) |
 
 *(Coincidencia volumétrica, IoU: 1 = idéntico.)*
 

reverse3d-0.13.0/reverse3d/_version.py

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

{reverse3d-0.11.3 → reverse3d-0.13.0}/reverse3d/recipes.py

@@ -177,6 +177,42 @@ _CAMERA_FEATURES = 4096
 _OBJECT_EXHAUSTIVE_LIMIT = 400
 
 
+_WHERE = {
+    "top": "from above",
+    "around": "around the object at mid height",
+    "low": "from a low angle",
+}
+
+
+def _quality_outputs(run: _Run, hull: Any) -> None:
+    """Confidence map (model_quality.glb) and capture advice from reverse3d-core."""
+    quality = getattr(hull, "quality", None) or {}
+    if hull.quality_path:
+        try:
+            import trimesh
+
+            glb = run.out / "model_quality.glb"
+            _export_glb(trimesh.load(hull.quality_path, process=False, force="mesh"), glb)
+            run.outputs["model_quality"] = str(glb)
+        except Exception as exc:  # the map is a bonus: never fail the model for it
+            logger.info("Confidence map skipped: %s", exc)
+    covered = quality.get("covered")
+    if covered is None or covered >= _WELL_COVERED:
+        return
+    for advice in quality.get("advice", [])[:2]:
+        where = _WHERE.get(str(advice.get("elevation")), "around the object")
+        photo = Path(str(advice.get("near_photo", ""))).stem
+        share = round(100 * float(advice.get("share", 0.0)))
+        run.warnings.append(
+            f"{share}% of the model is weakly supported by the photos: take more photos "
+            f"{where}, near where you took {photo}."
+        )
+
+
+# Share of the surface the photos must support well for no capture advice.
+_WELL_COVERED = 0.95
+
+
 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.
 
@@ -442,6 +478,7 @@ def _photos_to_model(run: _Run, src: Path, opt: RecipeOptions) -> MeshStats:
             mesh_path = photo.mesh_path
         else:
             run.details["silhouette"] = hull.to_dict()
+            _quality_outputs(run, hull)
             if hull.unreliable:
                 names = ", ".join(Path(n).stem for n in hull.unreliable[:5])
                 more = "…" if len(hull.unreliable) > 5 else ""

{reverse3d-0.11.3 → reverse3d-0.13.0}/reverse3d/reconstruction/silhouette.py

@@ -92,6 +92,12 @@ class HullResult:
     engine: str = "reverse3d"
     #: photos reverse3d-core judged inconsistent with the rest (moved object, bad cut-out)
     unreliable: list[str] = field(default_factory=list)
+    #: vertices reverse3d-core moved by photo consistency (0 without it)
+    refined_vertices: int = 0
+    #: reverse3d-core quality agent: share of the surface well supported and advice
+    quality: dict[str, object] = field(default_factory=dict)
+    #: confidence map (red -> green vertex colours), same coordinates as the model
+    quality_path: str | None = None
 
     def to_dict(self) -> dict[str, object]:
         return asdict(self)
@@ -367,6 +373,12 @@ def _complete_base(
     return out.reshape(volume.shape)
 
 
+def _outward_share(mesh: trimesh.Trimesh) -> float:
+    """Share of vertex normals pointing away from the centroid (about 1 when outward)."""
+    rel = np.asarray(mesh.vertices) - np.asarray(mesh.centroid)
+    return float(np.mean((rel * np.asarray(mesh.vertex_normals)).sum(axis=1) > 0))
+
+
 def _coarse_grabcut(image: np.ndarray, rect: tuple[int, int, int, int]) -> np.ndarray:
     """GrabCut at half resolution (4x fewer pixels): enough for a first silhouette."""
     h, w = image.shape[:2]
@@ -963,6 +975,22 @@ def visual_hull(
     mesh = trimesh.Trimesh(verts, faces, process=True)
     trimesh.smoothing.filter_taubin(mesh, lamb=0.5, nu=-0.53, iterations=15)
     mesh.fix_normals()
+    # fix_normals cannot tell outside from inside on a mesh that is not perfectly
+    # closed: make the normals point away from the object's centre.
+    if _outward_share(mesh) < 0.5:
+        mesh.invert()
+    refined_vertices = 0
+    refine_mesh = getattr(core, "refine_mesh", None) if core_cameras is not None else None
+    if refine_mesh is not None:
+        # reverse3d-core >= 0.3: photo consistency carves what silhouettes cannot see.
+        try:
+            mesh, stats = refine_mesh(
+                mesh, core_cameras, [small for small, _ in images], 0.5 * (2 * radius / (n - 1))
+            )
+            refined_vertices = int(stats.get("moved", 0))
+            logger.info("Photo consistency refined %d vertices", refined_vertices)
+        except Exception as exc:  # never fail a job because of the optional engine
+            logger.warning("reverse3d-core refinement failed (%s); keeping the hull", exc)
     # Real colours from the photos (kept by PLY export; the model gets them as GLB).
     mesh.visual = trimesh.visual.ColorVisuals(
         mesh, vertex_colors=_vertex_colors(mesh, views, images, masks)
@@ -971,6 +999,17 @@ def visual_hull(
     # Stand it upright: +Z along the table normal (or the mean camera "up").
     up = plane[0] if plane is not None else np.mean(cameras - center, axis=0)
     up = up / np.linalg.norm(up)
+    quality: dict[str, object] = {}
+    quality_colors: np.ndarray | None = None
+    assess_quality = getattr(core, "assess_quality", None) if core_cameras is not None else None
+    if assess_quality is not None:
+        # reverse3d-core >= 0.4: how well the photos support each part, and advice.
+        try:
+            report = assess_quality(mesh, core_cameras, up, 0.5 * (2 * radius / (n - 1)))
+            quality_colors = np.asarray(report["colors"])
+            quality = {"covered": float(report["covered"]), "advice": list(report["advice"])}
+        except Exception as exc:  # never fail a job because of the optional engine
+            logger.warning("reverse3d-core quality check failed (%s)", exc)
     side = np.cross([0.0, 1.0, 0.0] if abs(up[1]) < 0.9 else [1.0, 0.0, 0.0], up)
     side /= np.linalg.norm(side)
     basis = np.stack([side, np.cross(up, side), up])
@@ -983,6 +1022,12 @@ def visual_hull(
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
     mesh.export(output_path)
+    quality_path: str | None = None
+    if quality_colors is not None and len(quality_colors) == len(mesh.vertices):
+        heat = trimesh.Trimesh(mesh.vertices, mesh.faces, process=False)
+        heat.visual = trimesh.visual.ColorVisuals(heat, vertex_colors=quality_colors)
+        quality_path = str(output_path.with_name(output_path.stem + "_quality.ply"))
+        heat.export(quality_path)
     logger.info("Silhouette model: %d views, %d faces", len(views), len(mesh.faces))
     return HullResult(
         str(output_path),
@@ -1001,4 +1046,7 @@ def visual_hull(
         ]
         if core_weights is not None and engine != "reverse3d"
         else [],
+        refined_vertices,
+        quality,
+        quality_path,
     )

{reverse3d-0.11.3 → reverse3d-0.13.0/reverse3d.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reverse3d
-Version: 0.11.3
+Version: 0.13.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>
@@ -421,6 +421,8 @@ Si las fotos están borrosas o falta una herramienta, **no reintenta en vano**:
 |---|---|---|
 | Recortes perfectos | 0,943 | 0,941 |
 | 15 % de recortes defectuosos | 0,000 (pierde el objeto) | **0,921** |
+| Concavidad invisible a las siluetas (error en la ranura) | 0,154 | **0,091** (refinamiento por fotos, Core 0.3) |
+| Mapa de confianza y consejos de captura | — | ✅ Core 0.4 (`model_quality.glb`) |
 
 *(Coincidencia volumétrica, IoU: 1 = idéntico.)*
 

{reverse3d-0.11.3 → reverse3d-0.13.0}/tests/test_silhouette.py

@@ -421,3 +421,68 @@ def test_legs_stay_legs_when_the_base_is_completed() -> None:
     out = _complete_base(volume, grid, np.array([0.0, 0.0, 1.0]), 0.0, voxel).reshape(-1) > 0.5
     between = (np.abs(x) < 0.4) & (np.abs(y) < 0.4) & (z < 0.5)
     assert not out[between].any()
+
+
+class _RefiningCore(_FakeCore):
+    """A fake reverse3d-core >= 0.3 that also refines the mesh by photo consistency."""
+
+    def refine_mesh(self, mesh, cameras, images, step):  # type: ignore[no-untyped-def]
+        assert len(cameras) == len(images) and step > 0
+        return mesh, {"moved": 42, "vertices": len(mesh.vertices), "mean_offset": 0.0}
+
+
+def test_the_core_refines_the_hull_by_photo_consistency(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from reverse3d.reconstruction import silhouette
+
+    monkeypatch.setattr(silhouette, "core_engine", lambda: _RefiningCore())
+    images, text = _scene(tmp_path)
+    result = visual_hull(images, text, tmp_path / "hull.ply", resolution=48, refinements=1)
+    assert result.refined_vertices == 42
+
+
+class _QualityCore(_FakeCore):
+    """A fake reverse3d-core >= 0.4 with the quality agent."""
+
+    def assess_quality(self, mesh, cameras, up, step):  # type: ignore[no-untyped-def]
+        n = len(mesh.vertices)
+        colors = np.tile(np.array([[74, 222, 128, 255]], np.uint8), (n, 1))
+        advice = [{"elevation": "top", "share": 0.08, "near_photo": "img_03.png"}]
+        return {"confidence": np.ones(n), "colors": colors, "covered": 0.82, "advice": advice}
+
+
+def test_the_core_quality_agent_writes_a_confidence_map(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from reverse3d.reconstruction import silhouette
+
+    monkeypatch.setattr(silhouette, "core_engine", lambda: _QualityCore())
+    images, text = _scene(tmp_path)
+    result = visual_hull(images, text, tmp_path / "hull.ply", resolution=48, refinements=1)
+    assert result.quality["covered"] == pytest.approx(0.82)
+    assert result.quality_path is not None
+    heat = trimesh.load(result.quality_path, process=False)
+    assert len(heat.vertices) == len(trimesh.load(result.mesh_path, process=False).vertices)
+
+
+def test_capture_advice_becomes_a_warning_only_when_coverage_is_low(tmp_path: Path) -> None:
+    from types import SimpleNamespace
+
+    from reverse3d.config import Settings
+    from reverse3d.recipes import _quality_outputs, _Run
+
+    run = _Run(recipe="photos_to_model", settings=Settings(workspace=tmp_path), out=tmp_path)
+    advice = [{"elevation": "top", "share": 0.08, "near_photo": "IMG_5026.jpg"}]
+    _quality_outputs(
+        run, SimpleNamespace(quality={"covered": 0.82, "advice": advice}, quality_path=None)
+    )
+    assert run.warnings == [
+        "8% of the model is weakly supported by the photos: take more photos from above, "
+        "near where you took IMG_5026."
+    ]
+    run.warnings.clear()
+    _quality_outputs(
+        run, SimpleNamespace(quality={"covered": 0.98, "advice": advice}, quality_path=None)
+    )
+    assert run.warnings == []

reverse3d-0.11.3/reverse3d/_version.py

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