reverse3d 0.4.0__py3-none-any.whl

reverse3d/reverse_eng/mesh_cleaner.py

@@ -0,0 +1,304 @@
+"""Mesh repair, remeshing and alignment for scanned / reconstructed geometry.
+
+Pipeline (each step optional, executed in this order)::
+
+    sanitize (NaN/inf, degenerate & duplicate faces, merge vertices)
+      → component filtering (drop floating debris)
+      → normal/winding repair
+      → hole filling (small holes by trimesh, larger loops by centroid fan)
+      → Taubin smoothing (volume-preserving, unlike Laplacian)
+      → quadric decimation to a target face count
+      → alignment (OBB / PCA / center) + optional ground placement
+      → uniform scale (unit conversion)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Literal, cast
+
+import numpy as np
+import trimesh
+
+from reverse3d.config import Settings
+from reverse3d.errors import DependencyMissingError, InputValidationError, ProcessingError
+from reverse3d.mesh_io import load_mesh, save_mesh
+from reverse3d.reverse_eng.measure import MeshStats, compute_stats
+
+logger = logging.getLogger(__name__)
+
+AlignMode = Literal["none", "center", "obb", "pca"]
+
+
+@dataclass
+class CleanOptions:
+    """Options for :func:`clean_mesh`. Defaults are safe for most scans."""
+
+    keep_largest_only: bool = False
+    min_component_ratio: float = 0.01
+    fix_normals: bool = True
+    fill_holes: bool = True
+    max_hole_edges: int = 200
+    smooth_iterations: int = 0
+    target_faces: int | None = None
+    align: AlignMode = "none"
+    ground: bool = False
+    scale: float = 1.0
+
+    def validate(self) -> None:
+        if not 0 <= self.min_component_ratio < 1:
+            raise InputValidationError("min_component_ratio must be in [0, 1).")
+        if not 3 <= self.max_hole_edges <= 100_000:
+            raise InputValidationError("max_hole_edges must be in [3, 100000].")
+        if not 0 <= self.smooth_iterations <= 200:
+            raise InputValidationError("smooth_iterations must be in [0, 200].")
+        if self.target_faces is not None and self.target_faces < 4:
+            raise InputValidationError("target_faces must be >= 4.")
+        if self.align not in ("none", "center", "obb", "pca"):
+            raise InputValidationError("align must be none, center, obb or pca.")
+        if not 1e-9 < self.scale < 1e9:
+            raise InputValidationError("scale must be a positive, finite factor.")
+
+
+@dataclass
+class CleanReport:
+    """What :func:`clean_mesh` did, with before/after statistics."""
+
+    before: MeshStats
+    after: MeshStats
+    steps: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    output_path: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+# ─── individual operations ────────────────────────────────────────────────────
+
+
+def sanitize(mesh: trimesh.Trimesh) -> int:
+    """Remove NaN/inf vertices, degenerate and duplicate faces, merge coincident
+    vertices. Returns the number of faces removed."""
+    start = len(mesh.faces)
+    mesh.remove_infinite_values()
+    mesh.merge_vertices()
+    mesh.update_faces(mesh.nondegenerate_faces())
+    mesh.update_faces(mesh.unique_faces())
+    mesh.remove_unreferenced_vertices()
+    return start - len(mesh.faces)
+
+
+def filter_components(
+    mesh: trimesh.Trimesh, *, keep_largest_only: bool, min_ratio: float
+) -> tuple[trimesh.Trimesh, int]:
+    """Drop small disconnected pieces. Returns ``(mesh, removed_count)``.
+
+    Size is measured by surface area, not face count: scan debris is often
+    densely tessellated while the real part may be a low-poly CAD body.
+    """
+    parts = mesh.split(only_watertight=False)
+    if len(parts) <= 1:
+        return mesh, 0
+    parts = sorted(parts, key=lambda m: m.area, reverse=True)
+    if keep_largest_only:
+        kept = parts[:1]
+    else:
+        threshold = min_ratio * parts[0].area
+        kept = [p for p in parts if p.area >= threshold]
+    return cast(trimesh.Trimesh, trimesh.util.concatenate(kept)), len(parts) - len(kept)
+
+
+def _boundary_loops(mesh: trimesh.Trimesh) -> list[list[int]]:
+    """Return closed boundary loops as ordered vertex lists, oriented like the
+    adjacent faces' edges. Loops through non-manifold vertices are skipped."""
+    faces = mesh.faces
+    directed = np.concatenate([faces[:, [0, 1]], faces[:, [1, 2]], faces[:, [2, 0]]])
+    single = np.asarray(
+        trimesh.grouping.group_rows(np.sort(directed, axis=1), require_count=1)
+    ).reshape(-1)
+    if single.size == 0:
+        return []
+    boundary = directed[single]
+
+    successors: dict[int, int] = {}
+    ambiguous: set[int] = set()
+    for a, b in boundary:
+        if a in successors:
+            ambiguous.add(int(a))
+        successors[int(a)] = int(b)
+
+    loops: list[list[int]] = []
+    visited: set[int] = set()
+    for start in successors:
+        if start in visited or start in ambiguous:
+            continue
+        loop = [start]
+        visited.add(start)
+        current = successors[start]
+        valid = True
+        while current != start:
+            if current in visited or current in ambiguous or current not in successors:
+                valid = False
+                break
+            loop.append(current)
+            visited.add(current)
+            current = successors[current]
+        if valid and len(loop) >= 3:
+            loops.append(loop)
+    return loops
+
+
+def fill_boundary_loops(mesh: trimesh.Trimesh, max_hole_edges: int) -> tuple[trimesh.Trimesh, int]:
+    """Close every boundary loop up to ``max_hole_edges`` edges with a fan of
+    triangles around the loop centroid. Returns ``(mesh, holes_filled)``.
+
+    Suitable for roughly planar/convex holes typical of scan occlusions; very
+    large or saddle-shaped holes need a dedicated surface reconstruction.
+    """
+    loops = [loop for loop in _boundary_loops(mesh) if len(loop) <= max_hole_edges]
+    if not loops:
+        return mesh, 0
+    vertices: list[np.ndarray] = [np.asarray(mesh.vertices)]
+    new_faces: list[np.ndarray] = [np.asarray(mesh.faces)]
+    next_index = len(mesh.vertices)
+    for loop in loops:
+        # Existing faces traverse a→b; the patch must traverse b→a to keep winding consistent.
+        if len(loop) == 3:
+            new_faces.append(np.array([[loop[2], loop[1], loop[0]]]))
+            continue
+        centroid = mesh.vertices[loop].mean(axis=0)
+        vertices.append(centroid[None, :])
+        ring = np.array(loop)
+        fan = np.stack([np.roll(ring, -1), ring, np.full(len(ring), next_index)], axis=1)
+        new_faces.append(fan)
+        next_index += 1
+    filled = trimesh.Trimesh(
+        vertices=np.vstack(vertices), faces=np.vstack(new_faces), process=False
+    )
+    return filled, len(loops)
+
+
+def align_mesh(mesh: trimesh.Trimesh, mode: AlignMode) -> None:
+    """Align in place. ``obb``: minimum oriented box → axes (largest extent on X);
+    ``pca``: principal axes of the vertices; ``center``: bbox center to origin."""
+    if mode == "none":
+        return
+    if mode == "center":
+        mesh.apply_translation(-mesh.bounds.mean(axis=0))
+        return
+    if mode == "obb":
+        to_origin, extents = trimesh.bounds.oriented_bounds(mesh)
+        mesh.apply_transform(to_origin)
+        order = np.argsort(extents)[::-1]
+        permute = np.eye(4)
+        permute[:3, :3] = np.eye(3)[order]
+        if np.linalg.det(permute[:3, :3]) < 0:
+            permute[2, :3] *= -1
+        mesh.apply_transform(permute)
+        return
+    # PCA
+    centered = mesh.vertices - mesh.vertices.mean(axis=0)
+    _, _, vt = np.linalg.svd(centered, full_matrices=False)
+    rotation = vt.copy()
+    if np.linalg.det(rotation) < 0:
+        rotation[2] *= -1
+    transform = np.eye(4)
+    transform[:3, :3] = rotation
+    transform[:3, 3] = -rotation @ mesh.vertices.mean(axis=0)
+    mesh.apply_transform(transform)
+
+
+# ─── public API ───────────────────────────────────────────────────────────────
+
+
+def clean_mesh(
+    mesh: trimesh.Trimesh, options: CleanOptions | None = None
+) -> tuple[trimesh.Trimesh, CleanReport]:
+    """Repair ``mesh`` and return ``(clean_mesh, report)``. The input is not modified.
+
+    Raises:
+        InputValidationError: invalid options.
+        ProcessingError: the mesh became empty.
+        DependencyMissingError: decimation requested without ``fast-simplification``.
+    """
+    options = options or CleanOptions()
+    options.validate()
+    mesh = mesh.copy()
+    before = compute_stats(mesh)
+    steps: list[str] = []
+    warnings: list[str] = []
+
+    removed = sanitize(mesh)
+    steps.append(f"sanitize: removed {removed} degenerate/duplicate face(s)")
+
+    mesh, dropped = filter_components(
+        mesh, keep_largest_only=options.keep_largest_only, min_ratio=options.min_component_ratio
+    )
+    if dropped:
+        steps.append(f"components: dropped {dropped} small piece(s)")
+
+    if options.fill_holes:
+        trimesh.repair.fill_holes(mesh)
+        mesh, filled = fill_boundary_loops(mesh, options.max_hole_edges)
+        mesh.merge_vertices()
+        steps.append(f"holes: filled {filled} boundary loop(s)")
+
+    if options.fix_normals:
+        trimesh.repair.fix_normals(mesh)
+        steps.append("normals: winding and orientation fixed")
+
+    if options.smooth_iterations:
+        trimesh.smoothing.filter_taubin(mesh, iterations=options.smooth_iterations)
+        steps.append(f"smooth: Taubin x{options.smooth_iterations}")
+
+    if options.target_faces and len(mesh.faces) > options.target_faces:
+        try:
+            mesh = mesh.simplify_quadric_decimation(face_count=options.target_faces)
+        except ImportError as exc:
+            raise DependencyMissingError(
+                "Decimation requires the 'fast-simplification' package.",
+                hint="pip install fast-simplification",
+            ) from exc
+        steps.append(f"decimate: {len(mesh.faces)} face(s)")
+
+    if len(mesh.faces) == 0:
+        raise ProcessingError("Mesh is empty after cleaning; relax the options.")
+
+    align_mesh(mesh, options.align)
+    if options.align != "none":
+        steps.append(f"align: {options.align}")
+    if options.ground:
+        mesh.apply_translation([0.0, 0.0, -mesh.bounds[0][2]])
+        steps.append("ground: min Z moved to 0")
+    if options.scale != 1.0:
+        mesh.apply_scale(options.scale)
+        steps.append(f"scale: x{options.scale}")
+
+    after = compute_stats(mesh)
+    if not after.watertight:
+        warnings.append(
+            f"Mesh is still open ({after.boundary_edges} boundary edges); "
+            "raise max_hole_edges or re-scan the missing areas."
+        )
+    return mesh, CleanReport(before=before, after=after, steps=steps, warnings=warnings)
+
+
+def clean_mesh_file(
+    input_path: str | Path,
+    output_path: str | Path,
+    settings: Settings,
+    options: CleanOptions | None = None,
+    *,
+    overwrite: bool = False,
+) -> CleanReport:
+    """Load, clean and save a mesh file. Returns the :class:`CleanReport`."""
+    mesh = load_mesh(input_path, settings)
+    cleaned, report = clean_mesh(mesh, options)
+    report.output_path = str(save_mesh(cleaned, output_path, overwrite=overwrite))
+    logger.info(
+        "Cleaned %s: %d → %d faces", Path(input_path).name, report.before.faces, report.after.faces
+    )
+    return report

