mirrors/build123d
1
Fork 0
mirror of https://github.com/gumyr/build123d.git synced 2025-12-06 02:30:55 -08:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update object_*.py docstrings for more consistency and clarify how parameters work

Browse source 
General improvements:
- follow a similar opening structure
- add specificity to description and args
- remove plurality (sketch, part)
- remove hanging end stops from lists
- try to specify viable enums if mentioned and CAPITALIZE
This commit is contained in:
Jonathan Wagenet 2025-03-05 18:35:23 -05:00
parent 10a466f645
commit fcbd027137
3 changed files with 299 additions and 289 deletions
Download patch file Download diff file Expand all files Collapse all files

210
src/build123d/objects_curve.py
View file

@ -31,7 +31,6 @@ from __future__ import annotations
import copy as copy_module import copy as copy_module
from math import copysign, cos, radians, sin, sqrt from math import copysign, cos, radians, sin, sqrt
from scipy.optimize import minimize from scipy.optimize import minimize
from typing import Union
from collections.abc import Iterable from collections.abc import Iterable
@ -46,8 +45,8 @@ def _add_curve_to_context(curve, mode: Mode):
"""Helper function to add a curve to the context. """Helper function to add a curve to the context.
Args: Args:
curve (Union[Wire, Edge]): curve to add to the context (either a Wire or an Edge). curve (Wire | Edge): curve to add to the context (either a Wire or an Edge)
mode (Mode): combination mode. mode (Mode): combination mode
""" """
context: BuildLine | None = BuildLine._get_context(log=False) context: BuildLine | None = BuildLine._get_context(log=False)
@ -62,8 +61,8 @@ class BaseLineObject(Wire):
"""BaseLineObject specialized for Wire. """BaseLineObject specialized for Wire.
Args: Args:
curve (Wire): wire to create. curve (Wire): wire to create
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -78,8 +77,8 @@ class BaseEdgeObject(Edge):
"""BaseEdgeObject specialized for Edge. """BaseEdgeObject specialized for Edge.
Args: Args:
curve (Edge): edge to create. curve (Edge): edge to create
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -93,14 +92,14 @@ class BaseEdgeObject(Edge):
class Bezier(BaseEdgeObject): class Bezier(BaseEdgeObject):
"""Line Object: Bezier Curve """Line Object: Bezier Curve
Create a rational (with weights) or non-rational bezier curve. The first and last Add a non-rational bezier curve defined by a sequence of points and include optional
control points represent the start and end of the curve respectively. If weights weights to add a rational bezier curve. The number of weights must match the number
are provided, there must be one provided for each control point. of control points.
Args: Args:
cntl_pnts (sequence[VectorLike]): points defining the curve cntl_pnts (sequence[VectorLike]): points defining the curve
weights (list[float], optional): control point weights list. Defaults to None. weights (list[float], optional): control point weights. Defaults to None
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -124,14 +123,14 @@ class Bezier(BaseEdgeObject):
class CenterArc(BaseEdgeObject): class CenterArc(BaseEdgeObject):
"""Line Object: Center Arc """Line Object: Center Arc
Add center arc to the line. Add a circular arc defined by a center point and radius.
Args: Args:
center (VectorLike): center point of arc center (VectorLike): center point of arc
radius (float): arc radius radius (float): arc radius
start_angle (float): arc staring angle start_angle (float): arc starting angle from x-axis
arc_size (float): arc size arc_size (float): angular size of arc
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -177,19 +176,19 @@ class CenterArc(BaseEdgeObject):
class DoubleTangentArc(BaseEdgeObject): class DoubleTangentArc(BaseEdgeObject):
"""Line Object: Double Tangent Arc """Line Object: Double Tangent Arc
Create an arc defined by a point/tangent pair and another line which the other end Add a circular arc defined by a point/tangent pair and another line find a tangent to.
is tangent to.
The arc specified with TOP or BOTTOM depends on the geometry and isn't predictable.
Contains a solver. Contains a solver.
Args: Args:
pnt (VectorLike): starting point of tangent arc pnt (VectorLike): start point
tangent (VectorLike): tangent at starting point of tangent arc tangent (VectorLike): tangent at start point
other (Union[Curve, Edge, Wire]): reference line other (Curve | Edge | Wire): line object to tangent
keep (Keep, optional): selector for which arc to keep when two arcs are keep (Keep, optional): specify which arc if more than one, TOP or BOTTOM.
possible. The arc generated with TOP or BOTTOM depends on the geometry Defaults to Keep.TOP
and isn't necessarily easy to predict. Defaults to Keep.TOP. mode (Mode, optional): combination mode. Defaults to Mode.ADD
mode (Mode, optional): combination mode. Defaults to Mode.ADD.
Raises: Raises:
RunTimeError: no double tangent arcs found RunTimeError: no double tangent arcs found
@ -276,21 +275,21 @@ class DoubleTangentArc(BaseEdgeObject):
class EllipticalStartArc(BaseEdgeObject): class EllipticalStartArc(BaseEdgeObject):
"""Line Object: Elliptical Start Arc """Line Object: Elliptical Start Arc
Makes an arc of an ellipse from the start point. Add an elliptical arc defined by a start point, end point, x- and y- radii.
Args: Args:
start (VectorLike): initial point of arc start (VectorLike): start point
end (VectorLike): final point of arc end (VectorLike): end point
x_radius (float): semi-major radius x_radius (float): x radius of the ellipse (along the x-axis of plane)
y_radius (float): semi-minor radius y_radius (float): y radius of the ellipse (along the y-axis of plane)
rotation (float, optional): the angle from the x-axis of the plane to the x-axis rotation (float, optional): the angle from the x-axis of the plane to the x-axis
of the ellipse. Defaults to 0.0. of the ellipse. Defaults to 0.0
large_arc (bool, optional): True if the arc spans greater than 180 degrees. large_arc (bool, optional): True if the arc spans greater than 180 degrees.
Defaults to True. Defaults to True
sweep_flag (bool, optional): False if the line joining center to arc sweeps through sweep_flag (bool, optional): False if the line joining center to arc sweeps through
decreasing angles, or True if it sweeps through increasing angles. Defaults to True. decreasing angles, or True if it sweeps through increasing angles. Defaults to True
plane (Plane, optional): base plane. Defaults to Plane.XY. plane (Plane, optional): base plane. Defaults to Plane.XY
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -382,19 +381,21 @@ class EllipticalStartArc(BaseEdgeObject):
class EllipticalCenterArc(BaseEdgeObject): class EllipticalCenterArc(BaseEdgeObject):
"""Line Object: Elliptical Center Arc """Line Object: Elliptical Center Arc
Makes an arc of an ellipse from a center point. Adds an elliptical arc defined by a center point, x- and y- radii.
Args: Args:
center (VectorLike): ellipse center center (VectorLike): ellipse center
x_radius (float): x radius of the ellipse (along the x-axis of plane) x_radius (float): x radius of the ellipse (along the x-axis of plane)
y_radius (float): y radius of the ellipse (along the y-axis of plane) y_radius (float): y radius of the ellipse (along the y-axis of plane)
start_angle (float, optional): Defaults to 0.0. start_angle (float, optional): arc start angle from x-axis.
end_angle (float, optional): Defaults to 90.0. Defaults to 0.0
rotation (float, optional): amount to rotate arc. Defaults to 0.0. end_angle (float, optional): arc end angle from x-axis.
Defaults to 90.0
rotation (float, optional): angle to rotate arc. Defaults to 0.0
angular_direction (AngularDirection, optional): arc direction. angular_direction (AngularDirection, optional): arc direction.
Defaults to AngularDirection.COUNTER_CLOCKWISE. Defaults to AngularDirection.COUNTER_CLOCKWISE
plane (Plane, optional): base plane. Defaults to Plane.XY. plane (Plane, optional): base plane. Defaults to Plane.XY
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -438,17 +439,20 @@ class EllipticalCenterArc(BaseEdgeObject):
class Helix(BaseEdgeObject): class Helix(BaseEdgeObject):
"""Line Object: Helix """Line Object: Helix
Add a helix to the line. Add a helix defined by pitch, height, and radius. The helix may have a taper
defined by cone_angle.
Args: Args:
pitch (float): distance between successive loops pitch (float): distance between loops
height (float): helix size height (float): helix height
radius (float): helix radius radius (float): helix radius
center (VectorLike, optional): center point. Defaults to (0, 0, 0). center (VectorLike, optional): center point. Defaults to (0, 0, 0).
direction (VectorLike, optional): direction of central axis. Defaults to (0, 0, 1). direction (VectorLike, optional): direction of central axis. Defaults to (0, 0, 1).
cone_angle (float, optional): conical angle. Defaults to 0. cone_angle (float, optional): conical angle from direction.
lefthand (bool, optional): left handed helix. Defaults to False. Defaults to 0
mode (Mode, optional): combination mode. Defaults to Mode.ADD. lefthand (bool, optional): left handed helix. Defaults to False
mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -475,16 +479,17 @@ class Helix(BaseEdgeObject):
class FilletPolyline(BaseLineObject): class FilletPolyline(BaseLineObject):
"""Line Object: FilletPolyline """Line Object: Fillet Polyline
Add a sequence of straight lines defined by successive points that Add a sequence of straight lines defined by successive points that are filleted
are filleted to a given radius. to a given radius.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of two or more points pts (VectorLike | Iterable[VectorLike]): sequence of two or more points
radius (float): radius of filleted corners radius (float): fillet radius
close (bool, optional): close by generating an extra Edge. Defaults to False. close (bool, optional): close end points with extra Edge and corner fillets.
mode (Mode, optional): combination mode. Defaults to Mode.ADD. Defaults to False
mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Two or more points not provided ValueError: Two or more points not provided
@ -570,16 +575,16 @@ class FilletPolyline(BaseLineObject):
class JernArc(BaseEdgeObject): class JernArc(BaseEdgeObject):
"""JernArc """Line Object: Jern Arc
Circular tangent arc with given radius and arc_size Add a circular arc defined by a start point/tangent pair, radius and arc size.
Args: Args:
start (VectorLike): start point start (VectorLike): start point
tangent (VectorLike): tangent at start point tangent (VectorLike): tangent at start point
radius (float): arc radius radius (float): arc radius
arc_size (float): arc size in degrees (negative to change direction) arc_size (float): angular size of arc (negative to change direction)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Attributes: Attributes:
start (Vector): start point start (Vector): start point
@ -634,11 +639,11 @@ class JernArc(BaseEdgeObject):
class Line(BaseEdgeObject): class Line(BaseEdgeObject):
"""Line Object: Line """Line Object: Line
Add a straight line defined by two end points. Add a straight line defined by two points.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of two points pts (VectorLike | Iterable[VectorLike]): sequence of two points
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Two point not provided ValueError: Two point not provided
@ -665,13 +670,13 @@ class Line(BaseEdgeObject):
class IntersectingLine(BaseEdgeObject): class IntersectingLine(BaseEdgeObject):
"""Intersecting Line Object: Line """Intersecting Line Object: Line
Add a straight line that intersects another line at a given parameter and angle. Add a straight line defined by a point/direction pair and another line to intersect.
Args: Args:
start (VectorLike): start point start (VectorLike): start point
direction (VectorLike): direction to make line direction (VectorLike): direction to make line
other (Edge): stop at the intersection of other other (Edge): line object to intersect
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
@ -706,15 +711,17 @@ class IntersectingLine(BaseEdgeObject):
class PolarLine(BaseEdgeObject): class PolarLine(BaseEdgeObject):
"""Line Object: Polar Line """Line Object: Polar Line
Add line defined by a start point, length and angle. Add a straight line defined by a start point, length, and angle.
The length can specify the DIAGONAL, HORIZONTAL, or VERTICAL component of the triangle
defined by the angle.
Args: Args:
start (VectorLike): start point start (VectorLike): start point
length (float): line length length (float): line length
angle (float): angle from the local "X" axis. angle (float, optional): angle from the local x-axis
length_mode (LengthMode, optional): length value specifies a diagonal, horizontal length_mode (LengthMode, optional): how length defines the line.
or vertical value. Defaults to LengthMode.DIAGONAL Defaults to LengthMode.DIAGONAL
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Either angle or direction must be provided ValueError: Either angle or direction must be provided
@ -768,12 +775,12 @@ class PolarLine(BaseEdgeObject):
class Polyline(BaseLineObject): class Polyline(BaseLineObject):
"""Line Object: Polyline """Line Object: Polyline
Add a sequence of straight lines defined by successive point pairs. Add a sequence of straight lines defined by successive points.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of two or more points pts (VectorLike | Iterable[VectorLike]): sequence of two or more points
close (bool, optional): close by generating an extra Edge. Defaults to False. close (bool, optional): close by generating an extra Edge. Defaults to False
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Two or more points not provided ValueError: Two or more points not provided
@ -809,15 +816,15 @@ class Polyline(BaseLineObject):
class RadiusArc(BaseEdgeObject): class RadiusArc(BaseEdgeObject):
"""Line Object: Radius Arc """Line Object: Radius Arc
Add an arc defined by two end points and a radius Add a circular arc defined by two points and a radius.
Args: Args:
start_point (VectorLike): start start_point (VectorLike): start point
end_point (VectorLike): end end_point (VectorLike): end point
radius (float): radius radius (float): arc radius
short_sagitta (bool): If True selects the short sagitta, else the short_sagitta (bool): If True selects the short sagitta (height of arc from
long sagitta crossing the center. Defaults to True. chord), else the long sagitta crossing the center. Defaults to True
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Insufficient radius to connect end points ValueError: Insufficient radius to connect end points
@ -861,13 +868,13 @@ class RadiusArc(BaseEdgeObject):
class SagittaArc(BaseEdgeObject): class SagittaArc(BaseEdgeObject):
"""Line Object: Sagitta Arc """Line Object: Sagitta Arc
Add an arc defined by two points and the height of the arc (sagitta). Add a circular arc defined by two points and the sagitta (height of the arc from chord).
Args: Args:
start_point (VectorLike): start start_point (VectorLike): start point
end_point (VectorLike): end end_point (VectorLike): end point
sagitta (float): arc height sagitta (float): arc height from chord between points
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -905,15 +912,16 @@ class SagittaArc(BaseEdgeObject):
class Spline(BaseEdgeObject): class Spline(BaseEdgeObject):
"""Line Object: Spline """Line Object: Spline
Add a spline through the provided points optionally constrained by tangents. Add a spline defined by a sequence of points, optionally constrained by tangents.
Tangents and tangent scalars must have length of 2 for only the end points or a length
of the number of points.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of two or more points pts (VectorLike | Iterable[VectorLike]): sequence of two or more points
tangents (Iterable[VectorLike], optional): tangents at end points. Defaults to None. tangents (Iterable[VectorLike], optional): tangent directions. Defaults to None
tangent_scalars (Iterable[float], optional): change shape by amplifying tangent. tangent_scalars (Iterable[float], optional): tangent scales. Defaults to None
Defaults to None. periodic (bool, optional): make the spline periodic (closed). Defaults to False
periodic (bool, optional): make the spline periodic. Defaults to False. mode (Mode, optional): combination mode. Defaults to Mode.ADD
mode (Mode, optional): combination mode. Defaults to Mode.ADD.
""" """
_applies_to = [BuildLine._tag] _applies_to = [BuildLine._tag]
@ -963,14 +971,14 @@ class Spline(BaseEdgeObject):
class TangentArc(BaseEdgeObject): class TangentArc(BaseEdgeObject):
"""Line Object: Tangent Arc """Line Object: Tangent Arc
Add an arc defined by two points and a tangent. Add a circular arc defined by two points and a tangent.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of two points pts (VectorLike | Iterable[VectorLike]): sequence of two points
tangent (VectorLike): tangent to constrain arc tangent (VectorLike): tangent to constrain arc
tangent_from_first (bool, optional): apply tangent to first point. Note, applying tangent_from_first (bool, optional): apply tangent to first point. Applying
tangent to end point will flip the orientation of the arc. Defaults to True. tangent to end point will flip the orientation of the arc. Defaults to True
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Two points are required ValueError: Two points are required
@ -1005,11 +1013,11 @@ class TangentArc(BaseEdgeObject):
class ThreePointArc(BaseEdgeObject): class ThreePointArc(BaseEdgeObject):
"""Line Object: Three Point Arc """Line Object: Three Point Arc
Add an arc generated by three points. Add a circular arc defined by three points.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of three points pts (VectorLike | Iterable[VectorLike]): sequence of three points
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Three points must be provided ValueError: Three points must be provided

