capytaine.meshes.meshes module

class capytaine.meshes.meshes.Mesh(vertices: ndarray = None, faces: List[List[int]] | ndarray = None, *, faces_metadata: Dict[str, ndarray] | None = None, quadrature_method: str | None = None, name: str | None = None, auto_clean: bool = True, auto_check: bool = True)

Bases: AbstractMesh

Mesh class for representing and manipulating 3D surface meshes.

Parameters:

• vertices (np.ndarray, optional) – Array of mesh vertices coordinates with shape (n_vertices, 3). Each row represents one vertex’s (x, y, z) coordinates.

• faces (List[List[int]] or np.ndarray, optional) – Array of mesh connectivities for panels. Each row contains indices of vertices that form a face (triangles or quads).

• faces_metadata (Dict[str, np.ndarray]) – Some arrays with the same first dimension (should be the number of faces) storing some fields defined on all the faces of the mesh.

• name (str, optional) – Optional name for the mesh instance.

• auto_clean (bool, optional) – Whether to automatically clean the mesh upon initialization. Defaults to True.

• auto_check (bool, optional) – Whether to automatically check mesh quality upon initialization. Defaults to True.

Variables:

• vertices (np.ndarray) – Array of vertex coordinates with shape (n_vertices, 3).

• name (str or None) – Name of the mesh instance.

as_array_of_faces() → ndarray

Similar to as_list_of_faces but returns an array of shape (nb_faces, 3, 3) if only triangles, or (nb_faces, 4, 3) otherwise.

as_list_of_faces() → List[List[List[float]]]

Convert the Mesh instance to a list of faces defined by vertex coordinates.

Returns:

Each face is defined by a list of 3D coordinates. For example: [

[[x1, y1, z1], [x2, y2, z2], [x3, y3, z3]], [[x4, y4, z4], [x5, y5, z5], [x6, y6, z6]]

]

Return type:

list of list of list of float

clipped(*, origin, normal, name=None) → Mesh

Clip the mesh by a plane defined by origin and normal.

Parameters:

• origin (np.ndarray) – The point in space where the clipping plane intersects (3D point).

• normal (np.ndarray) – The normal vector defining the orientation of the clipping plane.

• name (Optional[str]) – A name for the newly created mesh

Returns:

A new Mesh instance that has been clipped.

Return type:

Mesh

copy(*, faces_metadata=None, name=None) → Mesh

export(format, **kwargs)

extract_faces(faces_id, *, name=None) → Mesh

Extract a subset of faces by their indices and return a new Mesh instance.

Parameters:

• faces_id (array_like) – Indices of faces to extract.

• name (str, optional) – A name for the new mesh

Returns:

New mesh containing only the specified faces.

Return type:

Mesh

extract_lid(z=0.0)

Split the mesh into a mesh of the hull and a mesh of the lid. By default, the lid is composed of the horizontal faces on the z=0 plane.

Parameters:

plane (Plane) – The plane on which to look for lid faces.

Returns:

hull mesh and lid mesh

Return type:

2-ple of Mesh

property faces: ndarray

Face connectivity as quadrilateral array.

Returns:

Array of shape (n_faces, 4) where triangular faces are padded by repeating the last vertex.

Return type:

np.ndarray

Notes

This property converts all faces to a uniform quad representation for compatibility with libraries expecting fixed-width face arrays.

property faces_areas: ndarray

Surface area of each face.

Returns:

Array of shape (n_faces,) containing the area of each face.

Return type:

np.ndarray

property faces_centers: ndarray

Geometric centers of each face.

Returns:

Array of shape (n_faces, 3) containing the center point of each face.

Return type:

np.ndarray

property faces_normals: ndarray

Normal vectors for each face.

Returns:

Array of shape (n_faces, 3) containing unit normal vectors.

Return type:

np.ndarray

property faces_radiuses: ndarray

Radii of each face (circumradius or characteristic size).

Returns:

Array of shape (n_faces,) containing the radius of each face.

Return type:

np.ndarray