reverse3d/reverse_eng/parametric.py

@@ -0,0 +1,154 @@
+"""Generate parametric CAD source (OpenSCAD / CadQuery) from fitted primitives.
+
+The output is a *starting point* for a CAD redesign: each detected primitive
+becomes a named, editable feature. Only numeric values coming from the fit are
+emitted (formatted floats), so no user/agent text can be injected into the
+generated program.
+"""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from reverse3d._version import __version__
+from reverse3d.errors import InputValidationError
+from reverse3d.reverse_eng.geometry_fit import FitReport, PrimitiveFit, plane_basis
+from reverse3d.security import prepare_output_file
+
+PARAMETRIC_EXTENSIONS = frozenset({".scad", ".py"})
+
+
+def _f(x: Any) -> str:
+    """Format a number. ``float()`` guarantees only numeric text is emitted."""
+    return f"{float(x):.6g}"
+
+
+def _vec(values: object) -> np.ndarray:
+    return np.asarray(values, dtype=np.float64).reshape(3)
+
+
+def _v3(values: np.ndarray) -> str:
+    return ", ".join(_f(x) for x in values)
+
+
+def _slab_thickness(report: FitReport) -> float:
+    return max(report.threshold * 2, 1e-3)
+
+
+def _rotation_from_z(axis: np.ndarray) -> tuple[float, np.ndarray]:
+    """Angle (deg) and rotation vector that map +Z onto ``axis``."""
+    z = np.array([0.0, 0.0, 1.0])
+    axis = axis / np.linalg.norm(axis)
+    cross = np.cross(z, axis)
+    if np.linalg.norm(cross) < 1e-9:
+        return (
+            (0.0, np.array([1.0, 0.0, 0.0])) if axis[2] > 0 else (180.0, np.array([1.0, 0.0, 0.0]))
+        )
+    angle = math.degrees(math.acos(float(np.clip(z @ axis, -1.0, 1.0))))
+    return angle, cross / np.linalg.norm(cross)
+
+
+def _openscad_feature(idx: int, fit: PrimitiveFit, slab: float) -> str:
+    p = fit.params
+    header = f"// [{idx}] {fit.kind}  inliers={fit.inliers}  rmse={_f(fit.rmse)}"
+    if fit.kind == "sphere":
+        center = _v3(_vec(p["center"]))
+        return f"{header}\ntranslate([{center}]) sphere(r={_f(p['radius'])});"
+    if fit.kind == "cylinder":
+        base, axis = _vec(p["axis_point"]), _vec(p["axis_direction"])
+        angle, rot = _rotation_from_z(axis)
+        return (
+            f"{header}\ntranslate([{_v3(base)}]) rotate(a={_f(angle)}, v=[{_v3(rot)}]) "
+            f"cylinder(h={_f(p['height'])}, r={_f(p['radius'])});"
+        )
+    normal, centroid = _vec(p["normal"]), _vec(p["centroid"])
+    u, v = plane_basis(normal)
+    ex, ey = np.asarray(p["extent_2d"], dtype=np.float64).reshape(2)
+    rows = [
+        [u[0], v[0], normal[0], centroid[0]],
+        [u[1], v[1], normal[1], centroid[1]],
+        [u[2], v[2], normal[2], centroid[2]],
+        [0, 0, 0, 1],
+    ]
+    matrix = "[" + ", ".join("[" + ", ".join(_f(x) for x in r) + "]" for r in rows) + "]"
+    return f"{header}\nmultmatrix({matrix}) cube([{_f(ex)}, {_f(ey)}, {_f(slab)}], center=true);"
+
+
+def generate_openscad(report: FitReport) -> str:
+    """Return an OpenSCAD program with one feature per detected primitive."""
+    slab = _slab_thickness(report)
+    features = "\n\n".join(
+        _openscad_feature(i, fit, slab) for i, fit in enumerate(report.primitives)
+    )
+    return (
+        f"// Auto-generated by reverse3d {__version__} (https://voxel.lat)\n"
+        "// Draft reconstruction from RANSAC primitive fitting. Review before manufacturing.\n"
+        f"// points={report.point_count}  threshold={_f(report.threshold)}  "
+        f"unexplained={report.unexplained_ratio}\n"
+        "$fn = 96;\n\n"
+        f"union() {{\n{_indent(features)}\n}}\n"
+    )
+
+
+def _cadquery_feature(idx: int, fit: PrimitiveFit, slab: float) -> str:
+    p = fit.params
+    name = f"f{idx}_{fit.kind}"
+    if fit.kind == "sphere":
+        return (
+            f"{name} = cq.Workplane('XY').sphere({_f(p['radius'])})"
+            f".translate(({_v3(_vec(p['center']))}))"
+        )
+    if fit.kind == "cylinder":
+        base, axis = _vec(p["axis_point"]), _vec(p["axis_direction"])
+        u, _ = plane_basis(axis)
+        return (
+            f"{name} = (cq.Workplane(cq.Plane(origin=({_v3(base)}), xDir=({_v3(u)}), "
+            f"normal=({_v3(axis)})))"
+            f".circle({_f(p['radius'])}).extrude({_f(p['height'])}))"
+        )
+    normal, centroid = _vec(p["normal"]), _vec(p["centroid"])
+    u, _ = plane_basis(normal)
+    ex, ey = np.asarray(p["extent_2d"], dtype=np.float64).reshape(2)
+    return (
+        f"{name} = (cq.Workplane(cq.Plane(origin=({_v3(centroid)}), xDir=({_v3(u)}), "
+        f"normal=({_v3(normal)})))"
+        f".rect({_f(ex)}, {_f(ey)}).extrude({_f(slab / 2)}, both=True))"
+    )
+
+
+def generate_cadquery(report: FitReport) -> str:
+    """Return a CadQuery (Python) script building the detected primitives."""
+    slab = _slab_thickness(report)
+    lines = [_cadquery_feature(i, fit, slab) for i, fit in enumerate(report.primitives)]
+    names = [f"f{i}_{fit.kind}" for i, fit in enumerate(report.primitives)]
+    union = names[0] + "".join(f".union({n})" for n in names[1:]) if names else "cq.Workplane('XY')"
+    return (
+        f'"""Auto-generated by reverse3d {__version__} (https://voxel.lat).\n\n'
+        "Draft reconstruction from RANSAC primitive fitting. Review before manufacturing.\n"
+        'Run with CadQuery (pip install cadquery) or open in CQ-editor.\n"""\n\n'
+        "import cadquery as cq\n\n" + "\n".join(lines) + f"\n\nresult = {union}\n"
+        "cq.exporters.export(result, 'reverse3d_model.step')\n"
+    )
+
+
+def export_parametric(
+    report: FitReport, output_path: str | Path, *, overwrite: bool = False
+) -> Path:
+    """Write OpenSCAD (``.scad``) or CadQuery (``.py``) source for ``report``."""
+    if not report.primitives:
+        raise InputValidationError("No primitives to export.")
+    out = prepare_output_file(
+        output_path, allowed_extensions=PARAMETRIC_EXTENSIONS, overwrite=overwrite
+    )
+    code = generate_openscad(report) if out.suffix.lower() == ".scad" else generate_cadquery(report)
+    out.write_text(code, encoding="utf-8")
+    return out
+
+
+def _indent(text: str, spaces: int = 4) -> str:
+    pad = " " * spaces
+    return "\n".join(pad + line if line else line for line in text.splitlines())