capytaine 3.0.0a1__cp313-cp313-macosx_15_0_x86_64.whl

capytaine/meshes/clip.py

@@ -0,0 +1,347 @@
+# Copyright 2025 Mews Labs
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+from typing import List, Set, Tuple
+
+import numpy as np
+
+
+def _get_intersection(
+    v1: np.ndarray,
+    v2: np.ndarray,
+    normal: np.ndarray,
+    origin: np.ndarray,
+    tol: float = 1e-8,
+) -> np.ndarray:
+    """Intersect a line segment with a plane.
+
+    Parameters
+    ----------
+    v1, v2 : numpy.ndarray
+        Endpoints of the segment expressed as 3D vectors.
+    normal : numpy.ndarray
+        Plane normal; does not need to be unit length.
+    origin : numpy.ndarray
+        Point lying on the plane.
+    tol : float, default=1e-8
+        Tolerance used to detect parallel segments and clamp the intersection
+        parameter to the segment bounds.
+
+    Returns
+    -------
+    numpy.ndarray
+        Intersection point located on the (possibly clamped) segment.
+
+    Raises
+    ------
+    ValueError
+        If the segment is parallel to the plane or the intersection lies
+        outside the tolerated segment range.
+    """
+    v1 = np.asarray(v1, dtype=float)
+    v2 = np.asarray(v2, dtype=float)
+    n = np.asarray(normal, dtype=float)
+    o = np.asarray(origin, dtype=float)
+
+    u = v2 - v1
+    denom = float(np.dot(n, u))
+    if abs(denom) < tol:
+        raise ValueError("Segment is parallel to the plane (no unique intersection).")
+
+    t = float(np.dot(n, (o - v1)) / denom)
+
+    if t < -tol or t > 1.0 + tol:
+        raise ValueError(f"Intersection t={t:.6g} lies outside the segment [0,1].")
+
+    t = max(0.0, min(1.0, t))
+    return v1 + t * u
+
+
+def compute_aspect_ratio(tri_pts: np.ndarray) -> float:
+    """Compute the aspect ratio of a triangle.
+
+    The aspect ratio is defined as the longest edge length divided by the
+    altitude relative to that edge.
+
+    Parameters
+    ----------
+    tri_pts : numpy.ndarray
+        Triangle vertices arranged in a ``(3, 3)`` array.
+
+    Returns
+    -------
+    float
+        Aspect ratio ``L / h`` (values greater than or equal to 1).
+
+    Raises
+    ------
+    ValueError
+        If the triangle is degenerate and its area approaches zero.
+    """
+    tri_pts = np.asarray(tri_pts, dtype=float)
+    if tri_pts.shape != (3, 3):
+        raise ValueError("tri_pts must have shape (3,3).")
+
+    edges = np.array(
+        [
+            np.linalg.norm(tri_pts[1] - tri_pts[0]),
+            np.linalg.norm(tri_pts[2] - tri_pts[1]),
+            np.linalg.norm(tri_pts[0] - tri_pts[2]),
+        ],
+        dtype=float,
+    )
+    L = float(np.max(edges))
+    i = int(np.argmax(edges))
+
+    A, B = tri_pts[i], tri_pts[(i + 1) % 3]
+    C = tri_pts[(i + 2) % 3]
+    area = 0.5 * np.linalg.norm(np.cross(B - A, C - A))
+    if area <= 0.0:
+        raise ValueError("Degenerate triangle: zero area.")
+    h = 2.0 * area / L
+    return L / h
+
+
+def _signed_distances(
+    verts: list[list[float]],
+    face: list[int],
+    normal: np.ndarray,
+    origin: np.ndarray,
+) -> np.ndarray:
+    """Evaluate signed distances of face vertices to a clipping plane.
+
+    Parameters
+    ----------
+    verts : list of list of float
+        All mesh vertices.
+    face : list of int
+        Indices of the vertices forming the face.
+    normal : numpy.ndarray
+        Plane normal vector.
+    origin : numpy.ndarray
+        Point belonging to the plane.
+
+    Returns
+    -------
+    numpy.ndarray
+        Signed distances for the vertices belonging to ``face``.
+    """
+    pts = np.asarray([verts[i] for i in face], dtype=float)
+    return (origin - pts) @ normal
+
+
+def _compute_keep_sets(
+    verts: list[list[float]],
+    face: list[int],
+    normal: np.ndarray,
+    origin: np.ndarray,
+    tol: float,
+) -> tuple[list[int], set[int], np.ndarray]:
+    """Split vertices of a face between kept and discarded sets.
+
+    Parameters
+    ----------
+    verts : list of list of float
+        All mesh vertices.
+    face : list of int
+        Indices forming the face currently being clipped.
+    normal : numpy.ndarray
+        Plane normal vector defining the clipping plane.
+    origin : numpy.ndarray
+        Point on the clipping plane.
+    tol : float
+        Tolerance used to consider vertices inside the kept half-space.
+
+    Returns
+    -------
+    list of int
+        Indices of vertices that remain after clipping.
+    set of int
+        Indices of vertices removed by the clipping plane.
+    numpy.ndarray
+        Signed distance of each face vertex to the plane.
+    """
+    s = _signed_distances(verts, face, normal, origin)
+    mask = s >= -tol
+    keep = [face[i] for i, m in enumerate(mask) if m]
+    unkeep = set(face) - set(keep)
+    return keep, unkeep, s
+
+
+def _compute_edge_intersections(
+    verts: list[list[float]],
+    face: list[int],
+    keep: list[int],
+    normal: np.ndarray,
+    origin: np.ndarray,
+    tol: float,
+) -> dict[tuple[int, int], int]:
+    """Intersect face edges with the clipping plane.
+
+    Parameters
+    ----------
+    verts : list of list of float
+        Mutable list of mesh vertices; intersection points are appended here.
+    face : list of int
+        Indices of the vertices forming the face being processed.
+    keep : list of int
+        Vertices that remain inside the kept half-space.
+    normal : numpy.ndarray
+        Plane normal vector.
+    origin : numpy.ndarray
+        Point belonging to the plane.
+    tol : float
+        Tolerance for plane intersection checks.
+
+    Returns
+    -------
+    dict[tuple[int, int], int]
+        Mapping from directed edges to newly created vertex indices.
+    """
+    keep_set = set(keep)
+    edges = list(zip(face, face[1:] + face[:1]))
+    cut_edges = [(i, j) for (i, j) in edges if (i in keep_set) ^ (j in keep_set)]
+
+    edge_inters: dict[tuple[int, int], int] = {}
+    for i, j in cut_edges:
+        ip = _get_intersection(
+            np.array(verts[i]), np.array(verts[j]), normal, origin, tol
+        )
+        idx = len(verts)
+        verts.append(ip.tolist())
+        edge_inters[(i, j)] = idx
+    return edge_inters
+
+
+def _build_clipped_boundary(
+    face: list[int],
+    keep: list[int],
+    edge_inters: dict[tuple[int, int], int],
+) -> list[int]:
+    """Assemble the boundary indices for a clipped polygon.
+
+    Parameters
+    ----------
+    face : list of int
+        Original face indices.
+    keep : list of int
+        Vertices that remain after clipping.
+    edge_inters : dict[tuple[int, int], int]
+        Mapping from edges to newly created intersection vertices.
+
+    Returns
+    -------
+    list of int
+        Ordered vertex indices describing the clipped boundary.
+    """
+    keep_set = set(keep)
+    boundary: list[int] = []
+    for i, j in zip(face, face[1:] + face[:1]):
+        if i in keep_set:
+            boundary.append(i)
+        if (i, j) in edge_inters:
+            boundary.append(edge_inters[(i, j)])
+    return boundary
+
+
+def clip_faces(
+    vertices: np.ndarray,
+    faces: list[list[int]],
+    normal: np.ndarray,
+    origin: np.ndarray,
+    tol: float = 1e-8,
+) -> Tuple[np.ndarray, List[List[int]], np.ndarray]:
+    """Clip faces of a mesh against a plane.
+
+    The kept half-space is defined by ``(v - origin) · normal >= -tol``.
+
+    Parameters
+    ----------
+    vertices : numpy.ndarray
+        Input vertex positions of shape ``(n, 3)``.
+    faces : list of list of int
+        Face connectivity; triangles and quads are supported.
+    normal : numpy.ndarray
+        Normal vector of the clipping plane.
+    origin : numpy.ndarray
+        Point located on the plane.
+    tol : float, default=1e-8
+        Tolerance for classifying vertices relative to the plane.
+
+    Returns
+    -------
+    np.ndarray of floats of shape (new_nb_vertices, 3)
+        The pruned vertex array
+    list of list of int
+        The list of of length new_nb_faces with clipped faces
+    np.ndarray of ints of shape (new_nb_faces,)
+        For each new face, the index of the face it comes from in the input.
+    """
+    normal = np.asarray(normal, dtype=float)
+    origin = np.asarray(origin, dtype=float)
+
+    verts: List[List[float]] = vertices.astype(float).tolist()
+    new_faces: List[Tuple[int, List[int]]] = []
+    # A new face is a tuple storing the index of the parent face in the
+    # original mesh and a list of vertices
+    dropped_vs: Set[int] = set()
+
+    for i_face, face in enumerate(faces):
+        keep, unkeep, _ = _compute_keep_sets(verts, face, normal, origin, tol)
+        dropped_vs.update(unkeep)
+
+        if len(keep) == 0:
+            continue  # fully outside
+        if len(keep) == len(face):
+            # Face fully inside → keep original (quad or triangle unchanged)
+            new_faces.append((i_face, list(face)))
+            continue
+
+        edge_inters = _compute_edge_intersections(
+            verts, face, keep, normal, origin, tol
+        )
+        boundary = _build_clipped_boundary(face, keep, edge_inters)
+
+        if len(boundary) == 3:
+            new_faces.append((i_face, boundary))
+        elif len(boundary) == 4:
+            # clipped quad → 2 triangles
+            new_faces.append((i_face, [boundary[0], boundary[1], boundary[2]]))
+            new_faces.append((i_face, [boundary[0], boundary[2], boundary[3]]))
+        elif len(boundary) == 5:
+            # pentagon → 1 triangle + 1 quad
+            tri = [boundary[0], boundary[1], boundary[2]]
+            quad = [boundary[0], boundary[2], boundary[3], boundary[4]]
+            new_faces.append((i_face, tri))
+            new_faces.append((i_face, quad))
+        else:
+            # fallback: fan triangulation
+            for k in range(1, len(boundary) - 1):
+                new_faces.append((i_face, [boundary[0], boundary[k], boundary[k + 1]]))
+
+    if not new_faces:
+        return np.empty((0, 3), dtype=float), [], np.empty((0,), dtype=int)
+
+    used = {idx for (_, f) in new_faces for idx in f}
+    dropped_vs -= used
+    keep_vs = [i for i in range(len(verts)) if i not in dropped_vs]
+    remap = {old: new for new, old in enumerate(keep_vs)}
+
+    pruned_verts = np.asarray([verts[i] for i in keep_vs], dtype=float)
+    pruned_faces = [[remap[i] for i in face] for (_, face) in new_faces]
+
+    parent_of_face = np.array([i_parent_face for (i_parent_face, _) in new_faces])
+
+    return pruned_verts, pruned_faces, parent_of_face

