""" build123d topology name: shape_core.py by: Gumyr date: January 07, 2025 desc: This module defines the foundational classes and methods for the build123d CAD library, enabling detailed geometric operations and 3D modeling capabilities. It provides a hierarchy of classes representing various geometric entities like vertices, edges, wires, faces, shells, solids, and compounds. These classes are designed to work seamlessly with the OpenCascade Python bindings, leveraging its robust CAD kernel. Key Features: - **Shape Base Class:** Implements core functionalities such as transformations (rotation, translation, scaling), geometric queries, and boolean operations (cut, fuse, intersect). - **Custom Utilities:** Includes helper classes like `ShapeList` for advanced filtering, sorting, and grouping of shapes, and `GroupBy` for organizing shapes by specific criteria. - **Type Safety:** Extensive use of Python typing features ensures clarity and correctness in type handling. - **Advanced Geometry:** Supports operations like finding intersections, computing bounding boxes, projecting faces, and generating triangulated meshes. The module is designed for extensibility, enabling developers to build complex 3D assemblies and perform detailed CAD operations programmatically while maintaining a clean and structured API. license: Copyright 2025 Gumyr 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 import copy import itertools import warnings from abc import ABC, abstractmethod from typing import ( cast as tcast, Any, Generic, Optional, Protocol, SupportsIndex, TypeVar, Union, overload, TYPE_CHECKING, ) from collections.abc import Callable, Iterable, Iterator import OCP.GeomAbs as ga import OCP.TopAbs as ta from IPython.lib.pretty import pretty, RepresentationPrinter from OCP.BOPAlgo import BOPAlgo_GlueEnum from OCP.BRep import BRep_Tool from OCP.BRepAdaptor import BRepAdaptor_Curve, BRepAdaptor_Surface from OCP.BRepAlgoAPI import ( BRepAlgoAPI_BooleanOperation, BRepAlgoAPI_Common, BRepAlgoAPI_Cut, BRepAlgoAPI_Fuse, BRepAlgoAPI_Section, BRepAlgoAPI_Splitter, ) from OCP.BRepBuilderAPI import ( BRepBuilderAPI_Copy, BRepBuilderAPI_GTransform, BRepBuilderAPI_MakeEdge, BRepBuilderAPI_MakeFace, BRepBuilderAPI_MakeVertex, BRepBuilderAPI_RightCorner, BRepBuilderAPI_RoundCorner, BRepBuilderAPI_Sewing, BRepBuilderAPI_Transform, BRepBuilderAPI_Transformed, ) from OCP.BRepCheck import BRepCheck_Analyzer from OCP.BRepExtrema import BRepExtrema_DistShapeShape from OCP.BRepFeat import BRepFeat_SplitShape from OCP.BRepGProp import BRepGProp, BRepGProp_Face from OCP.BRepIntCurveSurface import BRepIntCurveSurface_Inter from OCP.BRepMesh import BRepMesh_IncrementalMesh from OCP.BRepTools import BRepTools from OCP.Bnd import Bnd_Box, Bnd_OBB from OCP.GProp import GProp_GProps from OCP.Geom import Geom_Line from OCP.GeomAPI import GeomAPI_ProjectPointOnSurf from OCP.GeomLib import GeomLib_IsPlanarSurface from OCP.ShapeAnalysis import ShapeAnalysis_Curve from OCP.ShapeCustom import ShapeCustom, ShapeCustom_RestrictionParameters from OCP.ShapeFix import ShapeFix_Shape from OCP.ShapeUpgrade import ShapeUpgrade_UnifySameDomain from OCP.TopAbs import TopAbs_Orientation, TopAbs_ShapeEnum from OCP.TopExp import TopExp, TopExp_Explorer from OCP.TopLoc import TopLoc_Location from OCP.TopTools import ( TopTools_IndexedDataMapOfShapeListOfShape, TopTools_ListOfShape, TopTools_SequenceOfShape, ) from OCP.TopoDS import ( TopoDS, TopoDS_Compound, TopoDS_Face, TopoDS_Iterator, TopoDS_Shape, TopoDS_Shell, TopoDS_Solid, TopoDS_Vertex, TopoDS_Edge, TopoDS_Wire, ) from OCP.gce import gce_MakeLin from OCP.gp import gp_Ax1, gp_Ax2, gp_Ax3, gp_Dir, gp_Pnt, gp_Trsf, gp_Vec from anytree import NodeMixin, RenderTree from build123d.build_enums import CenterOf, GeomType, Keep, SortBy, Transition from build123d.geometry import ( DEG2RAD, TOLERANCE, Axis, BoundBox, Color, Location, Matrix, OrientedBoundBox, Plane, Vector, VectorLike, logger, ) from typing_extensions import Self from typing import Literal if TYPE_CHECKING: # pragma: no cover from .zero_d import Vertex # pylint: disable=R0801 from .one_d import Edge, Wire # pylint: disable=R0801 from .two_d import Face, Shell # pylint: disable=R0801 from .three_d import Solid # pylint: disable=R0801 from .composite import Compound # pylint: disable=R0801 from build123d.build_part import BuildPart # pylint: disable=R0801 Shapes = Literal["Vertex", "Edge", "Wire", "Face", "Shell", "Solid", "Compound"] TrimmingTool = Union[Plane, "Shell", "Face"] TOPODS = TypeVar("TOPODS", bound=TopoDS_Shape) class Shape(NodeMixin, Generic[TOPODS]): """Shape Base class for all CAD objects such as Edge, Face, Solid, etc. Args: obj (TopoDS_Shape, optional): OCCT object. Defaults to None. label (str, optional): Defaults to ''. color (Color, optional): Defaults to None. parent (Compound, optional): assembly parent. Defaults to None. Attributes: wrapped (TopoDS_Shape): the OCP object label (str): user assigned label color (Color): object color joints (dict[str:Joint]): dictionary of joints bound to this object (Solid only) children (Shape): list of assembly children of this object (Compound only) topo_parent (Shape): assembly parent of this object """ shape_LUT = { ta.TopAbs_VERTEX: "Vertex", ta.TopAbs_EDGE: "Edge", ta.TopAbs_WIRE: "Wire", ta.TopAbs_FACE: "Face", ta.TopAbs_SHELL: "Shell", ta.TopAbs_SOLID: "Solid", ta.TopAbs_COMPOUND: "Compound", ta.TopAbs_COMPSOLID: "CompSolid", } shape_properties_LUT = { ta.TopAbs_VERTEX: None, ta.TopAbs_EDGE: BRepGProp.LinearProperties_s, ta.TopAbs_WIRE: BRepGProp.LinearProperties_s, ta.TopAbs_FACE: BRepGProp.SurfaceProperties_s, ta.TopAbs_SHELL: BRepGProp.SurfaceProperties_s, ta.TopAbs_SOLID: BRepGProp.VolumeProperties_s, ta.TopAbs_COMPOUND: BRepGProp.VolumeProperties_s, ta.TopAbs_COMPSOLID: BRepGProp.VolumeProperties_s, } inverse_shape_LUT = {v: k for k, v in shape_LUT.items()} downcast_LUT = { ta.TopAbs_VERTEX: TopoDS.Vertex_s, ta.TopAbs_EDGE: TopoDS.Edge_s, ta.TopAbs_WIRE: TopoDS.Wire_s, ta.TopAbs_FACE: TopoDS.Face_s, ta.TopAbs_SHELL: TopoDS.Shell_s, ta.TopAbs_SOLID: TopoDS.Solid_s, ta.TopAbs_COMPOUND: TopoDS.Compound_s, ta.TopAbs_COMPSOLID: TopoDS.CompSolid_s, } geom_LUT_EDGE: dict[ga.GeomAbs_CurveType, GeomType] = { ga.GeomAbs_Line: GeomType.LINE, ga.GeomAbs_Circle: GeomType.CIRCLE, ga.GeomAbs_Ellipse: GeomType.ELLIPSE, ga.GeomAbs_Hyperbola: GeomType.HYPERBOLA, ga.GeomAbs_Parabola: GeomType.PARABOLA, ga.GeomAbs_BezierCurve: GeomType.BEZIER, ga.GeomAbs_BSplineCurve: GeomType.BSPLINE, ga.GeomAbs_OffsetCurve: GeomType.OFFSET, ga.GeomAbs_OtherCurve: GeomType.OTHER, } geom_LUT_FACE: dict[ga.GeomAbs_SurfaceType, GeomType] = { ga.GeomAbs_Plane: GeomType.PLANE, ga.GeomAbs_Cylinder: GeomType.CYLINDER, ga.GeomAbs_Cone: GeomType.CONE, ga.GeomAbs_Sphere: GeomType.SPHERE, ga.GeomAbs_Torus: GeomType.TORUS, ga.GeomAbs_BezierSurface: GeomType.BEZIER, ga.GeomAbs_BSplineSurface: GeomType.BSPLINE, ga.GeomAbs_SurfaceOfRevolution: GeomType.REVOLUTION, ga.GeomAbs_SurfaceOfExtrusion: GeomType.EXTRUSION, ga.GeomAbs_OffsetSurface: GeomType.OFFSET, ga.GeomAbs_OtherSurface: GeomType.OTHER, } _transModeDict = { Transition.TRANSFORMED: BRepBuilderAPI_Transformed, Transition.ROUND: BRepBuilderAPI_RoundCorner, Transition.RIGHT: BRepBuilderAPI_RightCorner, } class _DisplayNode(NodeMixin): """Used to create anytree structures from TopoDS_Shapes""" def __init__( self, label: str = "", address: int | None = None, position: Vector | Location | None = None, parent: Shape._DisplayNode | None = None, ): self.label = label self.address = address self.position = position self.parent = parent self.children: list[Shape] = [] _ordered_shapes = [ TopAbs_ShapeEnum.TopAbs_COMPOUND, TopAbs_ShapeEnum.TopAbs_SOLID, TopAbs_ShapeEnum.TopAbs_SHELL, TopAbs_ShapeEnum.TopAbs_FACE, TopAbs_ShapeEnum.TopAbs_WIRE, TopAbs_ShapeEnum.TopAbs_EDGE, TopAbs_ShapeEnum.TopAbs_VERTEX, ] # ---- Constructor ---- def __init__( self, obj: TopoDS_Shape | None = None, label: str = "", color: Color | None = None, parent: Compound | None = None, ): self.wrapped: TOPODS | None = ( tcast(Optional[TOPODS], downcast(obj)) if obj is not None else None ) self.for_construction = False self.label = label self._color = color # parent must be set following children as post install accesses children self.parent = parent # Extracted objects like Vertices and Edges may need to know where they came from self.topo_parent: Shape | None = None # ---- Properties ---- # pylint: disable=too-many-instance-attributes, too-many-public-methods @property @abstractmethod def _dim(self) -> int | None: """Dimension of the object""" @property def area(self) -> float: """area -the surface area of all faces in this Shape""" if self.wrapped is None: return 0.0 properties = GProp_GProps() BRepGProp.SurfaceProperties_s(self.wrapped, properties) return properties.Mass() @property def color(self) -> None | Color: """Get the shape's color. If it's None, get the color of the nearest ancestor, assign it to this Shape and return this value.""" # Find the correct color for this node if self._color is None: # Find parent color current_node: Compound | Shape | None = self while current_node is not None: parent_color = current_node._color if parent_color is not None: break current_node = current_node.parent node_color = parent_color else: node_color = self._color self._color = node_color # Set the node's color for next time return node_color @color.setter def color(self, value): """Set the shape's color""" self._color = value @property def geom_type(self) -> GeomType: """Gets the underlying geometry type. Returns: GeomType: The geometry type of the shape """ if self.wrapped is None: raise ValueError("Cannot determine geometry type of an empty shape") shape: TopAbs_ShapeEnum = shapetype(self.wrapped) if shape == ta.TopAbs_EDGE: geom = Shape.geom_LUT_EDGE[ BRepAdaptor_Curve(tcast(TopoDS_Edge, self.wrapped)).GetType() ] elif shape == ta.TopAbs_FACE: geom = Shape.geom_LUT_FACE[ BRepAdaptor_Surface(tcast(TopoDS_Face, self.wrapped)).GetType() ] else: geom = GeomType.OTHER return geom @property def is_manifold(self) -> bool: """is_manifold Check if each edge in the given Shape has exactly two faces associated with it (skipping degenerate edges). If so, the shape is manifold. Returns: bool: is the shape manifold or water tight """ # Extract one or more (if a Compound) shape from self if self.wrapped is None: return False shape_stack = get_top_level_topods_shapes(self.wrapped) while shape_stack: shape = shape_stack.pop(0) # Create an empty indexed data map to store the edges and their corresponding faces. shape_map = TopTools_IndexedDataMapOfShapeListOfShape() # Fill the map with edges and their associated faces in the given shape. Each edge in # the map is associated with a list of faces that share that edge. TopExp.MapShapesAndAncestors_s( # shape.wrapped, ta.TopAbs_EDGE, ta.TopAbs_FACE, shape_map shape, ta.TopAbs_EDGE, ta.TopAbs_FACE, shape_map, ) # Iterate over the edges in the map and checks if each edge is non-degenerate and has # exactly two faces associated with it. for i in range(shape_map.Extent()): # Access each edge in the map sequentially edge = TopoDS.Edge_s(shape_map.FindKey(i + 1)) vertex0 = TopoDS_Vertex() vertex1 = TopoDS_Vertex() # Extract the two vertices of the current edge and stores them in vertex0/1. TopExp.Vertices_s(edge, vertex0, vertex1) # Check if both vertices are null and if they are the same vertex. If so, the # edge is considered degenerate (i.e., has zero length), and it is skipped. if vertex0.IsNull() and vertex1.IsNull() and vertex0.IsSame(vertex1): continue # Check if the current edge has exactly two faces associated with it. If not, # it means the edge is not shared by exactly two faces, indicating that the # shape is not manifold. if shape_map.FindFromIndex(i + 1).Extent() != 2: return False return True @property def is_planar_face(self) -> bool: """Is the shape a planar face even though its geom_type may not be PLANE""" if self.wrapped is None or not isinstance(self.wrapped, TopoDS_Face): return False surface = BRep_Tool.Surface_s(self.wrapped) is_face_planar = GeomLib_IsPlanarSurface(surface, TOLERANCE) return is_face_planar.IsPlanar() @property def location(self) -> Location | None: """Get this Shape's Location""" if self.wrapped is None: return None return Location(self.wrapped.Location()) @location.setter def location(self, value: Location): """Set Shape's Location to value""" if self.wrapped is not None: self.wrapped.Location(value.wrapped) @property def matrix_of_inertia(self) -> list[list[float]]: """ Compute the inertia matrix (moment of inertia tensor) of the shape. The inertia matrix represents how the mass of the shape is distributed with respect to its reference frame. It is a 3×3 symmetric tensor that describes the resistance of the shape to rotational motion around different axes. Returns: list[list[float]]: A 3×3 nested list representing the inertia matrix. The elements of the matrix are given as: | Ixx Ixy Ixz | | Ixy Iyy Iyz | | Ixz Iyz Izz | where: - Ixx, Iyy, Izz are the moments of inertia about the X, Y, and Z axes. - Ixy, Ixz, Iyz are the products of inertia. Example: >>> obj = MyShape() >>> obj.matrix_of_inertia [[1000.0, 50.0, 0.0], [50.0, 1200.0, 0.0], [0.0, 0.0, 300.0]] Notes: - The inertia matrix is computed relative to the shape's center of mass. - It is commonly used in structural analysis, mechanical simulations, and physics-based motion calculations. """ properties = GProp_GProps() BRepGProp.VolumeProperties_s(self.wrapped, properties) inertia_matrix = properties.MatrixOfInertia() matrix = [] for i in range(3): matrix.append([inertia_matrix.Value(i + 1, j + 1) for j in range(3)]) return matrix @property def orientation(self) -> Vector | None: """Get the orientation component of this Shape's Location""" if self.location is None: return None return self.location.orientation @orientation.setter def orientation(self, rotations: VectorLike): """Set the orientation component of this Shape's Location to rotations""" loc = self.location if loc is not None: loc.orientation = Vector(rotations) self.location = loc @property def position(self) -> Vector | None: """Get the position component of this Shape's Location""" if self.wrapped is None or self.location is None: return None return self.location.position @position.setter def position(self, value: VectorLike): """Set the position component of this Shape's Location to value""" loc = self.location if loc is not None: loc.position = Vector(value) self.location = loc @property def principal_properties(self) -> list[tuple[Vector, float]]: """ Compute the principal moments of inertia and their corresponding axes. Returns: list[tuple[Vector, float]]: A list of tuples, where each tuple contains: - A `Vector` representing the axis of inertia. - A `float` representing the moment of inertia for that axis. Example: >>> obj = MyShape() >>> obj.principal_properties [(Vector(1, 0, 0), 1200.0), (Vector(0, 1, 0), 1000.0), (Vector(0, 0, 1), 300.0)] """ properties = GProp_GProps() BRepGProp.VolumeProperties_s(self.wrapped, properties) principal_props = properties.PrincipalProperties() principal_moments = principal_props.Moments() return [ (Vector(principal_props.FirstAxisOfInertia()), principal_moments[0]), (Vector(principal_props.SecondAxisOfInertia()), principal_moments[1]), (Vector(principal_props.ThirdAxisOfInertia()), principal_moments[2]), ] @property def static_moments(self) -> tuple[float, float, float]: """ Compute the static moments (first moments of mass) of the shape. The static moments represent the weighted sum of the coordinates with respect to the mass distribution, providing insight into the center of mass and mass distribution of the shape. Returns: tuple[float, float, float]: The static moments (Mx, My, Mz), where: - Mx is the first moment of mass about the YZ plane. - My is the first moment of mass about the XZ plane. - Mz is the first moment of mass about the XY plane. Example: >>> obj = MyShape() >>> obj.static_moments (150.0, 200.0, 50.0) """ properties = GProp_GProps() BRepGProp.VolumeProperties_s(self.wrapped, properties) return properties.StaticMoments() # ---- Class Methods ---- @classmethod @abstractmethod def cast(cls: type[Self], obj: TopoDS_Shape) -> Self: """Returns the right type of wrapper, given a OCCT object""" @classmethod @abstractmethod def extrude( cls, obj: Shape, direction: VectorLike ) -> Edge | Face | Shell | Solid | Compound: """extrude Extrude a Shape in the provided direction. * Vertices generate Edges * Edges generate Faces * Wires generate Shells * Faces generate Solids * Shells generate Compounds Args: direction (VectorLike): direction and magnitude of extrusion Raises: ValueError: Unsupported class RuntimeError: Generated invalid result Returns: Edge | Face | Shell | Solid | Compound: extruded shape """ # ---- Static Methods ---- @staticmethod def _build_tree( shape: TopoDS_Shape, tree: list[_DisplayNode], parent: _DisplayNode | None = None, limit: TopAbs_ShapeEnum = TopAbs_ShapeEnum.TopAbs_VERTEX, show_center: bool = True, ) -> list[_DisplayNode]: """Create an anytree copy of the TopoDS_Shape structure""" obj_type = Shape.shape_LUT[shape.ShapeType()] loc: Vector | Location if show_center: loc = Shape(shape).bounding_box().center() else: loc = Location(shape.Location()) tree.append(Shape._DisplayNode(obj_type, id(shape), loc, parent)) iterator = TopoDS_Iterator() iterator.Initialize(shape) parent_node = tree[-1] while iterator.More(): child = iterator.Value() if Shape._ordered_shapes.index( child.ShapeType() ) <= Shape._ordered_shapes.index(limit): Shape._build_tree(child, tree, parent_node, limit) iterator.Next() return tree @staticmethod def _show_tree(root_node, show_center: bool) -> str: """Display an assembly or TopoDS_Shape anytree structure""" # Calculate the size of the tree labels size_tuples = [(node.height, len(node.label)) for node in root_node.descendants] size_tuples.append((root_node.height, len(root_node.label))) # pylint: disable=cell-var-from-loop size_tuples_per_level = [ list(filter(lambda ll: ll[0] == l, size_tuples)) for l in range(root_node.height + 1) ] max_sizes_per_level = [ max(4, max(l[1] for l in level)) for level in size_tuples_per_level ] level_sizes_per_level = [ l + i * 4 for i, l in enumerate(reversed(max_sizes_per_level)) ] tree_label_width = max(level_sizes_per_level) + 1 # Build the tree line by line result = "" for pre, _fill, node in RenderTree(root_node): treestr = f"{pre}{node.label}".ljust(tree_label_width) if hasattr(root_node, "address"): address = node.address name = "" loc = ( "Center" + str(node.position.to_tuple()) if show_center else "Position" + str(node.position.to_tuple()) ) else: address = id(node) name = node.__class__.__name__.ljust(9) loc = ( "Center" + str(node.center().to_tuple()) if show_center else "Location" + repr(node.location) ) result += f"{treestr}{name}at {address:#x}, {loc}\n" return result @staticmethod def combined_center( objects: Iterable[Shape], center_of: CenterOf = CenterOf.MASS ) -> Vector: """combined center Calculates the center of a multiple objects. Args: objects (Iterable[Shape]): list of objects center_of (CenterOf, optional): centering option. Defaults to CenterOf.MASS. Raises: ValueError: CenterOf.GEOMETRY not implemented Returns: Vector: center of multiple objects """ objects = list(objects) if center_of == CenterOf.MASS: total_mass = sum(Shape.compute_mass(o) for o in objects) weighted_centers = [ o.center(CenterOf.MASS).multiply(Shape.compute_mass(o)) for o in objects ] sum_wc = weighted_centers[0] for weighted_center in weighted_centers[1:]: sum_wc = sum_wc.add(weighted_center) middle = Vector(sum_wc.multiply(1.0 / total_mass)) elif center_of == CenterOf.BOUNDING_BOX: total_mass = len(list(objects)) weighted_centers = [] for obj in objects: weighted_centers.append(obj.bounding_box().center()) sum_wc = weighted_centers[0] for weighted_center in weighted_centers[1:]: sum_wc = sum_wc.add(weighted_center) middle = Vector(sum_wc.multiply(1.0 / total_mass)) else: raise ValueError("CenterOf.GEOMETRY not implemented") return middle @staticmethod def compute_mass(obj: Shape) -> float: """Calculates the 'mass' of an object. Args: obj: Compute the mass of this object obj: Shape: Returns: """ if obj.wrapped is None: return 0.0 properties = GProp_GProps() calc_function = Shape.shape_properties_LUT[shapetype(obj.wrapped)] if not calc_function: raise NotImplementedError calc_function(obj.wrapped, properties) return properties.Mass() @staticmethod def get_shape_list( shape: Shape, entity_type: Literal[ "Vertex", "Edge", "Wire", "Face", "Shell", "Solid", "Compound" ], ) -> ShapeList: """Helper to extract entities of a specific type from a shape.""" if shape.wrapped is None: return ShapeList() shape_list = ShapeList( [shape.__class__.cast(i) for i in shape.entities(entity_type)] ) for item in shape_list: item.topo_parent = shape return shape_list @staticmethod def get_single_shape( shape: Shape, entity_type: Literal[ "Vertex", "Edge", "Wire", "Face", "Shell", "Solid", "Compound" ], ) -> Shape | None: """Helper to extract a single entity of a specific type from a shape, with a warning if count != 1.""" shape_list = Shape.get_shape_list(shape, entity_type) entity_count = len(shape_list) if entity_count != 1: warnings.warn( f"Found {entity_count} {entity_type.lower()}s, returning first", stacklevel=3, ) return shape_list[0] if shape_list else None # ---- Instance Methods ---- def __add__(self, other: None | Shape | Iterable[Shape]) -> Self | ShapeList[Self]: """fuse shape to self operator +""" # Convert `other` to list of base objects and filter out None values if other is None: summands = [] else: summands = [ shape # for o in (other if isinstance(other, (list, tuple)) else [other]) for o in ([other] if isinstance(other, Shape) else other) if o is not None for shape in o.get_top_level_shapes() ] # If there is nothing to add return the original object if not summands: return self # Check that all dimensions are the same addend_dim = self._dim if addend_dim is None: raise ValueError("Dimensions of objects to add to are inconsistent") if not all(summand._dim == addend_dim for summand in summands): raise ValueError("Only shapes with the same dimension can be added") if self.wrapped is None: # an empty object if len(summands) == 1: sum_shape = summands[0] else: sum_shape = summands[0].fuse(*summands[1:]) else: sum_shape = self.fuse(*summands) if SkipClean.clean and not isinstance(sum_shape, list): sum_shape = sum_shape.clean() return sum_shape def __and__(self, other: Shape | Iterable[Shape]) -> None | Self | ShapeList[Self]: """intersect shape with self operator &""" others = other if isinstance(other, (list, tuple)) else [other] if self.wrapped is None or (isinstance(other, Shape) and other.wrapped is None): raise ValueError("Cannot intersect shape with empty compound") new_shape = self.intersect(*others) if ( not isinstance(new_shape, list) and new_shape is not None and new_shape.wrapped is not None and SkipClean.clean ): new_shape = new_shape.clean() return new_shape def __copy__(self) -> Self: """Return shallow copy or reference of self Create an copy of this Shape that shares the underlying TopoDS_TShape. Used when there is a need for many objects with the same CAD structure but at different Locations, etc. - for examples fasteners in a larger assembly. By sharing the TopoDS_TShape, the memory size of such assemblies can be greatly reduced. Changes to the CAD structure of the base object will be reflected in all instances. """ reference = copy.deepcopy(self) if self.wrapped is not None: assert ( reference.wrapped is not None ) # Ensure mypy knows reference.wrapped is not None reference.wrapped.TShape(self.wrapped.TShape()) return reference def __deepcopy__(self, memo) -> Self: """Return deepcopy of self""" # The wrapped object is a OCCT TopoDS_Shape which can't be pickled or copied # with the standard python copy/deepcopy, so create a deepcopy 'memo' with this # value already copied which causes deepcopy to skip it. cls = self.__class__ result = cls.__new__(cls) memo[id(self)] = result if self.wrapped is not None: memo[id(self.wrapped)] = downcast(BRepBuilderAPI_Copy(self.wrapped).Shape()) for key, value in self.__dict__.items(): setattr(result, key, copy.deepcopy(value, memo)) if key == "joints": for joint in result.joints.values(): joint.parent = result return result def __eq__(self, other) -> bool: """Check if two shapes are the same. This method checks if the current shape is the same as the other shape. Two shapes are considered the same if they share the same TShape with the same Locations. Orientations may differ. Args: other (Shape): The shape to compare with. Returns: bool: True if the shapes are the same, False otherwise. """ if isinstance(other, Shape): return self.is_same(other) return NotImplemented def __hash__(self) -> int: """Return hash code""" if self.wrapped is None: return 0 return hash(self.wrapped) def __rmul__(self, other): """right multiply for positioning operator *""" if not ( isinstance(other, (list, tuple)) and all(isinstance(o, (Location, Plane)) for o in other) ): raise ValueError( "shapes can only be multiplied list of locations or planes" ) return [loc * self for loc in other] def __sub__(self, other: None | Shape | Iterable[Shape]) -> Self | ShapeList[Self]: """cut shape from self operator -""" if self.wrapped is None: raise ValueError("Cannot subtract shape from empty compound") # Convert `other` to list of base objects and filter out None values if other is None: subtrahends = [] else: subtrahends = [ shape # for o in (other if isinstance(other, (list, tuple)) else [other]) for o in ([other] if isinstance(other, Shape) else other) if o is not None for shape in o.get_top_level_shapes() ] # If there is nothing to subtract return the original object if not subtrahends: return self # Check that all dimensions are the same minuend_dim = self._dim if minuend_dim is None or any(s._dim is None for s in subtrahends): raise ValueError("Dimensions of objects to subtract from are inconsistent") # Check that the operation is valid subtrahend_dims = [s._dim for s in subtrahends if s._dim is not None] if any(d < minuend_dim for d in subtrahend_dims): raise ValueError( f"Only shapes with equal or greater dimension can be subtracted: " f"not {type(self).__name__} ({minuend_dim}D) and " f"{type(other).__name__} ({min(subtrahend_dims)}D)" ) # Do the actual cut operation difference = self.cut(*subtrahends) return difference def bounding_box( self, tolerance: float | None = None, optimal: bool = True ) -> BoundBox: """Create a bounding box for this Shape. Args: tolerance (float, optional): Defaults to None. Returns: BoundBox: A box sized to contain this Shape """ if self.wrapped is None: return BoundBox(Bnd_Box()) tolerance = TOLERANCE if tolerance is None else tolerance return BoundBox.from_topo_ds(self.wrapped, tolerance=tolerance, optimal=optimal) # Actually creating the abstract method causes the subclass to pass center_of # even when not required - possibly this could be improved. # @abstractmethod # def center(self, center_of: CenterOf) -> Vector: # """Compute the center with a specific type of calculation.""" def clean(self) -> Self: """clean Remove internal edges Returns: Shape: Original object with extraneous internal edges removed """ if self.wrapped is None: return self upgrader = ShapeUpgrade_UnifySameDomain(self.wrapped, True, True, True) upgrader.AllowInternalEdges(False) # upgrader.SetAngularTolerance(1e-5) try: upgrader.Build() self.wrapped = tcast(TOPODS, downcast(upgrader.Shape())) except Exception: warnings.warn(f"Unable to clean {self}", stacklevel=2) return self def closest_points(self, other: Shape | VectorLike) -> tuple[Vector, Vector]: """Points on two shapes where the distance between them is minimal""" return self.distance_to_with_closest_points(other)[1:3] def compound(self) -> Compound | None: """Return the Compound""" return None def compounds(self) -> ShapeList[Compound]: """compounds - all the compounds in this Shape""" return ShapeList() def copy_attributes_to( self, target: Shape, exceptions: Iterable[str] | None = None ): """Copy common object attributes to target Note that preset attributes of target will not be overridden. Args: target (Shape): object to gain attributes exceptions (Iterable[str], optional): attributes not to copy Raises: ValueError: invalid attribute """ # Find common attributes and eliminate exceptions attrs1 = set(self.__dict__.keys()) attrs2 = set(target.__dict__.keys()) common_attrs = attrs1 & attrs2 if exceptions is not None: common_attrs -= set(exceptions) for attr in common_attrs: # Copy the attribute only if the target's attribute not set if not getattr(target, attr): setattr(target, attr, getattr(self, attr)) # Attach joints to the new part if attr == "joints": joint: Joint for joint in target.joints.values(): joint.parent = target def cut(self, *to_cut: Shape) -> Self | ShapeList[Self]: """Remove the positional arguments from this Shape. Args: *to_cut: Shape: Returns: Self | ShapeList[Self]: Resulting object may be of a different class than self or a ShapeList if multiple non-Compound object created """ cut_op = BRepAlgoAPI_Cut() return self._bool_op((self,), to_cut, cut_op) def distance(self, other: Shape) -> float: """Minimal distance between two shapes Args: other: Shape: Returns: """ if self.wrapped is None or other.wrapped is None: raise ValueError("Cannot calculate distance to or from an empty shape") return BRepExtrema_DistShapeShape(self.wrapped, other.wrapped).Value() def distance_to(self, other: Shape | VectorLike) -> float: """Minimal distance between two shapes""" return self.distance_to_with_closest_points(other)[0] def distance_to_with_closest_points( self, other: Shape | VectorLike ) -> tuple[float, Vector, Vector]: """Minimal distance between two shapes and the points on each shape""" if self.wrapped is None or (isinstance(other, Shape) and other.wrapped is None): raise ValueError("Cannot calculate distance to or from an empty shape") if isinstance(other, Shape): topods_shape = tcast(TopoDS_Shape, other.wrapped) else: vec = Vector(other) topods_shape = BRepBuilderAPI_MakeVertex( gp_Pnt(vec.X, vec.Y, vec.Z) ).Vertex() dist_calc = BRepExtrema_DistShapeShape() dist_calc.LoadS1(self.wrapped) dist_calc.LoadS2(topods_shape) dist_calc.Perform() return ( dist_calc.Value(), Vector(dist_calc.PointOnShape1(1)), Vector(dist_calc.PointOnShape2(1)), ) def distances(self, *others: Shape) -> Iterator[float]: """Minimal distances to between self and other shapes Args: *others: Shape: Returns: """ if self.wrapped is None: raise ValueError("Cannot calculate distance to or from an empty shape") dist_calc = BRepExtrema_DistShapeShape() dist_calc.LoadS1(self.wrapped) for other_shape in others: if other_shape.wrapped is None: raise ValueError("Cannot calculate distance to or from an empty shape") dist_calc.LoadS2(other_shape.wrapped) dist_calc.Perform() yield dist_calc.Value() def edge(self) -> Edge | None: """Return the Edge""" return None # Note all sub-classes have vertices and vertex methods def edges(self) -> ShapeList[Edge]: """edges - all the edges in this Shape - subclasses may override""" return ShapeList() def entities(self, topo_type: Shapes) -> list[TopoDS_Shape]: """Return all of the TopoDS sub entities of the given type""" if self.wrapped is None: return [] return _topods_entities(self.wrapped, topo_type) def face(self) -> Face | None: """Return the Face""" return None def faces(self) -> ShapeList[Face]: """faces - all the faces in this Shape""" return ShapeList() def faces_intersected_by_axis( self, axis: Axis, tol: float = 1e-4, ) -> ShapeList[Face]: """Line Intersection Computes the intersections between the provided axis and the faces of this Shape Args: axis (Axis): Axis on which the intersection line rests tol (float, optional): Intersection tolerance. Defaults to 1e-4. Returns: list[Face]: A list of intersected faces sorted by distance from axis.position """ if self.wrapped is None: return ShapeList() line = gce_MakeLin(axis.wrapped).Value() intersect_maker = BRepIntCurveSurface_Inter() intersect_maker.Init(self.wrapped, line, tol) faces_dist = [] # using a list instead of a dictionary to be able to sort it while intersect_maker.More(): inter_pt = intersect_maker.Pnt() distance = axis.position.to_pnt().SquareDistance(inter_pt) faces_dist.append( ( intersect_maker.Face(), abs(distance), ) ) # will sort all intersected faces by distance whatever the direction is intersect_maker.Next() faces_dist.sort(key=lambda x: x[1]) faces = [face[0] for face in faces_dist] return ShapeList([self.__class__.cast(face) for face in faces]) def fix(self) -> Self: """fix - try to fix shape if not valid""" if self.wrapped is None: return self if not self.is_valid(): shape_copy: Shape = copy.deepcopy(self, None) shape_copy.wrapped = tcast(TOPODS, fix(self.wrapped)) return shape_copy return self def fuse( self, *to_fuse: Shape, glue: bool = False, tol: float | None = None ) -> Self | ShapeList[Self]: """fuse Fuse a sequence of shapes into a single shape. Args: to_fuse (sequence Shape): shapes to fuse glue (bool, optional): performance improvement for some shapes. Defaults to False. tol (float, optional): tolerance. Defaults to None. Returns: Self | ShapeList[Self]: Resulting object may be of a different class than self or a ShapeList if multiple non-Compound object created """ fuse_op = BRepAlgoAPI_Fuse() if glue: fuse_op.SetGlue(BOPAlgo_GlueEnum.BOPAlgo_GlueShift) if tol: fuse_op.SetFuzzyValue(tol) return_value = self._bool_op((self,), to_fuse, fuse_op) return return_value # def _entities_from( # self, child_type: Shapes, parent_type: Shapes # ) -> Dict[Shape, list[Shape]]: # """This function is very slow on M1 macs and is currently unused""" # if self.wrapped is None: # return {} # res = TopTools_IndexedDataMapOfShapeListOfShape() # TopExp.MapShapesAndAncestors_s( # self.wrapped, # Shape.inverse_shape_LUT[child_type], # Shape.inverse_shape_LUT[parent_type], # res, # ) # out: Dict[Shape, list[Shape]] = {} # for i in range(1, res.Extent() + 1): # out[self.__class__.cast(res.FindKey(i))] = [ # self.__class__.cast(el) for el in res.FindFromIndex(i) # ] # return out def get_top_level_shapes(self) -> ShapeList[Shape]: """ Retrieve the first level of child shapes from the shape. This method collects all the non-compound shapes directly contained in the current shape. If the wrapped shape is a `TopoDS_Compound`, it traverses its immediate children and collects all shapes that are not further nested compounds. Nested compounds are traversed to gather their non-compound elements without returning the nested compound itself. Returns: ShapeList[Shape]: A list of all first-level non-compound child shapes. Example: If the current shape is a compound containing both simple shapes (e.g., edges, vertices) and other compounds, the method returns a list of only the simple shapes directly contained at the top level. """ if self.wrapped is None: return ShapeList() return ShapeList( self.__class__.cast(s) for s in get_top_level_topods_shapes(self.wrapped) ) def intersect( self, *to_intersect: Shape | Axis | Plane ) -> None | Self | ShapeList[Self]: """Intersection of the arguments and this shape Args: to_intersect (sequence of Union[Shape, Axis, Plane]): Shape(s) to intersect with Returns: Self | ShapeList[Self]: Resulting object may be of a different class than self or a ShapeList if multiple non-Compound object created """ def _to_vertex(vec: Vector) -> Vertex: """Helper method to convert vector to shape""" return self.__class__.cast( downcast( BRepBuilderAPI_MakeVertex(gp_Pnt(vec.X, vec.Y, vec.Z)).Vertex() ) ) def _to_edge(axis: Axis) -> Edge: """Helper method to convert axis to shape""" return self.__class__.cast( BRepBuilderAPI_MakeEdge( Geom_Line( axis.position.to_pnt(), axis.direction.to_dir(), ) ).Edge() ) def _to_face(plane: Plane) -> Face: """Helper method to convert plane to shape""" return self.__class__.cast(BRepBuilderAPI_MakeFace(plane.wrapped).Face()) # Convert any geometry objects into their respective topology objects objs = [] for obj in to_intersect: if isinstance(obj, Vector): objs.append(_to_vertex(obj)) elif isinstance(obj, Axis): objs.append(_to_edge(obj)) elif isinstance(obj, Plane): objs.append(_to_face(obj)) elif isinstance(obj, Location): if obj.wrapped is None: raise ValueError("Cannot intersect with an empty location") objs.append(_to_vertex(tcast(Vector, obj.position))) else: objs.append(obj) # Find the shape intersections intersect_op = BRepAlgoAPI_Common() shape_intersections = self._bool_op((self,), objs, intersect_op) if isinstance(shape_intersections, ShapeList) and not shape_intersections: return None if ( not isinstance(shape_intersections, ShapeList) and shape_intersections.is_null() ): return None return shape_intersections def is_equal(self, other: Shape) -> bool: """Returns True if two shapes are equal, i.e. if they share the same TShape with the same Locations and Orientations. Also see :py:meth:`is_same`. Args: other: Shape: Returns: """ if self.wrapped is None or other.wrapped is None: return False return self.wrapped.IsEqual(other.wrapped) def is_null(self) -> bool: """Returns true if this shape is null. In other words, it references no underlying shape with the potential to be given a location and an orientation. Args: Returns: """ return self.wrapped is None or self.wrapped.IsNull() def is_same(self, other: Shape) -> bool: """Returns True if other and this shape are same, i.e. if they share the same TShape with the same Locations. Orientations may differ. Also see :py:meth:`is_equal` Args: other: Shape: Returns: """ if self.wrapped is None or other.wrapped is None: return False return self.wrapped.IsSame(other.wrapped) def is_valid(self) -> bool: """Returns True if no defect is detected on the shape S or any of its subshapes. See the OCCT docs on BRepCheck_Analyzer::IsValid for a full description of what is checked. Args: Returns: """ if self.wrapped is None: return True chk = BRepCheck_Analyzer(self.wrapped) chk.SetParallel(True) return chk.IsValid() def locate(self, loc: Location) -> Self: """Apply a location in absolute sense to self Args: loc: Location: Returns: """ if self.wrapped is None: raise ValueError("Cannot locate an empty shape") if loc.wrapped is None: raise ValueError("Cannot locate a shape at an empty location") self.wrapped.Location(loc.wrapped) return self def located(self, loc: Location) -> Self: """located Apply a location in absolute sense to a copy of self Args: loc (Location): new absolute location Returns: Shape: copy of Shape at location """ if self.wrapped is None: raise ValueError("Cannot locate an empty shape") if loc.wrapped is None: raise ValueError("Cannot locate a shape at an empty location") shape_copy: Shape = copy.deepcopy(self, None) shape_copy.wrapped.Location(loc.wrapped) # type: ignore return shape_copy def mesh(self, tolerance: float, angular_tolerance: float = 0.1): """Generate triangulation if none exists. Args: tolerance: float: angular_tolerance: float: (Default value = 0.1) Returns: """ if self.wrapped is None: raise ValueError("Cannot mesh an empty shape") if not BRepTools.Triangulation_s(self.wrapped, tolerance): BRepMesh_IncrementalMesh( self.wrapped, tolerance, True, angular_tolerance, True ) def mirror(self, mirror_plane: Plane | None = None) -> Self: """ Applies a mirror transform to this Shape. Does not duplicate objects about the plane. Args: mirror_plane (Plane): The plane to mirror about. Defaults to Plane.XY Returns: The mirrored shape """ if not mirror_plane: mirror_plane = Plane.XY if self.wrapped is None: return self transformation = gp_Trsf() transformation.SetMirror( gp_Ax2(mirror_plane.origin.to_pnt(), mirror_plane.z_dir.to_dir()) ) return self._apply_transform(transformation) def move(self, loc: Location) -> Self: """Apply a location in relative sense (i.e. update current location) to self Args: loc: Location: Returns: """ if self.wrapped is None: raise ValueError("Cannot move an empty shape") if loc.wrapped is None: raise ValueError("Cannot move a shape at an empty location") self.wrapped.Move(loc.wrapped) return self def moved(self, loc: Location) -> Self: """moved Apply a location in relative sense (i.e. update current location) to a copy of self Args: loc (Location): new location relative to current location Returns: Shape: copy of Shape moved to relative location """ if self.wrapped is None: raise ValueError("Cannot move an empty shape") if loc.wrapped is None: raise ValueError("Cannot move a shape at an empty location") shape_copy: Shape = copy.deepcopy(self, None) shape_copy.wrapped = tcast(TOPODS, downcast(self.wrapped.Moved(loc.wrapped))) return shape_copy def oriented_bounding_box(self) -> OrientedBoundBox: """Create an oriented bounding box for this Shape. Returns: OrientedBoundBox: A box oriented and sized to contain this Shape """ if self.wrapped is None: return OrientedBoundBox(Bnd_OBB()) return OrientedBoundBox(self) def project_faces( self, faces: list[Face] | Compound, path: Wire | Edge, start: float = 0, ) -> ShapeList[Face]: """Projected Faces following the given path on Shape Project by positioning each face of to the shape along the path and projecting onto the surface. Note that projection may result in distortion depending on the shape at a position along the path. .. image:: projectText.png Args: faces (Union[list[Face], Compound]): faces to project path: Path on the Shape to follow start: Relative location on path to start the faces. Defaults to 0. Returns: The projected faces """ # pylint: disable=too-many-locals path_length = path.length # The derived classes of Shape implement center shape_center = self.center() # pylint: disable=no-member if ( not isinstance(faces, (list, tuple)) and faces.wrapped is not None and isinstance(faces.wrapped, TopoDS_Compound) ): faces = faces.faces() first_face_min_x = faces[0].bounding_box().min.X logger.debug("projecting %d face(s)", len(faces)) # Position each face normal to the surface along the path and project to the surface projected_faces = [] for face in faces: bbox = face.bounding_box() face_center_x = (bbox.min.X + bbox.max.X) / 2 relative_position_on_wire = ( start + (face_center_x - first_face_min_x) / path_length ) path_position = path.position_at(relative_position_on_wire) path_tangent = path.tangent_at(relative_position_on_wire) projection_axis = Axis(path_position, shape_center - path_position) (surface_point, surface_normal) = self.find_intersection_points( projection_axis )[0] surface_normal_plane = Plane( origin=surface_point, x_dir=path_tangent, z_dir=surface_normal ) projection_face: Face = surface_normal_plane.from_local_coords( face.moved(Location((-face_center_x, 0, 0))) ) logger.debug("projecting face at %0.2f", relative_position_on_wire) projected_faces.append( projection_face.project_to_shape(self, surface_normal * -1)[0] ) logger.debug("finished projecting '%d' faces", len(faces)) return ShapeList(projected_faces) def radius_of_gyration(self, axis: Axis) -> float: """ Compute the radius of gyration of the shape about a given axis. The radius of gyration represents the distance from the axis at which the entire mass of the shape could be concentrated without changing its moment of inertia. It provides insight into how mass is distributed relative to the axis and is useful in structural analysis, rotational dynamics, and mechanical simulations. Args: axis (Axis): The axis about which the radius of gyration is computed. The axis should be defined in the same coordinate system as the shape. Returns: float: The radius of gyration in the same units as the shape's dimensions. Example: >>> obj = MyShape() >>> axis = Axis((0, 0, 0), (0, 0, 1)) >>> obj.radius_of_gyration(axis) 5.47 Notes: - The radius of gyration is computed based on the shape’s mass properties. - It is useful for evaluating structural stability and rotational behavior. """ properties = GProp_GProps() BRepGProp.VolumeProperties_s(self.wrapped, properties) return properties.RadiusOfGyration(axis.wrapped) def relocate(self, loc: Location): """Change the location of self while keeping it geometrically similar Args: loc (Location): new location to set for self """ if self.wrapped is None: raise ValueError("Cannot relocate an empty shape") if loc.wrapped is None: raise ValueError("Cannot relocate a shape at an empty location") if self.location != loc: old_ax = gp_Ax3() old_ax.Transform(self.location.wrapped.Transformation()) # type: ignore new_ax = gp_Ax3() new_ax.Transform(loc.wrapped.Transformation()) trsf = gp_Trsf() trsf.SetDisplacement(new_ax, old_ax) builder = BRepBuilderAPI_Transform(self.wrapped, trsf, True, True) self.wrapped = tcast(TOPODS, downcast(builder.Shape())) self.wrapped.Location(loc.wrapped) def rotate(self, axis: Axis, angle: float) -> Self: """rotate a copy Rotates a shape around an axis. Args: axis (Axis): rotation Axis angle (float): angle to rotate, in degrees Returns: a copy of the shape, rotated """ transformation = gp_Trsf() transformation.SetRotation(axis.wrapped, angle * DEG2RAD) return self._apply_transform(transformation) def scale(self, factor: float) -> Self: """Scales this shape through a transformation. Args: factor: float: Returns: """ transformation = gp_Trsf() transformation.SetScale(gp_Pnt(), factor) return self._apply_transform(transformation) def shape_type(self) -> Shapes: """Return the shape type string for this class""" return tcast(Shapes, Shape.shape_LUT[shapetype(self.wrapped)]) def shell(self) -> Shell | None: """Return the Shell""" return None def shells(self) -> ShapeList[Shell]: """shells - all the shells in this Shape""" return ShapeList() def show_topology( self, limit_class: Literal[ "Compound", "Edge", "Face", "Shell", "Solid", "Vertex", "Wire" ] = "Vertex", show_center: bool | None = None, ) -> str: """Display internal topology Display the internal structure of a Compound 'assembly' or Shape. Example: .. code:: >>> c1.show_topology() c1 is the root Compound at 0x7f4a4cafafa0, Location(...)) ├── Solid at 0x7f4a4cafafd0, Location(...)) ├── c2 is 1st compound Compound at 0x7f4a4cafaee0, Location(...)) │ ├── Solid at 0x7f4a4cafad00, Location(...)) │ └── Solid at 0x7f4a11a52790, Location(...)) └── c3 is 2nd Compound at 0x7f4a4cafad60, Location(...)) ├── Solid at 0x7f4a11a52700, Location(...)) └── Solid at 0x7f4a11a58550, Location(...)) Args: limit_class: type of displayed leaf node. Defaults to 'Vertex'. show_center (bool, optional): If None, shows the Location of Compound 'assemblies' and the bounding box center of Shapes. True or False forces the display. Defaults to None. Returns: str: tree representation of internal structure """ if ( self.wrapped is not None and isinstance(self.wrapped, TopoDS_Compound) and self.children ): show_center = False if show_center is None else show_center result = Shape._show_tree(self, show_center) else: tree = Shape._build_tree( tcast(TopoDS_Shape, self.wrapped), tree=[], limit=Shape.inverse_shape_LUT[limit_class], ) show_center = True if show_center is None else show_center result = Shape._show_tree(tree[0], show_center) return result def solid(self) -> Solid | None: """Return the Solid""" return None def solids(self) -> ShapeList[Solid]: """solids - all the solids in this Shape""" return ShapeList() @overload def split_by_perimeter( self, perimeter: Edge | Wire, keep: Literal[Keep.INSIDE, Keep.OUTSIDE] ) -> Face | Shell | ShapeList[Face] | None: """split_by_perimeter and keep inside or outside""" @overload def split_by_perimeter( self, perimeter: Edge | Wire, keep: Literal[Keep.BOTH] ) -> tuple[ Face | Shell | ShapeList[Face] | None, Face | Shell | ShapeList[Face] | None, ]: """split_by_perimeter and keep inside and outside""" @overload def split_by_perimeter( self, perimeter: Edge | Wire ) -> Face | Shell | ShapeList[Face] | None: """split_by_perimeter and keep inside (default)""" def split_by_perimeter(self, perimeter: Edge | Wire, keep: Keep = Keep.INSIDE): """split_by_perimeter Divide the faces of this object into those within the perimeter and those outside the perimeter. Note: this method may fail if the perimeter intersects shape edges. Args: perimeter (Union[Edge,Wire]): closed perimeter keep (Keep, optional): which object(s) to return. Defaults to Keep.INSIDE. Raises: ValueError: perimeter must be closed ValueError: keep must be one of Keep.INSIDE|OUTSIDE|BOTH Returns: Union[Face | Shell | ShapeList[Face] | None, Tuple[Face | Shell | ShapeList[Face] | None]: The result of the split operation. - **Keep.INSIDE**: Returns the inside part as a `Shell` or `Face`, or `None` if no inside part is found. - **Keep.OUTSIDE**: Returns the outside part as a `Shell` or `Face`, or `None` if no outside part is found. - **Keep.BOTH**: Returns a tuple `(inside, outside)` where each element is either a `Shell`, `Face`, or `None` if no corresponding part is found. """ def get(los: TopTools_ListOfShape) -> list: """Return objects from TopTools_ListOfShape as list""" shapes = [] for _ in range(los.Size()): first = los.First() if not first.IsNull(): shapes.append(self.__class__.cast(first)) los.RemoveFirst() return shapes def process_sides(sides): """Process sides to determine if it should be None, a single element, a Shell, or a ShapeList.""" # if not sides: # return None if len(sides) == 1: return sides[0] # Attempt to create a shell potential_shell = _sew_topods_faces([s.wrapped for s in sides]) if isinstance(potential_shell, TopoDS_Shell): return self.__class__.cast(potential_shell) return ShapeList(sides) if keep not in {Keep.INSIDE, Keep.OUTSIDE, Keep.BOTH}: raise ValueError( "keep must be one of Keep.INSIDE, Keep.OUTSIDE, or Keep.BOTH" ) if self.wrapped is None: raise ValueError("Cannot split an empty shape") # Process the perimeter if not perimeter.is_closed: raise ValueError("perimeter must be a closed Wire or Edge") perimeter_edges = TopTools_SequenceOfShape() for perimeter_edge in perimeter.edges(): perimeter_edges.Append(perimeter_edge.wrapped) # Split the shells by the perimeter edges lefts: list[Shell] = [] rights: list[Shell] = [] for target_shell in self.shells(): constructor = BRepFeat_SplitShape(target_shell.wrapped) constructor.Add(perimeter_edges) constructor.Build() lefts.extend(get(constructor.Left())) rights.extend(get(constructor.Right())) left = process_sides(lefts) right = process_sides(rights) # Is left or right the inside? perimeter_length = perimeter.length left_perimeter_length = sum(e.length for e in left.edges()) if left else 0 right_perimeter_length = sum(e.length for e in right.edges()) if right else 0 left_inside = abs(perimeter_length - left_perimeter_length) < abs( perimeter_length - right_perimeter_length ) if keep == Keep.BOTH: return (left, right) if left_inside else (right, left) if keep == Keep.INSIDE: return left if left_inside else right # keep == Keep.OUTSIDE: return right if left_inside else left def tessellate( self, tolerance: float, angular_tolerance: float = 0.1 ) -> tuple[list[Vector], list[tuple[int, int, int]]]: """General triangulated approximation""" if self.wrapped is None: raise ValueError("Cannot tessellate an empty shape") self.mesh(tolerance, angular_tolerance) vertices: list[Vector] = [] triangles: list[tuple[int, int, int]] = [] offset = 0 for face in self.faces(): assert face.wrapped is not None loc = TopLoc_Location() poly = BRep_Tool.Triangulation_s(face.wrapped, loc) trsf = loc.Transformation() reverse = face.wrapped.Orientation() == TopAbs_Orientation.TopAbs_REVERSED # add vertices vertices += [ Vector(v.X(), v.Y(), v.Z()) for v in ( poly.Node(i).Transformed(trsf) for i in range(1, poly.NbNodes() + 1) ) ] # add triangles triangles += [ ( ( t.Value(1) + offset - 1, t.Value(3) + offset - 1, t.Value(2) + offset - 1, ) if reverse else ( t.Value(1) + offset - 1, t.Value(2) + offset - 1, t.Value(3) + offset - 1, ) ) for t in poly.Triangles() ] offset += poly.NbNodes() return vertices, triangles def to_splines( self, degree: int = 3, tolerance: float = 1e-3, nurbs: bool = False ) -> Self: """to_splines Approximate shape with b-splines of the specified degree. Args: degree (int, optional): Maximum degree. Defaults to 3. tolerance (float, optional): Approximation tolerance. Defaults to 1e-3. nurbs (bool, optional): Use rational splines. Defaults to False. Returns: Self: Approximated shape """ if self.wrapped is None: raise ValueError("Cannot approximate an empty shape") params = ShapeCustom_RestrictionParameters() result = ShapeCustom.BSplineRestriction_s( self.wrapped, tolerance, # 3D tolerance tolerance, # 2D tolerance degree, 1, # dummy value, degree is leading ga.GeomAbs_C0, ga.GeomAbs_C0, True, # set degree to be leading not nurbs, params, ) return self.__class__.cast(result) def transform_geometry(self, t_matrix: Matrix) -> Self: """Apply affine transform WARNING: transform_geometry will sometimes convert lines and circles to splines, but it also has the ability to handle skew and stretching transformations. If your transformation is only translation and rotation, it is safer to use :py:meth:`transform_shape`, which doesn't change the underlying type of the geometry, but cannot handle skew transformations. Args: t_matrix (Matrix): affine transformation matrix Returns: Shape: a copy of the object, but with geometry transformed """ if self.wrapped is None: return self new_shape = copy.deepcopy(self, None) transformed = downcast( BRepBuilderAPI_GTransform(self.wrapped, t_matrix.wrapped, True).Shape() ) new_shape.wrapped = tcast(TOPODS, transformed) return new_shape def transform_shape(self, t_matrix: Matrix) -> Self: """Apply affine transform without changing type Transforms a copy of this Shape by the provided 3D affine transformation matrix. Note that not all transformation are supported - primarily designed for translation and rotation. See :transform_geometry: for more comprehensive transformations. Args: t_matrix (Matrix): affine transformation matrix Returns: Shape: copy of transformed shape with all objects keeping their type """ if self.wrapped is None: return self new_shape = copy.deepcopy(self, None) transformed = downcast( BRepBuilderAPI_Transform(self.wrapped, t_matrix.wrapped.Trsf()).Shape() ) new_shape.wrapped = tcast(TOPODS, transformed) return new_shape def transformed( self, rotate: VectorLike = (0, 0, 0), offset: VectorLike = (0, 0, 0) ) -> Self: """Transform Shape Rotate and translate the Shape by the three angles (in degrees) and offset. Args: rotate (VectorLike, optional): 3-tuple of angles to rotate, in degrees. Defaults to (0, 0, 0). offset (VectorLike, optional): 3-tuple to offset. Defaults to (0, 0, 0). Returns: Shape: transformed object """ # Convert to a Vector of radians rotate_vector = Vector(rotate).multiply(DEG2RAD) # Compute rotation matrix. t_rx = gp_Trsf() t_rx.SetRotation(gp_Ax1(gp_Pnt(0, 0, 0), gp_Dir(1, 0, 0)), rotate_vector.X) t_ry = gp_Trsf() t_ry.SetRotation(gp_Ax1(gp_Pnt(0, 0, 0), gp_Dir(0, 1, 0)), rotate_vector.Y) t_rz = gp_Trsf() t_rz.SetRotation(gp_Ax1(gp_Pnt(0, 0, 0), gp_Dir(0, 0, 1)), rotate_vector.Z) t_o = gp_Trsf() t_o.SetTranslation(Vector(offset).wrapped) return self._apply_transform(t_o * t_rx * t_ry * t_rz) def translate(self, vector: VectorLike) -> Self: """Translates this shape through a transformation. Args: vector: VectorLike: Returns: """ transformation = gp_Trsf() transformation.SetTranslation(Vector(vector).wrapped) return self._apply_transform(transformation) def wire(self) -> Wire | None: """Return the Wire""" return None def wires(self) -> ShapeList[Wire]: """wires - all the wires in this Shape""" return ShapeList() def _apply_transform(self, transformation: gp_Trsf) -> Self: """Private Apply Transform Apply the provided transformation matrix to a copy of Shape Args: transformation (gp_Trsf): transformation matrix Returns: Shape: copy of transformed Shape """ if self.wrapped is None: return self shape_copy: Shape = copy.deepcopy(self, None) transformed_shape = BRepBuilderAPI_Transform( self.wrapped, transformation, True, ).Shape() shape_copy.wrapped = tcast(TOPODS, downcast(transformed_shape)) return shape_copy def _bool_op( self, args: Iterable[Shape], tools: Iterable[Shape], operation: BRepAlgoAPI_BooleanOperation | BRepAlgoAPI_Splitter, ) -> Self | ShapeList[Self]: """Generic boolean operation Args: args: Iterable[Shape]: tools: Iterable[Shape]: operation: Union[BRepAlgoAPI_BooleanOperation: BRepAlgoAPI_Splitter]: Returns: """ args = list(args) tools = list(tools) # Find the highest order class from all the inputs Solid > Vertex order_dict = {type(s): type(s).order for s in [self] + args + tools} highest_order = sorted(order_dict.items(), key=lambda item: item[1])[-1] # The base of the operation base = args[0] if isinstance(args, (list, tuple)) else args arg = TopTools_ListOfShape() for obj in args: if obj.wrapped is not None: arg.Append(obj.wrapped) tool = TopTools_ListOfShape() for obj in tools: if obj.wrapped is not None: tool.Append(obj.wrapped) operation.SetArguments(arg) operation.SetTools(tool) operation.SetRunParallel(True) operation.Build() topo_result = downcast(operation.Shape()) # Clean if SkipClean.clean: upgrader = ShapeUpgrade_UnifySameDomain(topo_result, True, True, True) upgrader.AllowInternalEdges(False) try: upgrader.Build() topo_result = downcast(upgrader.Shape()) except Exception: warnings.warn("Boolean operation unable to clean", stacklevel=2) # Remove unnecessary TopoDS_Compound around single shape if isinstance(topo_result, TopoDS_Compound): topo_result = unwrap_topods_compound(topo_result, True) if isinstance(topo_result, TopoDS_Compound) and highest_order[1] != 4: results = ShapeList( highest_order[0].cast(s) for s in get_top_level_topods_shapes(topo_result) ) for result in results: base.copy_attributes_to(result, ["wrapped", "_NodeMixin__children"]) return results result = highest_order[0].cast(topo_result) base.copy_attributes_to(result, ["wrapped", "_NodeMixin__children"]) return result def _ocp_section( self: Shape, other: Vertex | Edge | Wire | Face ) -> tuple[list[Vertex], list[Edge]]: """_ocp_section Create a BRepAlgoAPI_Section object The algorithm is to build a Section operation between arguments and tools. The result of Section operation consists of vertices and edges. The result of Section operation contains: - new vertices that are subjects of V/V, E/E, E/F, F/F interferences - vertices that are subjects of V/E, V/F interferences - new edges that are subjects of F/F interferences - edges that are Common Blocks Args: other (Union[Vertex, Edge, Wire, Face]): shape to section with Returns: tuple[list[Vertex], list[Edge]]: section results """ if self.wrapped is None or other.wrapped is None: return ([], []) try: section = BRepAlgoAPI_Section(other.geom_adaptor(), self.wrapped) except (TypeError, AttributeError): try: section = BRepAlgoAPI_Section(self.geom_adaptor(), other.wrapped) except (TypeError, AttributeError): return ([], []) # Perform the intersection calculation section.Build() # Get the resulting shapes from the intersection intersection_shape = section.Shape() vertices = [] # Iterate through the intersection shape to find intersection points/edges explorer = TopExp_Explorer(intersection_shape, TopAbs_ShapeEnum.TopAbs_VERTEX) while explorer.More(): vertices.append(self.__class__.cast(downcast(explorer.Current()))) explorer.Next() edges = [] explorer = TopExp_Explorer(intersection_shape, TopAbs_ShapeEnum.TopAbs_EDGE) while explorer.More(): edges.append(self.__class__.cast(downcast(explorer.Current()))) explorer.Next() return (vertices, edges) def _repr_html_(self): """Jupyter 3D representation support""" from build123d.jupyter_tools import shape_to_html return shape_to_html(self)._repr_html_() class Comparable(ABC): """Abstract base class that requires comparison methods""" # ---- Instance Methods ---- @abstractmethod def __eq__(self, other: Any) -> bool: ... @abstractmethod def __lt__(self, other: Any) -> bool: ... # This TypeVar allows IDEs to see the type of objects within the ShapeList T = TypeVar("T", bound=Union[Shape, Vector]) K = TypeVar("K", bound=Comparable) class ShapePredicate(Protocol): """Predicate for shape filters""" # ---- Instance Methods ---- def __call__(self, shape: Shape) -> bool: ... class GroupBy(Generic[T, K]): """Result of a Shape.groupby operation. Groups can be accessed by index or key""" # ---- Constructor ---- def __init__( self, key_f: Callable[[T], K], shapelist: Iterable[T], *, reverse: bool = False, ): # can't be a dict because K may not be hashable self.key_to_group_index: list[tuple[K, int]] = [] self.groups: list[ShapeList[T]] = [] self.key_f = key_f for i, (key, shapegroup) in enumerate( itertools.groupby(sorted(shapelist, key=key_f, reverse=reverse), key=key_f) ): self.groups.append(ShapeList(shapegroup)) self.key_to_group_index.append((key, i)) # ---- Instance Methods ---- def __getitem__(self, key: int): return self.groups[key] def __iter__(self): return iter(self.groups) def __len__(self): return len(self.groups) def __repr__(self): return repr(ShapeList(self)) def __str__(self): return pretty(self) def group(self, key: K): """Select group by key""" for k, i in self.key_to_group_index: if key == k: return self.groups[i] raise KeyError(key) def group_for(self, shape: T): """Select group by shape""" return self.group(self.key_f(shape)) def _repr_pretty_( self, printer: RepresentationPrinter, cycle: bool = False ) -> None: """ Render a formatted representation of the object for pretty-printing in interactive environments. Args: printer (PrettyPrinter): The pretty printer instance handling the output. cycle (bool): Indicates if a reference cycle is detected to prevent infinite recursion. """ if cycle: printer.text("(...)") else: with printer.group(1, "[", "]"): for idx, item in enumerate(self): if idx: printer.text(",") printer.breakable() printer.pretty(item) class ShapeList(list[T]): """Subclass of list with custom filter and sort methods appropriate to CAD""" # ---- Properties ---- # pylint: disable=too-many-public-methods @property def first(self) -> T: """First element in the ShapeList""" return self[0] @property def last(self) -> T: """Last element in the ShapeList""" return self[-1] # ---- Instance Methods ---- def __add__(self, other: ShapeList) -> ShapeList[T]: # type: ignore """Combine two ShapeLists together operator +""" # return ShapeList(itertools.chain(self, other)) # breaks MacOS-13 return ShapeList(list(self) + list(other)) def __and__(self, other: ShapeList) -> ShapeList[T]: """Intersect two ShapeLists operator &""" return ShapeList(set(self) & set(other)) def __eq__(self, other: object) -> bool: """ShapeLists equality operator ==""" return ( set(self) == set(other) if isinstance(other, ShapeList) else NotImplemented # type: ignore ) @overload def __getitem__(self, key: SupportsIndex) -> T: ... @overload def __getitem__(self, key: slice) -> ShapeList[T]: ... def __getitem__(self, key: SupportsIndex | slice) -> T | ShapeList[T]: """Return slices of ShapeList as ShapeList""" if isinstance(key, slice): return ShapeList(list(self).__getitem__(key)) return list(self).__getitem__(key) def __gt__(self, sort_by: Axis | SortBy = Axis.Z) -> ShapeList[T]: # type: ignore """Sort operator >""" return self.sort_by(sort_by) def __lshift__(self, group_by: Axis | SortBy = Axis.Z) -> ShapeList[T]: """Group and select smallest group operator <<""" return self.group_by(group_by)[0] def __lt__(self, sort_by: Axis | SortBy = Axis.Z) -> ShapeList[T]: # type: ignore """Reverse sort operator <""" return self.sort_by(sort_by, reverse=True) # Normally implementing __eq__ is enough, but ShapeList subclasses list, # which already implements __ne__, so we need to override it, too def __ne__(self, other: ShapeList) -> bool: # type: ignore """ShapeLists inequality operator !=""" return ( set(self) != set(other) if isinstance(other, ShapeList) else NotImplemented ) def __or__(self, filter_by: Axis | GeomType = Axis.Z) -> ShapeList[T]: """Filter by axis or geomtype operator |""" return self.filter_by(filter_by) def __rshift__(self, group_by: Axis | SortBy = Axis.Z) -> ShapeList[T]: """Group and select largest group operator >>""" return self.group_by(group_by)[-1] def __sub__(self, other: ShapeList) -> ShapeList[T]: """Differences between two ShapeLists operator -""" return ShapeList(set(self) - set(other)) def center(self) -> Vector: """The average of the center of objects within the ShapeList""" if not self: return Vector(0, 0, 0) total_center = sum((o.center() for o in self), Vector(0, 0, 0)) return total_center / len(self) def compound(self) -> Compound: """Return the Compound""" compounds = self.compounds() compound_count = len(compounds) if compound_count != 1: warnings.warn( f"Found {compound_count} compounds, returning first", stacklevel=2 ) return compounds[0] def compounds(self) -> ShapeList[Compound]: """compounds - all the compounds in this ShapeList""" return ShapeList([c for shape in self for c in shape.compounds()]) # type: ignore def edge(self) -> Edge: """Return the Edge""" edges = self.edges() edge_count = len(edges) if edge_count != 1: warnings.warn(f"Found {edge_count} edges, returning first", stacklevel=2) return edges[0] def edges(self) -> ShapeList[Edge]: """edges - all the edges in this ShapeList""" return ShapeList([e for shape in self for e in shape.edges()]) # type: ignore def face(self) -> Face: """Return the Face""" faces = self.faces() face_count = len(faces) if face_count != 1: msg = f"Found {face_count} faces, returning first" warnings.warn(msg, stacklevel=2) return faces[0] def faces(self) -> ShapeList[Face]: """faces - all the faces in this ShapeList""" return ShapeList([f for shape in self for f in shape.faces()]) # type: ignore def filter_by( self, filter_by: ShapePredicate | Axis | Plane | GeomType | property, reverse: bool = False, tolerance: float = 1e-5, ) -> ShapeList[T]: """filter by Axis, Plane, or GeomType Either: - filter objects of type planar Face or linear Edge by their normal or tangent (respectively) and sort the results by the given axis, or - filter the objects by the provided type. Note that not all types apply to all objects. Args: filter_by (Union[Axis,Plane,GeomType]): axis, plane, or geom type to filter and possibly sort by. Filtering by a plane returns faces/edges parallel to that plane. reverse (bool, optional): invert the geom type filter. Defaults to False. tolerance (float, optional): maximum deviation from axis. Defaults to 1e-5. Raises: ValueError: Invalid filter_by type Returns: ShapeList: filtered list of objects """ # could be moved out maybe? def axis_parallel_predicate(axis: Axis, tolerance: float): def pred(shape: Shape): if shape.is_planar_face: assert shape.wrapped is not None and isinstance( shape.wrapped, TopoDS_Face ) gp_pnt = gp_Pnt() surface_normal = gp_Vec() u_val, _, v_val, _ = BRepTools.UVBounds_s(shape.wrapped) BRepGProp_Face(shape.wrapped).Normal( u_val, v_val, gp_pnt, surface_normal ) normalized_surface_normal = Vector( surface_normal.X(), surface_normal.Y(), surface_normal.Z() ).normalized() shape_axis = Axis(shape.center(), normalized_surface_normal) elif ( isinstance(shape.wrapped, TopoDS_Edge) and shape.geom_type == GeomType.LINE ): curve = shape.geom_adaptor() umin = curve.FirstParameter() tmp = gp_Pnt() res = gp_Vec() curve.D1(umin, tmp, res) start_pos = Vector(tmp) start_dir = Vector(gp_Dir(res)) shape_axis = Axis(start_pos, start_dir) else: return False return axis.is_parallel(shape_axis, tolerance) return pred def plane_parallel_predicate(plane: Plane, tolerance: float): plane_axis = Axis(plane.origin, plane.z_dir) plane_xyz = plane.z_dir.wrapped.XYZ() def pred(shape: Shape): if shape.is_planar_face: assert shape.wrapped is not None and isinstance( shape.wrapped, TopoDS_Face ) gp_pnt: gp_Pnt = gp_Pnt() surface_normal: gp_Vec = gp_Vec() u_val, _, v_val, _ = BRepTools.UVBounds_s(shape.wrapped) BRepGProp_Face(shape.wrapped).Normal( u_val, v_val, gp_pnt, surface_normal ) normalized_surface_normal = Vector(surface_normal).normalized() shape_axis = Axis(shape.center(), normalized_surface_normal) return plane_axis.is_parallel(shape_axis, tolerance) if isinstance(shape.wrapped, TopoDS_Wire): return all(pred(e) for e in shape.edges()) if isinstance(shape.wrapped, TopoDS_Edge): for curve in shape.wrapped.TShape().Curves(): if curve.IsCurve3D(): return ShapeAnalysis_Curve.IsPlanar_s( curve.Curve3D(), plane_xyz, tolerance ) return False return False return pred # convert input to callable predicate if callable(filter_by): predicate = filter_by elif isinstance(filter_by, property): def predicate(obj): return filter_by.__get__(obj) elif isinstance(filter_by, Axis): predicate = axis_parallel_predicate(filter_by, tolerance=tolerance) elif isinstance(filter_by, Plane): predicate = plane_parallel_predicate(filter_by, tolerance=tolerance) elif isinstance(filter_by, GeomType): def predicate(obj): return obj.geom_type == filter_by else: raise ValueError(f"Unsupported filter_by predicate: {filter_by}") # final predicate is negated if `reverse=True` if reverse: def actual_predicate(shape): return not predicate(shape) else: actual_predicate = predicate return ShapeList(filter(actual_predicate, self)) def filter_by_position( self, axis: Axis, minimum: float, maximum: float, inclusive: tuple[bool, bool] = (True, True), ) -> ShapeList[T]: """filter by position Filter and sort objects by the position of their centers along given axis. min and max values can be inclusive or exclusive depending on the inclusive tuple. Args: axis (Axis): axis to sort by minimum (float): minimum value maximum (float): maximum value inclusive (tuple[bool, bool], optional): include min,max values. Defaults to (True, True). Returns: ShapeList: filtered object list """ if inclusive == (True, True): objects = filter( lambda o: minimum <= axis.to_plane().to_local_coords(o).center().Z <= maximum, self, ) elif inclusive == (True, False): objects = filter( lambda o: minimum <= axis.to_plane().to_local_coords(o).center().Z < maximum, self, ) elif inclusive == (False, True): objects = filter( lambda o: minimum < axis.to_plane().to_local_coords(o).center().Z <= maximum, self, ) elif inclusive == (False, False): objects = filter( lambda o: minimum < axis.to_plane().to_local_coords(o).center().Z < maximum, self, ) return ShapeList(objects).sort_by(axis) def group_by( self, group_by: ( Callable[[Shape], K] | Axis | Edge | Wire | SortBy | property ) = Axis.Z, reverse=False, tol_digits=6, ) -> GroupBy[T, K]: """group by Group objects by provided criteria and then sort the groups according to the criteria. Note that not all group_by criteria apply to all objects. Args: group_by (SortBy, optional): group and sort criteria. Defaults to Axis.Z. reverse (bool, optional): flip order of sort. Defaults to False. tol_digits (int, optional): Tolerance for building the group keys by round(key, tol_digits) Returns: GroupBy[K, ShapeList]: sorted list of ShapeLists """ if isinstance(group_by, Axis): if group_by.wrapped is None: raise ValueError("Cannot group by an empty axis") assert group_by.location is not None axis_as_location = group_by.location.inverse() def key_f(obj): return round( (axis_as_location * Location(obj.center())).position.Z, tol_digits, ) elif hasattr(group_by, "wrapped"): if group_by.wrapped is None: raise ValueError("Cannot group by an empty object") if isinstance(group_by.wrapped, (TopoDS_Edge, TopoDS_Wire)): def key_f(obj): pnt1, _pnt2 = group_by.closest_points(obj.center()) return round(group_by.param_at_point(pnt1), tol_digits) elif isinstance(group_by, SortBy): if group_by == SortBy.LENGTH: def key_f(obj): return round(obj.length, tol_digits) elif group_by == SortBy.RADIUS: def key_f(obj): return round(obj.radius, tol_digits) elif group_by == SortBy.DISTANCE: def key_f(obj): return round(obj.center().length, tol_digits) elif group_by == SortBy.AREA: def key_f(obj): return round(obj.area, tol_digits) elif group_by == SortBy.VOLUME: def key_f(obj): return round(obj.volume, tol_digits) elif callable(group_by): key_f = group_by elif isinstance(group_by, property): key_f = group_by.__get__ else: raise ValueError(f"Unsupported group_by function: {group_by}") return GroupBy(key_f, self, reverse=reverse) def shell(self) -> Shell: """Return the Shell""" shells = self.shells() shell_count = len(shells) if shell_count != 1: warnings.warn(f"Found {shell_count} shells, returning first", stacklevel=2) return shells[0] def shells(self) -> ShapeList[Shell]: """shells - all the shells in this ShapeList""" return ShapeList([s for shape in self for s in shape.shells()]) # type: ignore def solid(self) -> Solid: """Return the Solid""" solids = self.solids() solid_count = len(solids) if solid_count != 1: warnings.warn(f"Found {solid_count} solids, returning first", stacklevel=2) return solids[0] def solids(self) -> ShapeList[Solid]: """solids - all the solids in this ShapeList""" return ShapeList([s for shape in self for s in shape.solids()]) # type: ignore def sort_by( self, sort_by: Axis | Callable[[T], K] | Edge | Wire | SortBy | property = Axis.Z, reverse: bool = False, ) -> ShapeList[T]: """sort by Sort objects by provided criteria. Note that not all sort_by criteria apply to all objects. Args: sort_by (Axis | Callable[[T], K] | Edge | Wire | SortBy, optional): sort criteria. Defaults to Axis.Z. reverse (bool, optional): flip order of sort. Defaults to False. Raises: ValueError: Cannot sort by an empty axis ValueError: Cannot sort by an empty object ValueError: Invalid sort_by criteria provided Returns: ShapeList: sorted list of objects """ if callable(sort_by): # If a callable is provided, use it directly as the key objects = sorted(self, key=sort_by, reverse=reverse) elif isinstance(sort_by, property): objects = sorted(self, key=sort_by.__get__, reverse=reverse) elif isinstance(sort_by, Axis): if sort_by.wrapped is None: raise ValueError("Cannot sort by an empty axis") assert sort_by.location is not None axis_as_location = sort_by.location.inverse() objects = sorted( self, key=lambda o: tcast( Location, (axis_as_location * Location(o.center())) ).position.Z, reverse=reverse, ) elif hasattr(sort_by, "wrapped"): if sort_by.wrapped is None: raise ValueError("Cannot sort by an empty object") if isinstance(sort_by.wrapped, (TopoDS_Edge, TopoDS_Wire)): def u_of_closest_center(obj) -> float: """u-value of closest point between object center and sort_by""" assert not isinstance(sort_by, SortBy) pnt1, _pnt2 = sort_by.closest_points(obj.center()) return sort_by.param_at_point(pnt1) # pylint: disable=unnecessary-lambda objects = sorted( self, key=lambda o: u_of_closest_center(o), reverse=reverse ) elif isinstance(sort_by, SortBy): if sort_by == SortBy.LENGTH: objects = sorted( self, key=lambda obj: obj.length, reverse=reverse, ) elif sort_by == SortBy.RADIUS: with_radius = [obj for obj in self if hasattr(obj, "radius")] objects = sorted( with_radius, key=lambda obj: obj.radius, # type: ignore reverse=reverse, ) elif sort_by == SortBy.DISTANCE: objects = sorted( self, key=lambda obj: obj.center().length, reverse=reverse, ) elif sort_by == SortBy.AREA: with_area = [obj for obj in self if hasattr(obj, "area")] objects = sorted( with_area, key=lambda obj: obj.area, # type: ignore reverse=reverse, ) elif sort_by == SortBy.VOLUME: with_volume = [obj for obj in self if hasattr(obj, "volume")] objects = sorted( with_volume, key=lambda obj: obj.volume, # type: ignore reverse=reverse, ) else: raise ValueError("Invalid sort_by criteria provided") return ShapeList(objects) def sort_by_distance( self, other: Shape | VectorLike, reverse: bool = False ) -> ShapeList[T]: """Sort by distance Sort by minimal distance between objects and other Args: other (Union[Shape,VectorLike]): reference object reverse (bool, optional): flip order of sort. Defaults to False. Returns: ShapeList: Sorted shapes """ distances = sorted( [(obj.distance_to(other), obj) for obj in self], # type: ignore key=lambda obj: obj[0], reverse=reverse, ) return ShapeList([obj[1] for obj in distances]) def vertex(self) -> Vertex: """Return the Vertex""" vertices = self.vertices() vertex_count = len(vertices) if vertex_count != 1: warnings.warn( f"Found {vertex_count} vertices, returning first", stacklevel=2 ) return vertices[0] def vertices(self) -> ShapeList[Vertex]: """vertices - all the vertices in this ShapeList""" return ShapeList([v for shape in self for v in shape.vertices()]) # type: ignore def wire(self) -> Wire: """Return the Wire""" wires = self.wires() wire_count = len(wires) if wire_count != 1: warnings.warn(f"Found {wire_count} wires, returning first", stacklevel=2) return wires[0] def wires(self) -> ShapeList[Wire]: """wires - all the wires in this ShapeList""" return ShapeList([w for shape in self for w in shape.wires()]) # type: ignore class Joint(ABC): """Joint Abstract Base Joint class - used to join two components together Args: parent (Union[Solid, Compound]): object that joint to bound to Attributes: label (str): user assigned label parent (Shape): object joint is bound to connected_to (Joint): joint that is connect to this joint """ # ---- Constructor ---- def __init__(self, label: str, parent: BuildPart | Solid | Compound): self.label = label self.parent = parent self.connected_to: Joint | None = None # ---- Properties ---- @property @abstractmethod def location(self) -> Location: """Location of joint""" @property @abstractmethod def symbol(self) -> Compound: """A CAD object positioned in global space to illustrate the joint""" # ---- Instance Methods ---- @abstractmethod def connect_to(self, *args, **kwargs): """All derived classes must provide a connect_to method""" @abstractmethod def relative_to(self, *args, **kwargs) -> Location: """Return relative location to another joint""" def _connect_to(self, other: Joint, **kwargs): # pragma: no cover """Connect Joint self by repositioning other""" if not isinstance(other, Joint): raise TypeError(f"other must of type Joint not {type(other)}") if self.parent.location is None: raise ValueError("Parent location is not set") relative_location = self.relative_to(other, **kwargs) other.parent.locate(tcast(Location, self.parent.location * relative_location)) self.connected_to = other class SkipClean: """Skip clean context for use in operator driven code where clean=False wouldn't work""" clean = True # ---- Instance Methods ---- def __enter__(self): SkipClean.clean = False def __exit__(self, exception_type, exception_value, traceback): SkipClean.clean = True def _sew_topods_faces(faces: Iterable[TopoDS_Face]) -> TopoDS_Shape: """Sew faces into a shell if possible""" shell_builder = BRepBuilderAPI_Sewing() for face in faces: shell_builder.Add(face) shell_builder.Perform() return downcast(shell_builder.SewedShape()) def _topods_entities(shape: TopoDS_Shape, topo_type: Shapes) -> list[TopoDS_Shape]: """Return the TopoDS_Shapes of topo_type from this TopoDS_Shape""" out = {} # using dict to prevent duplicates explorer = TopExp_Explorer(shape, Shape.inverse_shape_LUT[topo_type]) while explorer.More(): item = explorer.Current() out[hash(item)] = item # needed to avoid pseudo-duplicate entities explorer.Next() return list(out.values()) def _topods_face_normal_at(face: TopoDS_Face, surface_point: gp_Pnt) -> Vector: """Find the normal at a point on surface""" surface = BRep_Tool.Surface_s(face) # project point on surface projector = GeomAPI_ProjectPointOnSurf(surface_point, surface) u_val, v_val = projector.LowerDistanceParameters() gp_pnt = gp_Pnt() normal = gp_Vec() BRepGProp_Face(face).Normal(u_val, v_val, gp_pnt, normal) return Vector(normal).normalized() def downcast(obj: TopoDS_Shape) -> TopoDS_Shape: """Downcasts a TopoDS object to suitable specialized type Args: obj: TopoDS_Shape: Returns: """ f_downcast: Any = Shape.downcast_LUT[shapetype(obj)] return_value = f_downcast(obj) return return_value def fix(obj: TopoDS_Shape) -> TopoDS_Shape: """Fix a TopoDS object to suitable specialized type Args: obj: TopoDS_Shape: Returns: """ shape_fix = ShapeFix_Shape(obj) shape_fix.Perform() return downcast(shape_fix.Shape()) def get_top_level_topods_shapes( topods_shape: TopoDS_Shape | None, ) -> list[TopoDS_Shape]: """ Retrieve the first level of child shapes from the shape. This method collects all the non-compound shapes directly contained in the current shape. If the wrapped shape is a `TopoDS_Compound`, it traverses its immediate children and collects all shapes that are not further nested compounds. Nested compounds are traversed to gather their non-compound elements without returning the nested compound itself. Returns: list[TopoDS_Shape]: A list of all first-level non-compound child shapes. Example: If the current shape is a compound containing both simple shapes (e.g., edges, vertices) and other compounds, the method returns a list of only the simple shapes directly contained at the top level. """ if topods_shape is None: return ShapeList() first_level_shapes = [] stack = [topods_shape] while stack: current_shape = stack.pop() if isinstance(current_shape, TopoDS_Compound): iterator = TopoDS_Iterator() iterator.Initialize(current_shape) while iterator.More(): child_shape = downcast(iterator.Value()) if isinstance(child_shape, TopoDS_Compound): # Traverse further into the compound stack.append(child_shape) else: # Add non-compound shape first_level_shapes.append(child_shape) iterator.Next() else: first_level_shapes.append(current_shape) return first_level_shapes def shapetype(obj: TopoDS_Shape | None) -> TopAbs_ShapeEnum: """Return TopoDS_Shape's TopAbs_ShapeEnum""" if obj is None or obj.IsNull(): raise ValueError("Null TopoDS_Shape object") return obj.ShapeType() def topods_dim(topods: TopoDS_Shape) -> int | None: """Return the dimension of this TopoDS_Shape""" shape_dim_map = { (TopoDS_Vertex,): 0, (TopoDS_Edge, TopoDS_Wire): 1, (TopoDS_Face, TopoDS_Shell): 2, (TopoDS_Solid,): 3, } for shape_types, dim in shape_dim_map.items(): if isinstance(topods, shape_types): return dim if isinstance(topods, TopoDS_Compound): sub_dims = {topods_dim(s) for s in get_top_level_topods_shapes(topods)} return sub_dims.pop() if len(sub_dims) == 1 else None return None def unwrap_topods_compound( compound: TopoDS_Compound, fully: bool = True ) -> TopoDS_Compound | TopoDS_Shape: """Strip unnecessary Compound wrappers Args: compound (TopoDS_Compound): The TopoDS_Compound to unwrap. fully (bool, optional): return base shape without any TopoDS_Compound wrappers (otherwise one TopoDS_Compound is left). Defaults to True. Returns: TopoDS_Compound | TopoDS_Shape: base shape """ if compound.NbChildren() == 1: iterator = TopoDS_Iterator(compound) single_element = downcast(iterator.Value()) # If the single element is another TopoDS_Compound, unwrap it recursively if isinstance(single_element, TopoDS_Compound): return unwrap_topods_compound(single_element, fully) return single_element if fully else compound # If there are no elements or more than one element, return TopoDS_Compound return compound