primlib 0.3.0__py3-none-any.whl

primlib/triangle_mesh.py

@@ -0,0 +1,1910 @@
+import copy
+import logging
+import os
+from collections.abc import Callable
+from typing import Self, override
+
+import numpy as np
+import pyembree2
+from numpy.typing import ArrayLike
+from plyfile import PlyData, PlyElement
+from scipy.sparse import coo_array, csr_array, diags
+from scipy.sparse.csgraph import connected_components
+from scipy.sparse.linalg import eigsh, spsolve
+from scipy.spatial import ConvexHull
+from trafolib.trafo3d import Trafo3d
+
+from primlib.point_cloud import PointCloud
+from primlib.utils import scalar_to_bicolor, scalar_to_color
+from primlib.vertices import Vertices
+
+
+class TriangleMesh(Vertices):
+    """
+    A class representing a surface by a mesh of triangles.
+    """
+
+    __slots__ = (
+        "_face_colors",
+        "_face_normals",
+        "_faces",
+        "_vertex_adjacency",
+        "_vertex_face_incidence",
+    )
+
+    def __init__(
+        self,
+        vertices: ArrayLike | None = None,
+        faces: ArrayLike | None = None,
+        vertex_normals: ArrayLike | None = None,
+        face_normals: ArrayLike | None = None,
+        vertex_colors: ArrayLike | None = None,
+        face_colors: ArrayLike | None = None,
+    ) -> None:
+        """Constructor
+
+        :param vertices: Vertices of the triangle mesh, shape (n, 3)
+        :param faces: Faces of the triangle mesh as vertex indices,
+            shape (m, 3), integer type
+        :param vertex_normals: Normals for each vertex, shape (n, 3), normalized
+        :param face_normals: Normals for each face, shape (m, 3), normalized
+        :param vertex_colors: RGB colors for each vertex, shape (n, 3),
+            values [0.0..1.0]
+        :param face_colors: RGB colors for each face, shape (m, 3), values [0.0..1.0]
+        """
+        super().__init__(
+            vertices=vertices, normals=vertex_normals, colors=vertex_colors
+        )
+        # Define types and initialize
+        self._faces: np.ndarray = np.zeros((0, 3), dtype=int)
+        self._face_normals: np.ndarray = np.zeros((0, 3))
+        self._face_colors: np.ndarray = np.zeros((0, 3))
+        self._vertex_adjacency: csr_array | None = None
+        self._vertex_face_incidence: csr_array | None = None
+        # Initialize using parameters and setters
+        self.faces = faces
+        self.face_normals = face_normals
+        self.face_colors = face_colors
+
+    @property
+    def num_vertices(self) -> int:
+        """Number of vertices of the triangle mesh
+        :returns: Number of vertices
+        """
+        return self._vertices.shape[0]
+
+    @property
+    def num_faces(self) -> int:
+        """Number of faces of the triangle mesh
+        :returns: Number of faces
+        """
+        return self._faces.shape[0]
+
+    @property
+    def empty(self) -> bool:
+        """Check if triangle mesh is empty
+        :returns: True if triangle mesh has no vertices and no faces
+        """
+        return self.num_vertices == 0 and self.num_faces == 0
+
+    @override
+    def __str__(self) -> str:
+        """Get string representation of triangle mesh
+        :returns: String representation
+        """
+        if self.empty:
+            return "TriangleMesh(empty)"
+        pmin = self.min()
+        pmax = self.max()
+        result = (
+            f"TriangleMesh({self.num_vertices:_} vertices: "
+            + f"X[{pmin[0]:.3f}..{pmax[0]:.3f}], "
+            + f"Y[{pmin[1]:.3f}..{pmax[1]:.3f}], "
+            + f"Z[{pmin[2]:.3f}..{pmax[2]:.3f}]"
+        )
+        if self.has_normals:
+            result += ", vertex normals"
+        if self.has_colors:
+            result += ", vertex colors"
+        result += f", {self.num_faces:_} faces"
+        if self.has_face_normals:
+            result += ", face normals"
+        if self.has_face_colors:
+            result += ", face colors"
+        result += ")"
+        return result
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        """Check two triangle meshes for equality.
+
+        :param other: Other object
+        :returns: True if triangle meshes are equal
+        """
+        if not isinstance(other, TriangleMesh):
+            return NotImplemented
+        return (
+            super().__eq__(other)
+            # Faces
+            and self._faces.shape == other._faces.shape
+            and np.array_equal(self._faces, other._faces)
+            # Face normals
+            and self._face_normals.shape == other._face_normals.shape
+            and np.allclose(self._face_normals, other._face_normals)
+            # Face colors
+            and self._face_colors.shape == other._face_colors.shape
+            and np.allclose(
+                self._face_colors,
+                other._face_colors,
+                atol=1.0 / 255.0,
+            )
+        )
+
+    @override
+    def __ne__(self, other: object) -> bool:
+        """Check two triangle meshes for inequality
+
+        :param other: Other object
+        :returns: True, if triangle meshes are not equal
+        """
+        return not self.__eq__(other)
+
+    @override
+    def __iadd__(self, other: Vertices) -> Self:
+        """Concatenate another triangle mesh in-place
+
+        :param other: Other triangle mesh
+        :returns: This triangle mesh (self)
+        """
+        if not isinstance(other, TriangleMesh):
+            raise TypeError("Can only append another TriangleMesh")
+        if (
+            self.has_face_normals != other.has_face_normals
+            or self.has_face_colors != other.has_face_colors
+        ):
+            raise ValueError("Both meshes must have the same properties")
+        # Append vertices and vertex properties
+        vertex_offset = self.num_vertices
+        super().__iadd__(other)
+        # Append faces, adjusting vertex indices
+        self._faces = np.vstack((self._faces, other._faces + vertex_offset))
+        # Append face normals
+        if self.has_face_normals:
+            self._face_normals = np.vstack((self._face_normals, other._face_normals))
+        # Append face colors
+        if self.has_face_colors:
+            self._face_colors = np.vstack((self._face_colors, other._face_colors))
+        return self
+
+    @override
+    def __add__(self, other: Vertices) -> Self:
+        """Concatenate two triangle meshes
+
+        :param other: Other triangle mesh
+        :returns: New triangle mesh
+        """
+        result = self.copy()
+        result += other
+        return result
+
+    @override
+    def copy(self) -> Self:
+        """Get copy of triangle mesh
+
+        :returns: Copy
+        """
+        return copy.deepcopy(self)
+
+    @property
+    def faces(self) -> np.ndarray:
+        """Get faces
+
+        Faces are 3-tuples of indices of type integer referencing vertices;
+        for example: the face (3, 7, 3) is a triangle consisting of the
+        vertices 3, 7 and 3.
+
+        :returns: Faces, shape (n, 3), type int
+        """
+        return self._faces
+
+    @faces.setter
+    def faces(self, value: ArrayLike | None) -> None:
+        """Set faces
+
+        Faces are 3-tuples of indices of type integer referencing vertices;
+        for example: the face (3, 7, 3) is a triangle consisting of the
+        vertices 3, 7 and 3.
+
+        If there are face normals or face colors defined in the triangle
+        mesh, then the number of faces has to match their number.
+
+        :param value: Faces, shape (n, 3), type int
+        """
+        if value is None:
+            value = np.zeros((0, 3), dtype=int)
+        else:
+            value = np.asarray(value, dtype=int)
+        if value.ndim != 2 or value.shape[1] != 3:
+            raise Exception("Provide faces of shape (n, 3)")
+        if self.has_face_normals and value.shape[0] != self._face_normals.shape[0]:
+            raise Exception(
+                "Mesh already has face normals, provide proper amount of faces"
+            )
+        if self.has_face_colors and value.shape[0] != self._face_colors.shape[0]:
+            raise Exception(
+                "Mesh already has face colors, provide proper amount of faces"
+            )
+        unique_indices = np.unique(value)
+        if unique_indices.size > 0 and (
+            unique_indices[0] < 0 or unique_indices[-1] >= self.num_vertices
+        ):
+            logging.warning("Some faces reference invalid vertices.")
+        if unique_indices.size != self.num_vertices:
+            logging.warning("Some vertices are not referenced by faces.")
+        self._faces = value
+
+    @property
+    def face_normals(self) -> np.ndarray:
+        """Get face normals
+
+        Face normals are 3d vectors that are perpendicular to the respective
+        face/triangle. They are normalized, i.e. they have a length of 1.0.
+
+        :returns: Face normals, shape (n, 3)
+        """
+        return self._face_normals
+
+    @face_normals.setter
+    def face_normals(self, value: ArrayLike | None) -> None:
+        """Set face normals
+
+        If there are faces defined in the triangle mesh, then the number
+        of face normals has to match the number of faces.
+
+        Face normals should have a length > 0, otherwise an exception is
+        thrown. Face normals should have unit length. If not, normals will
+        be normalized and a warning is given.
+
+        :param value: Face normals, shape (n, 3)
+        """
+        if value is None:
+            value = np.zeros((0, 3))
+        else:
+            value = np.asarray(value, dtype=float)
+        if value.ndim != 2 or value.shape[1] != 3:
+            raise Exception("Provide normals of shape (n, 3)")
+        if value.shape[0] > 0 and value.shape[0] != self.num_faces:
+            raise Exception("Provide as many face normals as faces")
+        lengths = np.sqrt(value[:, 0] ** 2 + value[:, 1] ** 2 + value[:, 2] ** 2)
+        if np.any(np.isclose(lengths, 0.0)):
+            raise Exception("Some normals have zero lengths")
+        if not np.allclose(lengths, 1.0):
+            logging.warning("Some normals are not normalized. Normalizing...")
+            value = value / lengths[:, None]
+        self._face_normals = value
+
+    @property
+    def has_face_normals(self) -> bool:
+        """Check if triangle mesh has face normals
+
+        :returns: True, if triangle mesh has face normals
+        """
+        return self._face_normals.shape[0] > 0
+
+    @property
+    def face_colors(self) -> np.ndarray:
+        """Get face colors
+
+        Color are 3-tuples of RGB values in range [0..1] of type float.
+
+        :returns: Face colors, shape (n, 3)
+        """
+        return self._face_colors
+
+    @face_colors.setter
+    def face_colors(self, value: ArrayLike | None) -> None:
+        """Set face colors
+
+        If there are faces defined in the triangle mesh, then the number
+        of face colors has to match the number of faces.
+
+        Face colors are RGB values in range [0..1]. If values outside that
+        range are provided, values will be clipped and a warning is given.
+
+        :param value: Face colors, shape (n, 3)
+        """
+        if value is None:
+            face_colors = np.zeros((0, 3))
+        else:
+            face_colors = np.asarray(value, dtype=float)
+        if face_colors.ndim != 2 or face_colors.shape[1] != 3:
+            raise ValueError("Provide face colors of shape (n, 3)")
+        if face_colors.shape[0] > 0 and face_colors.shape[0] != self.num_faces:
+            raise ValueError("Provide as many face colors as faces")
+        if not np.all(np.logical_and(face_colors >= 0.0, face_colors <= 1.0)):
+            logging.warning("Some colors are out of bounds. Clipping to [0,1] ...")
+            face_colors = np.clip(face_colors, 0.0, 1.0)
+        self._face_colors = face_colors
+
+    @property
+    def has_face_colors(self) -> bool:
+        """Check if triangle mesh has face colors
+
+        :returns: True, if triangle mesh has face colors
+        """
+        return self._face_colors.shape[0] > 0
+
+    @staticmethod
+    def _load_face_data(
+        plydata: PlyData,
+    ) -> tuple[np.ndarray | None, np.ndarray | None, np.ndarray | None]:
+        """Helper method to read face data
+
+        :param plydata: PlyData
+        :returns: Faces, face normals and face colors
+        """
+        face_data = plydata["face"]
+        properties = {p.name: p.val_dtype for p in face_data.properties}
+        # Faces
+        if "vertex_indices" in properties:
+            face_index_key = "vertex_indices"
+        elif "vertex_index" in properties:
+            face_index_key = "vertex_index"
+        else:
+            raise Exception("Unable to find faces in triangle mesh")
+        faces = np.vstack([np.asarray(f) for f in face_data[face_index_key]]).astype(
+            int
+        )
+        # Face normals (if existing)
+        face_normals = None
+        face_normal_keys = ["nx", "ny", "nz"]
+        if all(k in properties for k in face_normal_keys):
+            face_normals = (
+                np.vstack([face_data["nx"], face_data["ny"], face_data["nz"]])
+                .astype(float)
+                .T
+            )
+        # Face colors (if existing)
+        face_colors = None
+        color_keys_rgb = ["red", "green", "blue"]
+        if all(k in properties for k in color_keys_rgb):
+            assert properties["red"] == "u1"
+            face_colors = np.vstack(
+                [face_data["red"], face_data["green"], face_data["blue"]]
+            ).T
+            face_colors = face_colors.astype(float) / 255.0
+        return faces, face_normals, face_colors
+
+    def _save_face_data(self) -> PlyElement:
+        """Helper method to save face data"""
+        # Collect dtypes
+        dtypes: list[tuple[str, str] | tuple[str, str, tuple[int, ...]]] = [
+            ("vertex_indices", "i4", (3,))
+        ]
+        if self.has_face_normals:
+            dtypes.extend([("nx", "f8"), ("ny", "f8"), ("nz", "f8")])
+        if self.has_face_colors:
+            dtypes.extend([("red", "u1"), ("green", "u1"), ("blue", "u1")])
+        # Collect data
+        element_data = np.empty(self._faces.shape[0], dtype=dtypes)
+        element_data["vertex_indices"] = self._faces
+        if self.has_face_normals:
+            element_data["nx"] = self._face_normals[:, 0]
+            element_data["ny"] = self._face_normals[:, 1]
+            element_data["nz"] = self._face_normals[:, 2]
+        if self.has_face_colors:
+            element_data["red"] = np.round(self._face_colors[:, 0] * 255.0).astype(
+                np.uint8
+            )
+            element_data["green"] = np.round(self._face_colors[:, 1] * 255.0).astype(
+                np.uint8
+            )
+            element_data["blue"] = np.round(self._face_colors[:, 2] * 255.0).astype(
+                np.uint8
+            )
+        return PlyElement.describe(element_data, "face")
+
+    @classmethod
+    @override
+    def from_ply(cls, path: str | os.PathLike) -> "TriangleMesh":
+        """Create triangle mesh from PLY file
+
+        :param path: Path to PLY file to read
+        :returns: Resulting triangle mesh
+        """
+        plydata = Vertices._read_ply_data(path)
+        vertices, normals, colors = Vertices._load_vertex_data(plydata)
+        faces, face_normals, face_colors = TriangleMesh._load_face_data(plydata)
+        return cls(
+            vertices=vertices,
+            faces=faces,
+            vertex_normals=normals,
+            face_normals=face_normals,
+            vertex_colors=colors,
+            face_colors=face_colors,
+        )
+
+    @override
+    def save_ply(self, path: str | os.PathLike) -> None:
+        """Save triangle mesh to PLY file
+
+        :param path: Path to PLY file to write
+        """
+        vertex_element = self._save_vertex_data()
+        face_element = self._save_face_data()
+        Vertices._write_ply_data(path, [vertex_element, face_element])
+
+    @override
+    def transform(self, trafo: Trafo3d) -> None:
+        """Transform triangle mesh by rigid transformation
+
+        :param trafo: Transformation
+        """
+        super().transform(trafo)
+        if self.has_face_normals:
+            self._face_normals = self._face_normals @ trafo.rotation_matrix.T
+
+    @classmethod
+    def create_triangle(cls, colorize: bool = False) -> "TriangleMesh":
+        """Create triangle mesh consisting of a single triangle
+
+        :param colorize: If true, the triangle has different
+            vertex colors for each vertex
+        :returns: Resulting triangle mesh
+        """
+        vertices = np.array(
+            (
+                (1.0, 0.0, 0.0),
+                (0.0, 1.0, 0.0),
+                (0.0, 0.0, 0.0),
+            )
+        )
+        faces = np.array(((0, 1, 2),), dtype=int)
+        if colorize:
+            vertex_colors = np.array(
+                (
+                    (1.0, 0.0, 0.0),
+                    (0.0, 1.0, 0.0),
+                    (0.0, 0.0, 1.0),
+                )
+            )
+        else:
+            vertex_colors = None
+        return TriangleMesh(vertices=vertices, faces=faces, vertex_colors=vertex_colors)
+
+    @classmethod
+    def create_rectangle(
+        cls,
+        scale: float | ArrayLike = 1.0,
+        resolution: int | ArrayLike = (2, 2),
+    ) -> "TriangleMesh":
+        """Create a rectangular triangle mesh
+
+        Rectangle is located in X/Y plane and starts at (0.0, 0.0, 0.0) and
+        extends to (scale, scale, 0.0).
+
+        Default resolution is (2, 2), which creates a rectangle just consisting
+        of 4 vertices and 2 faces/triangles.
+
+        :param scale: Scale of rectangle for X and Y as single float or 2d
+        :param resolution: Number of points in X and Y
+        :returns: Resulting triangle mesh
+        """
+        if isinstance(scale, float):
+            scale = np.array((scale, scale))
+        else:
+            scale = np.asarray(scale)
+            if scale.size != 2:
+                raise Exception("Provide proper scale.")
+        if isinstance(resolution, int):
+            resolution = np.array((resolution, resolution), dtype=int)
+        else:
+            resolution = np.asarray(resolution, dtype=int)
+            if resolution.size != 2:
+                raise Exception("Provide proper resolution.")
+        # Generate vertices
+        xs = np.linspace(0.0, 1.0, resolution[0])
+        ys = np.linspace(0.0, 1.0, resolution[1])
+        xx, yy = np.meshgrid(xs, ys, indexing="xy")
+        vertices = np.empty((resolution[0] * resolution[1], 3))
+        vertices[:, 0] = scale[0] * xx.flatten()
+        vertices[:, 1] = scale[1] * yy.flatten()
+        vertices[:, 2] = 0.0
+        # Generate faces
+        i = np.arange(resolution[0] - 1)
+        j = np.arange(resolution[1] - 1)
+        ii, jj = np.meshgrid(i, j, indexing="xy")
+        base = jj.flatten() * resolution[0] + ii.flatten()
+        v0 = base
+        v1 = base + 1
+        v2 = base + resolution[0]
+        v3 = base + resolution[0] + 1
+        tri_bottom_left = np.stack([v0, v1, v2], axis=-1)
+        tri_top_right = np.stack([v1, v3, v2], axis=-1)
+        faces = np.vstack([tri_bottom_left, tri_top_right])
+        # Normals
+        vertex_normals = np.tile((0.0, 0.0, 1.0), (vertices.shape[0], 1))
+        face_normals = np.tile((0.0, 0.0, 1.0), (faces.shape[0], 1))
+        return TriangleMesh(
+            vertices=vertices,
+            faces=faces,
+            vertex_normals=vertex_normals,
+            face_normals=face_normals,
+        )
+
+    @classmethod
+    def create_function(
+        cls,
+        fun: Callable[[ArrayLike], ArrayLike],
+        scale: float | ArrayLike = 1.0,
+        resolution: int | ArrayLike = (2, 2),
+    ) -> "TriangleMesh":
+        """Create a rectangular triangle mesh in X/Y with Z being
+            determined by a function
+
+        Example to create nice sinus-shaped bump on a rectangle of shape (1.0, 1.0):
+
+        bump = TriangleMesh.create_function(
+            lambda xy: np.sin(np.pi * xy[:, 0]) * np.sin(np.pi * xy[:, 1]),
+            scale=1.0,
+            resolution=(20, 20),
+        )
+
+        :param fun: Function, input is xy values of shape (n, 2),
+            output z values shape (n,)
+        :param scale: Scale of rectangle for X and Y as single float or 2d
+        :param resolution: Number of points in X and Y
+        :returns: Resulting triangle mesh
+        """
+        result = cls.create_rectangle(scale, resolution)
+        result._vertices[:, 2] = fun(result._vertices[:, :2])
+        result.compute_vertex_normals()
+        return result
+
+    @classmethod
+    def create_image(
+        cls, image: np.ndarray, pixel_sizes_mm: tuple[float, float] = (1.0, 1.0)
+    ) -> "TriangleMesh":
+        """Create a rectangular triangle mesh displaying an image
+
+        According to OpenCV convention, X is to the right, Y is down and Z
+        looks away from the viewer of we look at the image; so in contrast
+        to create_rectangle, we look at the "backside" of the image; so we
+        have to re-order the faces and fix all normals vectors...
+
+        :param image: RGB image, shape (height, width, 3)
+        :param pixel_sizes_mm: Size of pixels in X/Y in unit mm
+        :returns: Resulting triangle mesh
+        """
+        if image.ndim != 3 or image.shape[2] != 3:
+            raise Exception("Provide image of shape (n, m, 3)")
+        shape = np.array(image.shape)[[1, 0]]
+        result = cls.create_rectangle(pixel_sizes_mm * shape, shape + 1)
+        result.face_colors = np.vstack((image.reshape((-1, 3)), image.reshape((-1, 3))))
+        result.faces[:, [0, 1]] = result.faces[:, [1, 0]]
+        result.normals = np.tile((0.0, 0.0, -1.0), (result.num_vertices, 1))
+        result.face_normals = np.tile((0.0, 0.0, -1.0), (result.num_faces, 1))
+        return result
+
+    @classmethod
+    def create_box(cls, scale: float | ArrayLike = 1.0) -> "TriangleMesh":
+        """Create a box shaped triangle mesh
+
+        Box has 8 vertices, 6 faces with 2 triangles each, thats 12 mesh faces.
+        Box starts at (0, 0, 0) and extends to (scale, scale, scale).
+
+        :param scale: Scale of rectangle for X, Y and Z as single float or 3d
+        :returns: Resulting triangle mesh
+        """
+        if isinstance(scale, float):
+            scale = np.array((scale, scale, scale))
+        else:
+            scale = np.asarray(scale)
+            if scale.size != 3:
+                raise Exception("Provide proper scale.")
+        vertices = scale * np.array(
+            [
+                [0.0, 0.0, 0.0],  # 0: bottom-back-left
+                [1.0, 0.0, 0.0],  # 1: bottom-back-right
+                [1.0, 1.0, 0.0],  # 2: bottom-front-right
+                [0.0, 1.0, 0.0],  # 3: bottom-front-left
+                [0.0, 0.0, 1.0],  # 4: top-back-left
+                [1.0, 0.0, 1.0],  # 5: top-back-right
+                [1.0, 1.0, 1.0],  # 6: top-front-right
+                [0.0, 1.0, 1.0],  # 7: top-front-left
+            ],
+            dtype=float,
+        )
+        faces = np.array(
+            [
+                # Bottom face
+                [0, 2, 1],
+                [0, 3, 2],
+                # Top face
+                [4, 5, 6],
+                [4, 6, 7],
+                # Front face
+                [3, 7, 6],
+                [3, 6, 2],
+                # Back face
+                [0, 1, 5],
+                [0, 5, 4],
+                # Left face
+                [0, 4, 7],
+                [0, 7, 3],
+                # Right face
+                [1, 2, 6],
+                [1, 6, 5],
+            ],
+            dtype=int,
+        )
+        result = cls(vertices=vertices, faces=faces)
+        result.compute_vertex_normals()
+        return result
+
+    @classmethod
+    def create_sphere(
+        cls, radius: float = 1.0, num_vertices: int = 500
+    ) -> "TriangleMesh":
+        """Create a sphere shaped triangle mesh
+
+        Usees Fibonacci sphere algorithm to create a number of points
+        evenly distributed on the surface of a sphere as vertices.
+
+        Center of sphere is at (0, 0, 0).
+
+        :param radius: Sphere radius
+        :param num_vertices: Number of vertices of sphere
+        :returns: Resulting triangle mesh
+        """
+        indices = np.arange(0, num_vertices, dtype=float)
+        phi = (1.0 + np.sqrt(5.0)) / 2.0
+        z = 1.0 - (2.0 * indices + 1.0) / num_vertices
+        radii = np.sqrt(1.0 - z * z)
+        theta = 2.0 * np.pi * indices / phi
+        x = radii * np.cos(theta)
+        y = radii * np.sin(theta)
+        vertices = np.stack([x, y, z], axis=-1)
+        # Compute the convex hull of those points to triangulate the vertices
+        hull = ConvexHull(vertices)
+        faces = hull.simplices.copy()
+        # Compute face normals and check for orientation of normals;
+        # fix if necessary by re-ordering the vertex indices in the face
+        v0 = vertices[faces[:, 0]]
+        v1 = vertices[faces[:, 1]]
+        v2 = vertices[faces[:, 2]]
+        edge1 = v1 - v0
+        edge2 = v2 - v0
+        face_normals = np.cross(edge1, edge2)
+        face_centroids = (v0 + v1 + v2) / 3.0
+        orientations = np.sum(face_normals * face_centroids, axis=1)
+        flip_mask = orientations < 0
+        faces[flip_mask] = faces[flip_mask][:, [0, 2, 1]]
+        result = cls(vertices=radius * vertices, faces=faces)
+        result.compute_vertex_normals()
+        return result
+
+    @classmethod
+    def create_cone(
+        cls,
+        radius: float = 1.0,
+        height: float = 1.0,
+        resolution: int = 20,
+        split: int = 4,
+    ) -> "TriangleMesh":
+        """Create cone shaped triangle mesh
+
+        The bottom of the cone is a circle with center (0, 0, 0) in the X/Y plane,
+        the tip of the cone is at (0, 0, height).
+
+        The split is splits the cone into multiple sections in Z direction. That
+        helps avoiding long thin triangles which may cause visualization problems.
+        Increase split if your cone is very long: height >> radius.
+
+        :param radius: Radius of circle at the bottom
+        :param height: Height of cone in +Z direction
+        :param resolution: Number of intersections of circle and side
+        :param split: Number of intersections in Z direction
+        :returns: Resulting triangle mesh
+        """
+        angles = np.linspace(0.0, 2 * np.pi, resolution + 1)[:-1]
+        # 1. Bottom Cap Center Vertex & Ring
+        bottom_center_idx = 0
+        bottom_ring_vertices = np.zeros((resolution, 3))
+        bottom_ring_vertices[:, 0] = radius * np.cos(angles)
+        bottom_ring_vertices[:, 1] = radius * np.sin(angles)
+        # 2. Lateral Surface Rings (from base to just below the tip)
+        lateral_vertices_list = [bottom_ring_vertices]
+        for s in range(1, split):
+            z = s * (height / split)
+            r = radius * (1.0 - s / split)
+            ring = np.zeros((resolution, 3))
+            ring[:, 0] = r * np.cos(angles)
+            ring[:, 1] = r * np.sin(angles)
+            ring[:, 2] = z
+            lateral_vertices_list.append(ring)
+        # Apex Vertex at the top
+        apex_vertex = np.array([[0.0, 0.0, height]])
+        # Combine all vertices
+        bottom_center_vertex = np.array([[0.0, 0.0, 0.0]])
+        vertices = np.vstack(
+            (bottom_center_vertex, *lateral_vertices_list, apex_vertex)
+        )
+        # Offset index helper for rings
+        # bottom_center_idx = 0
+        # ring s starts at: 1 + (s * resolution)
+        # apex vertex is at the very end
+        apex_idx = len(vertices) - 1
+        # 3. Faces
+        i = np.arange(resolution)
+        next_i = (i + 1) % resolution
+        # Bottom cap faces
+        bottom_faces = np.zeros((resolution, 3), dtype=int)
+        bottom_faces[:, 0] = bottom_center_idx
+        bottom_faces[:, 1] = 1 + next_i
+        bottom_faces[:, 2] = 1 + i
+        # Lateral faces between rings and up to the apex
+        lateral_faces_list = []
+        for s in range(split):
+            curr_ring_start = 1 + s * resolution
+            if s < split - 1:
+                next_ring_start = 1 + (s + 1) * resolution
+                # Quad split into 2 triangles for each resolution step
+                for j in range(resolution):
+                    nxt = (j + 1) % resolution
+                    v0 = curr_ring_start + j
+                    v1 = curr_ring_start + nxt
+                    v2 = next_ring_start + nxt
+                    v3 = next_ring_start + j
+                    lateral_faces_list.append([v0, v1, v2])
+                    lateral_faces_list.append([v0, v2, v3])
+            else:
+                # Top section connecting the last ring to the apex
+                for j in range(resolution):
+                    nxt = (j + 1) % resolution
+                    v0 = curr_ring_start + j
+                    v1 = curr_ring_start + nxt
+                    lateral_faces_list.append([v0, v1, apex_idx])
+        lateral_faces = np.array(lateral_faces_list, dtype=int)
+        result = cls(
+            vertices=vertices,
+            faces=np.vstack((bottom_faces, lateral_faces)),
+        )
+        result.compute_vertex_normals()
+        return result
+
+    @classmethod
+    def create_cylinder(
+        cls,
+        radius: float = 1.0,
+        height: float = 1.0,
+        resolution: int = 20,
+        split: int = 4,
+    ) -> "TriangleMesh":
+        """Create cylinder shaped triangle mesh
+
+        The bottom of the cylinder is a circle with center (0, 0, 0) in the X/Y plane,
+        the top is a circle with center (0, 0, height) in the X/Y plane.
+
+        The split is splits the cylinder into multiple sections in Z direction. That
+        helps avoiding long thin triangles which may cause visualization problems.
+        Increase split if your cylinder is very long: height >> radius.
+
+        :param radius: Radius of circles at the bottom and top
+        :param height: Height of cylinder in +Z direction
+        :param resolution: Number of intersections of circle and sides
+        :param split: Number of intersections in Z direction
+        :returns: Resulting triangle mesh
+        """
+        # Ensure split is at least 1
+        split = max(1, split)
+        # Vertices for all levels along the height
+        angles = np.linspace(0.0, 2 * np.pi, resolution + 1)[:-1]
+        z_coords = np.linspace(0, height, split + 1)
+        ring_vertices = np.zeros((resolution, 3))
+        ring_vertices[:, 0] = radius * np.cos(angles)
+        ring_vertices[:, 1] = radius * np.sin(angles)
+        all_vertices = []
+        for z in z_coords:
+            v = ring_vertices.copy()
+            v[:, 2] = z
+            all_vertices.append(v)
+        # Center vertices for bottom and top caps
+        center_vertices = np.array(
+            (
+                (0.0, 0.0, 0.0),
+                (0.0, 0.0, height),
+            )
+        )
+        all_vertices.append(center_vertices)
+        vertices = np.vstack(all_vertices)
+        # Faces
+        i = np.arange(resolution)
+        next_i = (i + 1) % resolution
+        side_faces = []
+        for s in range(split):
+            base_idx = s * resolution
+            next_base_idx = (s + 1) * resolution
+            side_faces1 = np.zeros((resolution, 3), dtype=int)
+            side_faces1[:, 0] = base_idx + i
+            side_faces1[:, 1] = base_idx + next_i
+            side_faces1[:, 2] = next_base_idx + next_i
+            side_faces2 = np.zeros((resolution, 3), dtype=int)
+            side_faces2[:, 0] = base_idx + i
+            side_faces2[:, 1] = next_base_idx + next_i
+            side_faces2[:, 2] = next_base_idx + i
+            side_faces.append(side_faces1)
+            side_faces.append(side_faces2)
+        side_faces_array = np.vstack(side_faces)
+        # Bottom and top cap faces
+        bottom_center_idx = (split + 1) * resolution
+        top_center_idx = (split + 1) * resolution + 1
+        bottom_faces = np.zeros((resolution, 3), dtype=int)
+        bottom_faces[:, 0] = bottom_center_idx
+        bottom_faces[:, 1] = next_i
+        bottom_faces[:, 2] = i
+        top_top_base = split * resolution
+        top_faces = np.zeros((resolution, 3), dtype=int)
+        top_faces[:, 0] = top_center_idx
+        top_faces[:, 1] = top_top_base + i
+        top_faces[:, 2] = top_top_base + next_i
+        result = cls(
+            vertices=vertices,
+            faces=np.vstack((side_faces_array, bottom_faces, top_faces)),
+        )
+        result.compute_vertex_normals()
+        return result
+
+    @classmethod
+    def create_arrow(
+        cls,
+        cylinder_radius: float = 1.0,
+        cone_radius: float = 1.5,
+        cylinder_height: float = 5.0,
+        cone_height: float = 4.0,
+        resolution: int = 20,
+        cylinder_split: int = 4,
+        cone_split: int = 1,
+    ) -> "TriangleMesh":
+        """Create coordinate axis shaped triangle mesh
+
+        The bottom of the coordinate axis is a cylinder, the top is a cone.
+
+        :param cylinder_radius: Radius of the cylinder
+        :param cone_radius: Radius of the cone
+        :param cylinder_height: Height of cylinder
+        :param cone_height: Height of cone
+        :param resolution: Number of intersection of cylinder and cone
+        :param cylinder_split: Number of intersections in Z direction for cylinder
+        :param cone_split: Number of intersections in Z direction for cone
+        :returns: Resulting triangle mesh
+        """
+        cylinder = cls.create_cylinder(
+            cylinder_radius, cylinder_height, resolution, cylinder_split
+        )
+        cone = cls.create_cone(cone_radius, cone_height, resolution, cone_split)
+        cone.translate((0.0, 0.0, cylinder_height))
+        return cylinder + cone
+
+    @classmethod
+    def create_coordinate_frame(
+        cls, size: float = 1.0, pose: Trafo3d | None = None
+    ) -> "TriangleMesh":
+        """Create coordinate frame of a right-handed coordinate system
+
+        A single coordinate axis is an arrow that consists of a cylinder
+        with a cone as the tip. The three axes have colors red (X),
+        green (Y) and blue (Z).
+
+        :param size: Length of a single axis
+        :param pose: 6d pose of the coordinate system
+        :returns: Resulting triangle mesh
+        """
+        cylinder_radius = size / 40.0
+        cone_radius = 1.5 * cylinder_radius
+        cylinder_height = 0.9 * size
+        cone_height = 0.1 * size
+        x_axis = cls.create_arrow(
+            cylinder_radius, cone_radius, cylinder_height, cone_height
+        )
+        x_axis.paint_uniform_color((1.0, 0.0, 0.0))  # red
+        x_axis.transform(Trafo3d(rpy=(0.0, np.pi / 2, 0.0)))
+        y_axis = cls.create_arrow(
+            cylinder_radius, cone_radius, cylinder_height, cone_height
+        )
+        y_axis.paint_uniform_color((0.0, 1.0, 0.0))  # green
+        y_axis.transform(Trafo3d(rpy=(-np.pi / 2, 0.0, 0.0)))
+        z_axis = cls.create_arrow(
+            cylinder_radius, cone_radius, cylinder_height, cone_height
+        )
+        z_axis.paint_uniform_color((0.0, 0.0, 1.0))  # blue
+        cs = x_axis + y_axis + z_axis
+        if pose is not None:
+            cs.transform(pose)
+        return cs
+
+    @classmethod
+    def create_from_point_cloud_poisson(
+        cls,
+        pcl: PointCloud,
+        depth: int = 8,
+    ) -> "TriangleMesh":
+        raise NotImplementedError
+
+    def _select_by_vertices(self, inlier_mask_or_indices: np.ndarray) -> None:
+        """Select part of a triangle mesh referenced by vertices, helper function
+
+        Selects vertices, (vertex) normals and (vertex) colors, the last
+        two if they are available. Fixes vertex indices in faces due to
+        removed vertex indices.
+
+        :param inlier_mask_or_indices: Either boolean mask or indices
+        """
+        # Select vertices
+        self._vertices = self._vertices[inlier_mask_or_indices]
+        if self.has_normals:
+            self._normals = self._normals[inlier_mask_or_indices]
+        if self.has_colors:
+            self._colors = self._colors[inlier_mask_or_indices]
+        # Fix the vertex indexing in faces due to removed vertices
+        old_to_new_vertex_indices = np.cumsum(inlier_mask_or_indices) - 1
+        self._faces = old_to_new_vertex_indices[self._faces]
+
+    def select_by_vertices(self, inlier_mask_or_indices: np.ndarray) -> None:
+        """Select part of a triangle mesh referenced by by vertices
+
+        Selects vertices, (vertex) normals and (vertex) colors, the last
+        two if they are available. Fixes vertex indices in faces due to
+        removed vertex indices. Removes faces that contained those vertices.
+        Removes unreferenced vertices because those faces were removed.
+
+        :param inlier_mask_or_indices: Either boolean mask or indices
+        """
+        # If inlier_mask_or_indices is not a mask, convert it into one
+        if not isinstance(inlier_mask_or_indices[0], bool):
+            mask = np.zeros(self.num_vertices, dtype=bool)
+            mask[inlier_mask_or_indices] = True
+            inlier_mask_or_indices = mask
+        inlier_mask_faces = np.all(inlier_mask_or_indices[self._faces], axis=1)
+        # Remove vertices
+        self._select_by_vertices(inlier_mask_or_indices)
+        # Remove all faces that contained those vertices
+        self._select_by_faces(inlier_mask_faces)
+        # By removing those faces, there may be some unreferenced vertices
+        self.remove_unreferenced_vertices()
+
+    def get_selected_by_vertices(
+        self, inlier_mask_or_indices: np.ndarray
+    ) -> "TriangleMesh":
+        """Select part of a triangle mesh referenced by by vertices and
+            return as new triangle mesh
+
+        Selects vertices, (vertex) normals and (vertex) colors, the last
+        two if they are available. Fixes vertex indices in faces due to
+        removed vertex indices. Removes faces that contained those vertices.
+        Removes unreferenced vertices because those faces were removed.
+
+        :param inlier_mask_or_indices: Either boolean mask or indices
+        :returns: Resulting triangle mesh
+        """
+        result = self.copy()
+        result.select_by_vertices(inlier_mask_or_indices)
+        return result
+
+    def _select_by_faces(self, inlier_mask_or_indices: np.ndarray) -> None:
+        """Select part of a triangle mesh referenced by faces, helper function
+
+        Selects faces, face normals and faces colors, the last
+        two if they are available.
+
+        :param inlier_mask_or_indices: Either boolean mask or indices
+        """
+        self._faces = self._faces[inlier_mask_or_indices]
+        if self.has_face_normals:
+            self._face_normals = self._face_normals[inlier_mask_or_indices]
+        if self.has_face_colors:
+            self._face_colors = self._face_colors[inlier_mask_or_indices]
+
+    def select_by_faces(self, inlier_mask_or_indices: np.ndarray) -> None:
+        """Select part of a triangle mesh referenced by faces
+
+        Selects faces, face normals and faces colors, the last
+        two if they are available. Removes unreferenced vertices
+        because those faces were removed.
+
+        :param inlier_mask_or_indices: Either boolean mask or indices
+        """
+        self._select_by_faces(inlier_mask_or_indices)
+        self.remove_unreferenced_vertices()
+
+    def get_selected_by_faces(
+        self, inlier_mask_or_indices: np.ndarray
+    ) -> "TriangleMesh":
+        """Select part of a triangle mesh referenced by faces and
+            return as new triangle mesh
+
+        Selects faces, face normals and faces colors, the last
+        two if they are available. Removes unreferenced vertices
+        because those faces were removed.
+
+        :param inlier_mask_or_indices: Either boolean mask or indices
+        :returns: Resulting triangle mesh
+        """
+        result = self.copy()
+        result.select_by_faces(inlier_mask_or_indices)
+        return result
+
+    def remove_unreferenced_vertices(self) -> None:
+        """Removes unreferenced vertices
+
+        Removes vertices that are not referenced in faces
+        """
+        unique_vertices = np.unique(self._faces)
+        inlier_mask = np.zeros(self.num_vertices, dtype=bool)
+        inlier_mask[unique_vertices] = True
+        self._select_by_vertices(inlier_mask)
+
+    def remove_duplicate_vertices(self, tolerance: float = 1e-8) -> None:
+        """Merge duplicate or nearly identical vertices.
+
+        Vertices within the specified Euclidean distance are merged.
+        Vertex attributes are averaged. Degenerate faces created by
+        merging vertices are removed.
+
+        :param tolerance: Maximum distance between vertices to merge.
+        """
+        if self.empty:
+            return
+        # Find vertex pairs within tolerance
+        tree = self.kdtree()
+        pairs = tree.query_pairs(tolerance, output_type="ndarray")
+        if len(pairs) == 0:
+            return
+        # Group duplicate vertices using union-find
+        parent = np.arange(self.num_vertices)
+
+        def find(x):
+            while parent[x] != x:
+                parent[x] = parent[parent[x]]
+                x = parent[x]
+            return x
+
+        for a, b in pairs:
+            root_a = find(a)
+            root_b = find(b)
+            if root_a != root_b:
+                parent[root_b] = root_a
+        roots = np.array([find(i) for i in range(self.num_vertices)])
+        # Determine unique vertices and their groups
+        _, vertex_mapping = np.unique(roots, return_inverse=True)
+        # Identify first occurrence of each vertex
+        vertex_indices = np.unique(vertex_mapping, return_index=True)[1]
+        # Average vertex attributes within each group
+        n_unique = len(vertex_indices)
+        counts = np.bincount(vertex_mapping)
+        vertices_new = np.zeros((n_unique, 3))
+        np.add.at(vertices_new, vertex_mapping, self._vertices)
+        vertices_new /= counts[:, None]
+        # Average vertex normals if available
+        if self.has_normals:
+            normals = np.zeros((n_unique, 3))
+            np.add.at(normals, vertex_mapping, self._normals)
+            normals /= counts[:, None]
+            lengths = np.linalg.norm(normals, axis=1, keepdims=True)
+            normals = np.divide(
+                normals, lengths, out=np.zeros_like(normals), where=lengths > 0
+            )
+            self._normals = normals
+        # Average vertex colors if available
+        if self.has_colors:
+            colors = np.zeros((n_unique, *self._colors.shape[1:]))
+            np.add.at(colors, vertex_mapping, self._colors)
+            colors /= counts.reshape((-1,) + (1,) * (colors.ndim - 1))
+            self._colors = colors
+        # Select unique vertices
+        self._vertices = vertices_new
+        # Update face indices
+        self._faces = vertex_mapping[self._faces]
+        # Remove degenerate faces
+        valid_faces = (
+            (self._faces[:, 0] != self._faces[:, 1])
+            & (self._faces[:, 1] != self._faces[:, 2])
+            & (self._faces[:, 2] != self._faces[:, 0])
+        )
+        self._select_by_faces(valid_faces)
+
+    def remove_duplicate_faces(self) -> None:
+        """Remove duplicate faces from the triangle mesh.
+
+        Faces are considered duplicates if they reference the same three
+        vertices, regardless of vertex ordering.
+
+        Keeps the first occurrence of each unique face.
+        """
+        if self.num_faces == 0:
+            return
+        # Sort vertex indices to obtain a canonical face representation
+        sorted_faces = np.sort(self._faces, axis=1)
+        # Find unique faces and retain their first occurrences
+        _, indices = np.unique(sorted_faces, axis=0, return_index=True)
+        # Create mask preserving the original face ordering
+        face_mask = np.zeros(len(self._faces), dtype=bool)
+        face_mask[indices] = True
+        # Select unique faces and update associated face attributes
+        self._select_by_faces(face_mask)
+
+    def remove_degenerated_faces(self, area_tolerance: float = 1e-8) -> None:
+        """Removes degenerate faces
+
+        Removes degenerated faces which are faces where two or more
+        vertices are coincident, resulting in zero area.
+        """
+        areas = self.face_areas()
+        inlier_mask = areas >= area_tolerance
+        self.select_by_faces(inlier_mask)
+
+    def compute_vertex_normals(self) -> None:
+        """Compute vertex normals
+
+        Computes face normals first. Then for each vertex computes mean
+        normal from all face normals of adjacent faces.
+
+        Normalizes vertex normals, too. If any vertex normal has a zero size
+        an exception is thrown. Clean up mesh first.
+        """
+        self.compute_face_normals()
+        self._normals = np.zeros_like(self._vertices)
+        np.add.at(self._normals, self._faces[:, 0], self._face_normals)
+        np.add.at(self._normals, self._faces[:, 1], self._face_normals)
+        np.add.at(self._normals, self._faces[:, 2], self._face_normals)
+        # Normalize vertex normals
+        lengths = np.sqrt(
+            self._normals[:, 0] ** 2
+            + self._normals[:, 1] ** 2
+            + self._normals[:, 2] ** 2
+        )
+        if np.any(np.isclose(lengths, 0.0)):
+            raise Exception("Some normals have zero lengths")
+        self._normals = self._normals / lengths[:, None]
+
+    def compute_face_normals(self) -> None:
+        """Compute face normals
+
+        Computes normal vector of each face.
+
+        Orientation of normals vector is determined by order of vertices,
+        normal vector is cross product of vectors v0 to v1 and v0 to v2.
+
+        Normalizes face normals, too. If any face normal has a zero size
+        (which may happen if there are degenerate faces), an exception
+        is thrown. Clean up mesh first.
+        """
+        v0 = self._vertices[self._faces[:, 0]]
+        v1 = self._vertices[self._faces[:, 1]]
+        v2 = self._vertices[self._faces[:, 2]]
+        cross_products = np.cross(v1 - v0, v2 - v0)
+        lengths = np.sqrt(
+            cross_products[:, 0] ** 2
+            + cross_products[:, 1] ** 2
+            + cross_products[:, 2] ** 2
+        )
+        if np.any(np.isclose(lengths, 0.0)):
+            raise Exception(
+                "Some normals have zero lengths, there may be "
+                "degenerated triangles in the mesh"
+            )
+        self._face_normals = cross_products / lengths[:, None]
+
+    def compute_vertex_adjacency(self) -> None:
+        """Computes vertex adjacency: neighbor vertices of a vertex."""
+        i0, i1, i2 = self._faces[:, 0], self._faces[:, 1], self._faces[:, 2]
+        rows = np.concatenate([i0, i1, i2])
+        cols = np.concatenate([i1, i2, i0])
+        rows_ = np.concatenate([rows, cols])  # Ensure symmetry of matrix
+        cols_ = np.concatenate([cols, rows])
+        self._vertex_adjacency = coo_array(
+            (np.ones(rows_.shape[0], dtype=bool), (rows_, cols_)),
+            shape=(self.num_vertices, self.num_vertices),
+        ).tocsr()
+        assert self._vertex_adjacency is not None
+        self._vertex_adjacency.sum_duplicates()
+        self._vertex_adjacency.setdiag(False)
+        self._vertex_adjacency.eliminate_zeros()
+
+    @property
+    def vertex_adjacency(self) -> csr_array:
+        """Get the neighbor vertices of all vertices
+
+        :returns: Neighbor vertices of all vertices
+        """
+        if self._vertex_adjacency is None:
+            raise Exception("Compute vertex adjacency first")
+        return self._vertex_adjacency
+
+    def get_adjacent_vertices(self, vertex_index: int) -> list[int]:
+        """Get the neighbor vertices of a single vertex
+
+        :param vertex_index: Vertex index
+        :returns: List of neighbor vertices
+        """
+        if self._vertex_adjacency is None:
+            raise Exception("Compute vertex adjacency first")
+        if not 0 <= vertex_index < self.num_vertices:
+            raise IndexError(f"Vertex index {vertex_index} is out of range")
+        # The indptr/indices slicing is the most efficient because it avoids
+        # constructing any intermediate sparse object; it's the standard
+        # CSR idiom. Compacter is self._adjacency[[vertex_index]].indices
+        # but it is less fast.
+        start = self._vertex_adjacency.indptr[vertex_index]
+        end = self._vertex_adjacency.indptr[vertex_index + 1]
+        return self._vertex_adjacency.indices[start:end].tolist()
+
+    def compute_vertex_face_incidence(self) -> None:
+        """Compute vertex-face incidences: incident faces of a vertex."""
+        vertices = self._faces.reshape(-1)
+        faces = np.repeat(np.arange(self.num_faces), 3)
+        self._vertex_face_incidence = coo_array(
+            (
+                np.ones(vertices.size, dtype=bool),
+                (vertices, faces),
+            ),
+            shape=(self.num_vertices, self.num_faces),
+        ).tocsr()
+        # Normally unnecessary for valid triangle meshes, but keeps the matrix
+        # well-formed if a face contains a repeated vertex.
+        assert self._vertex_face_incidence is not None
+        self._vertex_face_incidence.sum_duplicates()
+        self._vertex_face_incidence.data[:] = True
+
+    @property
+    def vertex_face_incidence(self):
+        """Get the incident faces of all vertices
+
+        :returns: Incident faces of all vertices
+        """
+        if self._vertex_face_incidence is None:
+            raise RuntimeError("Compute vertex-face incidence first")
+        return self._vertex_face_incidence
+
+    def get_incident_faces(self, vertex_index: int) -> list[int]:
+        """Get the incident faces of a single vertex
+
+        :param vertex_index: Vertex index
+        :returns: List of incident faces
+        """
+        if self._vertex_face_incidence is None:
+            raise RuntimeError("Compute vertex-face incidence first")
+        if not 0 <= vertex_index < self.num_vertices:
+            raise IndexError(f"Vertex index {vertex_index} is out of range")
+        start = self._vertex_face_incidence.indptr[vertex_index]
+        end = self._vertex_face_incidence.indptr[vertex_index + 1]
+        return self._vertex_face_incidence.indices[start:end].tolist()
+
+    def get_unique_edges(self) -> np.ndarray:
+        """Get unique edges of a mesh
+
+        Compute all edges, ensuring that the result contains each undirected edge
+        only once; The output is sorted lexicographically by vertex index
+
+        :returns: Unique edges of mesh
+        """
+        edges = np.concatenate(
+            [self._faces[:, [0, 1]], self._faces[:, [1, 2]], self._faces[:, [2, 0]]],
+            axis=0,
+        )
+        edges.sort(axis=1)
+        return np.unique(edges, axis=0)
+
+    def compute_laplacian(self) -> csr_array:
+        """Computes the combinatorial graph Laplacian matrix
+
+        The combinatorial graph Laplacian matrix L is difference of the degree
+        matrix D (every element of the diagonal contains the number of
+        connections a vertex has to other vertices) and the adjacency matrix A;
+        because in a mesh A is symmetric, L is symmetric too.
+
+        :returns: Combinatorial graph Laplacian matrix
+        """
+        if self._vertex_adjacency is None:
+            self.compute_vertex_adjacency()
+        adjacency = self._vertex_adjacency
+        assert adjacency is not None
+        degrees = np.asarray(adjacency.sum(axis=1)).ravel()
+        return csr_array(diags(degrees, dtype=float, format="csr") - adjacency)
+
+    def compute_cotangent_laplacian(self) -> csr_array:
+        """Computes the cotangent Laplacian matrix
+
+        :returns: cotangent Laplacian matrix
+        """
+        # Compute double triangle areas
+        i0, i1, i2 = self._faces.T
+        v0 = self._vertices[i0]
+        v1 = self._vertices[i1]
+        v2 = self._vertices[i2]
+        e0 = v2 - v1
+        e1 = v0 - v2
+        e2 = v1 - v0
+        cross = np.cross(e0, -e2)
+        double_area = np.linalg.norm(cross, axis=1)
+        if np.any(np.isclose(double_area, 0.0)):
+            raise Exception("Some triangles have zero area")
+        # Compute cotangents of opposite angles
+        cot0 = np.einsum("ij,ij->i", -e1, -e2) / double_area
+        cot1 = np.einsum("ij,ij->i", -e2, -e0) / double_area
+        cot2 = np.einsum("ij,ij->i", -e0, -e1) / double_area
+        # Construct symmetric cotangent weights
+        rows = np.concatenate([i1, i2, i2, i0, i0, i1])
+        cols = np.concatenate([i2, i1, i0, i2, i1, i0])
+        weights = 0.5 * np.concatenate(
+            [
+                cot0,
+                cot0,
+                cot1,
+                cot1,
+                cot2,
+                cot2,
+            ]
+        )
+        # Construct off-diagonal entries
+        L = coo_array(
+            (weights, (rows, cols)),
+            shape=(self.num_vertices, self.num_vertices),
+        ).tocsr()
+        L.sum_duplicates()
+        # Set diagonal entries to ensure zero row sums
+        L.setdiag(-np.asarray(L.sum(axis=1)).ravel())
+        return L.tocsr()
+
+    def compute_mass_matrix(self) -> csr_array:
+        """Computes the lumped barycentric mass matrix
+
+        :returns: Lumped barycentric mass matrix
+        """
+        i0, i1, i2 = self._faces.T
+        v0 = self._vertices[i0]
+        v1 = self._vertices[i1]
+        v2 = self._vertices[i2]
+        areas = 0.5 * np.linalg.norm(
+            np.cross(v1 - v0, v2 - v0),
+            axis=1,
+        )
+        vertex_areas = np.zeros(self.num_vertices)
+        np.add.at(vertex_areas, i0, areas / 3.0)
+        np.add.at(vertex_areas, i1, areas / 3.0)
+        np.add.at(vertex_areas, i2, areas / 3.0)
+        return csr_array(diags(vertex_areas, format="csr"))
+
+    def face_areas(self) -> np.ndarray:
+        """Get face areas
+
+        :returns: Face areas
+        """
+        v0 = self._vertices[self._faces[:, 0]]
+        v1 = self._vertices[self._faces[:, 1]]
+        v2 = self._vertices[self._faces[:, 2]]
+        cross_products = np.cross(v1 - v0, v2 - v0)
+        lengths = np.sqrt(
+            cross_products[:, 0] ** 2
+            + cross_products[:, 1] ** 2
+            + cross_products[:, 2] ** 2
+        )
+        return 0.5 * lengths
+
+    def smoothness(self) -> tuple[float, np.ndarray]:
+        """Computes global and per-vertex geometric smoothness.
+
+        Smoothness is measured using the cotangent Laplacian and the
+        lumped mass matrix, approximating the Laplace-Beltrami operator.
+
+        The first result is the global smoothness, normalized by the
+        total surface area (area-weighted mean squared curvature).
+        The second result contains the per-vertex curvature magnitudes.
+
+        Small per-vertex values indicate locally flatter geometry,
+        while large values indicate stronger local curvature.
+
+        The measure is not scale-invariant. For example, scaling a
+        mesh by a factor of 2 reduces its normalized squared-curvature
+        measure by a factor of 4.
+
+        :returns: A tuple containing global smoothness and per-vertex
+            curvature magnitudes.
+        """
+        L = self.compute_cotangent_laplacian()
+        M = self.compute_mass_matrix()
+        laplacian_vectors = spsolve(M, L @ self._vertices)
+        smoothness_per_vertex = np.linalg.norm(laplacian_vectors, axis=1)
+        vertex_areas = M.diagonal()
+        global_smoothness = np.sum(vertex_areas * smoothness_per_vertex**2) / np.sum(
+            vertex_areas
+        )
+        return global_smoothness, smoothness_per_vertex
+
+    def sample_random_surface_points(
+        self,
+        num_points: int,
+        rng: np.random.Generator | None = None,
+    ) -> PointCloud:
+        """Samples a number of random points on the surface of the mesh
+
+        The points are uniformly distributed over the surface.
+
+        :param num_points: Number of points to sample
+        :param rng: NumPy random number generator
+        :returns: Resulting point cloud
+        """
+        if rng is None:
+            rng = np.random.default_rng()
+        # Pick faces proportional to area
+        areas = self.face_areas()
+        face_indices = rng.choice(
+            self.num_faces, size=num_points, p=areas / np.sum(areas)
+        )
+        # Uniform barycentric sampling within each picked triangle
+        r1 = np.sqrt(rng.random(num_points))
+        r2 = rng.random(num_points)
+        a = 1 - r1
+        b = r1 * (1 - r2)
+        c = r1 * r2
+        # Interpolate vertices
+        v0 = self._vertices[self._faces[face_indices, 0]]
+        v1 = self._vertices[self._faces[face_indices, 1]]
+        v2 = self._vertices[self._faces[face_indices, 2]]
+        vertices = a[:, None] * v0 + b[:, None] * v1 + c[:, None] * v2
+        # Interpolate normals
+        if self.has_normals:
+            n0 = self._normals[self._faces[face_indices, 0]]
+            n1 = self._normals[self._faces[face_indices, 1]]
+            n2 = self._normals[self._faces[face_indices, 2]]
+            normals = a[:, None] * n0 + b[:, None] * n1 + c[:, None] * n2
+        elif self.has_face_normals:
+            normals = self._face_normals[face_indices]
+        else:
+            normals = None
+        # Interpolate colors
+        if self.has_colors:
+            c0 = self._colors[self._faces[face_indices, 0]]
+            c1 = self._colors[self._faces[face_indices, 1]]
+            c2 = self._colors[self._faces[face_indices, 2]]
+            colors = a[:, None] * c0 + b[:, None] * c1 + c[:, None] * c2
+        elif self.has_face_colors:
+            colors = self._face_colors[face_indices]
+        else:
+            colors = None
+        return PointCloud(vertices, normals, colors)
+
+    def distances(
+        self,
+        other: "ArrayLike | PointCloud",
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Computes unsigned distance between triangle mesh and points
+
+        :param other: Points or point cloud of n points
+        :returns: Unsigned distances, shape (n,)
+        """
+        mesh = pyembree2.triangle_mesh(
+            vertices=np.ascontiguousarray(self.vertices),
+            faces=np.ascontiguousarray(self.faces),
+        )
+        if isinstance(other, PointCloud):
+            query_points = other.vertices
+        else:
+            query_points = np.asarray(other)
+        _, face_indices, points, unsigned_distances = pyembree2.unsigned_distance(
+            meshes=[mesh], points=np.ascontiguousarray(query_points)
+        )
+        return unsigned_distances, face_indices, points
+
+    def signed_distances(
+        self,
+        other: "ArrayLike | PointCloud",
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Computes signed distance between triangle mesh and points
+
+        :param other: Points or point cloud of n points
+        :returns: Signed distances, shape (n,)
+        """
+        if not self.has_normals:
+            raise Exception("Computation of signed distances needs vertex normals")
+        mesh = pyembree2.triangle_mesh(
+            vertices=np.ascontiguousarray(self.vertices),
+            faces=np.ascontiguousarray(self.faces),
+            vertex_normals=np.ascontiguousarray(self.normals),
+        )
+        if isinstance(other, PointCloud):
+            query_points = other.vertices
+        else:
+            query_points = np.asarray(other)
+        _, face_indices, points, signed_distances = pyembree2.signed_distance(
+            meshes=[mesh], points=np.ascontiguousarray(query_points)
+        )
+        return signed_distances, face_indices, points
+
+    def colorize_faces_by_scalar(
+        self,
+        scalars: ArrayLike,
+        cmap: str = "viridis",
+        min_max: tuple[float, float] | None = None,
+        nan_color: tuple[float, float, float] = (1, 0, 0),
+    ) -> None:
+        """Colorizes mesh faces by scalar
+
+        :param scalars: Scalar values, length has to match number of faces
+        :param cmap: Matplotlib color map string
+        :param min_max: Minimum and maximum
+        :param nan_color: Color for NaN values, RGB values [0..1]
+        """
+        scalars = np.asarray(scalars)
+        if scalars.ndim != 1 or scalars.size != self.num_faces:
+            raise Exception("Provide correct number of values to colorize faces")
+        self._face_colors = scalar_to_color(scalars, cmap, min_max, nan_color)
+
+    def colorize_faces_by_scalar_bicolor(
+        self,
+        scalars: ArrayLike,
+        cmaps: tuple[str, str] = ("Blues", "Reds"),
+        vmax: float | None = None,
+        nan_color: tuple[float, float, float] = (0, 1, 0),
+    ) -> None:
+        """Colorizes mesh faces by scalar, pos/neg in separate colors
+
+        :param scalars: Scalar values, length has to match number of faces
+        :param cmaps: Matplotlib color map strings for pos/neg
+        :param vmax: Maximum (pos/neg) value
+        :param nan_color: Color for NaN values, RGB values [0..1]
+        """
+        scalars = np.asarray(scalars)
+        if scalars.ndim != 1 or scalars.size != self.num_faces:
+            raise Exception("Provide correct number of values to colorize faces")
+        self._face_colors = scalar_to_bicolor(scalars, cmaps, vmax, nan_color)
+
+    def icp(
+        self,
+        other: "ArrayLike | PointCloud",
+        max_iterations: int = 1000,
+        tolerance: float = 1e-6,
+    ) -> Trafo3d:
+        """Register a point cloud to the mesh using Iterative Closest Point (ICP)
+
+        Uses the iterative closest point algorithm (ICP) to register a
+        point cloud to the triangle mesh.
+
+        :param other: Points or point cloud
+        :param max_iterations: Number maximum number of iterations
+        :param tolerance: If mean distance improvement from iteration to
+            iteration is smaller than tolerance, stop iteration
+        :returns: Transformation from self to other
+        """
+        if isinstance(other, PointCloud):
+            other = other.vertices
+        else:
+            other = np.asarray(other)
+        dst = other.copy()
+        prev_err = np.inf
+        for _ in range(max_iterations):
+            distances, _, closest_points = self.distances(dst)
+            trafo = PointCloud(closest_points).estimate_transform(dst)
+            dst = trafo * dst
+            err = np.abs(np.mean(distances))
+            if np.abs(prev_err - err) < tolerance:
+                break
+            prev_err = err
+        return PointCloud(other).estimate_transform(dst).inverse
+
+    def cluster_by_connectivity(self, min_faces: int = 0) -> list["TriangleMesh"]:
+        """Split the mesh into connected components based on vertex connectivity
+
+        :param min_faces: Minimum number of faces required for a mesh to be included;
+            Meshes with fewer faces are discarded
+        :returns: Resulting meshes
+        """
+        if min_faces < 0:
+            raise ValueError("min_faces must be non-negative")
+        if self._vertex_adjacency is None:
+            self.compute_vertex_adjacency()
+        assert self._vertex_adjacency is not None
+        # Find connected components
+        n_components, labels = connected_components(
+            self._vertex_adjacency, directed=False, return_labels=True
+        )
+        # Assign each face to its corresponding component
+        face_labels = labels[self._faces[:, 0]]
+        # Count faces per component
+        face_counts = np.bincount(face_labels, minlength=n_components)
+        # Select components satisfying the minimum face count
+        valid_components = np.flatnonzero(face_counts >= min_faces)
+        # Collect meshes
+        meshes = []
+        for component in valid_components:
+            # Get vertices and faces belonging to this component
+            vertex_mask = labels == component
+            face_mask = face_labels == component
+            component_vertices = self._vertices[vertex_mask]
+            component_faces = self._faces[face_mask]
+            # Remap face indices to the new vertex array
+            vertex_indices = np.full(len(self._vertices), -1, dtype=int)
+            vertex_indices[vertex_mask] = np.arange(np.count_nonzero(vertex_mask))
+            component_faces = vertex_indices[component_faces]
+            # Create new TriangleMesh
+            mesh = TriangleMesh(vertices=component_vertices, faces=component_faces)
+            meshes.append(mesh)
+        return meshes
+
+    def smooth_explicit(self, iterations: int = 10, lam: float = 0.1) -> None:
+        """Smooth the mesh using explicit Laplacian smoothing.
+
+        Vertex positions are iteratively updated by moving each vertex in the
+        direction of its discrete Laplacian. The Laplacian is computed using the
+        cotangent discretization of the Laplace-Beltrami operator and normalized
+        by the vertex mass matrix.
+
+        At each iteration, the following linear system is solved to determine
+        the vertex displacements:
+
+            M * delta = L * V
+
+        The vertex positions are then updated explicitly:
+
+            V_new = V_old - lam * delta
+
+        where:
+            L : Cotangent stiffness matrix
+            M : Diagonal vertex mass matrix
+            V : Vertex position matrix (n_vertices x 3)
+            delta : Discrete Laplacian displacement
+            lam : Smoothing step size
+
+        Since the update is explicit, the smoothing step size must be
+        sufficiently small to ensure numerical stability. Repeated smoothing
+        generally reduces high-frequency surface variations but also causes
+        the mesh to shrink and geometric details to be lost.
+
+        The mass matrix accounts for the local vertex areas and provides a
+        geometry-aware normalization of the cotangent Laplacian. Unlike
+        implicit Laplacian smoothing, this method computes the displacement
+        from the current vertex positions before updating them, rather than
+        solving directly for the new vertex positions.
+
+        :param iterations: Number of smoothing iterations
+        :param lam: Smoothing step size Larger values produce stronger
+            smoothing per iteration but may lead to numerical instability
+        """
+        L = self.compute_cotangent_laplacian()
+        M = self.compute_mass_matrix()
+        V = self._vertices.copy()
+        for _ in range(iterations):
+            rhs = L @ V
+            delta = spsolve(M, rhs)
+            V -= lam * delta
+        self._vertices = V
+
+    def smooth_implicit(self, iterations: int = 10, lam: float = 1.0) -> None:
+        """Smooth the mesh using implicit Laplacian smoothing.
+
+        Vertex positions are iteratively updated by solving a sparse linear
+        system. Unlike explicit smoothing, the new vertex positions are
+        determined implicitly from the smoothing equation.
+
+        The update is obtained by solving:
+
+            (M + lam * L) * V_new = M * V_old
+
+        where:
+            L : Cotangent stiffness matrix
+            M : Diagonal vertex mass matrix
+            V_old : Vertex positions before the update
+            V_new : Updated vertex positions
+            lam : Smoothing parameter
+
+        The mass matrix provides area-weighted normalization, while the
+        cotangent stiffness matrix describes the local mesh connectivity and
+        geometry.
+
+        Implicit integration is generally more numerically stable than explicit
+        integration and permits larger smoothing parameters without the same
+        time-step restrictions. However, repeated smoothing still causes mesh
+        shrinkage and loss of geometric detail.
+
+        The system matrix (M + lam * L) is constructed only once because the
+        mesh connectivity and geometry-dependent matrices remain fixed during
+        the iterations.
+
+        Unlike explicit smoothing, this method solves directly for the
+        updated vertex positions rather than first calculating a
+        displacement from the previous positions.
+
+        :param iterations: Number of smoothing iterations
+        :param lam: Smoothing parameter. Larger values generally produce stronger
+            smoothing per iteration
+        """
+        L = self.compute_cotangent_laplacian()
+        M = self.compute_mass_matrix()
+        A = M + lam * L  # Build system matrix
+        V = self._vertices.copy()
+        for _ in range(iterations):
+            rhs = M @ V
+            V = spsolve(A, rhs)
+        self._vertices = V
+
+    def smooth_taubin(
+        self,
+        iterations: int = 10,
+        lam: float = 0.5,
+        mu: float = -0.53,
+        normalize_parameters: bool = True,
+    ) -> None:
+        """Smooth the mesh using Taubin smoothing.
+
+        Taubin smoothing reduces surface noise while mitigating the shrinkage
+        typically introduced by conventional Laplacian smoothing.
+
+        Each iteration consists of two consecutive Laplacian smoothing steps:
+
+        * Smoothing step (lambda): Applies Laplacian smoothing to attenuate
+            high-frequency geometric variations.
+        * Expansion step (mu): Applies a second Laplacian operation with a
+            negative parameter to compensate for the shrinkage introduced
+            by the first step.
+
+        The vertex updates are computed using the cotangent Laplacian
+        normalized by the diagonal vertex mass matrix:
+
+            delta = M^(-1) * L * V
+
+            V = V - lam * delta
+            V = V - mu * delta
+
+        If parameter normalization is enabled, the Laplacian is spectrally
+        scaled using an estimate of its largest eigenvalue. The scaling is
+        based on the symmetric mass-normalized Laplacian:
+
+            A = M^(-1/2) * L * M^(-1/2)
+
+        Both Taubin parameters are divided by the estimated largest
+        eigenvalue to obtain scale-adjusted smoothing parameters.
+
+        Taubin smoothing reduces the volume shrinkage associated with
+        ordinary Laplacian smoothing but does not guarantee volume
+        preservation.
+
+        The method performs explicit Laplacian updates and does not solve
+        a linear system for the vertex positions.
+
+        :param iterations: Number of Taubin smoothing iterations. Each
+            iteration consists of one smoothing step followed by one expansion
+            step
+        :param lam: Positive smoothing parameter controlling the strength
+            of the first Laplacian step
+        :param mu: Negative expansion parameter controlling the strength
+            of the second Laplacian step. It compensates for the shrinkage
+            introduced by the smoothing step
+        :param normalize_parameters: If True, scales both smoothing
+            parameters using an estimate of the largest eigenvalue of the
+            symmetric mass-normalized Laplacian. This makes the parameters
+            less dependent on the magnitude of the Laplacian eigenvalues
+        """
+        if iterations < 0:
+            raise ValueError("Iterations must be non-negative.")
+        if lam <= 0:
+            raise ValueError("Lambda must be positive.")
+        if mu >= 0:
+            raise ValueError("Mu must be negative.")
+        if iterations == 0:
+            return
+        L = self.compute_cotangent_laplacian()
+        vertex_areas = self.compute_mass_matrix().diagonal()
+        if np.any(vertex_areas <= 0):
+            raise ValueError("Mesh contains vertices with zero area.")
+        if normalize_parameters:
+            # Construct symmetric mass-normalized Laplacian
+            inv_sqrt_areas = 1.0 / np.sqrt(vertex_areas)
+            D = diags(inv_sqrt_areas, format="csr")
+            A = D @ L @ D
+            # Estimate largest eigenvalue
+            lambda_max = eigsh(
+                A,
+                k=1,
+                which="LM",
+                return_eigenvectors=False,
+            )[0]
+            if lambda_max <= 0:
+                raise ValueError("Invalid Laplacian spectrum.")
+            # Scale Taubin parameters
+            lam /= lambda_max
+            mu /= lambda_max
+        V = self._vertices.copy()
+        for _ in range(iterations):
+            # Smoothing step
+            delta = (L @ V) / vertex_areas[:, None]
+            V -= lam * delta
+            # Expansion step
+            delta = (L @ V) / vertex_areas[:, None]
+            V -= mu * delta
+        self._vertices = V
+
+    def compute_vertex_quadrics(self):
+        """Compute vertex quadrics
+
+        See Garland, M. and Heckbert, P. S.: Surface Simplification
+            Using Quadric Error Metrics, 1997
+        https://www.cs.cmu.edu/~garland/Papers/quadrics.pdf
+        """
+        # Plane equations: nx*x + ny*y + nz*z + d = 0
+        # (nx, ny, nz) are the face normals and d = -(nx*x + ny*y + nz*z)
+        planes = np.empty((self.num_faces, 4), dtype=np.float64)
+        planes[:, :3] = self._face_normals
+        planes[:, 3] = -np.einsum(
+            "ij,ij->i", self._face_normals, self._vertices[self._faces[:, 0]]
+        )
+        # Outer product for every face: Fundamental error quadric K_p
+        face_quadrics = planes[:, :, None] * planes[:, None, :]
+        # Sum all 16 quadric entries over incident faces simultaneously
+        assert self._vertex_face_incidence is not None
+        vertex_quadrics = (
+            self._vertex_face_incidence @ face_quadrics.reshape(self.num_faces, 16)
+        ).reshape(self.num_vertices, 4, 4)
+        return vertex_quadrics
+
+    def best_collapse_positions_all_edges(self, vertex_quadrics, rcond=1e-12):
+        edges = self.get_unique_edges()
+
+        u, v = edges[:, 0], edges[:, 1]
+        Q = vertex_quadrics[u] + vertex_quadrics[v]  # (E, 4, 4)
+
+        p0 = self._vertices[u]
+        p1 = self._vertices[v]
+        midpoint = 0.5 * (p0 + p1)
+
+        # Evaluate a batch of homogeneous positions against the corresponding Q.
+        def costs_at(points):
+            hp = np.concatenate(
+                [points, np.ones((len(points), 1), dtype=points.dtype)],
+                axis=1,
+            )
+            return np.einsum("ei,eij,ej->e", hp, Q, hp)
+
+        # Initial fallback candidates: endpoints and midpoint.
+        candidates = np.stack([p0, p1, midpoint], axis=1)  # (E, 3, 3)
+        candidate_costs = np.stack(
+            [costs_at(p0), costs_at(p1), costs_at(midpoint)],
+            axis=1,
+        )  # (E, 3)
+
+        # The unconstrained optimum solves A p = -b, where
+        # Q = [[A, b], [b.T, c]].
+        A = Q[:, :3, :3]
+        b = Q[:, :3, 3]
+
+        # Batched SVD identifies singular/ill-conditioned systems.
+        singular_values = np.linalg.svd(A, compute_uv=False)
+        well_conditioned = singular_values[:, -1] > rcond * singular_values[:, 0]
+
+        optimal = np.zeros((len(edges), 3), dtype=self._vertices.dtype)
+        valid_indices = np.flatnonzero(well_conditioned)
+        print(len(valid_indices))
+
+        try:
+            optimal[valid_indices] = np.linalg.solve(
+                A[valid_indices],
+                -b[valid_indices, :, None],
+            )[..., 0]
+        except np.linalg.LinAlgError:
+            # Fall back to solving each system separately.
+            for i in valid_indices:
+                try:
+                    optimal[i] = np.linalg.solve(A[i], -b[i])
+                except np.linalg.LinAlgError:
+                    well_conditioned[i] = False
+
+        if np.any(well_conditioned):
+            indices = np.flatnonzero(well_conditioned)
+            optimal_costs = costs_at(optimal[indices])
+
+            candidates[indices, 0, :] = optimal[indices]
+            candidate_costs[indices, 0] = optimal_costs
+
+        best_indices = np.argmin(candidate_costs, axis=1)
+        rows = np.arange(len(edges))
+
+        return candidates[rows, best_indices], candidate_costs[rows, best_indices]