150
src/build123d/objects_part.py
View file

@ -44,10 +44,10 @@ class BasePartObject(Part):
Args: Args:
solid (Solid): object to create solid (Solid): object to create
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
or max of object. Defaults to None. or MAX of object. Defaults to None
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -103,16 +103,16 @@ class BasePartObject(Part):
class Box(BasePartObject): class Box(BasePartObject):
"""Part Object: Box """Part Object: Box
Create a box(es) and combine with part. Add a box defined by length, width, and height.
Args: Args:
length (float): box size length (float): box length
width (float): box size width (float): box width
height (float): box size height (float): box height
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER). or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
mode (Mode, optional): combine mode. Defaults to Mode.ADD. mode (Mode, optional): combine mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -147,17 +147,17 @@ class Box(BasePartObject):
class Cone(BasePartObject): class Cone(BasePartObject):
"""Part Object: Cone """Part Object: Cone
Create a cone(s) and combine with part. Add a cone defined by bottom radius, top radius, and height.
Args: Args:
bottom_radius (float): cone size bottom_radius (float): bottom radius
top_radius (float): top size, could be zero top_radius (float): top radius, may be zero
height (float): cone size height (float): cone height
arc_size (float, optional): angular size of cone. Defaults to 360. arc_size (float, optional): angular size of cone. Defaults to 360
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER). or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
mode (Mode, optional): combine mode. Defaults to Mode.ADD. mode (Mode, optional): combine mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -200,14 +200,14 @@ class Cone(BasePartObject):
class CounterBoreHole(BasePartObject): class CounterBoreHole(BasePartObject):
"""Part Operation: Counter Bore Hole """Part Operation: Counter Bore Hole
Create a counter bore hole in part. Subtract a counter bore hole defined by radius, counter bore radius, counter bore and depth.
Args: Args:
radius (float): hole size radius (float): hole radius
counter_bore_radius (float): counter bore size counter_bore_radius (float): counter bore radius
counter_bore_depth (float): counter bore depth counter_bore_depth (float): counter bore depth
depth (float, optional): hole depth - None implies through part. Defaults to None. depth (float, optional): hole depth, through part if None. Defaults to None
mode (Mode, optional): combination mode. Defaults to Mode.SUBTRACT. mode (Mode, optional): combination mode. Defaults to Mode.SUBTRACT
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -253,14 +253,15 @@ class CounterBoreHole(BasePartObject):
class CounterSinkHole(BasePartObject): class CounterSinkHole(BasePartObject):
"""Part Operation: Counter Sink Hole """Part Operation: Counter Sink Hole
Create a counter sink hole in part. Subtract a countersink hole defined by radius, countersink radius, countersink
angle, and depth.
Args: Args:
radius (float): hole size radius (float): hole radius
counter_sink_radius (float): counter sink size counter_sink_radius (float): countersink radius
depth (float, optional): hole depth - None implies through part. Defaults to None. depth (float, optional): hole depth, through part if None. Defaults to None
counter_sink_angle (float, optional): cone angle. Defaults to 82. counter_sink_angle (float, optional): cone angle. Defaults to 82
mode (Mode, optional): combination mode. Defaults to Mode.SUBTRACT. mode (Mode, optional): combination mode. Defaults to Mode.SUBTRACT
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -310,16 +311,16 @@ class CounterSinkHole(BasePartObject):
class Cylinder(BasePartObject): class Cylinder(BasePartObject):
"""Part Object: Cylinder """Part Object: Cylinder
Create a cylinder(s) and combine with part. Add a cylinder defined by radius and height.
Args: Args:
radius (float): cylinder size radius (float): cylinder radius
height (float): cylinder size height (float): cylinder height
arc_size (float, optional): angular size of cone. Defaults to 360. arc_size (float, optional): angular size of cone. Defaults to 360.
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER). or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
mode (Mode, optional): combine mode. Defaults to Mode.ADD. mode (Mode, optional): combine mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -358,12 +359,12 @@ class Cylinder(BasePartObject):
class Hole(BasePartObject): class Hole(BasePartObject):
"""Part Operation: Hole """Part Operation: Hole
Create a hole in part. Subtract a hole defined by radius and depth.
Args: Args:
radius (float): hole size radius (float): hole radius
depth (float, optional): hole depth - None implies through part. Defaults to None. depth (float, optional): hole depth, through part if None. Defaults to None
mode (Mode, optional): combination mode. Defaults to Mode.SUBTRACT. mode (Mode, optional): combination mode. Defaults to Mode.SUBTRACT
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -405,17 +406,17 @@ class Hole(BasePartObject):
class Sphere(BasePartObject): class Sphere(BasePartObject):
"""Part Object: Sphere """Part Object: Sphere
Create a sphere(s) and combine with part. Add a sphere defined by a radius.
Args: Args:
radius (float): sphere size radius (float): sphere radius
arc_size1 (float, optional): angular size of sphere. Defaults to -90. arc_size1 (float, optional): angular size of bottom hemisphere. Defaults to -90.
arc_size2 (float, optional): angular size of sphere. Defaults to 90. arc_size2 (float, optional): angular size of top hemisphere. Defaults to 90.
arc_size3 (float, optional): angular size of sphere. Defaults to 360. arc_size3 (float, optional): angular revolution about pole. Defaults to 360.
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER). or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
mode (Mode, optional): combine mode. Defaults to Mode.ADD. mode (Mode, optional): combine mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -457,18 +458,18 @@ class Sphere(BasePartObject):
class Torus(BasePartObject): class Torus(BasePartObject):
"""Part Object: Torus """Part Object: Torus
Create a torus(es) and combine with part. Add a torus defined by major and minor radii.
Args: Args:
major_radius (float): torus size major_radius (float): major torus radius
minor_radius (float): torus size minor_radius (float): minor torus radius
major_arc_size (float, optional): angular size of torus. Defaults to 0. minor_start_angle (float, optional): angle to start minor arc. Defaults to 0
minor_arc_size (float, optional): angular size or torus. Defaults to 360. minor_end_angle (float, optional): angle to end minor arc. Defaults to 360
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). major_angle (float, optional): angle to revolve minor arc. Defaults to 360
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER). align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
mode (Mode, optional): combine mode. Defaults to Mode.ADD. or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
mode (Mode, optional): combine mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]
@ -513,20 +514,21 @@ class Torus(BasePartObject):
class Wedge(BasePartObject): class Wedge(BasePartObject):
"""Part Object: Wedge """Part Object: Wedge
Create a wedge(s) and combine with part. Add a wedge with a near face defined by xsize and z size, a far face defined by
xmin to xmax and zmin to zmax, and a depth of ysize.
Args: Args:
xsize (float): distance along the X axis xsize (float): length of near face along x-axis
ysize (float): distance along the Y axis ysize (float): length of part along y-axis
zsize (float): distance along the Z axis zsize (float): length of near face z-axis
xmin (float): minimum X location xmin (float): minimum position far face along x-axis
zmin (float): minimum Z location zmin (float): minimum position far face along z-axis
xmax (float): maximum X location xmax (float): maximum position far face along x-axis
zmax (float): maximum Z location zmax (float): maximum position far face along z-axis
rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0). rotation (RotationLike, optional): angles to rotate about axes. Defaults to (0, 0, 0)
align (Align | tuple[Align, Align, Align] | None, optional): align min, center, align (Align | tuple[Align, Align, Align] | None, optional): align MIN, CENTER,
or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER). or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
mode (Mode, optional): combine mode. Defaults to Mode.ADD. mode (Mode, optional): combine mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildPart._tag] _applies_to = [BuildPart._tag]

