Shells

volmdlr shells module.

class volmdlr.shells.ClosedShell3D(faces: List[Face3D], color: Tuple[float, float, float] | None = None, alpha: float = 1.0, name: str = '', bounding_box: BoundingBox | None = None, reference_path: str = '#')

Bases: Shell3D

A 3D closed shell composed of multiple faces.

This class represents a 3D closed shell, which is a collection of connected faces with a volume. It is a subclass of the Shell3D class and inherits all of its attributes and methods. In addition, it has a method to check whether a face is inside the shell.

STEP_FUNCTION = 'CLOSED_SHELL'

static clean_faces(union_faces, list_new_faces)

Clean union faces.

eliminate_not_valid_closedshell_faces()

Eliminate not valid closed shell faces resulted from boolean operations.

get_coincident_faces(shell2, abs_tol: float = 1e-06)

Finds all pairs of faces that are coincident faces, that is, faces lying on the same plane.

returns a List of tuples with the face pairs.

static get_faces_to_be_merged(union_faces)

Gets faces that are adjacent, and sharing the same surface, so they can be merged.

get_ray_casting_line_segment(point3d)

Gets the best ray for performing ray casting algorithm.

get_subtraction_valid_faces(new_faces, valid_faces, shell2, keep_interior_faces)

Gets valid faces for subtraction Boolean operations.

Parameters:

• new_faces – list of new divided faces.

• valid_faces – list of already validated faces.

• shell2 – other shell.

• keep_interior_faces – Boolean to decide to keep interior faces on reference shell or not.

Returns:

return a list a valid faces.

intersecting_faces_combinations(shell2, tol=1e-08)

Gets intersecting faces combinations.

Parameters:

• shell2 – ClosedShell3D

• tol – Corresponds to the tolerance to consider two faces as intersecting faces

Returns:

returns a dictionary containing as keys the combination of intersecting faces

and as the values the resulting primitive from the two intersecting faces. It is done, so it is not needed to calculate the same intersecting primitive twice.

intersection(shell2, tol=1e-08)

Given two ClosedShell3D, it returns the new object resulting from the intersection of the two.

intersection_faces(shell2, intersecting_faces, dict_faces_intersections)

Gets new faces for intersection Boolean operation between two closed shell 3d.

Parameters:

• shell2 – other shell

• intersecting_faces – list of all intersecting faces.

• dict_faces_intersections – Dictionary containing all combination of faces intersection, with corresponding intersections.

Returns:

list of new faces for intersection of two closed shells 3d.

is_face_between_shells(shell2, face)

Verify if face is between the two shells.

Parameters:

• shell2 – other shell

• face – face to be verified.

Returns:

is_face_inside(face: Face3D)

Verifies if a face is inside the closed shell 3D.

Parameters:

face – other face.

Returns:

returns True if face is inside, and False otherwise.

is_inside_shell(shell2)

Returns True if all the points of self are inside shell2 and no face are intersecting.

This method is not exact.

merge_faces()

Merges all shells’ adjacent faces into one.

point_inside(point3d: Point3D, **kwargs)

Ray Casting algorithm.

Returns True if the point is inside the Shell, False otherwise

set_operations_exterior_face(new_face, valid_faces, list_coincident_faces, shell2)

Selects exterior faces during bool operations, like union or subtraction.

Parameters:

• new_face – divided faces.

• valid_faces – list of already validated faces.

• shell2 – other shell.

• list_coincident_faces – list of coincident faces.

Returns:

static set_operations_interior_face(new_face, faces, shell2)

Verify if new face is inside reference shell for Boolean operations.

Parameters:

• new_face – new divided face.

• faces – list of already validated faces.

• shell2 – reference shell, to help decide if a new divided face should be saved or not.

set_operations_valid_exterior_faces(new_faces: List[Face3D], valid_faces: List[Face3D], list_coincident_faces: List[Face3D], shell2)

Select the valid faces from the new faces created during Boolean operations.

Parameters:

• new_faces – list of new divided faces.

• valid_faces – list of already validated faces.

• list_coincident_faces – if of coincident faces.

• shell2 – shell2, used in the Boolean operation.

Returns:

subtract(shell2, tol=1e-08)

Given Two closed shells, it returns a new subtracted OpenShell3D.

