capytaine.meshes package

Subpackages

Submodules

Module contents

class capytaine.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)[source]

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[source]

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]]][source]

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[source]

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[source]
export(format, **kwargs)[source]
extract_faces(faces_id, *, name=None) → Mesh[source]

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)[source]

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[source]

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) → Mesh[source]

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, symmetry_warning_detail='') → Mesh[source]

Join several meshes and return a new Mesh instance.

Parameters:

  • meshes (List[AbstractMesh]) – 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

  • symmetry_warning_detail (str, optional) – Additional context to include in symmetry warning messages (e.g., “hull mesh and lid mesh”)

Returns:

  • Mesh – New mesh containing vertices and faces from all meshes.

  • list of arrays – The boolean masks relating each faces to the component it came from Only returned in return_masks==True

See also

__add__

Implements the + operator for mesh joining.

merged(*, name=None) → Mesh[source]
mirrored(plane: Literal['xOz', 'yOz'], *, name=None) → Mesh[source]
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, nb_quad_points, 3) and weights has shape (n_faces, nb_quad_points).

Return type:

tuple[np.ndarray, np.ndarray]

rotated_with_matrix(R, *, name=None) → Mesh[source]

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

show(*, backend=None, **kwargs)[source]

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()[source]

Print a summary of the mesh properties.

Notes

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

translated(shift, *, name=None) → Mesh[source]

Return a new Mesh translated along vector-like shift.

with_normal_vector_going_down(**kwargs) → Mesh[source]

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)[source]
class capytaine.meshes.ReflectionSymmetricMesh(half: AbstractMesh, *, plane: str, faces_metadata: Dict[str, ndarray] | None = None, name: str | None = None)[source]

Bases: AbstractMesh

A mesh with reflection symmetry across a plane.

This class represents a mesh that has reflection symmetry across either the xOz plane (y=0) or yOz plane (x=0). Only half of the mesh is stored, and the full mesh can be reconstructed by reflecting across the symmetry plane.

Supports nested symmetries: if the half mesh is itself a ReflectionSymmetricMesh, this represents a quarter mesh with symmetries across both planes.

Variables:

  • half (AbstractMesh) – The half mesh

  • plane (str) – The symmetry plane, either “xOz” or “yOz”

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

  • name (str, optional) – Name for the mesh

Examples

>>> # Create a mesh with xOz symmetry (y=0 plane)
>>> half_mesh = Mesh(vertices=..., faces=...)
>>> symmetric_mesh = ReflectionSymmetricMesh(half=half_mesh, plane="xOz")
>>>
>>> # Create a mesh with both xOz and yOz symmetries (quarter mesh)
>>> quarter_mesh = Mesh(vertices=..., faces=...)
>>> sym_xOz = ReflectionSymmetricMesh(half=quarter_mesh, plane="xOz")
>>> sym_both = ReflectionSymmetricMesh(half=sym_xOz, plane="yOz")
>>>
>>> # Get the full merged mesh
>>> full_mesh = symmetric_mesh.merged()
clipped(*, origin, normal, name=None) → ReflectionSymmetricMesh | Mesh[source]
copy(*, faces_metadata=None, name=None) → ReflectionSymmetricMesh[source]
export(format, **kwargs)[source]
extract_faces(faces_id, *, name=None) → Mesh[source]
extract_lid(z=0.0)[source]
property faces: ndarray
property faces_areas: ndarray
property faces_centers: ndarray
property faces_normals: ndarray
property faces_radiuses: ndarray
generate_lid(z=0.0, faces_max_radius=None, name=None)[source]
join_meshes(*meshes, return_masks=False, name=None, symmetry_warning_detail='') → ReflectionSymmetricMesh | Mesh[source]
merged(name=None) → Mesh[source]
mirrored(plane: Literal['xOz', 'yOz'], *, name=None) → ReflectionSymmetricMesh[source]
property nb_faces: int
property nb_vertices: int
property quadrature_points: ndarray
rotated_with_matrix(R, *, name=None) → Mesh[source]
show(*, backend=None, ghost_meshes=None, **kwargs)[source]
translated(shift, *, name=None) → ReflectionSymmetricMesh | Mesh[source]
property vertices: ndarray
with_normal_vector_going_down(**kwargs) → ReflectionSymmetricMesh[source]
with_quadrature(quadrature_method)[source]
class capytaine.meshes.RotationSymmetricMesh(wedge: AbstractMesh, n: int, *, axis: Literal['z+', 'z-'] = 'z+', faces_metadata: Dict[str, ndarray] | None = None, name: str | None = None)[source]

Bases: AbstractMesh

A mesh with rotation symmetry around the Oz axis.

This class represents a mesh that has n-fold rotational symmetry about the z-axis. Only a wedge (1/n of the full mesh) is stored, and the full mesh can be reconstructed by rotating the wedge n times.

Supports nested symmetries: the wedge mesh can be a ReflectionSymmetricMesh for dihedral symmetry.

Variables:

  • wedge (AbstractMesh) – The wedge mesh (1/n of the full mesh)

  • n (int) – The rotation order (number of rotations to complete full circle)

  • axis (either 'z+' or 'z-') – Only the z-axis is supported, but two possible orientations can be used. Both are equivalent, except for the ordering of the sub-meshes.

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

  • name (str, optional) – Name for the mesh

Examples

>>> # Create a mesh with 3-fold rotation symmetry about z-axis
>>> wedge_mesh = Mesh(vertices=..., faces=...)
>>> symmetric_mesh = RotationSymmetricMesh(wedge=wedge_mesh, n=3)
>>>
>>> # Get the full merged mesh
>>> full_mesh = symmetric_mesh.merged()
clipped(*, origin, normal, name=None) → RotationSymmetricMesh | Mesh[source]
copy(*, faces_metadata=None, name=None) → RotationSymmetricMesh[source]
export(format, **kwargs)[source]
extract_faces(faces_id, *, name=None) → Mesh[source]
extract_lid(z=0.0)[source]
property faces: ndarray
property faces_areas: ndarray
property faces_centers: ndarray
property faces_normals: ndarray
property faces_radiuses: ndarray
classmethod from_profile_points(points: ndarray, n: int, *, faces_metadata=None, name=None)[source]

Return the mesh defined by the set of points repeated n times around the z-axis.

Points will be sorted by increasing z-coordinate before making a mesh, in order to ensure that the normal vector are outwards.

Parameters:

  • points (array of shape (…, 3)) – A list of points in 3D.

  • n (int) – The rotation order (number of rotations to complete full circle)

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

  • name (str, optional) – Name for the mesh

Example

>>> meridian_points = np.array([(np.sqrt(1-z**2), 0.0, z) for z in np.linspace(-1.0, 1.0, 10)])
>>> sphere = RotationSymmetricMesh.from_profile_points(meridian_points, n=10)
generate_lid(z=0.0, faces_max_radius=None, name=None)[source]
join_meshes(*meshes, return_masks=False, name=None, symmetry_warning_detail='') → RotationSymmetricMesh | Mesh[source]
merged(name=None) → Mesh[source]
mirrored(plane: Literal['xOz', 'yOz'], *, name=None) → RotationSymmetricMesh[source]
property nb_faces: int
property nb_vertices: int
property quadrature_points: ndarray
rotated_with_matrix(R, *, name=None) → RotationSymmetricMesh | Mesh[source]
show(*, backend=None, ghost_meshes=None, **kwargs)[source]
translated(shift, *, name=None) → RotationSymmetricMesh | Mesh[source]
property vertices: ndarray
with_normal_vector_going_down(**kwargs) → RotationSymmetricMesh[source]
with_quadrature(quadrature_method)[source]