mmgpy 0.5.0__cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

mmgpy/repair/_core.py

@@ -0,0 +1,226 @@
+"""Core repair functionality for mmgpy.
+
+This module provides the auto_repair convenience function and the RepairReport
+dataclass for summarizing repair operations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mmgpy import Mesh
+
+
+@dataclass(frozen=True, slots=True)
+class RepairReport:
+    """Report summarizing mesh repair operations.
+
+    Attributes
+    ----------
+    duplicate_vertices_removed : int
+        Number of duplicate vertices removed.
+    orphan_vertices_removed : int
+        Number of orphan vertices removed.
+    degenerate_elements_removed : int
+        Number of degenerate elements removed.
+    inverted_elements_fixed : int
+        Number of inverted elements fixed.
+    duplicate_elements_removed : int
+        Number of duplicate elements removed.
+    vertices_before : int
+        Number of vertices before repair.
+    vertices_after : int
+        Number of vertices after repair.
+    elements_before : int
+        Number of elements before repair.
+    elements_after : int
+        Number of elements after repair.
+    operations_applied : tuple[str, ...]
+        Names of repair operations that were applied.
+
+    Examples
+    --------
+    >>> from mmgpy.repair import auto_repair
+    >>> mesh, report = auto_repair(mesh)
+    >>> print(report)
+    RepairReport:
+      Duplicate vertices removed: 12
+      Orphan vertices removed: 3
+      Degenerate elements removed: 2
+      Inverted elements fixed: 5
+    >>> print(f"Vertices: {report.vertices_before} -> {report.vertices_after}")
+
+    """
+
+    duplicate_vertices_removed: int = 0
+    orphan_vertices_removed: int = 0
+    degenerate_elements_removed: int = 0
+    inverted_elements_fixed: int = 0
+    duplicate_elements_removed: int = 0
+    vertices_before: int = 0
+    vertices_after: int = 0
+    elements_before: int = 0
+    elements_after: int = 0
+    operations_applied: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def total_repairs(self) -> int:
+        """Total number of repairs made."""
+        return (
+            self.duplicate_vertices_removed
+            + self.orphan_vertices_removed
+            + self.degenerate_elements_removed
+            + self.inverted_elements_fixed
+            + self.duplicate_elements_removed
+        )
+
+    @property
+    def was_modified(self) -> bool:
+        """True if any repairs were made."""
+        return self.total_repairs > 0
+
+    def __str__(self) -> str:
+        """Return a human-readable summary."""
+        lines = ["RepairReport:"]
+
+        if self.duplicate_vertices_removed > 0:
+            lines.append(
+                f"  Duplicate vertices removed: {self.duplicate_vertices_removed}",
+            )
+        if self.orphan_vertices_removed > 0:
+            lines.append(f"  Orphan vertices removed: {self.orphan_vertices_removed}")
+        if self.degenerate_elements_removed > 0:
+            lines.append(
+                f"  Degenerate elements removed: {self.degenerate_elements_removed}",
+            )
+        if self.inverted_elements_fixed > 0:
+            lines.append(f"  Inverted elements fixed: {self.inverted_elements_fixed}")
+        if self.duplicate_elements_removed > 0:
+            lines.append(
+                f"  Duplicate elements removed: {self.duplicate_elements_removed}",
+            )
+
+        if len(lines) == 1:
+            lines.append("  No repairs needed")
+        else:
+            lines.append(
+                f"  Vertices: {self.vertices_before} -> {self.vertices_after}",
+            )
+            lines.append(f"  Elements: {self.elements_before} -> {self.elements_after}")
+
+        return "\n".join(lines)
+
+
+def auto_repair(
+    mesh: Mesh,
+    *,
+    duplicate_tolerance: float = 1e-10,
+    degenerate_tolerance: float = 1e-10,
+) -> tuple[Mesh, RepairReport]:
+    """Apply all safe repair operations to the mesh.
+
+    This convenience function applies the following repairs in order:
+    1. Remove duplicate vertices
+    2. Remove degenerate elements
+    3. Fix inverted elements
+    4. Remove duplicate elements
+    5. Remove orphan vertices (cleanup)
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+    duplicate_tolerance : float, optional
+        Tolerance for duplicate vertex detection. Default is 1e-10.
+    degenerate_tolerance : float, optional
+        Tolerance for degenerate element detection. Default is 1e-10.
+
+    Returns
+    -------
+    tuple[Mesh, RepairReport]
+        The repaired mesh and a report summarizing the operations.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import auto_repair
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, report = auto_repair(mesh)
+    >>> if report.was_modified:
+    ...     print(f"Applied {report.total_repairs} repairs")
+    ...     print(report)
+
+    """
+    from mmgpy import MeshKind  # noqa: PLC0415
+    from mmgpy.repair._elements import (  # noqa: PLC0415
+        fix_inverted_elements,
+        remove_degenerate_elements,
+        remove_duplicate_elements,
+    )
+    from mmgpy.repair._vertices import (  # noqa: PLC0415
+        remove_duplicate_vertices,
+        remove_orphan_vertices,
+    )
+
+    vertices_before = len(mesh.get_vertices())
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements_before = len(mesh.get_tetrahedra())
+    else:
+        elements_before = len(mesh.get_triangles())
+
+    operations_applied: list[str] = []
+
+    mesh, duplicate_verts = remove_duplicate_vertices(
+        mesh,
+        tolerance=duplicate_tolerance,
+    )
+    if duplicate_verts > 0:
+        operations_applied.append("remove_duplicate_vertices")
+
+    mesh, degenerate_elems = remove_degenerate_elements(
+        mesh,
+        tolerance=degenerate_tolerance,
+    )
+    if degenerate_elems > 0:
+        operations_applied.append("remove_degenerate_elements")
+
+    mesh, inverted_elems = fix_inverted_elements(mesh)
+    if inverted_elems > 0:
+        operations_applied.append("fix_inverted_elements")
+
+    mesh, duplicate_elems = remove_duplicate_elements(mesh)
+    if duplicate_elems > 0:
+        operations_applied.append("remove_duplicate_elements")
+
+    mesh, orphan_verts = remove_orphan_vertices(mesh)
+    if orphan_verts > 0:
+        operations_applied.append("remove_orphan_vertices")
+
+    vertices_after = len(mesh.get_vertices())
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements_after = len(mesh.get_tetrahedra())
+    else:
+        elements_after = len(mesh.get_triangles())
+
+    report = RepairReport(
+        duplicate_vertices_removed=duplicate_verts,
+        orphan_vertices_removed=orphan_verts,
+        degenerate_elements_removed=degenerate_elems,
+        inverted_elements_fixed=inverted_elems,
+        duplicate_elements_removed=duplicate_elems,
+        vertices_before=vertices_before,
+        vertices_after=vertices_after,
+        elements_before=elements_before,
+        elements_after=elements_after,
+        operations_applied=tuple(operations_applied),
+    )
+
+    return mesh, report
+
+
+__all__ = [
+    "RepairReport",
+    "auto_repair",
+]

mmgpy/repair/_elements.py

@@ -0,0 +1,241 @@
+"""Element repair operations for mmgpy.
+
+This module provides functions for repairing element-related mesh issues
+including degenerate elements, inverted elements, and duplicate elements.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from mmgpy import Mesh
+
+_GEOMETRY_TOLERANCE = 1e-10
+
+
+def _compute_tetra_volumes(
+    vertices: np.ndarray,
+    tetrahedra: np.ndarray,
+) -> np.ndarray:
+    """Compute signed volumes for tetrahedra."""
+    tet_verts = vertices[tetrahedra]
+    v0, v1, v2, v3 = tet_verts[:, 0], tet_verts[:, 1], tet_verts[:, 2], tet_verts[:, 3]
+    edge_matrices = np.stack([v1 - v0, v2 - v0, v3 - v0], axis=-1)
+    return np.linalg.det(edge_matrices) / 6.0
+
+
+def _compute_triangle_areas_2d(
+    vertices: np.ndarray,
+    triangles: np.ndarray,
+) -> np.ndarray:
+    """Compute signed areas for 2D triangles."""
+    tri_verts = vertices[triangles]
+    v0, v1, v2 = tri_verts[:, 0], tri_verts[:, 1], tri_verts[:, 2]
+    cross_z = (v1[:, 0] - v0[:, 0]) * (v2[:, 1] - v0[:, 1]) - (v2[:, 0] - v0[:, 0]) * (
+        v1[:, 1] - v0[:, 1]
+    )
+    return 0.5 * cross_z
+
+
+def _compute_triangle_areas_3d(
+    vertices: np.ndarray,
+    triangles: np.ndarray,
+) -> np.ndarray:
+    """Compute areas for 3D triangles (unsigned)."""
+    tri_verts = vertices[triangles]
+    v0, v1, v2 = tri_verts[:, 0], tri_verts[:, 1], tri_verts[:, 2]
+    edge1 = v1 - v0
+    edge2 = v2 - v0
+    cross = np.cross(edge1, edge2)
+    return 0.5 * np.linalg.norm(cross, axis=1)
+
+
+def remove_degenerate_elements(
+    mesh: Mesh,
+    tolerance: float = 1e-10,
+) -> tuple[Mesh, int]:
+    """Remove elements with zero or near-zero volume/area.
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+    tolerance : float, optional
+        Tolerance for considering an element as degenerate.
+        Default is 1e-10.
+
+    Returns
+    -------
+    tuple[Mesh, int]
+        The repaired mesh and the number of elements removed.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import remove_degenerate_elements
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, removed_count = remove_degenerate_elements(mesh)
+    >>> print(f"Removed {removed_count} degenerate elements")
+
+    """
+    from mmgpy import Mesh, MeshKind  # noqa: PLC0415
+    from mmgpy.repair._vertices import remove_orphan_vertices  # noqa: PLC0415
+
+    vertices = mesh.get_vertices()
+
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements = mesh.get_tetrahedra()
+        if len(elements) == 0:
+            return mesh, 0
+        volumes = _compute_tetra_volumes(vertices, elements)
+        valid_mask = np.abs(volumes) >= tolerance
+    elif mesh.kind == MeshKind.TRIANGULAR_2D:
+        elements = mesh.get_triangles()
+        if len(elements) == 0:
+            return mesh, 0
+        areas = _compute_triangle_areas_2d(vertices, elements)
+        valid_mask = np.abs(areas) >= tolerance
+    else:  # TRIANGULAR_SURFACE
+        elements = mesh.get_triangles()
+        if len(elements) == 0:
+            return mesh, 0
+        areas = _compute_triangle_areas_3d(vertices, elements)
+        valid_mask = areas >= tolerance
+
+    removed_count = int(np.sum(~valid_mask))
+
+    if removed_count == 0:
+        return mesh, 0
+
+    new_elements = elements[valid_mask]
+    new_mesh = Mesh(vertices.copy(), new_elements)
+    new_mesh, _ = remove_orphan_vertices(new_mesh)
+
+    return new_mesh, removed_count
+
+
+def fix_inverted_elements(mesh: Mesh) -> tuple[Mesh, int]:
+    """Fix inverted elements by reversing their vertex order.
+
+    Inverted elements have negative volume (tetrahedra) or negative area
+    (2D triangles). This function flips the orientation to make them positive.
+
+    Note
+    ----
+    For surface meshes (TRIANGULAR_SURFACE), this function returns immediately
+    without making changes. Surface mesh orientation is determined by normal
+    direction which requires additional context (e.g., inside/outside knowledge)
+    that cannot be inferred from geometry alone. Use mesh-specific tools for
+    surface normal correction if needed.
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+
+    Returns
+    -------
+    tuple[Mesh, int]
+        The repaired mesh and the number of elements fixed.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import fix_inverted_elements
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, fixed_count = fix_inverted_elements(mesh)
+    >>> print(f"Fixed {fixed_count} inverted elements")
+
+    """
+    from mmgpy import Mesh, MeshKind  # noqa: PLC0415
+
+    vertices = mesh.get_vertices()
+
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements = mesh.get_tetrahedra().copy()
+        if len(elements) == 0:
+            return mesh, 0
+        volumes = _compute_tetra_volumes(vertices, elements)
+        inverted_mask = volumes < -_GEOMETRY_TOLERANCE
+        elements[inverted_mask] = elements[inverted_mask][:, [0, 2, 1, 3]]
+    elif mesh.kind == MeshKind.TRIANGULAR_2D:
+        elements = mesh.get_triangles().copy()
+        if len(elements) == 0:
+            return mesh, 0
+        areas = _compute_triangle_areas_2d(vertices, elements)
+        inverted_mask = areas < -_GEOMETRY_TOLERANCE
+        elements[inverted_mask] = elements[inverted_mask][:, [0, 2, 1]]
+    else:  # TRIANGULAR_SURFACE
+        return mesh, 0
+
+    fixed_count = int(np.sum(inverted_mask))
+
+    if fixed_count == 0:
+        return mesh, 0
+
+    new_mesh = Mesh(vertices.copy(), elements)
+    return new_mesh, fixed_count
+
+
+def remove_duplicate_elements(mesh: Mesh) -> tuple[Mesh, int]:
+    """Remove duplicate elements (same vertices, any order).
+
+    Elements are considered duplicates if they reference the same set
+    of vertices, regardless of the vertex ordering.
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+
+    Returns
+    -------
+    tuple[Mesh, int]
+        The repaired mesh and the number of elements removed.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import remove_duplicate_elements
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, removed_count = remove_duplicate_elements(mesh)
+    >>> print(f"Removed {removed_count} duplicate elements")
+
+    """
+    from mmgpy import Mesh, MeshKind  # noqa: PLC0415
+    from mmgpy.repair._vertices import remove_orphan_vertices  # noqa: PLC0415
+
+    vertices = mesh.get_vertices()
+
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements = mesh.get_tetrahedra()
+    else:
+        elements = mesh.get_triangles()
+
+    if len(elements) == 0:
+        return mesh, 0
+
+    sorted_elements = np.sort(elements, axis=1)
+    _, unique_indices = np.unique(sorted_elements, axis=0, return_index=True)
+    unique_indices = np.sort(unique_indices)
+
+    removed_count = len(elements) - len(unique_indices)
+
+    if removed_count == 0:
+        return mesh, 0
+
+    new_elements = elements[unique_indices]
+    new_mesh = Mesh(vertices.copy(), new_elements)
+    new_mesh, _ = remove_orphan_vertices(new_mesh)
+
+    return new_mesh, removed_count
+
+
+__all__ = [
+    "fix_inverted_elements",
+    "remove_degenerate_elements",
+    "remove_duplicate_elements",
+]