subtract_to_closed_shell(shell2: ClosedShell3D, tol: float = 1e-08)

Subtracts shell2’s volume from self.

Parameters:

• shell2 – other shell

• tol – tolerance

Returns:

subtraction_faces(shell2, intersecting_faces, dict_faces_intersections, keep_interior_faces: bool)

Gets new faces for subtraction Boolean operation between two closed shell 3d.

Parameters:

• shell2 – other shell

• intersecting_faces – list of all intersecting faces.

• dict_faces_intersections – Dictionary containing all combination of faces intersection, with corresponding intersections.

Returns:

list of new faces for subtraction of two closed shells 3.

union(shell2: ClosedShell3D, tol: float = 1e-08)

Given Two closed shells, it returns a new united ClosedShell3D object.

union_faces(shell2, intersecting_faces, dict_faces_intersections, list_coincident_faces)

Gets new faces for union Boolean operation between two closed shell 3d.

Parameters:

• shell2 – other shell

• intersecting_faces – list of all intersecting faces.

• dict_faces_intersections – Dictionary containing all combination of faces intersection, with corresponding intersections.

• list_coincident_faces – list of coincident faces.

Returns:

list of new faces for union of two closed shell3.

valid_intersection_faces(new_faces, valid_faces, shell2)

Validate Boolean intersection operation new faces.

Parameters:

• new_faces – list of new divided faces.

• valid_faces – list of already validated faces.

• shell2 – other shell.

Returns:

validate_intersection_operation(shell2)

Verifies if two shells are valid for union or subtractions operations.

Its Verifies if they are disjointed or if one is totally inside the other. If it returns an empty list, it means the two shells are valid to continue the operation.

static validate_non_intersecting_faces(shell2, non_intersecting_faces, intersection_method=False)

Gets lists of faces that never intersect with any of the shell2’s faces.

Parameters:

• shell2 – ClosedShell3D.

• non_intersecting_faces –

• intersection_method – determines if running for intersection operation.

returns a list of all the faces that never intersect any face of the other shell.

validate_set_operation(shell2, tol)

Verifies if two shells are valid for union or subtractions operations.

Its Verifies if they are disjointed or if one is totally inside the other.

If it returns an empty list, it means the two shells are valid to continue the operation.

static validate_set_operations_faces(faces)

Final validation of new faces created during intersections or subtractions of two closed shells.

Parameters:

faces – new faces.

Returns:

valid faces.

volume()

Does not consider holes.

class volmdlr.shells.ClosedTriangleShell3D(faces: List[Triangle3D], color: Tuple[float, float, float] | None = None, alpha: float = 1.0, reference_path: str = '#', name: str = '')

Bases: OpenTriangleShell3D, ClosedShell3D

A 3D closed shell composed of multiple triangle faces.

This class represents a 3D closed shell, which is a collection of connected triangle faces with a volume. It is a subclass of both the ClosedShell3D and OpenTriangleShell3D classes and inherits all of their attributes and methods.

Parameters:

• faces (List[Triangle3D]) – The triangle faces of the shell.

• color (Tuple[float, float, float]) – The color of the shell.

• alpha (float) – The transparency of the shell, should be a value in the range (0, 1).

• name (str) – The name of the shell.

are_normals_pointing_inwards()

Verifies if all face’s normal are pointing inwards the closed shell.

are_normals_pointing_outwards()

Verifies if all face’s normal are pointing outwards the closed shell.

turn_normals_inwards()

Turns the normals of the closed shells faces always inwards.

Returns:

A new ClosedTriangleShell3D object having all faces normals pointing inwards.

turn_normals_outwards()

Turns the normals of the closed shells faces always outwards.

Returns:

A new ClosedTriangleShell3D object having all faces normals pointing outwards.

class volmdlr.shells.DisplayTriangleShell3D(positions: ndarray[Any, dtype[float]], indices: ndarray[Any, dtype[int]], reference_path: str = '#', name: str = '')

Bases: Shell3D

A Triangle Shell 3D optimized for display and saving purpose.

This shell has the particularity to not instantiate the Triangle3D objects, to reduce memory usage and improve performance.

babylon_meshes(merge_meshes=True)

Overload of ‘babylon_meshes’ for performance.

concatenate(other: DisplayTriangleShell3D) → DisplayTriangleShell3D