property faces_vertices_centers: ndarray

Calculate the center of vertices that form the faces.

Returns:

Array of shape (n_faces, 3) containing the centroid of each face’s vertices.

Return type:

np.ndarray

classmethod from_list_of_faces(list_faces, *, quadrature_method=None, faces_metadata=None, name=None, auto_clean=True, auto_check=True) → Mesh

Create a Mesh instance from a list of faces defined by vertex coordinates.

Parameters:

• list_faces (list of list of list of float) – Each face is defined by a list of 3D coordinates. For example: [

  [[x1, y1, z1], [x2, y2, z2], [x3, y3, z3]], [[x4, y4, z4], [x5, y5, z5], [x6, y6, z6]]

  ]

• faces_metadata (Optional[Dict[str, np.ndarray]])

• name (str, optional) – A name for the new mesh.

• auto_clean (bool, optional) – Whether to automatically clean the mesh upon initialization. Defaults to True.

• auto_check (bool, optional) – Whether to automatically check mesh quality upon initialization. Defaults to True.

Returns:

An instance of Mesh with: - unique vertices extracted from the input - faces defined as indices into the vertex array

Return type:

Mesh

generate_lid(z=0.0, faces_max_radius=None, name=None)

Return a mesh of the internal free surface of the body.

Parameters:

• z (float, optional) – Vertical position of the lid. Default: 0.0

• faces_max_radius (float, optional) – resolution of the mesh of the lid. Default: mean of hull mesh resolution.

• name (str, optional) – A name for the new mesh

Returns:

lid of internal surface

Return type:

Mesh

join_meshes(*, return_masks=False, name=None) → Mesh

Join several meshes and return a new Mesh instance.

Parameters:

• meshes (List[Mesh]) – Meshes to be joined

• return_masks (bool, optional) – If True, additionally return a list of numpy masks establishing the origin of each face in the new mesh. (Default: False)

• name (str, optional) – A name for the new object

Returns:

New mesh containing vertices and faces from all meshes.

Return type:

Mesh

See also

__add__

Implements the + operator for mesh joining.

merged(*, name=None) → Mesh

mirrored(plane: Literal['xOz', 'yOz'], *, name=None) → Mesh

property nb_faces: int

Number of faces in the mesh.

property nb_quads: int

Number of quadrilateral faces (4-vertex) in the mesh.

property nb_triangles: int

Number of triangular faces (3-vertex) in the mesh.

property nb_vertices: int

Number of vertices in the mesh.

property quadrature_points: Tuple[ndarray, ndarray]

Quadrature points and weights for numerical integration.

Returns:

(points, weights) where points has shape (n_faces, 1, 3) and weights has shape (n_faces, 1), using face centers and areas.

Return type:

tuple[np.ndarray, np.ndarray]

rotated_with_matrix(R, *, name=None) → Mesh

Return a new Mesh rotated using the provided 3×3 rotation matrix.

show(*, backend=None, **kwargs)

Visualize the mesh using the specified backend.

Parameters:

• backend (str, optional) – Visualization backend to use. Options are ‘pyvista’ or ‘matplotlib’. By default, try several until an installed one is found.

• normal_vectors (bool, optional) – If True, display normal vectors on each face.

• **kwargs – Additional keyword arguments passed to the visualization backend. See visualization

Returns:

Visualization object returned by the backend (e.g., matplotlib figure).

Return type:

object

Raises:

NotImplementedError – If the specified backend is not supported.

summary()

Print a summary of the mesh properties.

Notes

Displays the mesh name, vertex count, face count, and bounding box.

translated(shift, *, name=None) → Mesh

Return a new Mesh translated along vector-like shift.

with_normal_vector_going_down(**kwargs) → Mesh

Ensure normal vectors point downward (negative z-direction).

Returns:

Self if normals already point down, otherwise modifies face orientation.

Return type:

Mesh

Notes

Used for lid meshes to avoid irregular frequency issues by ensuring consistent normal vector direction.

with_quadrature(quadrature_method)