capytaine/meshes/export.py

@@ -0,0 +1,89 @@
+import numpy as np
+import xarray as xr
+
+from capytaine.tools.optional_imports import import_optional_dependency
+
+
+def export_mesh(mesh, format: str):
+    format = format.lower()
+    if format == "pyvista":
+        return export_to_pyvista(mesh)
+    elif format == "xarray":
+        return export_to_xarray(mesh)
+    elif format == "meshio":
+        return export_to_meshio(mesh)
+    elif format == "trimesh":
+        return export_to_trimesh(mesh)
+    else:
+        raise ValueError(f"Unrecognized output format: {format}")
+
+
+def export_to_pyvista(mesh):
+    """
+    Build a PyVista UnstructuredGrid from a list of faces (triangles or quads).
+    """
+    pv = import_optional_dependency("pyvista")
+
+    # flatten into the VTK cell‐array format: [n0, i0, i1, ..., in-1, n1, j0, j1, ...]
+    flat_cells = []
+    cell_types = []
+    for face in mesh._faces:
+        n = len(face)
+        flat_cells.append(n)
+        flat_cells.extend(face)
+        if n == 3:
+            cell_types.append(pv.CellType.TRIANGLE)
+        elif n == 4:
+            cell_types.append(pv.CellType.QUAD)
+        else:
+            # if you ever have ngons, you can map them as POLYGON:
+            cell_types.append(pv.CellType.POLYGON)
+
+    cells_array = np.array(flat_cells, dtype=np.int64)
+    cell_types = np.array(cell_types, dtype=np.uint8)
+
+    return pv.UnstructuredGrid(cells_array, cell_types, mesh.vertices.astype(np.float32))
+
+
+def export_to_xarray(mesh):
+    return xr.Dataset(
+            {
+                "mesh_vertices": (
+                    ["face", "vertices_of_face", "space_coordinate"],
+                    mesh.as_array_of_faces()
+                    )
+                },
+            coords={
+                "space_coordinate": ["x", "y", "z"],
+                })
+
+
+def export_to_meshio(mesh):
+    meshio = import_optional_dependency("meshio")
+
+    quads = [f for f in mesh._faces if len(f) == 4]
+    tris = [f for f in mesh._faces if len(f) == 3]
+
+    cells = []
+    if quads:
+        cells.append(meshio.CellBlock("quad", np.array(quads, dtype=np.int32)))
+    if tris:
+        cells.append(meshio.CellBlock("triangle", np.array(tris, dtype=np.int32)))
+
+    return meshio.Mesh(points=mesh.vertices, cells=cells)
+
+
+def export_to_trimesh(mesh):
+    trimesh = import_optional_dependency("trimesh")
+    triangle_faces = []
+    for face in mesh._faces:
+        if len(face) == 4 and face[3] != face[2]:
+            triangle_faces.append([face[0], face[1], face[2]])
+            triangle_faces.append([face[0], face[2], face[3]])
+        else:
+            triangle_faces.append(face[:3])
+    return trimesh.Trimesh(
+        vertices=mesh.vertices,
+        faces=np.array(triangle_faces),
+        process=False
+    )