Concatenates two DisplayTriangleShell3D instances into a single instance.

This method merges the positions and indices of both shells. If the same vertex exists in both shells, it is only included once in the merged shell to optimize memory usage. It also ensures that each face is represented uniquely by sorting the vertices of each triangle.

Parameters:

other – Another DisplayTriangleShell3D instance to concatenate with this instance.

Returns:

A new DisplayTriangleShell3D instance representing the concatenated shells.

classmethod dict_to_object(dict_: Dict[str, Any], **kwargs) → DisplayTriangleShell3D

Overload of ‘dict_to_object’ for performance.

classmethod from_triangle_shell(triangle_shell: OpenTriangleShell3D | ClosedTriangleShell3D) → DisplayTriangleShell3D

Instantiate a DisplayTriangleShell3D from an OpenTriangleShell3D or a ClosedTriangleShell3D.

Parameters:

triangle_shell (OpenTriangleShell3D | ClosedTriangleShell3D) – The triangle shell to create the DisplayTriangleShell3D from.

Returns:

The created DisplayTriangleShell3D.

Return type:

DisplayTriangleShell3D

get_bounding_box() → BoundingBox

Gets the Shell bounding box.

to_dict(*args, **kwargs)

Overload of ‘to_dict’ for performance.

class volmdlr.shells.OpenShell3D(faces: List[Face3D], color: Tuple[float, float, float] | None = None, alpha: float = 1.0, name: str = '', bounding_box: BoundingBox | None = None, reference_path: str = '#')

Bases: Shell3D

A 3D Open shell composed of multiple faces.

This class represents a 3D open shell, which is a collection of connected faces with no volume. It is a subclass of the Shell3D class and inherits all of its attributes and methods.

STEP_FUNCTION = 'OPEN_SHELL'

union(shell2)

Combine two shells faces.

Returns:

a new OpenShell3D with the combined faces.

class volmdlr.shells.OpenTriangleShell3D(faces: List[Triangle3D], color: Tuple[float, float, float] | None = None, alpha: float = 1.0, reference_path: str = '#', name: str = '')

Bases: OpenShell3D

A 3D open shell composed of multiple triangle faces.

This class represents a 3D open shell, which is a collection of connected triangle faces with no volume. It is a subclass of the OpenShell3D class and inherits all of its attributes and methods.

Parameters:

• faces (List[Triangle3D]) – The triangle faces of the shell.

• color (Tuple[float, float, float]) – The color of the shell.

• alpha (float) – The transparency of the shell, should be a value in the range (0, 1).

• name (str) – The name of the shell.

decimate(target_count: int, update_rate: int = 5, aggressiveness: float = 7.0, max_iterations: int = 100, verbose: bool = False, lossless: bool = False, threshold_lossless: float = 0.001, alpha: float = 1e-09, k: int = 3, preserve_border: bool = True)

Decimate the triangle shell, and return it.

Note: threshold = alpha * pow(iteration + k, aggressiveness)

Parameters:

• target_count (int) – Target number of triangles. Not used if lossless is True.

• update_rate (int) – Number of iterations between each update. If lossless flag is set to True, rate is 1.

• aggressiveness (float) – Parameter controlling the growth rate of the threshold at each iteration when lossless is False.

• max_iterations (int) – Maximal number of iterations.

• verbose (bool) – Control verbosity.

• lossless (bool) – Use the lossless simplification method.

• threshold_lossless (float) – Maximal error after which a vertex is not deleted. Only for lossless method.

• alpha (float) – Parameter for controlling the threshold growth.

• k (int) – Parameter for controlling the threshold growth.

• preserve_border (bool) – Flag for preserving vertices on open border.

Returns:

The decimated triangle shell.

Return type:

OpenTriangleShell3D

classmethod dict_to_object(dict_: Dict[str, Any], **kwargs) → OpenTriangleShell3D

Overload of ‘dict_to_object’ for performance.

classmethod from_mesh_data(vertices: Iterable[Iterable[float]], faces: Iterable[Iterable[int]], name: str = '')

Create a TriangleShell3D from mesh data: vertices and faces described as index of vertices.

Parameters:

• vertices (Iterable[Iterable[float]]) – The vertices of the mesh.

• faces (Iterable[Iterable[int]]) – The faces of the mesh, using vertices indexes.

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

Returns:

The created TriangleShell3D.

Return type:

TriangleShell3D

classmethod from_trimesh(trimesh, name: str = '')

Creates a TriangleShell3D from Trimesh.

get_bounding_box() → BoundingBox

Gets the Shell bounding box.

to_dict(*args, **kwargs)

Overload of ‘to_dict’ for performance.

to_display_triangle_shell() → DisplayTriangleShell3D

Create a DisplayTriangleShell3D from the current TriangleShell3D.

Returns:

The created DisplayTriangleShell3D.

Return type:

DisplayTriangleShell3D

to_mesh_data(round_vertices: bool, n_decimals: int = 9) → Tuple[ndarray[Any, dtype[float]], ndarray[Any, dtype[int]]]

Convert the TriangleShell3D to mesh data: vertices and faces described as index of vertices.

Parameters:

• round_vertices (bool) – Allows to choose to round vertices coordinates or not. Rounding vertices coordinates allows to prevent numerical imprecision, which allows vertex sharing between adjacent triangles.

• n_decimals (float) – int

Returns:

The vertices and faces composing the mesh data.

Return type:

Tuple[NDArray[float], NDArray[int]]

to_trimesh()

Creates a Trimesh from a TriangleShell3D.

triangulation()

Triangulation of an Open Triangle Shell 3D.

class volmdlr.shells.Shell3D(faces: List[Face3D], color: Tuple[float, float, float] | None = None, alpha: float = 1.0, name: str = '', bounding_box: BoundingBox | None = None, reference_path: str = '#')

Bases: CompositePrimitive3D

A 3D shell composed of multiple faces.

This class represents a 3D shell, which is a collection of connected faces with volume. It is a subclass of the CompositePrimitive3D class and inherits all of its attributes and methods.

Parameters:

• faces (List[Face3D]) – The faces of the shell.

• color (Tuple[float, float, float]) – The color of the shell.

• alpha (float) – The transparency of the shell, should be a value in the interval (0, 1).

• name (str) – The name of the shell.

• bounding_box (volmdlr.core.BoundingBox) – The bounding box of the shell.

STEP_FUNCTION = None

babylon_meshes(merge_meshes=True)

Returns the babylonjs mesh.

property bounding_box

Returns the boundary box.

copy(deep=True, memo=None)

Copy of Shell3D.

Returns:

return a copy a shell 3D.

cut_by_plane(plane_3d: Plane3D)

Cut Shell3D by plane 3d.

Parameters:

plane_3d – plane 3d o cut shell.

Returns:

return a list of faces containing the shell’s sections at the plane 3d given.

face_on_shell(face, abs_tol: float = 1e-06)

Verifies if a face lies on the shell’s surface.

faces_graph(verify_connected_components=True)

Gets the shells faces topology graph using networkx.

Returns:

return a networkx graph for a shell faces.

frame_mapping(frame: Frame3D, side: str)

Changes frame_mapping and return a new OpenShell3D.

side = ‘old’ or ‘new’.

classmethod from_faces(faces, name: str = '')

Defines a List of separated OpenShell3D from a list of faces, based on the faces graph.

classmethod from_step(arguments, object_dict, **kwargs)

Converts a step primitive to an Open Shell 3D.

Parameters:

• arguments (list) – The arguments of the step primitive.

• object_dict (dict) – The dictionary containing all the step primitives that have already been instantiated.

Returns:

The corresponding OpenShell3D object.

Return type:

volmdlr.faces.OpenShell3D

get_bounding_box()

Gets the Shell bounding box.

get_geo_lines(update_data, point_mesh_size: float | None = None)

Gets the lines that define an OpenShell3D geometry in a .geo file.

Parameters:

• update_data (dict) – Data used for VolumeModel defined with different shells

• point_mesh_size (float, optional) – The mesh size at a specific point, defaults to None

Returns:

A list of lines that describe the geometry & the updated data

Return type:

Tuple(List[str], dict)

get_mesh_lines_with_transfinite_curves(min_points, size)

Gets Shells’ mesh lines with transfinite curves.

get_minimum_distance_nearby_faces(other_shell)

Gets the nearby faces of the two shells where the minimum distance points could be, for further calculations.

Parameters:

other_shell – other shell.

Returns:

A list faces of self, with the closest faces to shell2, and another faces list of shell2,