mmgpy/repair/_vertices.py

@@ -0,0 +1,219 @@
+"""Vertex repair operations for mmgpy.
+
+This module provides functions for repairing vertex-related mesh issues
+including duplicate vertices, orphan vertices, and close vertices.
+
+Note:
+    Choosing between ``remove_duplicate_vertices`` and ``merge_close_vertices``:
+
+    - Use ``remove_duplicate_vertices`` (default tolerance=1e-10) for exact or
+      near-exact duplicates that result from numerical precision issues or
+      mesh generation artifacts.
+
+    - Use ``merge_close_vertices`` (default tolerance=1e-6) when you want to
+      merge vertices that are geometrically close but not necessarily duplicates,
+      such as when simplifying meshes or cleaning up imported geometry.
+
+    The ``auto_repair`` function uses ``remove_duplicate_vertices`` (strict
+    tolerance) to avoid unintentionally merging distinct vertices. Call
+    ``merge_close_vertices`` separately if aggressive vertex merging is desired.
+
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+if TYPE_CHECKING:
+    from mmgpy import Mesh
+
+_logger = logging.getLogger(__name__)
+
+_LARGE_PAIR_THRESHOLD = 100_000
+
+
+def remove_duplicate_vertices(
+    mesh: Mesh,
+    tolerance: float = 1e-10,
+) -> tuple[Mesh, int]:
+    """Remove exact duplicate vertices from the mesh.
+
+    Uses KD-tree for O(n log n) duplicate detection. Vertices within
+    the tolerance distance are considered duplicates.
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+    tolerance : float, optional
+        Distance tolerance for considering vertices as duplicates.
+        Default is 1e-10.
+
+    Returns
+    -------
+    tuple[Mesh, int]
+        The repaired mesh and the number of vertices removed.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import remove_duplicate_vertices
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, removed_count = remove_duplicate_vertices(mesh)
+    >>> print(f"Removed {removed_count} duplicate vertices")
+
+    """
+    from mmgpy import Mesh, MeshKind  # noqa: PLC0415
+
+    vertices = mesh.get_vertices()
+    n_vertices = len(vertices)
+    min_vertices_for_duplicates = 2
+
+    if n_vertices < min_vertices_for_duplicates:
+        return mesh, 0
+
+    tree = cKDTree(vertices)
+    pairs = tree.query_pairs(r=tolerance, output_type="ndarray")
+
+    if len(pairs) == 0:
+        return mesh, 0
+
+    if len(pairs) > _LARGE_PAIR_THRESHOLD:
+        _logger.warning(
+            "Found %d vertex pairs within tolerance %g. This may indicate "
+            "the tolerance is too large or the mesh has many near-coincident "
+            "vertices. Consider using a smaller tolerance.",
+            len(pairs),
+            tolerance,
+        )
+
+    mapping = np.arange(n_vertices)
+    for i, j in pairs:
+        canonical = min(mapping[i], mapping[j])
+        mapping[i] = canonical
+        mapping[j] = canonical
+
+    for i in range(n_vertices):
+        root = i
+        while mapping[root] != root:
+            root = mapping[root]
+        mapping[i] = root
+
+    unique_indices = np.where(mapping == np.arange(n_vertices))[0]
+    new_vertices = vertices[unique_indices]
+
+    old_to_new = np.zeros(n_vertices, dtype=np.int32)
+    for new_idx, old_idx in enumerate(unique_indices):
+        old_to_new[old_idx] = new_idx
+
+    final_mapping = old_to_new[mapping]
+
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements = mesh.get_tetrahedra()
+        new_elements = final_mapping[elements]
+    else:
+        elements = mesh.get_triangles()
+        new_elements = final_mapping[elements]
+
+    new_mesh = Mesh(new_vertices, new_elements)
+    removed_count = n_vertices - len(new_vertices)
+
+    return new_mesh, removed_count
+
+
+def remove_orphan_vertices(mesh: Mesh) -> tuple[Mesh, int]:
+    """Remove vertices not referenced by any element.
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+
+    Returns
+    -------
+    tuple[Mesh, int]
+        The repaired mesh and the number of vertices removed.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import remove_orphan_vertices
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, removed_count = remove_orphan_vertices(mesh)
+    >>> print(f"Removed {removed_count} orphan vertices")
+
+    """
+    from mmgpy import Mesh, MeshKind  # noqa: PLC0415
+
+    vertices = mesh.get_vertices()
+    n_vertices = len(vertices)
+
+    if mesh.kind == MeshKind.TETRAHEDRAL:
+        elements = mesh.get_tetrahedra()
+    else:
+        elements = mesh.get_triangles()
+
+    if len(elements) == 0:
+        return mesh, 0
+
+    used_vertices = np.unique(elements.flatten())
+
+    if len(used_vertices) == n_vertices:
+        return mesh, 0
+
+    new_vertices = vertices[used_vertices]
+
+    old_to_new = np.full(n_vertices, -1, dtype=np.int32)
+    old_to_new[used_vertices] = np.arange(len(used_vertices), dtype=np.int32)
+
+    new_elements = old_to_new[elements]
+
+    new_mesh = Mesh(new_vertices, new_elements)
+    removed_count = n_vertices - len(new_vertices)
+
+    return new_mesh, removed_count
+
+
+def merge_close_vertices(
+    mesh: Mesh,
+    tolerance: float = 1e-6,
+) -> tuple[Mesh, int]:
+    """Merge vertices that are within tolerance distance of each other.
+
+    Similar to remove_duplicate_vertices but with a larger default tolerance.
+    This is useful for meshes with vertices that are nearly coincident but
+    not exactly duplicate.
+
+    Parameters
+    ----------
+    mesh : Mesh
+        The mesh to repair.
+    tolerance : float, optional
+        Distance tolerance for merging vertices. Default is 1e-6.
+
+    Returns
+    -------
+    tuple[Mesh, int]
+        The repaired mesh and the number of vertices merged.
+
+    Examples
+    --------
+    >>> from mmgpy import Mesh
+    >>> from mmgpy.repair import merge_close_vertices
+    >>> mesh = Mesh(vertices, cells)
+    >>> mesh, merged_count = merge_close_vertices(mesh, tolerance=1e-6)
+    >>> print(f"Merged {merged_count} close vertices")
+
+    """
+    return remove_duplicate_vertices(mesh, tolerance=tolerance)
+
+
+__all__ = [
+    "merge_close_vertices",
+    "remove_duplicate_vertices",
+    "remove_orphan_vertices",
+]