228
src/build123d/objects_sketch.py
View file

@ -66,10 +66,10 @@ class BaseSketchObject(Sketch):
Args: Args:
face (Face): face to create face (Face): face to create
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to None. Defaults to None
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -109,13 +109,13 @@ class BaseSketchObject(Sketch):
class Circle(BaseSketchObject): class Circle(BaseSketchObject):
"""Sketch Object: Circle """Sketch Object: Circle
Add circle(s) to the sketch. Add circle defined by radius.
Args: Args:
radius (float): circle size radius (float): circle radius
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -139,15 +139,15 @@ class Circle(BaseSketchObject):
class Ellipse(BaseSketchObject): class Ellipse(BaseSketchObject):
"""Sketch Object: Ellipse """Sketch Object: Ellipse
Add ellipse(s) to sketch. Add ellipse defined by x- and y- radii.
Args: Args:
x_radius (float): horizontal radius x_radius (float): x radius of the ellipse (along the x-axis of plane)
y_radius (float): vertical radius y_radius (float): y radius of the ellipse (along the y-axis of plane)
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -174,20 +174,19 @@ class Ellipse(BaseSketchObject):
class Polygon(BaseSketchObject): class Polygon(BaseSketchObject):
"""Sketch Object: Polygon """Sketch Object: Polygon
Add polygon(s) defined by given sequence of points to sketch. Add polygon defined by given sequence of points.
Note that the order of the points define the normal of the Face that is created in Note: the order of the points defines the resulting normal of the Face in Algebra
Algebra mode, where counter clockwise order creates Faces with their normal being up mode, where counter-clockwise order creates an upward normal while clockwise order
while a clockwise order will have a normal that is down. In Builder mode, all Faces a downward normal. In Builder mode, the Face is added with an upward normal.
added to the sketch are up.
Args: Args:
pts (Union[VectorLike, Iterable[VectorLike]]): sequence of points defining the pts (VectorLike | Iterable[VectorLike]): sequence of points defining the
vertices of the polygon vertices of the polygon
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -214,15 +213,15 @@ class Polygon(BaseSketchObject):
class Rectangle(BaseSketchObject): class Rectangle(BaseSketchObject):
"""Sketch Object: Rectangle """Sketch Object: Rectangle
Add rectangle(s) to sketch. Add rectangle defined by width and height.
Args: Args:
width (float): horizontal size width (float): rectangle width
height (float): vertical size height (float): rectangle height
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -247,18 +246,18 @@ class Rectangle(BaseSketchObject):
class RectangleRounded(BaseSketchObject): class RectangleRounded(BaseSketchObject):
"""Sketch Object: RectangleRounded """Sketch Object: Rectangle Rounded
Add rectangle(s) with filleted corners to sketch. Add rectangle defined by width and height with filleted corners.
Args: Args:
width (float): horizontal size width (float): rectangle width
height (float): vertical size height (float): rectangle height
radius (float): fillet radius radius (float): fillet radius
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -290,19 +289,18 @@ class RectangleRounded(BaseSketchObject):
class RegularPolygon(BaseSketchObject): class RegularPolygon(BaseSketchObject):
"""Sketch Object: Regular Polygon """Sketch Object: Regular Polygon
Add regular polygon(s) to sketch. Add regular polygon defined by radius and side count. Use major_radius to define whether
the polygon circumscribes (along the vertices) or inscribes (along the sides) the radius circle.
Args: Args:
radius (float): distance from origin to vertices (major), or radius (float): construction radius
optionally from the origin to side (minor) with major_radius = False side_count (int): number of sides
side_count (int): number of polygon sides major_radius (bool): If True the radius is the major radius (circumscribed circle),
major_radius (bool): If True the radius is the major radius, else the else the radius is the minor radius (inscribed circle). Defaults to True
radius is the minor radius (also known as inscribed radius). rotation (float, optional): angle to rotate object. Defaults to 0
Defaults to True. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
rotation (float, optional): angles to rotate objects. Defaults to 0. Defaults to (Align.CENTER, Align.CENTER)
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional): combination mode. Defaults to Mode.ADD.
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -361,15 +359,15 @@ class RegularPolygon(BaseSketchObject):
class SlotArc(BaseSketchObject): class SlotArc(BaseSketchObject):
"""Sketch Object: Arc Slot """Sketch Object: Slot Arc
Add slot(s) following an arc to sketch. Add slot defined by a line and height. May be an arc, stright line, spline, etc.
Args: Args:
arc (Union[Edge, Wire]): center line of slot arc (Edge | Wire): center line of slot
height (float): diameter of end circles height (float): diameter of end arcs
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -393,18 +391,17 @@ class SlotArc(BaseSketchObject):
class SlotCenterPoint(BaseSketchObject): class SlotCenterPoint(BaseSketchObject):
"""Sketch Object: Center Point Slot """Sketch Object: Slot Center Point
Add a slot(s) defined by the center of the slot and the center of one of the Add a slot defined by the center of the slot and the center of one end arc.
circular arcs at the end. The other end will be generated to create a symmetric The slot will be symmetric about the center point.
slot.
Args: Args:
center (VectorLike): slot center point center (VectorLike): center point
point (VectorLike): slot center of arc point point (VectorLike): center of arc point
height (float): diameter of end circles height (float): diameter of end arcs
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -446,16 +443,15 @@ class SlotCenterPoint(BaseSketchObject):
class SlotCenterToCenter(BaseSketchObject): class SlotCenterToCenter(BaseSketchObject):
"""Sketch Object: Center to Center points Slot """Sketch Object: Slot Center To Center
Add slot(s) defined by the distance between the center of the two Add slot defined by the distance between the centers of the two end arcs.
end arcs.
Args: Args:
center_separation (float): distance between two arc centers center_separation (float): distance between arc centers
height (float): diameter of end circles height (float): diameter of end arcs
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -490,17 +486,17 @@ class SlotCenterToCenter(BaseSketchObject):
class SlotOverall(BaseSketchObject): class SlotOverall(BaseSketchObject):
"""Sketch Object: Center to Center points Slot """Sketch Object: Slot Overall
Add slot(s) defined by the overall with of the slot. Add slot defined by the overall width and height.
Args: Args:
width (float): overall width of the slot width (float): overall width of slot
height (float): diameter of end circles height (float): diameter of end arcs
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
_applies_to = [BuildSketch._tag] _applies_to = [BuildSketch._tag]
@ -541,21 +537,24 @@ class SlotOverall(BaseSketchObject):
class Text(BaseSketchObject): class Text(BaseSketchObject):
"""Sketch Object: Text """Sketch Object: Text
Add text(s) to the sketch. Add text defined by text string and font size.
May have difficulty finding non-system fonts depending on platform and render default.
font_path defines an exact path to a font file and overrides font.
Args: Args:
txt (str): text to be rendered txt (str): text to render
font_size (float): size of the font in model units font_size (float): size of the font in model units
font (str, optional): font name. Defaults to "Arial". font (str, optional): font name. Defaults to "Arial"
font_path (str, optional): system path to font library. Defaults to None. font_path (str, optional): system path to font file. Defaults to None
font_style (Font_Style, optional): style. Defaults to Font_Style.REGULAR. font_style (Font_Style, optional): font style, REGULAR, BOLD, or ITALIC.
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. Defaults to Font_Style.REGULAR
Defaults to (Align.CENTER, Align.CENTER). align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
path (Union[Edge, Wire], optional): path for text to follow. Defaults to None. Defaults to (Align.CENTER, Align.CENTER)
path (Edge | Wire, optional): path for text to follow. Defaults to None
position_on_path (float, optional): the relative location on path to position the position_on_path (float, optional): the relative location on path to position the
text, values must be between 0.0 and 1.0. Defaults to 0.0. text, values must be between 0.0 and 1.0. Defaults to 0.0
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
""" """
# pylint: disable=too-many-instance-attributes # pylint: disable=too-many-instance-attributes
@ -604,18 +603,18 @@ class Text(BaseSketchObject):
class Trapezoid(BaseSketchObject): class Trapezoid(BaseSketchObject):
"""Sketch Object: Trapezoid """Sketch Object: Trapezoid
Add trapezoid(s) to the sketch. Add trapezoid defined by major width, height, and interior angle(s).
Args: Args:
width (float): horizontal width width (float): trapezoid major width
height (float): vertical height height (float): trapezoid height
left_side_angle (float): bottom left interior angle left_side_angle (float): bottom left interior angle
right_side_angle (float, optional): bottom right interior angle. If not provided, right_side_angle (float, optional): bottom right interior angle. If not provided,
the trapezoid will be symmetric. Defaults to None. the trapezoid will be symmetric. Defaults to None
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to (Align.CENTER, Align.CENTER). Defaults to (Align.CENTER, Align.CENTER)
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: Give angles result in an invalid trapezoid ValueError: Give angles result in an invalid trapezoid
@ -685,21 +684,22 @@ class Trapezoid(BaseSketchObject):
class Triangle(BaseSketchObject): class Triangle(BaseSketchObject):
"""Sketch Object: Triangle """Sketch Object: Triangle
Add any triangle to the sketch by specifying the length of any side and any Add a triangle defined by one side length and any of two other side lengths or interior
two other side lengths or interior angles. Note that the interior angles are angles. The interior angles are opposite the side with the same designation
opposite the side with the same designation (i.e. side 'a' is opposite angle 'A'). (i.e. side 'a' is opposite angle 'A'). Side 'a' is the bottom side, followed by 'b'
on the right, going counter-clockwise.
Args: Args:
a (float, optional): side 'a' length. Defaults to None. a (float, optional): side 'a' length. Defaults to None
b (float, optional): side 'b' length. Defaults to None. b (float, optional): side 'b' length. Defaults to None
c (float, optional): side 'c' length. Defaults to None. c (float, optional): side 'c' length. Defaults to None
A (float, optional): interior angle 'A' in degrees. Defaults to None. A (float, optional): interior angle 'A'. Defaults to None
B (float, optional): interior angle 'B' in degrees. Defaults to None. B (float, optional): interior angle 'B'. Defaults to None
C (float, optional): interior angle 'C' in degrees. Defaults to None. C (float, optional): interior angle 'C'. Defaults to None
rotation (float, optional): angles to rotate objects. Defaults to 0. rotation (float, optional): angle to rotate object. Defaults to 0
align (Union[Align, tuple[Align, Align]], optional): align min, center, or max of object. align (Align | tuple[Align, Align], optional): align MIN, CENTER, or MAX of object.
Defaults to None. Defaults to None
mode (Mode, optional): combination mode. Defaults to Mode.ADD. mode (Mode, optional): combination mode. Defaults to Mode.ADD
Raises: Raises:
ValueError: One length and two other values were not provided ValueError: One length and two other values were not provided