capytaine/meshes/geometry.py

@@ -0,0 +1,259 @@
+# Copyright 2025 Mews Labs
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import List
+from functools import reduce
+from itertools import chain
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def get_vertices_face(face, vertices):
+    if len(face) == 4 and face[2] != face[3]:
+        return (
+            vertices[face[0]],
+            vertices[face[1]],
+            vertices[face[2]],
+            vertices[face[3]],
+        )
+    else:
+        return vertices[face[0]], vertices[face[1]], vertices[face[2]]
+
+
+def compute_faces_normals(vertices, faces):
+    normals = []
+    for face in faces:
+        if len(face) == 4 and face[2] != face[3]:
+            normal = _quad_normal(vertices, face[0], face[1], face[2], face[3])
+        else:
+            normal = _triangle_normal(vertices, face[0], face[1], face[2])
+        normals.append(normal)
+    return np.array(normals)
+
+
+def compute_faces_areas(vertices, faces):
+    areas = []
+    for face in faces:
+        verts = get_vertices_face(face, vertices)
+        if len(verts) == 4:
+            a, b, c, d = verts
+            area1 = 0.5 * np.linalg.norm(np.cross(b - a, c - a))
+            area2 = 0.5 * np.linalg.norm(np.cross(c - a, d - a))
+            areas.append(area1 + area2)
+        else:
+            a, b, c = verts
+            areas.append(0.5 * np.linalg.norm(np.cross(b - a, c - a)))
+    return np.array(areas)
+
+
+def compute_faces_centers(vertices, faces):
+    centers = []
+    for face in faces:
+        verts = get_vertices_face(face, vertices)
+        if len(verts) == 4:
+            a, b, c, d = verts
+            area1 = 0.5 * np.linalg.norm(np.cross(b - a, c - a))
+            area2 = 0.5 * np.linalg.norm(np.cross(c - a, d - a))
+            c1 = (a + b + c) / 3
+            c2 = (a + c + d) / 3
+            center = (c1 * area1 + c2 * area2) / (area1 + area2)
+        else:
+            a, b, c = verts
+            center = (a + b + c) / 3
+        centers.append(center)
+    return np.array(centers)
+
+
+def compute_faces_radii(vertices, faces):
+    centers = compute_faces_centers(vertices, faces)
+    distances = []
+    for face, center in zip(faces, centers):
+        d = compute_distance_between_points(vertices[face[0]], center)
+        distances.append(d)
+    return np.array(distances)
+
+
+def compute_gauss_legendre_2_quadrature(vertices, faces):
+    # Parameters of Gauss-Legendre 2 quadrature scheme
+    local_points = np.array([(+1/np.sqrt(3), +1/np.sqrt(3)),
+             (+1/np.sqrt(3), -1/np.sqrt(3)),
+             (-1/np.sqrt(3), +1/np.sqrt(3)),
+             (-1/np.sqrt(3), -1/np.sqrt(3))])
+    local_weights = np.array([1/4, 1/4, 1/4, 1/4])
+
+    # Application to mesh
+    faces = vertices[faces[:, :], :]
+    nb_faces = faces.shape[0]
+    nb_quad_points = len(local_weights)
+    points = np.empty((nb_faces, nb_quad_points, 3))
+    weights = np.empty((nb_faces, nb_quad_points))
+    for i_face in range(nb_faces):
+        for k_quad in range(nb_quad_points):
+            xk, yk = local_points[k_quad, :]
+            points[i_face, k_quad, :] = (
+                      (1+xk)*(1+yk) * faces[i_face, 0, :]
+                    + (1+xk)*(1-yk) * faces[i_face, 1, :]
+                    + (1-xk)*(1-yk) * faces[i_face, 2, :]
+                    + (1-xk)*(1+yk) * faces[i_face, 3, :]
+                    )/4
+            dxidx = ((1+yk)*faces[i_face, 0, :] + (1-yk)*faces[i_face, 1, :]
+                     - (1-yk)*faces[i_face, 2, :] - (1+yk)*faces[i_face, 3, :])/4
+            dxidy = ((1+xk)*faces[i_face, 0, :] - (1+xk)*faces[i_face, 1, :]
+                     - (1-xk)*faces[i_face, 2, :] + (1-xk)*faces[i_face, 3, :])/4
+            detJ = np.linalg.norm(np.cross(dxidx, dxidy))
+            weights[i_face, k_quad] = local_weights[k_quad] * 4 * detJ
+
+    return points, weights
+
+
+def _triangle_normal(vertices, v0_idx, v1_idx, v2_idx):
+    """
+    Compute normal vector of a triangle face.
+
+    Parameters
+    ----------
+    vertices : ndarray
+        Vertex coordinate array.
+    v0_idx, v1_idx, v2_idx : int
+        Indices of triangle vertices.
+
+    Returns
+    -------
+    np.ndarray
+        Normalized normal vector (3,)
+    """
+    v0, v1, v2 = vertices[v0_idx], vertices[v1_idx], vertices[v2_idx]
+    normal = np.cross(v1 - v0, v2 - v0)
+    return normal / np.linalg.norm(normal)
+
+
+def _quad_normal(vertices, v0_idx, v1_idx, v2_idx, v3_idx):
+    """
+    Compute normal vector of a quadrilateral face via diagonals.
+
+    Parameters
+    ----------
+    vertices : ndarray
+        Vertex coordinate array.
+    v0_idx, v1_idx, v2_idx, v3_idx : int
+        Indices of quad vertices.
+
+    Returns
+    -------
+    np.ndarray
+        Normalized normal vector (3,)
+    """
+    v0, v1, v2, v3 = (
+        vertices[v0_idx],
+        vertices[v1_idx],
+        vertices[v2_idx],
+        vertices[v3_idx],
+    )
+    ac = v2 - v0
+    bd = v3 - v1
+    normal = np.cross(ac, bd)
+    return normal / np.linalg.norm(normal)
+
+
+def compute_distance_between_points(a, b):
+    """
+    Compute Euclidean distance between two points in n-dimensional space.
+
+    Parameters
+    ----------
+    a, b : array_like
+        Coordinate arrays (length 3 or more).
+
+    Returns
+    -------
+    float
+        Euclidean distance.
+    """
+    a = np.asarray(a)
+    b = np.asarray(b)
+    return np.linalg.norm(b - a)
+
+def faces_in_group(faces: NDArray[np.integer], group: NDArray[np.integer]) -> NDArray[np.bool_]:
+    """Identification of faces with vertices within group.
+
+    Parameters
+    ----------
+    faces : NDArray[np.integer]
+        Mesh faces. Expecting a numpy array of shape N_faces x N_vertices_per_face.
+    group : NDArray[np.integer]
+        Group of connected vertices
+
+    Returns
+    -------
+    NDArray[np.bool]
+        Mask of faces containing vertices from the group
+    """
+    return np.any(np.isin(faces, group), axis=1)
+
+def clustering(faces: NDArray[np.integer]) -> List[NDArray[np.integer]]:
+    """Clustering of vertices per connected faces.
+
+    Parameters
+    ----------
+    faces : NDArray[np.integer]
+        Mesh faces. Expecting a numpy array of shape N_faces x N_vertices_per_face.
+
+    Returns
+    -------
+    list[NDArray[np.integer]]
+        Groups of connected vertices.
+    """
+    vert_groups: list[NDArray[np.integer]] = []
+    mask = np.ones(faces.shape[0], dtype=bool)
+    while np.any(mask):
+        # Consider faces whose vertices are not already identified in a group.
+        # Start new group by considering first face
+        remaining_faces = faces[mask]
+        group = remaining_faces[0]
+        rem_mask = np.ones(remaining_faces.shape[0], dtype=bool)
+        # Iterative update of vertices group. Output final result to frozenset
+        while not np.allclose(new:=faces_in_group(remaining_faces, group), rem_mask):
+            group = np.unique(remaining_faces[new])
+            rem_mask = new
+        else:
+            group = np.unique(remaining_faces[new])
+        vert_groups.append(group)
+        # Identify faces that have no vertices in current groups
+        mask = ~reduce(np.logical_or, [faces_in_group(faces, group) for group in vert_groups])
+    return vert_groups
+
+
+def connected_components(mesh):
+    """Returns a list of meshes that each corresponds to the a connected component in the original mesh.
+    Assumes the mesh is mostly conformal without duplicate vertices.
+    """
+    # Get connected vertices
+    vertices_components = clustering(mesh.faces)
+    # Verification
+    if sum(len(group) for group in vertices_components) != len(set(chain.from_iterable(vertices_components))):
+        raise ValueError("Error in connected components clustering. Some elements are duplicated")
+    # The components are found. The rest is just about retrieving the faces in each components.
+    faces_components = [np.argwhere(faces_in_group(mesh.faces, group)) for group in vertices_components]
+    components = [mesh.extract_faces(f) for f in faces_components]
+    return components
+
+
+def connected_components_of_waterline(mesh, z=0.0):
+    if np.any(mesh.vertices[:, 2] > z + 1e-8):
+        mesh = mesh.immersed_part(free_surface=z)
+    fs_vertices_indices = np.where(np.isclose(mesh.vertices[:, 2], z))[0]
+    fs_faces_indices = np.where(np.any(np.isin(mesh.faces, fs_vertices_indices), axis=1))[0]
+    crown_mesh = mesh.extract_faces(fs_faces_indices)
+    return connected_components(crown_mesh)