with those closest to self.

intersection_external_aabb_volume(shell2: OpenShell3D, resolution: float)

Aabb made of the intersection points and the points of self external to shell2.

intersection_internal_aabb_volume(shell2: OpenShell3D, resolution: float)

Aabb made of the intersection points and the points of self internal to shell2.

is_disjoint_from(shell2, tol=1e-08)

Verifies and returns a Boolean if two shells are disjointed or not.

is_face_intersecting(face: Face3D)

Verifies if face is intersecting shell somehow.

is_intersecting_with(shell2)

Verifies if two closed shells are intersecting somehow.

static is_shell_open(faces, faces_graph=None)

Returns True if shell is an open shell.

line_intersections(line3d: Line3D) → List[Tuple[Face3D, List[Point3D]]]

Gets the intersections of a Shell3D with a Line Segment 3D.

Parameters:

line3d – other line segment.

Returns:

List of tuples (face, intersections).

linesegment_intersections(linesegment3d: LineSegment3D) → List[Tuple[Face3D, List[Point3D]]]

Gets the intersections of a Shell3D with a Line Segment 3D.

Parameters:

linesegment3d – other line segment.

Returns:

List of tuples (face, intersections).

minimum_distance(other_shell, return_points=False)

Calculates the minimum distance between two shells 3D.

Parameters:

• other_shell – other shell.

• return_points – weather to return the minimum distance corresponding points.

Returns:

minimum distance, and if condition is True, the corresponding points.

minimum_distance_point(point: Point3D) → Point3D

Computes the distance of a point to a Shell3D, whether it is inside or outside the Shell3D.

minimum_distance_points(shell2)

Returns a Measure object if the distance is not zero, otherwise returns None.

plot(ax=None, color: str = 'k', alpha: float = 1.0)

Plot a Shell 3D using Matplotlib.

point_on_shell(point: Point3D)

Verify if a point is on the shell (on one of the shell’s faces).

Parameters:

point – point to be verified.

Returns:

return True or False.

project_coincident_faces_of(shell)

Divides self’s faces based on coincident shell’s faces.

rotation(center: Point3D, axis: Vector3D, angle: float)

Open Shell 3D / Closed Shell 3D rotation.

Parameters:

• center – rotation center.

• axis – rotation axis.

• angle – angle rotation.

Returns:

a new rotated OpenShell3D.

shell_decomposition()

Decomposition of a shell 3D.

to_dict(*args, **kwargs)

Serializes a 3-dimensional open shell into a dictionary.

This method does not use pointers for faces as it has no sense to have duplicate faces.

Returns:

A serialized version of the OpenShell3D

Return type:

dict

. see also::

How `serialization and de-serialization`_ works in dessia_common

. _serialization and deserialization: https://documentation.dessia.tech/dessia_common/customizing.html#overloading-the-dict-to-object-method

to_step(current_id)

Creates step file entities from volmdlr objects.

to_step_face_ids(current_id)

Creates step file entities from volmdlr objects.

to_step_product(current_id)

Creates step file entities from volmdlr objects.

to_triangle_shell() → OpenTriangleShell3D | ClosedTriangleShell3D

Convert the current shell to a triangle shell.

If the current shell is already a triangle shell, return it “as is”. This conversion conserves the Open / Closed specification.

translation(offset: Vector3D)

Shell3D translation.

Parameters:

offset – translation vector.

Returns:

A new translated Open Shell 3D.

triangulation() → Mesh3D

Performs triangulation on a Shell3D object.

This method iterates through each face of the Shell3D object and attempts to perform a triangulation. In cases where a face cannot be triangulated, a warning is issued, and the method proceeds to the next face. The triangulation of successfully processed faces are collected and merged into a single Mesh3D object.

Returns:

A Mesh3D object representing the triangulated shell.

Return type:

display.Mesh3D

property vertices_graph

Gets the shells faces graph using networkx.

Returns:

return a networkx graph for a shell faces’ vertices.

property vertices_points

Gets the shell’s vertices points.

volmdlr.shells.union_list_of_shells(list_shells, abs_tol: float = 1e-06)

Perform union operations with all shells from a list, until all groups of adjacent shells are merged.

Parameters:

• list_shells – A list of shells.

• abs_tol – tolerance.

Returns:

A list of merged shells