CadQuery Class Summary
This page documents all of the methods and functions of the CadQuery classes, organized alphabetically.
See also
For a listing organized by functional area, see theAPI Reference
Core Classes
| 2D sketch. |
| Defines a coordinate system in space, in which 2D coordinates can be used. |
| Nested assembly of Workplane and Shape objects defining their relative positions. |
alias of |
Topological Classes
| Represents a shape in the system. |
| A Single Point in Space |
| A trimmed curve that represents the border of a face |
| A series of connected, ordered Edges, that typically bounds a Face |
| a bounded surface that represents part of the boundary of a solid |
| the outer boundary of a surface |
| a single solid |
| a collection of disconnected solids |
Geometry Classes
| Create a 3-dimensional vector |
| A 3d , 4x4 transformation matrix. |
| A 2D coordinate system in space |
| Location in 3D space. |
Selector Classes
| Filters a list of objects. |
Selects object nearest the provided point. | |
| Selects objects inside the 3D box defined by 2 points. |
| A selector that handles selection on the basis of a single direction vector. |
| Selects objects parallel with the provided direction. |
| Selects objects aligned with the provided direction. |
| Selects objects perpendicular with the provided direction. |
| Selects objects having the prescribed geometry type. |
| Select the object with the Nth radius. |
| Sorts objects into a list with order determined by the distance of their center projected onto the specified direction. |
| Selects objects closest or farthest in the specified direction. |
| Filters for objects parallel (or normal) to the specified direction then returns the Nth one. |
| Select the object(s) with the Nth length |
| Selects the object(s) with Nth area |
| Base class for selectors that operates with two other selectors. |
| Intersection selector. |
| Union selector. |
| Difference selector. |
| Inverts the selection of given selector. |
| Filter lists objects using a simple string syntax. |
Class Details
- classcadquery.Assembly(obj:Shape|Workplane|None=None,loc:Location|None=None,name:str|None=None,color:Color|None=None,material:Material|None=None,metadata:Dict[str,Any]|None=None)[source]
Bases:
objectNested assembly of Workplane and Shape objects defining their relative positions.
- Parameters:
- __init__(obj:Shape|Workplane|None=None,loc:Location|None=None,name:str|None=None,color:Color|None=None,material:Material|None=None,metadata:Dict[str,Any]|None=None)[source]
construct an assembly
- Parameters:
obj (Shape |Workplane |None) – root object of the assembly (default: None)
loc (Location |None) – location of the root object (default: None, interpreted as identity transformation)
name (str |None) – unique name of the root object (default: None, resulting in an UUID being generated)
color (Color |None) – color of the added object (default: None)
material (Material |None) – material (for visual and/or physical properties) of the added object (default: None)
metadata (Dict[str,Any]|None) – a store for user-defined metadata (default: None)
- Returns:
An Assembly object.
To create an empty assembly use:
assy=Assembly(None)
To create one constraint a root object:
b=Workplane().box(1,1,1)assy=Assembly(b,Location(Vector(0,0,1)),name="root")
- __iter__(loc:Location|None=None,name:str|None=None,color:Color|None=None)→Iterator[Tuple[Shape,str,Location,Color|None]][source]
Assembly iterator yielding shapes, names, locations and colors.
- __weakref__
list of weak references to the object
- add(obj:Assembly,loc:Location|None=None,name:str|None=None,color:Color|None=None)→Self[source]
- add(obj:Shape|Workplane|None,loc:Location|None=None,name:str|None=None,color:Color|None=None,material:Material|str|None=None,metadata:Dict[str,Any]|None=None)→Self
Add a subassembly to the current assembly.
- addSubshape(s:Shape,name:str|None=None,color:Color|None=None,layer:str|None=None)→Assembly[source]
Handles name, color and layer metadata for subshapes.
- constrain(q1:str,q2:str,kind:Literal['Plane','Point','Axis','PointInPlane','Fixed','FixedPoint','FixedAxis','PointOnLine','FixedRotation'],param:Any=None)→Self[source]
- constrain(q1:str,kind:Literal['Plane','Point','Axis','PointInPlane','Fixed','FixedPoint','FixedAxis','PointOnLine','FixedRotation'],param:Any=None)→Self
- constrain(id1:str,s1:Shape,id2:str,s2:Shape,kind:Literal['Plane','Point','Axis','PointInPlane','Fixed','FixedPoint','FixedAxis','PointOnLine','FixedRotation'],param:Any=None)→Self
- constrain(id1:str,s1:Shape,kind:Literal['Plane','Point','Axis','PointInPlane','Fixed','FixedPoint','FixedAxis','PointOnLine','FixedRotation'],param:Any=None)→Self
Define a new constraint.
- export(path:str,exportType:Literal['STEP','XML','XBF','GLTF','VTKJS','VRML','STL']|None=None,mode:Literal['default','fused']='default',tolerance:float=0.1,angularTolerance:float=0.1,**kwargs)→Self[source]
Save assembly to a file.
- Parameters:
path (str) – Path and filename for writing.
exportType (Literal['STEP','XML','XBF','GLTF','VTKJS','VRML','STL']|None) – export format (default: None, results in format being inferred form the path)
mode (Literal['default','fused']) – STEP only - See
exportAssembly().tolerance (float) – the deflection tolerance, in model units. Only used for glTF, VRML. Default 0.1.
angularTolerance (float) – the angular tolerance, in radians. Only used for glTF, VRML. Default 0.1.
**kwargs – Additional keyword arguments. Only used for STEP, glTF and STL.See
exportAssembly().ascii (bool) – STL only - Sets whether or not STL export should be text or binary
- Return type:
Self
- classmethodimportStep(path:str)→Self[source]
Reads an assembly from a STEP file.
- Parameters:
path (str) – Path and filename for reading.
- Returns:
An Assembly object.
- Return type:
Self
- classmethodload(path:str,importType:Literal['STEP','XML','XBF']|None=None)→Self[source]
Load step, xbf or xml.
- Parameters:
path (str)
importType (Literal['STEP','XML','XBF']|None)
- Return type:
Self
- remove(name:str)→Assembly[source]
Remove a part/subassembly from the current assembly.
- Parameters:
name (str) – Name of the part/subassembly to be removed
- Returns:
The modified assembly
- Return type:
NOTE This method can cause problems with deeply nested assemblies and does not removeconstraints associated with the removed part/subassembly.
- save(path:str,exportType:Literal['STEP','XML','XBF','GLTF','VTKJS','VRML','STL']|None=None,mode:Literal['default','fused']='default',tolerance:float=0.1,angularTolerance:float=0.1,**kwargs)→Self[source]
Save assembly to a file.
- Parameters:
path (str) – Path and filename for writing.
exportType (Literal['STEP','XML','XBF','GLTF','VTKJS','VRML','STL']|None) – export format (default: None, results in format being inferred form the path)
mode (Literal['default','fused']) – STEP only - See
exportAssembly().tolerance (float) – the deflection tolerance, in model units. Only used for glTF, VRML. Default 0.1.
angularTolerance (float) – the angular tolerance, in radians. Only used for glTF, VRML. Default 0.1.
**kwargs – Additional keyword arguments. Only used for STEP, glTF and STL.See
exportAssembly().ascii (bool) – STL only - Sets whether or not STL export should be text or binary
- Return type:
Self
- solve(verbosity:int=0)→Self[source]
Solve the constraints.
- Parameters:
verbosity (int)
- Return type:
Self
- classcadquery.BoundBox(bb:Bnd_Box)[source]
Bases:
objectA BoundingBox for an object or set of objects. Wraps the OCP one
- Parameters:
bb (Bnd_Box)
- __weakref__
list of weak references to the object
- add(obj:Tuple[float,float,float]|Vector|BoundBox,tol:float|None=None)→BoundBox[source]
Returns a modified (expanded) bounding box
- obj can be one of several things:
a 3-tuple corresponding to x,y, and z amounts to add
a vector, containing the x,y,z values to add
another bounding box, where a new box will be created thatencloses both.
This bounding box is not changed.
- enlarge(tol:float)→BoundBox[source]
Returns a modified (expanded) bounding box, expanded in alldirections by the tolerance value.
This means that the minimum values of its X, Y and Z intervalsof the bounding box are reduced by the absolute value of tol, whilethe maximum values are increased by the same amount.
- Parameters:
tol (float)
- Return type:
- staticfindOutsideBox2D(bb1:BoundBox,bb2:BoundBox)→BoundBox|None[source]
Compares bounding boxes
Compares bounding boxes. Returns none if neither is inside the other.Returns the outer one if either is outside the other.
BoundBox.isInside works in 3d, but this is a 2d bounding box, so itdoesn’t work correctly plus, there was all kinds of rounding error inthe built-in implementation i do not understand.
- classcadquery.Color(name:str)[source]
- classcadquery.Color(r:float,g:float,b:float,a:float=0,srgb:bool=True)
- classcadquery.Color
Bases:
objectWrapper for the OCCT color object Quantity_ColorRGBA.
- __getstate__()→Tuple[float,float,float,float][source]
Helper for pickle.
- Return type:
Tuple[float, float, float, float]
- __weakref__
list of weak references to the object
- classcadquery.Compound(obj:TopoDS_Shape)[source]
a collection of disconnected solids
- Parameters:
obj (TopoDS_Shape)
- ancestors(shape:Shape,kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'])→Compound[source]
Iterate over ancestors, i.e. shapes of same kind within shape that contain elements of self.
- cut(*toCut:Shape,tol:float|None=None)→Compound[source]
Remove the positional arguments from this Shape.
- intersect(*toIntersect:Shape,tol:float|None=None)→Compound[source]
Intersection of the positional arguments and this Shape.
- classmethodmakeCompound(listOfShapes:Iterable[Shape])→Compound[source]
Create a compound out of a list of shapes
- classmethodmakeText(text:str,size:float,height:float,font:str='Arial',fontPath:str|None=None,kind:Literal['regular','bold','italic']='regular',halign:Literal['center','left','right']='center',valign:Literal['center','top','bottom']='center',position:Plane=Plane(origin=(0.0,0.0,0.0),xDir=(1.0,0.0,0.0),normal=(0.0,0.0,1.0)))→Shape[source]
Create a 3D text
- cadquery.Constraint
alias of
ConstraintSpec
- classcadquery.DirectionMinMaxSelector(vector:Vector,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
CenterNthSelectorSelects objects closest or farthest in the specified direction.
- Applicability:
All object types. for a vertex, its point is used. for all other kindsof objects, the center of mass of the object is used.
You can use the string shortcuts >(X|Y|Z) or <(X|Y|Z) if you want to selectbased on a cardinal direction.
For example this:
CQ(aCube).faces(DirectionMinMaxSelector((0,0,1),True))
Means to select the face having the center of mass farthest in the positivez direction, and is the same as:
CQ(aCube).faces(">Z")
- Parameters:
vector (Vector)
directionMax (bool)
tolerance (float)
- classcadquery.DirectionSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
BaseDirSelectorSelects objects aligned with the provided direction.
- Applicability:
Linear EdgesPlanar Faces
Use the string syntax shortcut +/-(X|Y|Z) if you want to select based on a cardinal direction.
Example:
CQ(aCube).faces(DirectionSelector((0,0,1)))
selects faces with the normal in the z direction, and is equivalent to:
CQ(aCube).faces("+Z")
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.Edge(obj:TopoDS_Shape)[source]
A trimmed curve that represents the border of a face
- Parameters:
obj (TopoDS_Shape)
- hasPCurve(f:Face)→bool[source]
Check if self has a pcurve defined on f.
- Parameters:
f (Face)
- Return type:
bool
- classmethodmakeBezier(points:List[Vector])→Edge[source]
Create a cubic Bézier Curve from the points.
- classmethodmakeEllipse(x_radius:float,y_radius:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),xdir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(1.0,0.0,0.0),angle1:float=360.0,angle2:float=360.0,sense:~typing.Literal[-1,1]=1)→Edge[source]
Makes an Ellipse centered at the provided point, having normal in the provided direction.
- Parameters:
cls
x_radius (float) – x radius of the ellipse (along the x-axis of plane the ellipse should lie in)
y_radius (float) – y radius of the ellipse (along the y-axis of plane the ellipse should lie in)
pnt (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the center of the ellipse
dir (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the direction of the plane the ellipse should lie in
angle1 (float) – start angle of arc
angle2 (float) – end angle of arc (angle2 == angle1 return closed ellipse = default)
sense (Literal[-1,1]) – clockwise (-1) or counter clockwise (1)
xdir (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
- Returns:
an Edge
- Return type:
- classmethodmakeLine(v1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Edge[source]
Create a line between two points
- Parameters:
- Returns:
A linear edge between the two provided points
- Return type:
- classmethodmakeSpline(listOfVector:List[Vector],tangents:Sequence[Vector]|None=None,periodic:bool=False,parameters:Sequence[float]|None=None,scale:bool=True,tol:float=1e-06)→Edge[source]
Interpolate a spline through the provided points.
- Parameters:
listOfVector (List[Vector]) – a list of Vectors that represent the points
tangents (Sequence[Vector]|None) – tuple of Vectors specifying start and finish tangent
periodic (bool) – creation of periodic curves
parameters (Sequence[float]|None) – the value of the parameter at each interpolation point. (The interpolatedcurve is represented as a vector-valued function of a scalar parameter.) If periodic ==True, then len(parameters) must be len(intepolation points) + 1, otherwise len(parameters)must be equal to len(interpolation points).
scale (bool) – whether to scale the specified tangent vectors before interpolating. Eachtangent is scaled, so it’s length is equal to the derivative of the Lagrange interpolatedcurve. I.e., set this to True, if you want to use only the direction of the tangentvectors specified by
tangents, but not their magnitude.tol (float) – tolerance of the algorithm (consult OCC documentation). Used to check that thespecified points are not too close to each other, and that tangent vectors are not tooshort. (In either case interpolation may fail.)
- Returns:
an Edge
- Return type:
- classmethodmakeSplineApprox(listOfVector:List[Vector],tol:float=0.001,smoothing:Tuple[float,float,float]|None=None,minDeg:int=1,maxDeg:int=6)→Edge[source]
Approximate a spline through the provided points.
- Parameters:
listOfVector (List[Vector]) – a list of Vectors that represent the points
tol (float) – tolerance of the algorithm (consult OCC documentation).
smoothing (Tuple[float,float,float]|None) – optional tuple of 3 weights use for variational smoothing (default: None)
minDeg (int) – minimum spline degree. Enforced only when smothing is None (default: 1)
maxDeg (int) – maximum spline degree (default: 6)
- Returns:
an Edge
- Return type:
- classmethodmakeTangentArc(v1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v3:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Edge[source]
Makes a tangent arc from point v1, in the direction of v2 and ends at v3.
- Parameters:
- Returns:
an edge
- Return type:
- classmethodmakeThreePointArc(v1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v3:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Edge[source]
Makes a three point arc through the provided points
- Parameters:
- Returns:
an edge object through the three points
- Return type:
- classcadquery.Face(obj:TopoDS_Shape)[source]
Bases:
Shapea bounded surface that represents part of the boundary of a solid
- Parameters:
obj (TopoDS_Shape)
- extend(d:float,umin:bool=True,umax:bool=True,vmin:bool=True,vmax:bool=True)→Face[source]
Extend a face. Does not work well in periodic directions.
- Parameters:
d (float) – length of the extension.
umin (bool) – extend along the umin isoline.
umax (bool) – extend along the umax isoline.
vmin (bool) – extend along the vmin isoline.
vmax (bool) – extend along the vmax isoline.
- Return type:
- isoline(param:float|int,direction:Literal['u','v']='v')→Edge[source]
Construct an isoline.
- Parameters:
param (float |int)
direction (Literal['u','v'])
- Return type:
- isolines(params:Iterable[float|int],direction:Literal['u','v']='v')→List[Edge][source]
Construct multiple isolines.
- Parameters:
params (Iterable[float |int])
direction (Literal['u','v'])
- Return type:
List[Edge]
- classmethodmakeFromWires(outerWire:Wire,innerWires:List[Wire]=[])→Face[source]
Makes a planar face from one or more wires
- classmethodmakeNSidedSurface(edges:~typing.Iterable[~cadquery.occ_impl.shapes.Edge|~cadquery.occ_impl.shapes.Wire],constraints:~typing.Iterable[~cadquery.occ_impl.shapes.Edge|~cadquery.occ_impl.shapes.Wire|~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]|~OCP.gp.gp_Pnt],continuity:~OCP.GeomAbs.GeomAbs_Shape=<GeomAbs_Shape.GeomAbs_C0:0>,degree:int=3,nbPtsOnCur:int=15,nbIter:int=2,anisotropy:bool=False,tol2d:float=1e-05,tol3d:float=0.0001,tolAng:float=0.01,tolCurv:float=0.1,maxDeg:int=8,maxSegments:int=9)→Face[source]
Returns a surface enclosed by a closed polygon defined by ‘edges’ and ‘constraints’.
- Parameters:
edges (list ofedges orwires) – edges
constraints (list ofpoints oredges) – constraints
continuity (GeomAbs_Shape) – OCC.Core.GeomAbs continuity condition
degree (int) – >=2
nbPtsOnCur (int) – number of points on curve >= 15
nbIter (int) – number of iterations >= 2
anisotropy (bool) – bool Anisotropy
tol2d (float) – 2D tolerance >0
tol3d (float) – 3D tolerance >0
tolAng (float) – angular tolerance
tolCurv (float) – tolerance for curvature >0
maxDeg (int) – highest polynomial degree >= 2
maxSegments (int) – greatest number of segments >= 2
- Return type:
- classmethodmakeRuledSurface(edgeOrWire1:Edge,edgeOrWire2:Edge)→Face[source]
- classmethodmakeRuledSurface(edgeOrWire1:Wire,edgeOrWire2:Wire)→Face
makeRuledSurface(Edge|Wire,Edge|Wire) – Make a ruled surfaceCreate a ruled surface out of two edges or wires. If wires are used thenthese must have the same number of edges
- classmethodmakeSplineApprox(points:List[List[Vector]],tol:float=0.01,smoothing:Tuple[float,float,float]|None=None,minDeg:int=1,maxDeg:int=3)→Face[source]
Approximate a spline surface through the provided points.
- Parameters:
points (List[List[Vector]]) – a 2D list of Vectors that represent the points
tol (float) – tolerance of the algorithm (consult OCC documentation).
smoothing (Tuple[float,float,float]|None) – optional tuple of 3 weights use for variational smoothing (default: None)
minDeg (int) – minimum spline degree. Enforced only when smothing is None (default: 1)
maxDeg (int) – maximum spline degree (default: 6)
- Return type:
- normalAt(u:float|int,v:float|int)→Tuple[Vector,Vector][source]
- normalAt(locationVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]|None=None)→Vector
Computes the normal vector at the desired location on the face.
- Returns:
a vector representing the direction
- Parameters:
locationVector (a vector that lies on the surface.) – the location to compute the normal at. If none, the center of the face is used.
- Return type:
Computes the normal vector at the desired location in the u,v parameter space.
- Returns:
a vector representing the normal direction and the position
- Parameters:
u – the u parametric location to compute the normal at.
v – the v parametric location to compute the normal at.
locationVector (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]|None)
- Return type:
- normals(us:Iterable[float|int],vs:Iterable[float|int])→Tuple[List[Vector],List[Vector]][source]
Computes the normal vectors at the desired locations in the u,v parameter space.
- Returns:
a tuple of list of vectors representing the normal directions and the positions
- Parameters:
us (Iterable[float |int]) – the u parametric locations to compute the normal at.
vs (Iterable[float |int]) – the v parametric locations to compute the normal at.
- Return type:
- paramAt(pt:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Tuple[float,float][source]
Computes the (u,v) pair closest to a given vector.
- Returns:
(u, v) tuple
- Parameters:
pt (a vector that lies on orclose to the surface.) – the location to compute the normal at.
- Return type:
Tuple[float, float]
- params(pts:Iterable[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]],tol:float=1e-09)→Tuple[List[float],List[float]][source]
Computes (u,v) pairs closest to given vectors.
- Returns:
list of (u, v) tuples
- Parameters:
pts (a list ofvectors that lie on the surface.) – the points to compute the normals at.
tol (float)
- Return type:
Tuple[List[float],List[float]]
- positionAt(u:float|int,v:float|int)→Vector[source]
Computes the position vector at the desired location in the u,v parameter space.
- Returns:
a vector representing the position
- Parameters:
u (float |int) – the u parametric location to compute the normal at.
v (float |int) – the v parametric location to compute the normal at.
- Return type:
- positions(uvs:Iterable[Tuple[int|float,int|float]])→List[Vector][source]
Computes position vectors at the desired locations in the u,v parameter space.
- Returns:
list of vectors corresponding to the requested u,v positions
- Parameters:
uvs (Iterable[Tuple[int |float,int |float]]) – iterable of u,v pairs.
- Return type:
List[Vector]
- thicken(thickness:float)→Solid[source]
Return a thickened face
- Parameters:
thickness (float)
- Return type:
- toArcs(tolerance:float=0.001)→Face[source]
Approximate planar face with arcs and straight line segments.
- Parameters:
tolerance (float) – Approximation tolerance.
- Return type:
- toPln()→gp_Pln[source]
Convert this face to a gp_Pln.
Note the Location of the resulting plane may not equal the center of this face,however the resulting plane will still contain the center of this face.
- Return type:
gp_Pln
- trim(outer:Wire,*inner:Wire)→Self[source]
- trim(u0:float|int,u1:float|int,v0:float|int,v1:float|int,tol:float|int=1e-06)→Self
- trim(pt1:Tuple[int|float,int|float],pt2:Tuple[int|float,int|float],pt3:Tuple[int|float,int|float],*pts:Tuple[int|float,int|float])→Self
Trim the face in the (u,v) space to (u0, u1)x(v1, v2).
NB: this operation is done on the base geometry.
Trim the face using a polyline defined in the (u,v) space.
Trim using wires. The provided wires need to have a pcurve on self.
- Parameters:
u0 (float |int)
u1 (float |int)
v0 (float |int)
v1 (float |int)
tol (float |int)
- Return type:
Self
- classcadquery.Location(t:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])[source]
Bases:
objectLocation in 3D space. Depending on usage can be absolute or relative.
This class wraps the TopLoc_Location class from OCCT. It can be used to move Shapeobjects in both relative and absolute manner. It is the preferred type to locate objectsin CQ.
- Parameters:
t (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
- __init__(t:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angles:Tuple[int|float,int|float,int|float])→None[source]
- __init__(T:TopLoc_Location)→None
- __init__(t:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],ax:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angle:int|float)→None
- __init__(t:Plane)→None
- __init__(x:int|float=0,y:int|float=0,z:int|float=0,rx:int|float=0,ry:int|float=0,rz:int|float=0)→None
- __init__(T:gp_Trsf)→None
- __init__(t:Plane,v:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→None
- __init__(t:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→None
Location with translation t with respect to the original location.
Location with translation (x,y,z) and 3 rotation angles.
Location corresponding to the location of the Plane t.
Location corresponding to the angular location of the Plane t with translation v.
Location wrapping the low-level TopLoc_Location object t
Location wrapping the low-level gp_Trsf object t
- Location with translation t and rotation around ax by angle
with respect to the original location.
Location with translation t and 3 rotation angles.
- Parameters:
t (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
- Return type:
None
- __weakref__
list of weak references to the object
- classcadquery.Material(name:str|None=None,**kwargs)[source]
Bases:
objectWrapper for the OCCT material classes XCAFDoc_Material and XCAFDoc_VisMaterial.XCAFDoc_Material is focused on physical material properties andXCAFDoc_VisMaterial is for visual properties to be used when rendering.
- Parameters:
name (str |None)
- __getstate__()→Tuple[str,str,float,str][source]
Allows pickling.
- Return type:
Tuple[str, str, float, str]
- __init__(name:str|None=None,**kwargs)[source]
Can be passed an arbitrary string name for the material along with keywordarguments defining some other characteristics of the material. If nothing ispassed, arbitrary defaults are used.
- Parameters:
name (str |None)
- __setstate__(data:Tuple[str,str,float,str])[source]
Allows pickling.
- Parameters:
data (Tuple[str,str,float,str])
- __weakref__
list of weak references to the object
- propertydensity:float
Get the density value of the material.
- propertydensityUnit:str
Get the units that the material density is defined in.
- propertydescription:str
Get the string description of the material.
- propertyname:str
Get the string name of the material.
- classcadquery.Matrix[source]
- classcadquery.Matrix(matrix:gp_GTrsf|gp_Trsf)
- classcadquery.Matrix(matrix:Sequence[Sequence[float]])
Bases:
objectA 3d , 4x4 transformation matrix.
Used to move geometry in space.
The provided “matrix” parameter may be None, a gp_GTrsf, or a nested list ofvalues.
If given a nested list, it is expected to be of the form:
- [[m11, m12, m13, m14],
[m21, m22, m23, m24],[m31, m32, m33, m34]]
A fourth row may be given, but it is expected to be: [0.0, 0.0, 0.0, 1.0]since this is a transform matrix.
- __getitem__(rc:Tuple[int,int])→float[source]
Provide Matrix[r, c] syntax for accessing individual values. The rowand column parameters start at zero, which is consistent with mostpython libraries, but is counter to gp_GTrsf(), which is 1-indexed.
- Parameters:
rc (Tuple[int,int])
- Return type:
float
- __init__()→None[source]
- __init__(matrix:gp_GTrsf|gp_Trsf)→None
- __init__(matrix:Sequence[Sequence[float]])→None
- __weakref__
list of weak references to the object
- classcadquery.NearestToPointSelector(pnt)[source]
Bases:
SelectorSelects object nearest the provided point.
If the object is a vertex or point, the distanceis used. For other kinds of shapes, the center of massis used to to compute which is closest.
Applicability: All Types of Shapes
Example:
CQ(aCube).vertices(NearestToPointSelector((0,1,0)))
returns the vertex of the unit cube closest to the point x=0,y=1,z=0
- classcadquery.ParallelDirSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
BaseDirSelectorSelects objects parallel with the provided direction.
- Applicability:
Linear EdgesPlanar Faces
Use the string syntax shortcut |(X|Y|Z) if you want to select based on a cardinal direction.
Example:
CQ(aCube).faces(ParallelDirSelector((0,0,1)))
selects faces with the normal parallel to the z direction, and is equivalent to:
CQ(aCube).faces("|Z")
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.PerpendicularDirSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
BaseDirSelectorSelects objects perpendicular with the provided direction.
- Applicability:
Linear EdgesPlanar Faces
Use the string syntax shortcut #(X|Y|Z) if you want to select based on acardinal direction.
Example:
CQ(aCube).faces(PerpendicularDirSelector((0,0,1)))
selects faces with the normal perpendicular to the z direction, and is equivalent to:
CQ(aCube).faces("#Z")
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.Plane(origin:Tuple[int|float,int|float,int|float]|Vector,xDir:Vector=None,normal:Tuple[int|float,int|float,int|float]|Vector=(0,0,1))[source]
Bases:
objectA 2D coordinate system in space
A 2D coordinate system in space, with the x-y axes on the plane, and aparticular point as the origin.
A plane allows the use of 2D coordinates, which are later converted toglobal, 3d coordinates when the operations are complete.
Frequently, it is not necessary to create work planes, as they can becreated automatically from faces.
- Parameters:
- __hash__=None
- __init__(loc:Location)[source]
- __init__(origin:Tuple[int|float,int|float,int|float]|Vector,xDir:Tuple[int|float,int|float,int|float]|Vector|None=None,normal:Tuple[int|float,int|float,int|float]|Vector=(0,0,1))
Create a Plane from origin in global coordinates, vector xDir, and normal direction for the plane.
Create a Plane from Location loc.
- __weakref__
list of weak references to the object
- classmethodnamed(stdName:str,origin=(0,0,0))→Plane[source]
Create a predefined Plane based on the conventional names.
- Parameters:
stdName (string) – one of (XY|YZ|ZX|XZ|YX|ZY|front|back|left|right|top|bottom)
origin (3-tuple ofthe origin ofthe new plane,in global coordinates.) – the desired origin, specified in global coordinates
- Return type:
Available named planes are as follows. Direction references refer tothe global directions.
Name
xDir
yDir
zDir
XY
+x
+y
+z
YZ
+y
+z
+x
ZX
+z
+x
+y
XZ
+x
+z
-y
YX
+y
+x
-z
ZY
+z
+y
-x
front
+x
+y
+z
back
-x
+y
-z
left
+z
+y
-x
right
-z
+y
+x
top
+x
-z
+y
bottom
+x
+z
-y
- rotated(rotate=(0,0,0))[source]
Returns a copy of this plane, rotated about the specified axes
Since the z axis is always normal the plane, rotating around Z willalways produce a plane that is parallel to this one.
The origin of the workplane is unaffected by the rotation.
Rotations are done in order x, y, z. If you need a different order,manually chain together multiple rotate() commands.
- Parameters:
rotate – Vector [xDegrees, yDegrees, zDegrees]
- Returns:
a copy of this plane rotated as requested.
- setOrigin2d(x,y)[source]
Set a new origin in the plane itself
Set a new origin in the plane itself. The plane’s orientation andxDrection are unaffected.
- Parameters:
x (float) – offset in the x direction
y (float) – offset in the y direction
- Returns:
void
The new coordinates are specified in terms of the current 2D system.As an example:
p = Plane.XY()p.setOrigin2d(2, 2)p.setOrigin2d(2, 2)
results in a plane with its origin at (x, y) = (4, 4) in globalcoordinates. Both operations were relative to local coordinates of theplane.
- toLocalCoords(obj)[source]
Project the provided coordinates onto this plane
- Parameters:
obj – an object or vector to convert
- Returns:
an object of the same type, but converted to local coordinates
Most of the time, the z-coordinate returned will be zero, because mostoperations based on a plane are all 2D. Occasionally, though, 3Dpoints outside of the current plane are transformed. One such example is
Workplane.box(), where 3D corners of a box are transformed toorient the box in space correctly.
- classcadquery.Selector[source]
Bases:
objectFilters a list of objects.
Filters must provide a single method that filters objects.
- __weakref__
list of weak references to the object
- classcadquery.Shape(obj:TopoDS_Shape)[source]
Bases:
objectRepresents a shape in the system. Wraps TopoDS_Shape.
- Parameters:
obj (TopoDS_Shape)
- CenterOfBoundBox(tolerance:float|None=None)→Vector[source]
- Parameters:
tolerance (float |None) – Tolerance passed to the
BoundingBox()method- Returns:
Center of the bounding box of this shape
- Return type:
- staticCombinedCenter(objects:Iterable[Shape])→Vector[source]
Calculates the center of mass of multiple objects.
- staticCombinedCenterOfBoundBox(objects:List[Shape])→Vector[source]
Calculates the center of a bounding box of multiple objects.
- CompSolids()→List[CompSolid][source]
- Returns:
All the compsolids in this Shape
- Return type:
List[CompSolid]
- Compounds()→List[Compound][source]
- Returns:
All the compounds in this Shape
- Return type:
List[Compound]
- Volume(tol:float|None=None)→float[source]
- Returns:
The volume of this Shape
- Parameters:
tol (float |None)
- Return type:
float
- __weakref__
list of weak references to the object
- ancestors(shape:Shape,kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'])→Compound[source]
Iterate over ancestors, i.e. shapes of same kind within shape that contain self.
- classmethodcast(obj:TopoDS_Shape,forConstruction:bool=False)→Shape[source]
Returns the right type of wrapper, given a OCCT object
- Parameters:
obj (TopoDS_Shape)
forConstruction (bool)
- Return type:
- staticcomputeMass(obj:Shape,tol:float|None=None)→float[source]
Calculates the ‘mass’ of an object.
- Parameters:
obj (Shape) – Compute the mass of this object
tol (float |None) – Numerical integration tolerance (optional).
- Return type:
float
- copy(mesh:bool=False)→T[source]
Creates a new object that is a copy of this object.
- Parameters:
self (T)
mesh (bool) – should I copy the triangulation too (default: False)
- Returns:
a copy of the object
- Return type:
T
- cut(*toCut:Shape,tol:float|None=None)→Shape[source]
Remove the positional arguments from this Shape.
- distance(other:Shape)→float[source]
Minimal distance between two shapes
- Parameters:
other (Shape)
- Return type:
float
- distances(*others:Shape)→Iterator[float][source]
Minimal distances to between self and other shapes
- Parameters:
others (Shape)
- Return type:
Iterator[float]
- export(fname:str,tolerance:float=0.1,angularTolerance:float=0.1,opt:Dict[str,Any]|None=None)[source]
Export Shape to file.
- Parameters:
self (T)
fname (str)
tolerance (float)
angularTolerance (float)
opt (Dict[str,Any]|None)
- exportBin(f:str|BytesIO)→bool[source]
Export this shape to a binary BREP file.
- Parameters:
f (str |BytesIO)
- Return type:
bool
- exportBrep(f:str|BytesIO)→bool[source]
Export this shape to a BREP file
- Parameters:
f (str |BytesIO)
- Return type:
bool
- exportStep(fileName:str,**kwargs)→IFSelect_ReturnStatus[source]
Export this shape to a STEP file.
kwargs is used to provide optional keyword arguments to configure the exporter.
- Parameters:
fileName (str) – Path and filename for writing.
write_pcurves (bool) –
Enable or disable writing parametric curves to the STEP file. Default True.
If False, writes STEP file without pcurves. This decreases the size of the resulting STEP file.
precision_mode (int) – Controls the uncertainty value for STEP entities. Specify -1, 0, or 1. Default 0.See OCCT documentation.
- Return type:
IFSelect_ReturnStatus
- exportStl(fileName:str,tolerance:float=0.001,angularTolerance:float=0.1,ascii:bool=False,relative:bool=True,parallel:bool=True)→bool[source]
Exports a shape to a specified STL file.
- Parameters:
fileName (str) – The path and file name to write the STL output to.
tolerance (float) – A linear deflection setting which limits the distance between a curve and its tessellation.Setting this value too low will result in large meshes that can consume computing resources.Setting the value too high can result in meshes with a level of detail that is too low.Default is 1e-3, which is a good starting point for a range of cases.
angularTolerance (float) – Angular deflection setting which limits the angle between subsequent segments in a polyline. Default is 0.1.
ascii (bool) – Export the file as ASCII (True) or binary (False) STL format. Default is binary.
relative (bool) – If True, tolerance will be scaled by the size of the edge being meshed. Default is True.Setting this value to True may cause large features to become faceted, or small features dense.
parallel (bool) – If True, OCCT will use parallel processing to mesh the shape. Default is True.
- Return type:
bool
- facesIntersectedByLine(point:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],axis:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],tol:float=0.0001,direction:Literal['AlongAxis','Opposite']|None=None)[source]
Computes the intersections between the provided line and the faces of this Shape
- Parameters:
point (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – Base point for defining a line
axis (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – Axis on which the line rests
tol (float) – Intersection tolerance
direction (Literal['AlongAxis','Opposite']|None) – Valid values: “AlongAxis”, “Opposite”;If specified, will ignore all faces that are not in the specified directionincluding the face where the point lies if it is the case
- Returns:
A list of intersected faces sorted by distance from point
- fuse(*toFuse:Shape,glue:bool=False,tol:float|None=None)→Shape[source]
Fuse the positional arguments with this Shape.
- geomType()→Literal['Vertex','Wire','Shell','Solid','Compound','PLANE','CYLINDER','CONE','SPHERE','TORUS','BEZIER','BSPLINE','REVOLUTION','EXTRUSION','OFFSET','OTHER','LINE','CIRCLE','ELLIPSE','HYPERBOLA','PARABOLA'][source]
Gets the underlying geometry type.
Implementations can return any values desired, but the values the useruses in type filters should correspond to these.
As an example, if a user does:
CQ(object).faces("%mytype")
The expectation is that the geomType attribute will return ‘mytype’
The return values depend on the type of the shape:
Vertex: always ‘Vertex’Edge: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER,BSPLINE, OFFSET, OTHERFace: PLANE, CYLINDER, CONE, SPHERE, TORUS, BEZIER, BSPLINE,REVOLUTION, EXTRUSION, OFFSET, OTHERSolid: ‘Solid’Shell: ‘Shell’Compound: ‘Compound’Wire: ‘Wire’- Returns:
A string according to the geometry type
- Return type:
Literal[‘Vertex’, ‘Wire’, ‘Shell’, ‘Solid’, ‘Compound’, ‘PLANE’, ‘CYLINDER’, ‘CONE’, ‘SPHERE’, ‘TORUS’, ‘BEZIER’, ‘BSPLINE’, ‘REVOLUTION’, ‘EXTRUSION’, ‘OFFSET’, ‘OTHER’, ‘LINE’, ‘CIRCLE’, ‘ELLIPSE’, ‘HYPERBOLA’, ‘PARABOLA’]
- hashCode()→int[source]
Returns a hashed value denoting this shape. It is computed from theTShape and the Location. The Orientation is not used.
- Return type:
int
- classmethodimportBin(f:str|BytesIO)→Shape[source]
Import shape from a binary BREP file.
- Parameters:
f (str |BytesIO)
- Return type:
- classmethodimportBrep(f:str|BytesIO)→Shape[source]
Import shape from a BREP file
- Parameters:
f (str |BytesIO)
- Return type:
- intersect(*toIntersect:Shape,tol:float|None=None)→Shape[source]
Intersection of the positional arguments and this Shape.
- isEqual(other:Shape)→bool[source]
Returns True if two shapes are equal, i.e. if they share the sameTShape with the same Locations and Orientations. Also see
isSame().- Parameters:
other (Shape)
- Return type:
bool
- isNull()→bool[source]
Returns true if this shape is null. In other words, it references nounderlying shape with the potential to be given a location and anorientation.
- Return type:
bool
- isSame(other:Shape)→bool[source]
Returns True if other and this shape are same, i.e. if they share thesame TShape with the same Locations. Orientations may differ. Also see
isEqual()- Parameters:
other (Shape)
- Return type:
bool
- isValid()→bool[source]
Returns True if no defect is detected on the shape S or any of itssubshapes. See the OCCT docs on BRepCheck_Analyzer::IsValid for a fulldescription of what is checked.
- Return type:
bool
- locate(loc:Location)→T[source]
Apply a location in absolute sense to self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- located(loc:Location)→T[source]
Apply a location in absolute sense to a copy of self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- staticmatrixOfInertia(obj:Shape)→List[List[float]][source]
Calculates the matrix of inertia of an object.Since the part’s density is unknown, this result is inertia/density with units of [1/length].:param obj: Compute the matrix of inertia of this object
- Parameters:
obj (Shape)
- Return type:
List[List[float]]
- mesh(tolerance:float,angularTolerance:float=0.1)[source]
Generate triangulation if none exists.
- Parameters:
tolerance (float)
angularTolerance (float)
- mirror(mirrorPlane:Literal['XY','YX','XZ','ZX','YZ','ZY']|Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]='XY',basePointVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]=(0,0,0))→Shape[source]
Applies a mirror transform to this Shape. Does not duplicate objectsabout the plane.
- Parameters:
mirrorPlane (Literal['XY','YX','XZ','ZX','YZ','ZY']|~cadquery.occ_impl.geom.Vector |~typing.Tuple[int |float,int |float]|~typing.Tuple[int |float,int |float,int |float]) – The direction of the plane to mirror about - one of‘XY’, ‘XZ’ or ‘YZ’
basePointVector (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – The origin of the plane to mirror about
- Returns:
The mirrored shape
- Return type:
- move(x:float|int=0,y:float|int=0,z:float|int=0,rx:float|int=0,ry:float|int=0,rz:float|int=0)→T[source]
- move(loc:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T
- move(loc:Location)→T
Apply a location in relative sense (i.e. update current location) to self.
Apply translation and rotation in relative sense (i.e. update current location) to self.
Apply a VectorLike in relative sense (i.e. update current location) to self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- moved(loc:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T[source]
- moved(loc1:Location,loc2:Location,*locs:Location)→T
- moved(loc1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],loc2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],*locs:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T
- moved(locs:Sequence[Location])→T
- moved(loc:Location)→T
- moved(x:float|int=0,y:float|int=0,z:float|int=0,rx:float|int=0,ry:float|int=0,rz:float|int=0)→T
- moved(loc:Sequence[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]])→T
Apply a location in relative sense (i.e. update current location) to a copy of self.
Apply multiple locations.
Apply multiple locations.
Apply translation and rotation in relative sense to a copy of self.
Apply a VectorLike in relative sense to a copy of self.
Apply multiple VectorLikes in relative sense to a copy of self.
Apply multiple VectorLikes in relative sense to a copy of self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- rotate(startVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],endVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angleDegrees:float)→T[source]
Rotates a shape around an axis.
- Parameters:
self (T)
startVector (either a 3-tuple ora Vector) – start point of rotation axis
endVector (either a 3-tuple ora Vector) – end point of rotation axis
angleDegrees (float) – angle to rotate, in degrees
- Returns:
a copy of the shape, rotated
- Return type:
T
- scale(factor:float)→Shape[source]
Scales this shape through a transformation.
- Parameters:
factor (float)
- Return type:
- siblings(shape:Shape,kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'],level:int=1)→Compound[source]
Iterate over siblings, i.e. shapes within shape that share subshapes of kind with self.
- toSplines(degree:int=3,tolerance:float=0.001,nurbs:bool=False)→T[source]
Approximate shape with b-splines of the specified degree.
- Parameters:
self (T)
degree (int) – Maximum degree.
tolerance (float) – Approximation tolerance.
nurbs (bool) – Use rational splines.
- Return type:
T
- toVtkPolyData(tolerance:float|None=None,angularTolerance:float|None=None,normals:bool=False)→vtkPolyData[source]
Convert shape to vtkPolyData
- Parameters:
tolerance (float |None)
angularTolerance (float |None)
normals (bool)
- Return type:
vtkPolyData
- transformGeometry(tMatrix:Matrix)→Shape[source]
Transforms this shape by tMatrix.
WARNING: transformGeometry will sometimes convert lines and circles tosplines, but it also has the ability to handle skew and stretchingtransformations.
If your transformation is only translation and rotation, it is safer touse
transformShape(), which doesn’t change the underlying typeof the geometry, but cannot handle skew transformations.
- transformShape(tMatrix:Matrix)→Shape[source]
Transforms this Shape by tMatrix. Also see
transformGeometry().
- translate(vector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T[source]
Translates this shape through a transformation.
- Parameters:
self (T)
vector (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
- Return type:
T
- classcadquery.Shell(obj:TopoDS_Shape)[source]
Bases:
Shapethe outer boundary of a surface
- Parameters:
obj (TopoDS_Shape)
- classcadquery.Sketch(parent:~typing.Any=None,locs:~typing.Iterable[~cadquery.occ_impl.geom.Location]=(<cadquery.occ_impl.geom.Locationobject>,),obj:~cadquery.occ_impl.shapes.Compound|None=None)[source]
Bases:
object2D sketch. Supports faces, edges and edges with constraints based construction.
- __init__(parent:~typing.Any=None,locs:~typing.Iterable[~cadquery.occ_impl.geom.Location]=(<cadquery.occ_impl.geom.Locationobject>,),obj:~cadquery.occ_impl.shapes.Compound|None=None)[source]
Construct an empty sketch.
- __iter__()→Iterator[Face][source]
Iterate over faces-locations combinations. If not faces are presentiterate over edges:
- Return type:
Iterator[Face]
- __mul__(other:Sketch)→T[source]
Intersect self and other.
- Parameters:
self (T)
other (Sketch)
- Return type:
T
- __sub__(other:Sketch)→T[source]
Subtract other from self.
- Parameters:
self (T)
other (Sketch)
- Return type:
T
- __truediv__(other:Sketch)→T[source]
Split self with other.
- Parameters:
self (T)
other (Sketch)
- Return type:
T
- __weakref__
list of weak references to the object
- apply(f:Callable[[Iterable[Shape|Location]],Iterable[Shape|Location]])[source]
Apply a callable to all items at once.
- arc(p1:Vector|Tuple[int|float,int|float],p2:Vector|Tuple[int|float,int|float],p3:Vector|Tuple[int|float,int|float],tag:str|None=None,forConstruction:bool=False)→T[source]
- arc(c:Vector|Tuple[int|float,int|float],r:int|float,a:int|float,da:int|float,tag:str|None=None,forConstruction:bool=False)→T
- arc(p2:Vector|Tuple[int|float,int|float],p3:Vector|Tuple[int|float,int|float],tag:str|None=None,forConstruction:bool=False)→T
Construct an arc.
- assemble(mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Assemble edges into faces.
- Parameters:
self (T)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- bezier(pts:Iterable[Vector|Tuple[int|float,int|float]],tag:str|None=None,forConstruction:bool=False)→T[source]
Construct an bezier curve.
The edge will pass through the last points, and the inner pointsare bezier control points.
- Parameters:
self (T)
pts (Iterable[Vector |Tuple[int |float,int |float]])
tag (str |None)
forConstruction (bool)
- Return type:
T
- chamfer(d:int|float)→T[source]
Add a chamfer based on current selection.
- Parameters:
self (T)
d (int |float)
- Return type:
T
- circle(r:int|float,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct a circular face.
- Parameters:
self (T)
r (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- close(tag:str|None=None)→T[source]
Connect last edge to the first one.
- Parameters:
self (T)
tag (str |None)
- Return type:
T
- constrain(tag1:str,tag2:str,constraint:Literal['Fixed','FixedPoint','Coincident','Angle','Length','Distance','Radius','Orientation','ArcAngle'],arg:Any)→T[source]
- constrain(tag:str,constraint:Literal['Fixed','FixedPoint','Coincident','Angle','Length','Distance','Radius','Orientation','ArcAngle'],arg:Any)→T
Add a constraint.
- Parameters:
self (T)
tag (str)
constraint (Literal['Fixed','FixedPoint','Coincident','Angle','Length','Distance','Radius','Orientation','ArcAngle'])
arg (Any)
- Return type:
T
- distribute(n:int,start:int|float=0,stop:int|float=1,rotate:bool=True)→T[source]
Distribute locations along selected edges or wires.
- Parameters:
self (T)
n (int)
start (int |float)
stop (int |float)
rotate (bool)
- Return type:
T
- each(callback:Callable[[Location],Face|Sketch|Compound],mode:Literal['a','s','i','c','r']='a',tag:str|None=None,ignore_selection:bool=False)→T[source]
Apply a callback on all applicable entities.
- edge(val:Edge,tag:str|None=None,forConstruction:bool=False)→T[source]
Add an edge to the sketch.
- Parameters:
self (T)
val (Edge)
tag (str |None)
forConstruction (bool)
- Return type:
T
- edges(s:str|Selector|None=None,tag:str|None=None)→T[source]
Select edges.
- Parameters:
self (T)
s (str |Selector |None)
tag (str |None)
- Return type:
T
- ellipse(a1:int|float,a2:int|float,angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct an elliptical face.
- Parameters:
self (T)
a1 (int |float)
a2 (int |float)
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- export(fname:str,tolerance:float=0.1,angularTolerance:float=0.1,opt:Dict[str,Any]|None=None)→T[source]
Export Sketch to file.
- Parameters:
self (T)
path – Filename.
tolerance (float) – the deflection tolerance, in model units. Default 0.1.
angularTolerance (float) – the angular tolerance, in radians. Default 0.1.
opt (Dict[str,Any]|None) – additional options passed to the specific exporter. Default None.
fname (str)
- Returns:
Self.
- Return type:
T
- face(b:Wire|Iterable[Edge]|Shape|T,angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None,ignore_selection:bool=False)→T[source]
Construct a face from a wire or edges.
- faces(s:str|Selector|None=None,tag:str|None=None)→T[source]
Select faces.
- Parameters:
self (T)
s (str |Selector |None)
tag (str |None)
- Return type:
T
- fillet(d:int|float)→T[source]
Add a fillet based on current selection.
- Parameters:
self (T)
d (int |float)
- Return type:
T
- hull(mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Generate a convex hull from current selection or all objects.
- Parameters:
self (T)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- importDXF(filename:str,tol:float=1e-06,exclude:List[str]=[],include:List[str]=[],angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Import a DXF file and construct face(s)
- Parameters:
self (T)
filename (str)
tol (float)
exclude (List[str])
include (List[str])
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- invoke(f:Callable[[T],T]|Callable[[T],None]|Callable[[],None])[source]
Invoke a callable mapping Sketch to Sketch or None. Supports alsocallables that take no arguments such as breakpoint. Returns self if callablereturns None.
- Parameters:
self (T)
f (Callable[[T],T]|Callable[[T],None]|Callable[[],None]) – Callable to be invoked.
- Returns:
Sketch object.
- located(loc:Location)→T[source]
Create a partial copy of the sketch with a new location.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- moved(loc:Location)→T[source]
- moved(loc1:Location,loc2:Location,*locs:Location)→T
- moved(locs:Sequence[Location])→T
- moved(x:int|float=0,y:int|float=0,z:int|float=0,rx:int|float=0,ry:int|float=0,rz:int|float=0)→T
- moved(loc:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T
- moved(loc1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],loc2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],*locs:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T
- moved(loc:Sequence[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]])→T
Create a partial copy of the sketch with moved _faces.
- offset(d:int|float,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Offset selected wires or edges.
- Parameters:
self (T)
d (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- parray(r:int|float,a1:int|float,da:int|float,n:int,rotate:bool=True)→T[source]
Generate a polar array of locations.
- Parameters:
self (T)
r (int |float)
a1 (int |float)
da (int |float)
n (int)
rotate (bool)
- Return type:
T
- polygon(pts:Iterable[Vector|Tuple[int|float,int|float]],angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct a polygonal face.
- Parameters:
self (T)
pts (Iterable[Vector |Tuple[int |float,int |float]])
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- push(locs:Iterable[Location|Vector|Tuple[int|float,int|float]],tag:str|None=None)→T[source]
Set current selection to given locations or points.
- rarray(xs:int|float,ys:int|float,nx:int,ny:int)→T[source]
Generate a rectangular array of locations.
- Parameters:
self (T)
xs (int |float)
ys (int |float)
nx (int)
ny (int)
- Return type:
T
- rect(w:int|float,h:int|float,angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct a rectangular face.
- Parameters:
self (T)
w (int |float)
h (int |float)
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- regularPolygon(r:int|float,n:int,angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct a regular polygonal face.
- Parameters:
self (T)
r (int |float)
n (int)
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- replace()→T[source]
Replace the underlying faces with the selection.
- Parameters:
self (T)
- Return type:
T
- segment(p2:Vector|Tuple[int|float,int|float],tag:str|None=None,forConstruction:bool=False)→T[source]
- segment(p1:Vector|Tuple[int|float,int|float],p2:Vector|Tuple[int|float,int|float],tag:str|None=None,forConstruction:bool=False)→T
- segment(l:int|float,a:int|float,tag:str|None=None,forConstruction:bool=False)→T
Construct a segment.
- slot(w:int|float,h:int|float,angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct a slot-shaped face.
- Parameters:
self (T)
w (int |float)
h (int |float)
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- solve()→T[source]
Solve current constraints and update edge positions.
- Parameters:
self (T)
- Return type:
T
- spline(pts:Iterable[Vector|Tuple[int|float,int|float]],tangents:Iterable[Vector|Tuple[int|float,int|float]]|None,periodic:bool,tag:str|None=None,forConstruction:bool=False)→T[source]
- spline(pts:Iterable[Vector|Tuple[int|float,int|float]],tag:str|None=None,forConstruction:bool=False)→T
Construct a spline edge.
- trapezoid(w:int|float,h:int|float,a1:int|float,a2:float|None=None,angle:int|float=0,mode:Literal['a','s','i','c','r']='a',tag:str|None=None)→T[source]
Construct a trapezoidal face.
- Parameters:
self (T)
w (int |float)
h (int |float)
a1 (int |float)
a2 (float |None)
angle (int |float)
mode (Literal['a','s','i','c','r'])
tag (str |None)
- Return type:
T
- classcadquery.Solid(obj:TopoDS_Shape)[source]
a single solid
- Parameters:
obj (TopoDS_Shape)
- classmethodextrudeLinear(face:Face,vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],taper:float|int=0)→Solid[source]
- classmethodextrudeLinear(outerWire:Wire,innerWires:List[Wire],vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],taper:float|int=0)→Solid
Attempt to extrude the list of wires into a prismatic solid in the provided direction
- Parameters:
- Returns:
a Solid object
- Return type:
The wires must not intersect
Extruding wires is very non-trivial. Nested wires imply very different geometry, andthere are many geometries that are invalid. In general, the following conditions must be met:
all wires must be closed
there cannot be any intersecting or self-intersecting wires
wires must be listed from outside in
more than one levels of nesting is not supported reliably
This method will attempt to sort the wires, but there is much work remaining to make this methodreliable.
- classmethodextrudeLinearWithRotation(outerWire:Wire,innerWires:List[Wire],vecCenter:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angleDegrees:float|int)→Solid[source]
- classmethodextrudeLinearWithRotation(face:Face,vecCenter:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angleDegrees:float|int)→Solid
Creates a ‘twisted prism’ by extruding, while simultaneously rotating around the extrusion vector.
Though the signature may appear to be similar enough to extrudeLinear to merit combining them, theconstruction methods used here are different enough that they should be separate.
At a high level, the steps followed are:
accept a set of wires
create another set of wires like this one, but which are transformed and rotated
create a ruledSurface between the sets of wires
create a shell and compute the resulting object
- Parameters:
outerWire (Wire) – the outermost wire
innerWires (List[Wire]) – a list of inner wires
vecCenter (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – the center point about which to rotate. the axis of rotation is defined byvecNormal, located at vecCenter.
vecNormal (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – a vector along which to extrude the wires
angleDegrees (float |int) – the angle to rotate through while extruding
- Returns:
a Solid object
- Return type:
- classmethodinterpPlate(surf_edges,surf_pts,thickness,degree=3,nbPtsOnCur=15,nbIter=2,anisotropy=False,tol2d=1e-05,tol3d=0.0001,tolAng=0.01,tolCurv=0.1,maxDeg=8,maxSegments=9)→Solid|Face[source]
Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and going through ‘surf_pts’ points.
- Parameters:
surf_edges – list of [x,y,z] float ordered coordinatesor list of ordered or unordered wires
surf_pts – list of [x,y,z] float coordinates (uses only edges if [])
thickness – thickness may be negative or positive depending on direction, (returns 2D surface if 0)
degree – >=2
nbPtsOnCur – number of points on curve >= 15
nbIter – number of iterations >= 2
anisotropy – bool Anisotropy
tol2d – 2D tolerance >0
tol3d – 3D tolerance >0
tolAng – angular tolerance
tolCurv – tolerance for curvature >0
maxDeg – highest polynomial degree >= 2
maxSegments – greatest number of segments >= 2
- Return type:
- staticisSolid(obj:Shape)→bool[source]
Returns true if the object is a solid, false otherwise
- Parameters:
obj (Shape)
- Return type:
bool
- classmethodmakeBox(length,width,height,[pnt,dir])--Makeaboxlocatedinpntwiththedimensions(length,width,height)[source]
By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
- classmethodmakeCone(radius1:float,radius2:float,height:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees:float=360)→Solid[source]
Make a cone with given radii and heightBy default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360
- classmethodmakeCylinder(radius:float,height:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees:float=360)→Solid[source]
makeCylinder(radius,height,[pnt,dir,angle]) –Make a cylinder with a given radius and heightBy default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360
- classmethodmakeLoft(listOfWire:List[Wire],ruled:bool=False)→Solid[source]
makes a loft from a list of wiresThe wires will be converted into faces when possible– it is presumed that nobody ever actuallywants to make an infinitely thin shell for a real FreeCADPart.
- classmethodmakeSphere(radius:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees1:float=0,angleDegrees2:float=90,angleDegrees3:float=360)→Shape[source]
Make a sphere with a given radiusBy default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=0, angle2=90 and angle3=360
- classmethodmakeTorus(radius1:float,radius2:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees1:float=0,angleDegrees2:float=360)→Solid[source]
makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]) –Make a torus with a given radii and anglesBy default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0,angle1=360 and angle=360
- classmethodmakeWedge(dx:float,dy:float,dz:float,xmin:float,zmin:float,xmax:float,zmax:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0))→Solid[source]
Make a wedge located in pntBy default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
- classmethodrevolve(outerWire:Wire,innerWires:List[Wire],angleDegrees:float|int,axisStart:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],axisEnd:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Solid[source]
- classmethodrevolve(face:Face,angleDegrees:float|int,axisStart:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],axisEnd:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Solid
Attempt to revolve the list of wires into a solid in the provided direction
- Parameters:
outerWire (Wire) – the outermost wire
innerWires (List[Wire]) – a list of inner wires
angleDegrees (float,anything less than 360 degrees will leave the shape open) – the angle to revolve through.
axisStart (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – the start point of the axis of rotation
axisEnd (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – the end point of the axis of rotation
- Returns:
a Solid object
- Return type:
The wires must not intersect
all wires must be closed
there cannot be any intersecting or self-intersecting wires
wires must be listed from outside in
more than one levels of nesting is not supported reliably
the wire(s) that you’re revolving cannot be centered
This method will attempt to sort the wires, but there is much work remaining to make this methodreliable.
- classmethodsweep(outerWire:Wire,innerWires:List[Wire],path:Wire|Edge,makeSolid:bool=True,isFrenet:bool=False,mode:Vector|Wire|Edge|None=None,transitionMode:Literal['transformed','round','right']='transformed')→Shape[source]
- classmethodsweep(face:Face,path:Wire|Edge,makeSolid:bool=True,isFrenet:bool=False,mode:Vector|Wire|Edge|None=None,transitionMode:Literal['transformed','round','right']='transformed')→Shape
Attempt to sweep the list of wires into a prismatic solid along the provided path
- Parameters:
outerWire (Wire) – the outermost wire
innerWires (List[Wire]) – a list of inner wires
path (Wire |Edge) – The wire to sweep the face resulting from the wires over
makeSolid (bool) – return Solid or Shell (default True)
isFrenet (bool) – Frenet mode (default False)
mode (Vector |Wire |Edge |None) – additional sweep mode parameters
transitionMode (Literal['transformed','round','right']) – handling of profile orientation at C1 path discontinuities.Possible values are {‘transformed’,’round’, ‘right’} (default: ‘right’).
- Returns:
a Solid object
- Return type:
- classcadquery.StringSyntaxSelector(selectorString)[source]
Bases:
SelectorFilter lists objects using a simple string syntax. All of the filters available in the string syntaxare also available ( usually with more functionality ) through the creation of full-fledgedselector objects. see
Selectorand its subclassesFiltering works differently depending on the type of object list being filtered.
- Parameters:
selectorString – A two-part selector string, [selector][axis]
- Returns:
objects that match the specified selector
*Modifiers* are
('|','+','-','<','>','%')- |:
parallel to ( same as
ParallelDirSelector). Can return multiple objects.- #:
perpendicular to (same as
PerpendicularDirSelector)- +:
positive direction (same as
DirectionSelector)- -:
negative direction (same as
DirectionSelector)- >:
maximize (same as
DirectionMinMaxSelectorwith directionMax=True)- <:
minimize (same as
DirectionMinMaxSelectorwith directionMax=False )- %:
curve/surface type (same as
TypeSelector)
*axisStrings* are:
X,Y,Z,XY,YZ,XZor(x,y,z)which defines an arbitrary directionIt is possible to combine simple selectors together using logical operations.The following operations are supported
- and:
Logical AND, e.g. >X and >Y
- or:
Logical OR, e.g. |X or |Y
- not:
Logical NOT, e.g. not #XY
- exc(ept):
Set difference (equivalent to AND NOT): |X exc >Z
Finally, it is also possible to use even more complex expressions with nestingand arbitrary number of terms, e.g.
(not >X[0] and #XY) or >XY[0]
Selectors are a complex topic: seeSelectors Reference for more information
- classcadquery.TypeSelector(typeString:str)[source]
Bases:
SelectorSelects objects having the prescribed geometry type.
- Applicability:
Faces: PLANE, CYLINDER, CONE, SPHERE, TORUS, BEZIER, BSPLINE, REVOLUTION, EXTRUSION, OFFSET, OTHEREdges: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER, BSPLINE, OFFSET, OTHER
You can use the string selector syntax. For example this:
CQ(aCube).faces(TypeSelector("PLANE"))
will select 6 faces, and is equivalent to:
CQ(aCube).faces("%PLANE")
- Parameters:
typeString (str)
- classcadquery.Vector(x:float,y:float,z:float)[source]
- classcadquery.Vector(x:float,y:float)
- classcadquery.Vector(v:Vector)
- classcadquery.Vector(v:Sequence[float])
- classcadquery.Vector(v:gp_Vec|gp_Pnt|gp_Dir|gp_XYZ)
- classcadquery.Vector
Bases:
objectCreate a 3-dimensional vector
- Parameters:
args – a 3D vector, with x-y-z parts.
- you can either provide:
nothing (in which case the null vector is return)
a gp_Vec
a vector ( in which case it is copied )
a 3-tuple
a 2-tuple (z assumed to be 0)
three float values: x, y, and z
two float values: x,y
- Center()→Vector[source]
Return the vector itself
The center of myself is myself.Provided so that vectors, vertices, and other shapes all support acommon interface, when Center() is requested for all objects on thestack.
- Return type:
- __getstate__()→tuple[float,float,float][source]
Helper for pickle.
- Return type:
tuple[float, float, float]
- __hash__=None
- __init__(x:float,y:float,z:float)→None[source]
- __init__(x:float,y:float)→None
- __init__(v:Vector)→None
- __init__(v:Sequence[float])→None
- __init__(v:gp_Vec|gp_Pnt|gp_Dir|gp_XYZ)→None
- __init__()→None
- __weakref__
list of weak references to the object
- multiply(scale:float)→Vector[source]
Return a copy multiplied by the provided scalar
- Parameters:
scale (float)
- Return type:
- classcadquery.Vertex(obj:TopoDS_Shape,forConstruction:bool=False)[source]
Bases:
ShapeA Single Point in Space
- Parameters:
obj (TopoDS_Shape)
forConstruction (bool)
- classcadquery.Wire(obj:TopoDS_Shape)[source]
A series of connected, ordered Edges, that typically bounds a Face
- Parameters:
obj (TopoDS_Shape)
- classmethodassembleEdges(listOfEdges:Iterable[Edge])→Wire[source]
Attempts to build a wire that consists of the edges in the provided list
- Parameters:
cls
listOfEdges (Iterable[Edge]) – a list of Edge objects. The edges are not to be consecutive.
- Returns:
a wire with the edges assembled
- Return type:
BRepBuilderAPI_MakeWire::Error() values:
BRepBuilderAPI_WireDone = 0
BRepBuilderAPI_EmptyWire = 1
BRepBuilderAPI_DisconnectedWire = 2
BRepBuilderAPI_NonManifoldWire = 3
- classmethodcombine(listOfWires:Iterable[Wire|Edge],tol:float=1e-09)→List[Wire][source]
Attempt to combine a list of wires and edges into a new wire.
- fillet(radius:float,vertices:Iterable[Vertex]|None=None)→Wire[source]
Apply 2D or 3D fillet to a wire
- classmethodmakeCircle(radius:float,center:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],normal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Wire[source]
Makes a Circle centered at the provided point, having normal in the provided direction
- Parameters:
radius (float) – floating point radius of the circle, must be > 0
center (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the center of the circle
normal (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the direction of the plane the circle should lie in
- Return type:
- classmethodmakeEllipse(x_radius:float,y_radius:float,center:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],normal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],xDir:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angle1:float=360.0,angle2:float=360.0,rotation_angle:float=0.0,closed:bool=True)→Wire[source]
Makes an Ellipse centered at the provided point, having normal in the provided direction
- Parameters:
x_radius (float) – floating point major radius of the ellipse (x-axis), must be > 0
y_radius (float) – floating point minor radius of the ellipse (y-axis), must be > 0
center (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the center of the circle
normal (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the direction of the plane the circle should lie in
angle1 (float) – start angle of arc
angle2 (float) – end angle of arc
rotation_angle (float) – angle to rotate the created ellipse / arc
xDir (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
closed (bool)
- Return type:
- classmethodmakeHelix(pitch:float,height:float,radius:float,center:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angle:float=360.0,lefthand:bool=False)→Wire[source]
Make a helix with a given pitch, height and radiusBy default a cylindrical surface is used to create the helix. Ifthe fourth parameter is set (the apex given in degree) a conical surface is used instead’
- classmethodmakePolygon(listOfVertices:Iterable[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]],forConstruction:bool=False,close:bool=False)→Wire[source]
Construct a polygonal wire from points.
- classcadquery.Workplane(obj:Vector|Location|Shape|Sketch)[source]
- classcadquery.Workplane(inPlane:Plane|str='XY',origin:Tuple[float,float]|Tuple[float,float,float]|Vector=(0,0,0),obj:Vector|Location|Shape|Sketch|None=None)
Bases:
objectDefines a coordinate system in space, in which 2D coordinates can be used.
- Parameters:
plane (a Plane object, ora string in (XY|YZ|XZ|front|back|top|bottom|left|right)) – the plane in which the workplane will be done
origin (a 3-tuple in global coordinates, orNone to default to the origin) – the desired origin of the new workplane
obj (a CAD primitive, orNone to use the centerpoint ofthe plane as the initialstack value.) – an object to use initially for the stack
- Raises:
ValueError if the provided plane is not a plane, a valid named workplane
- Returns:
A Workplane object, with coordinate system matching the supplied plane.
The most common use is:
s=Workplane("XY")
After creation, the stack contains a single point, the origin of the underlying plane,and thecurrent point is on the origin.
Note
You can also create workplanes on the surface of existing faces using
workplane()- __add__(other:Workplane|Solid|Compound)→T[source]
Syntactic sugar for union.
Notice that
r=a+bis equivalent tor=a.union(b)andr=a|b.
- __and__(other:Workplane|Solid|Compound)→T[source]
Syntactic sugar for intersect.
Notice that
r=a&bis equivalent tor=a.intersect(b).Example:
Box=Workplane("XY").box(1,1,1,centered=(False,False,False))Sphere=Workplane("XY").sphere(1)result=Box&Sphere
- __init__(obj:Vector|Location|Shape|Sketch)→None[source]
- __init__(inPlane:Plane|str='XY',origin:Tuple[float,float]|Tuple[float,float,float]|Vector=(0,0,0),obj:Vector|Location|Shape|Sketch|None=None)→None
make a workplane from a particular plane
- Parameters:
inPlane (a Plane object, ora string in (XY|YZ|XZ|front|back|top|bottom|left|right)) – the plane in which the workplane will be done
origin (a 3-tuple in global coordinates, orNone to default to the origin) – the desired origin of the new workplane
obj (a CAD primitive, orNone to use the centerpoint ofthe plane as the initialstack value.) – an object to use initially for the stack
- Raises:
ValueError if the provided plane is not a plane, or one of XY|YZ|XZ
- Returns:
A Workplane object, with coordinate system matching the supplied plane.
The most common use is:
s=Workplane("XY")
After creation, the stack contains a single point, the origin of the underlying plane, andthecurrent point is on the origin.
- __iter__()→Iterator[Shape][source]
Special method for iterating over Shapes in objects
- Parameters:
self (T)
- Return type:
Iterator[Shape]
- __mul__(other:Workplane|Solid|Compound)→T[source]
Syntactic sugar for intersect.
Notice that
r=a*bis equivalent tor=a.intersect(b).Example:
Box=Workplane("XY").box(1,1,1,centered=(False,False,False))Sphere=Workplane("XY").sphere(1)result=Box*Sphere
- __or__(other:Workplane|Solid|Compound)→T[source]
Syntactic sugar for union.
Notice that
r=a|bis equivalent tor=a.union(b)andr=a+b.Example:
Box=Workplane("XY").box(1,1,1,centered=(False,False,False))Sphere=Workplane("XY").sphere(1)result=Box|Sphere
- __sub__(other:Workplane|Solid|Compound)→T[source]
Syntactic sugar for cut.
Notice that
r=a-bis equivalent tor=a.cut(b).Example:
Box=Workplane("XY").box(1,1,1,centered=(False,False,False))Sphere=Workplane("XY").sphere(1)result=Box-Sphere
- __truediv__(other:Workplane|Solid|Compound)→T[source]
Syntactic sugar for intersect.
Notice that
r=a/bis equivalent tor=a.split(b).Example:
Box=Workplane("XY").box(1,1,1,centered=(False,False,False))Sphere=Workplane("XY").sphere(1)result=Box/Sphere
- __weakref__
list of weak references to the object
- add(obj:Workplane)→T[source]
- add(obj:Vector|Location|Shape|Sketch)→T
- add(obj:Iterable[Vector|Location|Shape|Sketch])→T
Adds an object or a list of objects to the stack
- Parameters:
obj (a Workplane,CAD primitive, orlist ofCAD primitives) – an object to add
- Returns:
a Workplane with the requested operation performed
If a Workplane object, the values of that object’s stack are added. Ifa list of cad primitives, they are all added. If a single CAD primitivethen it is added.
Used in rare cases when you need to combine the results of several CQresults into a single Workplane object.
- all()→List[T][source]
Return a list of all CQ objects on the stack.
useful when you need to operate on the elementsindividually.
Contrast with vals, which returns the underlyingobjects for all of the items on the stack
- Parameters:
self (T)
- Return type:
List[T]
- ancestors(kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'],tag:str|None=None)→T[source]
Select topological ancestors.
- Parameters:
self (T)
kind (Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound']) – kind of ancestor, e.g. “Face” or “Edge”
tag (str |None) – if set, search the tagged object instead of self
- Returns:
a Workplane object whose stack contains selected ancestors.
- Return type:
T
- apply(f:Callable[[Iterable[Vector|Location|Shape|Sketch]],Iterable[Vector|Location|Shape|Sketch]])→T[source]
Apply a callable to all items at once.
- bezier(listOfXYTuple:Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector],forConstruction:bool=False,includeCurrent:bool=False,makeWire:bool=False)→T[source]
Make a cubic Bézier curve by the provided points (2D or 3D).
- Parameters:
self (T)
listOfXYTuple (Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector]) – Bezier control points and end point.All points except the last point are Bezier control points,and the last point is the end point
includeCurrent (bool) – Use the current point as a starting point of the curve
makeWire (bool) – convert the resulting bezier edge to a wire
forConstruction (bool)
- Returns:
a Workplane object with the current point at the end of the bezier
- Return type:
T
The Bézier Will begin at either current point or the first pointof listOfXYTuple, and end with the last point of listOfXYTuple
- box(length:float,width:float,height:float,centered:bool|Tuple[bool,bool,bool]=True,combine:bool|Literal['cut','a','s']=True,clean:bool=True)→T[source]
Return a 3d box with specified dimensions for each object on the stack.
- Parameters:
self (T)
length (float) – box size in X direction
width (float) – box size in Y direction
height (float) – box size in Z direction
centered (bool |Tuple[bool,bool,bool]) – If True, the box will be centered around the reference point.If False, the corner of the box will be on the reference point and it willextend in the positive x, y and z directions. Can also use a 3-tuple tospecify centering along each axis.
combine (bool |Literal['cut','a','s']) – should the results be combined with other solids on the stack(and each other)?
clean (bool) – call
clean()afterwards to have a clean shape
- Return type:
T
One box is created for each item on the current stack. If no items are on the stack, one boxusing the current workplane center is created.
If combine is true, the result will be a single object on the stack. If a solid was foundin the chain, the result is that solid with all boxes produced fused onto it otherwise, theresult is the combination of all the produced boxes.
If combine is false, the result will be a list of the boxes produced.
Most often boxes form the basis for a part:
# make a single box with lower left corner at origins=Workplane().box(1,2,3,centered=False)
But sometimes it is useful to create an array of them:
# create 4 small square bumps on a larger base plate:s=(Workplane().box(4,4,0.5).faces(">Z").workplane().rect(3,3,forConstruction=True).vertices().box(0.25,0.25,0.25,combine=True))
- cboreHole(diameter:float,cboreDiameter:float,cboreDepth:float,depth:float|None=None,clean:bool=True)→T[source]
Makes a counterbored hole for each item on the stack.
- Parameters:
self (T)
diameter (float) – the diameter of the hole
cboreDiameter (float) – the diameter of the cbore, must be greater than hole diameter
cboreDepth (float > 0) – depth of the counterbore
depth (float > 0 orNone to drill thru the entire part) – the depth of the hole
clean (bool) – call
clean()afterwards to have a clean shape
- Return type:
T
The surface of the hole is at the current workplane plane.
One hole is created for each item on the stack. A very common use case is to use aconstruction rectangle to define the centers of a set of holes, like so:
s=(Workplane().box(2,4,0.5).faces(">Z").workplane().rect(1.5,3.5,forConstruction=True).vertices().cboreHole(0.125,0.25,0.125,depth=None))
This sample creates a plate with a set of holes at the corners.
Plugin Note: this is one example of the power of plugins. Counterbored holes are quitetime consuming to create, but are quite easily defined by users.
see
cskHole()to make countersinks instead of counterbores
- center(x:float,y:float)→T[source]
Shift local coordinates to the specified location.
The location is specified in terms of local coordinates.
- Parameters:
self (T)
x (float) – the new x location
y (float) – the new y location
- Returns:
the Workplane object, with the center adjusted.
- Return type:
T
The current point is set to the new center.This method is useful to adjust the center point after it has been created automatically ona face, but not where you’d like it to be.
In this example, we adjust the workplane center to be at the corner of a cube, instead ofthe center of a face, which is the default:
# this workplane is centered at x=0.5,y=0.5, the center of the upper faces=Workplane().box(1,1,1).faces(">Z").workplane()s=s.center(-0.5,-0.5)# move the center to the cornert=s.circle(0.25).extrude(0.2)assertt.faces().size()==9# a cube with a cylindrical nub at the top right corner
The result is a cube with a round boss on the corner
- chamfer(length:float,length2:float|None=None)→T[source]
Chamfers a solid on the selected edges.
The edges on the stack are chamfered. The solid to which theedges belong must be in the parent chain of the selectededges.
Optional parameterlength2 can be supplied with a differentvalue thanlength for a chamfer that is shorter on one sidelonger on the other side.
- Parameters:
self (T)
length (float) – the length of the chamfer, must be greater than zero
length2 (float |None) – optional parameter for asymmetrical chamfer
- Raises:
ValueError – if at least one edge is not selected
ValueError – if the solid containing the edge is not in the chain
- Returns:
CQ object with the resulting solid selected.
- Return type:
T
This example will create a unit cube, with the top edges chamfered:
s=Workplane("XY").box(1,1,1).faces("+Z").chamfer(0.1)
This example will create chamfers longer on the sides:
s=Workplane("XY").box(1,1,1).faces("+Z").chamfer(0.2,0.1)
- circle(radius:float,forConstruction:bool=False)→T[source]
Make a circle for each item on the stack.
- Parameters:
self (T)
radius (float) – radius of the circle
forConstruction (true if the wires are for reference,false if they are creatingpart geometry) – should the new wires be reference geometry only?
- Returns:
a new CQ object with the created wires on the stack
- Return type:
T
A common use case is to use a for-construction rectangle to define the centers of ahole pattern:
s=Workplane().rect(4.0,4.0,forConstruction=True).vertices().circle(0.25)
Creates 4 circles at the corners of a square centered on the origin. Another common case isto use successive circle() calls to create concentric circles. This works because thecenter of a circle is its reference point:
s=Workplane().circle(2.0).circle(1.0)
Creates two concentric circles, which when extruded will form a ring.
- Future Enhancements:
better way to handle forConstructionproject points not in the workplane plane onto the workplane plane
- clean()→T[source]
Cleans the current solid by removing unwanted edges from thefaces.
Normally you don’t have to call this function. It isautomatically called after each related operation. You candisable this behavior withclean=False parameter if methodhas any. In some cases this can improve performancedrastically but is generally dis-advised since it may breaksome operations such as fillet.
Note that in some cases where lots of solid operations arechained,clean() may actually improve performance sincethe shape is ‘simplified’ at each step and thus next operationis easier.
Also note that, due to limitation of the underlying engine,clean may fail to produce a clean output in some cases such asspherical faces.
- Parameters:
self (T)
- Return type:
T
- close()→T[source]
End construction, and attempt to build a closed wire.
- Returns:
a CQ object with a completed wire on the stack, if possible.
- Parameters:
self (T)
- Return type:
T
After 2D (or 3D) drafting with methods such as lineTo, threePointArc,tangentArcPoint and polyline, it is necessary to convert the edgesproduced by these into one or more wires.
When a set of edges is closed, CadQuery assumes it is safe to buildthe group of edges into a wire. This example builds a simple triangularprism:
s=Workplane().lineTo(1,0).lineTo(1,1).close().extrude(0.2)
- combine(clean:bool=True,glue:bool=False,tol:float|None=None)→T[source]
Attempts to combine all of the items on the stack into a single item.
WARNING: all of the items must be of the same type!
- Parameters:
self (T)
clean (bool) – call
clean()afterwards to have a clean shapeglue (bool) – use a faster gluing mode for non-overlapping shapes (default False)
tol (float |None) – tolerance value for fuzzy bool operation mode (default None)
- Raises:
ValueError if there are no items on the stack, or if they cannot be combined
- Returns:
a CQ object with the resulting object selected
- Return type:
T
- combineSolids(otherCQToCombine:Workplane|None=None)→Workplane[source]
!!!DEPRECATED!!! use union()Combines all solids on the current stack, and any context object, togetherinto a single object.
After the operation, the returned solid is also the context solid.
- Parameters:
otherCQToCombine (Workplane |None) – another CadQuery to combine.
- Returns:
a CQ object with the resulting combined solid on the stack.
- Return type:
Most of the time, both objects will contain a single solid, which iscombined and returned on the stack of the new object.
- compounds(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select compounds on the stack, optionally filtering the selection. If there are multipleobjects on the stack, they are collected and a list of all the distinct compoundsis returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains all of thedistinct compounds ofall objects onthe current stack, filtered by the provided selector.
- Return type:
T
A compound contains multiple CAD primitives that resulted from a single operation, such asa union, cut, split, or fillet. Compounds can contain multiple edges, wires, or solids.
- consolidateWires()→T[source]
Attempt to consolidate wires on the stack into a single.If possible, a new object with the results are returned.if not possible, the wires remain separated
- Parameters:
self (T)
- Return type:
T
- copyWorkplane(obj:T)→T[source]
Copies the workplane from obj.
- Parameters:
obj (a CQ object) – an object to copy the workplane from
- Returns:
a CQ object with obj’s workplane
- Return type:
T
- cskHole(diameter:float,cskDiameter:float,cskAngle:float,depth:float|None=None,clean:bool=True)→T[source]
Makes a countersunk hole for each item on the stack.
- Parameters:
self (T)
diameter (float > 0) – the diameter of the hole
cskDiameter (float) – the diameter of the countersink, must be greater than hole diameter
cskAngle (float > 0) – angle of the countersink, in degrees ( 82 is common )
depth (float > 0 orNone to drill thru the entire part.) – the depth of the hole
clean (bool) – call
clean()afterwards to have a clean shape
- Return type:
T
The surface of the hole is at the current workplane.
One hole is created for each item on the stack. A very common use case is to use aconstruction rectangle to define the centers of a set of holes, like so:
s=(Workplane().box(2,4,0.5).faces(">Z").workplane().rect(1.5,3.5,forConstruction=True).vertices().cskHole(0.125,0.25,82,depth=None))
This sample creates a plate with a set of holes at the corners.
Plugin Note: this is one example of the power of plugins. CounterSunk holes are quitetime consuming to create, but are quite easily defined by users.
see
cboreHole()to make counterbores instead of countersinks
- cut(toCut:Workplane|Solid|Compound,clean:bool=True,tol:float|None=None)→T[source]
Cuts the provided solid from the current solid, IE, perform a solid subtraction.
- Parameters:
- Raises:
ValueError – if there is no solid to subtract from in the chain
- Returns:
a Workplane object with the resulting object selected
- Return type:
T
- cutBlind(until:float|Literal['next','last']|Face,clean:bool=True,both:bool=False,taper:float|None=None)→T[source]
Use all un-extruded wires in the parent chain to create a prismatic cut from existing solid.
Specify either a distance value, or one of “next”, “last” to indicate a face to cut to.
Similar to extrude, except that a solid in the parent chain is required to remove materialfrom. cutBlind always removes material from a part.
- Parameters:
self (T)
until (float |Literal['next','last']|~cadquery.occ_impl.shapes.Face) – The distance to cut to, normal to the workplane plane. When a negative floatis passed the cut extends this far in the opposite direction to the normal of the plane(i.e in the solid). The string “next” cuts until the next face orthogonal to the wirenormal. “last” cuts to the last face. If an object of type Face is passed, then the cutwill extend until this face.
clean (bool) – call
clean()afterwards to have a clean shapeboth (bool) – cut in both directions symmetrically
taper (float |None) – angle for optional tapered extrusion
- Raises:
ValueError – if there is no solid to subtract from in the chain
- Returns:
a CQ object with the resulting object selected
- Return type:
T
see
cutThruAll()to cut material from the entire part
- cutEach(fcn:Callable[[Location],Shape],useLocalCoords:bool=False,clean:bool=True)→T[source]
Evaluates the provided function at each point on the stack (ie, eachpoint)and then cuts the result from the context solid.
- Parameters:
self (T)
fcn (Callable[[Location],Shape]) – a function suitable for use in the eachpoint method: ie, that accepts a vector
useLocalCoords (bool) – same as for
eachpoint()clean (bool) – call
clean()afterwards to have a clean shape
- Raises:
ValueError – if no solids or compounds are found in the stack or parent chain
- Returns:
a CQ object that contains the resulting solid
- Return type:
T
- cutThruAll(clean:bool=True,taper:float=0)→T[source]
Use all un-extruded wires in the parent chain to create a prismatic cut from existing solid.Cuts through all material in both normal directions of workplane.
Similar to extrude, except that a solid in the parent chain is required to remove materialfrom. cutThruAll always removes material from a part.
- Parameters:
self (T)
clean (bool) – call
clean()afterwards to have a clean shapetaper (float)
- Raises:
ValueError – if there is no solid to subtract from in the chain
ValueError – if there are no pending wires to cut with
- Returns:
a CQ object with the resulting object selected
- Return type:
T
see
cutBlind()to cut material to a limited depth
- cylinder(height:float,radius:float,direct:~typing.Tuple[float,float,float]|~cadquery.occ_impl.geom.Vector=Vector:(0.0,0.0,1.0),angle:float=360,centered:bool|~typing.Tuple[bool,bool,bool]=True,combine:bool|~typing.Literal['cut','a','s']=True,clean:bool=True)→T[source]
Returns a cylinder with the specified radius and height for each point on the stack
- Parameters:
self (T)
height (float) – The height of the cylinder
radius (float) – The radius of the cylinder
direct (A three-tuple) – The direction axis for the creation of the cylinder
angle (float > 0) – The angle to sweep the cylinder arc through
centered (bool |Tuple[bool,bool,bool]) – If True, the cylinder will be centered around the reference point. If False,the corner of a bounding box around the cylinder will be on the reference point and itwill extend in the positive x, y and z directions. Can also use a 3-tuple to specifycentering along each axis.
combine (true to combine shapes,false otherwise) – Whether the results should be combined with other solids on the stack(and each other)
clean (bool) – call
clean()afterwards to have a clean shape
- Returns:
A cylinder object for each point on the stack
- Return type:
T
One cylinder is created for each item on the current stack. If no items are on the stack, onecylinder is created using the current workplane center.
If combine is true, the result will be a single object on the stack. If a solid was foundin the chain, the result is that solid with all cylinders produced fused onto it otherwise,the result is the combination of all the produced cylinders.
If combine is false, the result will be a list of the cylinders produced.
- each(callback:Callable[[Vector|Location|Shape|Sketch],Shape],useLocalCoordinates:bool=False,combine:bool|Literal['cut','a','s']=True,clean:bool=True)→T[source]
Runs the provided function on each value in the stack, and collects the return values intoa new CQ object.
Special note: a newly created workplane always has its center point as its only stack item
- Parameters:
self (T)
callBackFunction – the function to call for each item on the current stack.
useLocalCoordinates (bool) – should values be converted from local coordinates first?
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shapecallback (Callable[[Vector |Location |Shape |Sketch],Shape])
- Return type:
T
The callback function must accept one argument, which is the item on the stack, and returnone object, which is collected. If the function returns None, nothing is added to the stack.The object passed into the callBackFunction is potentially transformed to local coordinates,if useLocalCoordinates is true
useLocalCoordinates is very useful for plugin developers.
If false, the callback function is assumed to be working in global coordinates. Objectscreated are added as-is, and objects passed into the function are sent in using globalcoordinates
If true, the calling function is assumed to be working in local coordinates. Objects aretransformed to local coordinates before they are passed into the callback method, and resultobjects are transformed to global coordinates after they are returned.
This allows plugin developers to create objects in local coordinates, without worryingabout the fact that the working plane is different than the global coordinate system.
TODO: wrapper object for Wire will clean up forConstruction flag everywhere
- eachpoint(arg:Shape|Workplane|Callable[[Location],Shape],useLocalCoordinates:bool=False,combine:bool|Literal['cut','a','s']=False,clean:bool=True)→T[source]
Same as each(), except arg is translated by the positions on the stack. If arg is a callback function, then the function is called for each point on the stack, and the resulting shape is used.:return: CadQuery object which contains a list of vectors (points ) on its stack.
- Parameters:
self (T)
useLocalCoordinates (bool) – should points be in local or global coordinates
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shape
- Return type:
T
The resulting object has a point on the stack for each object on the original stack.Vertices and points remain a point. Faces, Wires, Solids, Edges, and Shells are convertedto a point by using their center of mass.
If the stack has zero length, a single point is returned, which is the center of the currentworkplane/coordinate system
- edges(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select the edges of objects on the stack, optionally filtering the selection. If there aremultiple objects on the stack, the edges of all objects are collected and a list of all thedistinct edges is returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains all of thedistinct edges ofall objects onthe current stack, filtered by the provided selector.
- Return type:
T
If there are no edges for any objects on the current stack, an empty CQ object is returned
The typical use is to select the edges of a single object on the stack. For example:
Workplane().box(1,1,1).faces("+Z").edges().size()
returns 4, because the topmost face of a cube will contain four edges. Similarly:
Workplane().box(1,1,1).edges().size()
returns 12, because a cube has a total of 12 edges, And:
Workplane().box(1,1,1).edges("|Z").size()
returns 4, because a cube has 4 edges parallel to the z direction
- ellipse(x_radius:float,y_radius:float,rotation_angle:float=0.0,forConstruction:bool=False)→T[source]
Make an ellipse for each item on the stack.
- Parameters:
self (T)
x_radius (float) – x radius of the ellipse (x-axis of plane the ellipse should lie in)
y_radius (float) – y radius of the ellipse (y-axis of plane the ellipse should lie in)
rotation_angle (float) – angle to rotate the ellipse
forConstruction (true if the wires are for reference,false if they are creatingpart geometry) – should the new wires be reference geometry only?
- Returns:
a new CQ object with the created wires on the stack
- Return type:
T
NOTE Due to a bug in opencascade (https://tracker.dev.opencascade.org/view.php?id=31290)the center of mass (equals center for next shape) is shifted. To create concentric ellipsesuse:
Workplane("XY").center(10,20).ellipse(100,10).center(0,0).ellipse(50,5)
- ellipseArc(x_radius:float,y_radius:float,angle1:float=360,angle2:float=360,rotation_angle:float=0.0,sense:Literal[-1,1]=1,forConstruction:bool=False,startAtCurrent:bool=True,makeWire:bool=False)→T[source]
Draw an elliptical arc with x and y radiuses either with start point at current point oror current point being the center of the arc
- Parameters:
self (T)
x_radius (float) – x radius of the ellipse (along the x-axis of plane the ellipse should lie in)
y_radius (float) – y radius of the ellipse (along the y-axis of plane the ellipse should lie in)
angle1 (float) – start angle of arc
angle2 (float) – end angle of arc (angle2 == angle1 return closed ellipse = default)
rotation_angle (float) – angle to rotate the created ellipse / arc
sense (Literal[-1,1]) – clockwise (-1) or counter clockwise (1)
startAtCurrent (bool) – True: start point of arc is moved to current point; False: center ofarc is on current point
makeWire (bool) – convert the resulting arc edge to a wire
forConstruction (bool)
- Return type:
T
- end(n:int=1)→Workplane[source]
Return the nth parent of this CQ element
- Parameters:
n (int) – number of ancestor to return (default: 1)
- Return type:
a CQ object
- Raises:
ValueError if there are no more parents in the chain.
For example:
CQ(obj).faces("+Z").vertices().end()
will return the same as:
CQ(obj).faces("+Z")
- export(fname:str,tolerance:float=0.1,angularTolerance:float=0.1,opt:Dict[str,Any]|None=None)→T[source]
Export Workplane to file.
- Parameters:
self (T)
path – Filename.
tolerance (float) – the deflection tolerance, in model units. Default 0.1.
angularTolerance (float) – the angular tolerance, in radians. Default 0.1.
opt (Dict[str,Any]|None) – additional options passed to the specific exporter. Default None.
fname (str)
- Returns:
Self.
- Return type:
T
- exportSvg(fileName:str)→None[source]
Exports the first item on the stack as an SVG file
For testing purposes mainly.
- Parameters:
fileName (str) – the filename to export, absolute path to the file
- Return type:
None
- extrude(until:float|Literal['next','last']|Face,combine:bool|Literal['cut','a','s']=True,clean:bool=True,both:bool=False,taper:float|None=None)→T[source]
Use all un-extruded wires in the parent chain to create a prismatic solid.
- Parameters:
self (T)
until (float |Literal['next','last']|~cadquery.occ_impl.shapes.Face) – The distance to extrude, normal to the workplane plane. When a float ispassed, the extrusion extends this far and a negative value is in the opposite directionto the normal of the plane. The string “next” extrudes until the next face orthogonal tothe wire normal. “last” extrudes to the last face. If a object of type Face is passed thenthe extrusion will extend until this face.Note that the Workplane must contain a Solid for extruding to a given face.
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shapeboth (bool) – extrude in both directions symmetrically
taper (float |None) – angle for optional tapered extrusion
- Returns:
a CQ object with the resulting solid selected.
- Return type:
T
The returned object is always a CQ object, and depends on whether combine is True, andwhether a context solid is already defined:
- if combine is False, the new value is pushed onto the stack. Note that when extruding
until a specified face, combine can not be False
- if combine is true, the value is combined with the context solid if it exists,
and the resulting solid becomes the new context solid.
- faces(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select the faces of objects on the stack, optionally filtering the selection. If there aremultiple objects on the stack, the faces of all objects are collected and a list of all thedistinct faces is returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains all of thedistinct faces ofall objects onthe current stack, filtered by the provided selector.
- Return type:
T
If there are no faces for any objects on the current stack, an empty CQ objectis returned.
The typical use is to select the faces of a single object on the stack. For example:
Workplane().box(1,1,1).faces("+Z").size()
returns 1, because a cube has one face with a normal in the +Z direction. Similarly:
Workplane().box(1,1,1).faces().size()
returns 6, because a cube has a total of 6 faces, And:
Workplane().box(1,1,1).faces("|Z").size()
returns 2, because a cube has 2 faces having normals parallel to the z direction
- fillet(radius:float)→T[source]
Fillets a solid on the selected edges.
The edges on the stack are filleted. The solid to which the edges belong must be in theparent chain of the selected edges.
- Parameters:
self (T)
radius (float) – the radius of the fillet, must be > zero
- Raises:
ValueError – if at least one edge is not selected
ValueError – if the solid containing the edge is not in the chain
- Returns:
CQ object with the resulting solid selected.
- Return type:
T
This example will create a unit cube, with the top edges filleted:
s=Workplane().box(1,1,1).faces("+Z").edges().fillet(0.1)
- filter(f:Callable[[Vector|Location|Shape|Sketch],bool])→T[source]
Filter items using a boolean predicate.
- findFace(searchStack:bool=True,searchParents:bool=True)→Face[source]
Finds the first face object in the chain, searching from the current nodebackwards through parents until one is found.
- Parameters:
searchStack (bool) – should objects on the stack be searched first.
searchParents (bool) – should parents be searched?
- Returns:
A face or None if no face is found.
- Return type:
- findSolid(searchStack:bool=True,searchParents:bool=True)→Solid|Compound[source]
Finds the first solid object in the chain, searching from the current nodebackwards through parents until one is found.
- Parameters:
searchStack (bool) – should objects on the stack be searched first?
searchParents (bool) – should parents be searched?
- Raises:
ValueError – if no solid is found
- Return type:
This function is very important for chains that are modifying a single parent object,most often a solid.
Most of the time, a chain defines or selects a solid, and then modifies it using workplanesor other operations.
Plugin Developers should make use of this method to find the solid that should be modified,if the plugin implements a unary operation, or if the operation will automatically merge itsresults with an object already on the stack.
- first()→T[source]
Return the first item on the stack
- Returns:
the first item on the stack.
- Return type:
a CQ object
- Parameters:
self (T)
- hLine(distance:float,forConstruction:bool=False)→T[source]
Make a horizontal line from the current point the provided distance
- Parameters:
self (T)
distance (float) –
distance from current point
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
- hLineTo(xCoord:float,forConstruction:bool=False)→T[source]
Make a horizontal line from the current point to the provided x coordinate.
Useful if it is more convenient to specify the end location rather than distance,as in
hLine()- Parameters:
self (T)
xCoord (float) – x coordinate for the end of the line
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
- hole(diameter:float,depth:float|None=None,clean:bool=True)→T[source]
Makes a hole for each item on the stack.
- Parameters:
self (T)
diameter (float) – the diameter of the hole
depth (float > 0 orNone to drill thru the entire part.) – the depth of the hole
clean (bool) – call
clean()afterwards to have a clean shape
- Return type:
T
The surface of the hole is at the current workplane.
One hole is created for each item on the stack. A very common use case is to use aconstruction rectangle to define the centers of a set of holes, like so:
s=(Workplane().box(2,4,0.5).faces(">Z").workplane().rect(1.5,3.5,forConstruction=True).vertices().hole(0.125,82))
This sample creates a plate with a set of holes at the corners.
Plugin Note: this is one example of the power of plugins. CounterSunk holes are quitetime consuming to create, but are quite easily defined by users.
see
cboreHole()andcskHole()to make counterbores or countersinks
- interpPlate(surf_edges:Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]|Sequence[Edge|Wire]|Workplane,surf_pts:Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]=[],thickness:float=0,combine:bool|Literal['cut','a','s']=False,clean:bool=True,degree:int=3,nbPtsOnCur:int=15,nbIter:int=2,anisotropy:bool=False,tol2d:float=1e-05,tol3d:float=0.0001,tolAng:float=0.01,tolCurv:float=0.1,maxDeg:int=8,maxSegments:int=9)→T[source]
Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and goingthrough ‘surf_pts’ points. Using pushPoints directly with interpPlate and combine=True, can bevery resource intensive depending on the complexity of the shape. In this case set combine=False.
- Parameters:
self (T)
surf_edges (Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]|Sequence[Edge |Wire]|Workplane) – list of [x,y,z] ordered coordinates or list of ordered or unordered edges, wires
surf_pts (Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]) – list of points (uses only edges if [])
thickness (float) – value may be negative or positive depending on thickening direction (2D surface if 0)
combine (bool |Literal['cut','a','s']) – should the results be combined with other solids on the stack (and each other)?
clean (bool) – call
clean()afterwards to have a clean shapedegree (int) – >= 2
nbPtsOnCur (int) – number of points on curve >= 15
nbIter (int) – number of iterations >= 2
anisotropy (bool) – = bool Anisotropy
tol2d (float) – 2D tolerance
tol3d (float) – 3D tolerance
tolAng (float) – angular tolerance
tolCurv (float) – tolerance for curvature
maxDeg (int) – highest polynomial degree >= 2
maxSegments (int) – greatest number of segments >= 2
- Return type:
T
- intersect(toIntersect:Workplane|Solid|Compound,clean:bool=True,tol:float|None=None)→T[source]
Intersects the provided solid from the current solid.
- Parameters:
- Raises:
ValueError – if there is no solid to intersect with in the chain
- Returns:
a Workplane object with the resulting object selected
- Return type:
T
- invoke(f:Callable[[T],T]|Callable[[T],None]|Callable[[],None])→T[source]
Invoke a callable mapping Workplane to Workplane or None. Supports alsocallables that take no arguments such as breakpoint. Returns self if callablereturns None.
- Parameters:
self (T)
f (Callable[[T],T]|Callable[[T],None]|Callable[[],None]) – Callable to be invoked.
- Returns:
Workplane object.
- Return type:
T
- item(i:int)→T[source]
Return the ith item on the stack.
- Return type:
a CQ object
- Parameters:
self (T)
i (int)
- largestDimension()→float[source]
Finds the largest dimension in the stack.
Used internally to create thru features, this is how you can computehow long or wide a feature must be to make sure to cut through all of the material
- Raises:
ValueError – if no solids or compounds are found
- Returns:
A value representing the largest dimension of the first solid on the stack
- Return type:
float
- line(xDist:float,yDist:float,forConstruction:bool=False)→T[source]
Make a line from the current point to the provided point, usingdimensions relative to the current point
- Parameters:
self (T)
xDist (float) – x distance from current point
yDist (float) – y distance from current point
forConstruction (bool)
- Returns:
the workplane object with the current point at the end of the new line
- Return type:
T
see
lineTo()if you want to use absolute coordinates to make a line instead.
- lineTo(x:float,y:float,forConstruction:bool=False)→T[source]
Make a line from the current point to the provided point
- Parameters:
self (T)
x (float) – the x point, in workplane plane coordinates
y (float) – the y point, in workplane plane coordinates
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
See
line()if you want to use relative dimensions to make a line instead.
- loft(ruled:bool=False,combine:bool|Literal['cut','a','s']=True,clean:bool=True)→T[source]
Make a lofted solid, through the set of wires.
- Parameters:
self (T)
ruled (bool) – When set toTrue connects each section linearly and without continuity
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shape
- Returns:
a Workplane object containing the created loft
- Return type:
T
- map(f:Callable[[Vector|Location|Shape|Sketch],Vector|Location|Shape|Sketch])→T[source]
Apply a callable to every item separately.
- mirror(mirrorPlane:Literal['XY','YX','XZ','ZX','YZ','ZY']|Tuple[float,float]|Tuple[float,float,float]|Vector|Face|Workplane='XY',basePointVector:Tuple[float,float]|Tuple[float,float,float]|Vector|None=None,union:bool=False)→T[source]
Mirror a single CQ object.
- Parameters:
self (T)
mirrorPlane (string,one of"XY","YX","XZ","ZX","YZ","ZY" the planesorthe normal vector ofthe plane eg (1,0,0) ora Face object) – the plane to mirror about
basePointVector (Tuple[float,float]|Tuple[float,float,float]|Vector |None) – the base point to mirror about (this is overwritten if a Face is passed)
union (bool) – If true will perform a union operation on the mirrored object
- Return type:
T
- mirrorX()→T[source]
Mirror entities around the x axis of the workplane plane.
- Returns:
a new object with any free edges consolidated into as few wires as possible.
- Parameters:
self (T)
- Return type:
T
All free edges are collected into a wire, and then the wire is mirrored,and finally joined into a new wire
Typically used to make creating wires with symmetry easier.
- mirrorY()→T[source]
Mirror entities around the y axis of the workplane plane.
- Returns:
a new object with any free edges consolidated into as few wires as possible.
- Parameters:
self (T)
- Return type:
T
All free edges are collected into a wire, and then the wire is mirrored,and finally joined into a new wire
Typically used to make creating wires with symmetry easier. This line of code:
s=Workplane().lineTo(2,2).threePointArc((3,1),(2,0)).mirrorX().extrude(0.25)
Produces a flat, heart shaped object
- move(xDist:float=0,yDist:float=0)→T[source]
Move the specified distance from the current point, without drawing.
- Parameters:
self (T)
xDist (float, ornone for zero) – desired x distance, in local coordinates
yDist (float, ornone for zero.) – desired y distance, in local coordinates
- Return type:
T
Not to be confused with
center(), which moves the center of the entireworkplane, this method only moves the current point ( and therefore does not affect objectsalready drawn ).See
moveTo()to do the same thing but using absolute coordinates
- moveTo(x:float=0,y:float=0)→T[source]
Move to the specified point, without drawing.
- Parameters:
self (T)
x (float, ornone for zero) – desired x location, in local coordinates
y (float, ornone for zero.) – desired y location, in local coordinates
- Return type:
T
Not to be confused with
center(), which moves the center of the entireworkplane, this method only moves the current point ( and therefore does not affect objectsalready drawn ).See
move()to do the same thing but using relative dimensions
- newObject(objlist:Iterable[Vector|Location|Shape|Sketch])→T[source]
Create a new workplane object from this one.
Overrides CQ.newObject, and should be used by extensions, plugins, andsubclasses to create new objects.
- Parameters:
self (T)
objlist (a list ofCAD primitives) – new objects to put on the stack
- Returns:
a new Workplane object with the current workplane as a parent.
- Return type:
T
- offset2D(d:float,kind:Literal['arc','intersection','tangent']='arc',forConstruction:bool=False)→T[source]
Creates a 2D offset wire.
- Parameters:
self (T)
d (float) – thickness. Negative thickness denotes offset to inside.
kind (Literal['arc','intersection','tangent']) – offset kind. Use “arc” for rounded and “intersection” for sharp edges (default: “arc”)
forConstruction (bool) – Should the result be added to pending wires?
- Returns:
CQ object with resulting wire(s).
- Return type:
T
- parametricCurve(func:Callable[[float],Tuple[float,float]|Tuple[float,float,float]|Vector],N:int=400,start:float=0,stop:float=1,tol:float=1e-06,minDeg:int=1,maxDeg:int=6,smoothing:Tuple[float,float,float]|None=(1,1,1),makeWire:bool=True)→T[source]
Create a spline curve approximating the provided function.
- Parameters:
self (T)
func (float --> (float,float,float)) – function f(t) that will generate (x,y,z) pairs
N (int) – number of points for discretization
start (float) – starting value of the parameter t
stop (float) – final value of the parameter t
tol (float) – tolerance of the algorithm (default: 1e-6)
minDeg (int) – minimum spline degree (default: 1)
maxDeg (int) – maximum spline degree (default: 6)
smoothing (Tuple[float,float,float]|None) – optional parameters for the variational smoothing algorithm (default: (1,1,1))
makeWire (bool) – convert the resulting spline edge to a wire
- Returns:
a Workplane object with the current point unchanged
- Return type:
T
- parametricSurface(func:Callable[[float,float],Tuple[float,float]|Tuple[float,float,float]|Vector],N:int=20,start:float=0,stop:float=1,tol:float=0.01,minDeg:int=1,maxDeg:int=6,smoothing:Tuple[float,float,float]|None=(1,1,1))→T[source]
Create a spline surface approximating the provided function.
- Parameters:
self (T)
func ((float,float)--> (float,float,float)) – function f(u,v) that will generate (x,y,z) pairs
N (int) – number of points for discretization in one direction
start (float) – starting value of the parameters u,v
stop (float) – final value of the parameters u,v
tol (float) – tolerance used by the approximation algorithm (default: 1e-3)
minDeg (int) – minimum spline degree (default: 1)
maxDeg (int) – maximum spline degree (default: 3)
smoothing (Tuple[float,float,float]|None) – optional parameters for the variational smoothing algorithm (default: (1,1,1))
- Returns:
a Workplane object with the current point unchanged
- Return type:
T
This method might be unstable and may require tuning of the tol parameter.
- placeSketch(*sketches:Sketch)→T[source]
Place the provided sketch(es) based on the current items on the stack.
- Returns:
Workplane object with the sketch added.
- Parameters:
self (T)
sketches (Sketch)
- Return type:
T
- polarArray(radius:float,startAngle:float,angle:float,count:int,fill:bool=True,rotate:bool=True)→T[source]
Creates a polar array of points and pushes them onto the stack.The zero degree reference angle is located along the local X-axis.
- Parameters:
self (T)
radius (float) – Radius of the array.
startAngle (float) – Starting angle (degrees) of array. Zero degrees issituated along the local X-axis.
angle (float) – The angle (degrees) to fill with elements. A positivevalue will fill in the counter-clockwise direction. If fill isFalse, angle is the angle between elements.
count (int) – Number of elements in array. (count >= 1)
fill (bool) – Interpret the angle as total if True (default: True).
rotate (bool) – Rotate every item (default: True).
- Return type:
T
- polarLine(distance:float,angle:float,forConstruction:bool=False)→T[source]
Make a line of the given length, at the given angle from the current point
- Parameters:
self (T)
distance (float) – distance of the end of the line from the current point
angle (float) – angle of the vector to the end of the line with the x-axis
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
- polarLineTo(distance:float,angle:float,forConstruction:bool=False)→T[source]
Make a line from the current point to the given polar coordinates
Useful if it is more convenient to specify the end location rather thanthe distance and angle from the current point
- Parameters:
self (T)
distance (float) – distance of the end of the line from the origin
angle (float) – angle of the vector to the end of the line with the x-axis
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
- polygon(nSides:int,diameter:float,forConstruction:bool=False,circumscribed:bool=False)→T[source]
Make a polygon for each item on the stack.
By default, each polygon is created by inscribing it in a circle of thespecified diameter, such that the first vertex is oriented in the x direction.Alternatively, each polygon can be created by circumscribing it arounda circle of the specified diameter, such that the midpoint of the first edgeis oriented in the x direction. Circumscribed polygons are thus rotated bypi/nSides radians relative to the inscribed polygon. This ensures the extentof the polygon along the positive x-axis is always known.This has the advantage of not requiring additional formulae for purposes such astiling on the x-axis (at least for even sided polygons).
- Parameters:
self (T)
nSides (int) – number of sides, must be >= 3
diameter (float) – the diameter of the circle for constructing the polygon
circumscribed (true to create the polygon by circumscribing it about a circle,false to create the polygon by inscribing it in a circle) – circumscribe the polygon about a circle
forConstruction (bool)
- Returns:
a polygon wire
- Return type:
T
- polyline(listOfXYTuple:Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector],forConstruction:bool=False,includeCurrent:bool=False)→T[source]
Create a polyline from a list of points
- Parameters:
self (T)
listOfXYTuple (Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]) – a list of points in Workplane coordinates (2D or 3D)
forConstruction (true if the edges are for reference,false if they are for creating geometrypart geometry) – whether or not the edges are used for reference
includeCurrent (bool) – use current point as a starting point of the polyline
- Returns:
a new CQ object with a list of edges on the stack
- Return type:
T
NOTE most commonly, the resulting wire should be closed.
- pushPoints(pntList:Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector|Location])→T[source]
Pushes a list of points onto the stack as vertices.The points are in the 2D coordinate space of the workplane face
- Parameters:
self (T)
pntList (list of 2-tuples, inlocal coordinates) – a list of points to push onto the stack
- Returns:
a new workplane with the desired points on the stack.
- Return type:
T
A common use is to provide a list of points for a subsequent operation, such as creatingcircles or holes. This example creates a cube, and then drills three holes through it,based on three points:
s=(Workplane().box(1,1,1).faces(">Z").workplane().pushPoints([(-0.3,0.3),(0.3,0.3),(0,0)]))body=s.circle(0.05).cutThruAll()
Here the circle function operates on all three points, and is then extruded to create threeholes. See
circle()for how it works.
- radiusArc(endPoint:Tuple[float,float]|Tuple[float,float,float]|Vector,radius:float,forConstruction:bool=False)→T[source]
Draw an arc from the current point to endPoint with an arc defined by the radius.
- Parameters:
self (T)
endPoint (2-tuple,in workplane coordinates) – end point for the arc
radius (float,the radius ofthe arc between start point and end point.) – the radius of the arc
forConstruction (bool)
- Returns:
a workplane with the current point at the end of the arc
- Return type:
T
Given that a closed contour is drawn clockwise;A positive radius means convex arc and negative radius means concave arc.
- rarray(xSpacing:float,ySpacing:float,xCount:int,yCount:int,center:bool|Tuple[bool,bool]=True)→T[source]
Creates an array of points and pushes them onto the stack.If you want to position the array at another point, create another workplanethat is shifted to the position you would like to use as a reference
- Parameters:
self (T)
xSpacing (float) – spacing between points in the x direction ( must be >= 0)
ySpacing (float) – spacing between points in the y direction ( must be >= 0)
xCount (int) – number of points ( > 0 )
yCount (int) – number of points ( > 0 )
center (bool |Tuple[bool,bool]) – If True, the array will be centered around the workplane center.If False, the lower corner will be on the reference point and the array willextend in the positive x and y directions. Can also use a 2-tuple to specifycentering along each axis.
- Return type:
T
- rect(xLen:float,yLen:float,centered:bool|Tuple[bool,bool]=True,forConstruction:bool=False)→T[source]
Make a rectangle for each item on the stack.
- Parameters:
self (T)
xLen (float) – length in the x direction (in workplane coordinates)
yLen (float) – length in the y direction (in workplane coordinates)
centered (bool |Tuple[bool,bool]) – If True, the rectangle will be centered around the referencepoint. If False, the corner of the rectangle will be on the reference point andit will extend in the positive x and y directions. Can also use a 2-tuple tospecify centering along each axis.
forConstruction (true if the wires are for reference,false if they are creating partgeometry) – should the new wires be reference geometry only?
- Returns:
a new CQ object with the created wires on the stack
- Return type:
T
A common use case is to use a for-construction rectangle to define the centers of a holepattern:
s=Workplane().rect(4.0,4.0,forConstruction=True).vertices().circle(0.25)
Creates 4 circles at the corners of a square centered on the origin.
Negative values for xLen and yLen are permitted, although they only have an effect whencentered is False.
- Future Enhancements:
project points not in the workplane plane onto the workplane plane
- revolve(angleDegrees:float=360.0,axisStart:Tuple[float,float]|Tuple[float,float,float]|Vector|None=None,axisEnd:Tuple[float,float]|Tuple[float,float,float]|Vector|None=None,combine:bool|Literal['cut','a','s']=True,clean:bool=True)→T[source]
Use all un-revolved wires in the parent chain to create a solid.
- Parameters:
self (T)
angleDegrees (float,anything less than 360 degrees will leave the shape open) – the angle to revolve through.
axisStart (Tuple[float,float]|Tuple[float,float,float]|Vector |None) – the start point of the axis of rotation
axisEnd (Tuple[float,float]|Tuple[float,float,float]|Vector |None) – the end point of the axis of rotation
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shape
- Returns:
a CQ object with the resulting solid selected.
- Return type:
T
The returned object is always a CQ object, and depends on whether combine is True, andwhether a context solid is already defined:
if combine is False, the new value is pushed onto the stack.
if combine is true, the value is combined with the context solid if it exists,and the resulting solid becomes the new context solid.
Note
Keep in mind thataxisStart andaxisEnd are defined relative to the current Workplane center position.So if for example you want to revolve a circle centered at (10,0,0) around the Y axis, be sure to either
move()(ormoveTo())the current Workplane position or specifyaxisStart andaxisEnd with the correct vector position.In this example (0,0,0), (0,1,0) as axis coords would fail.
- rotate(axisStartPoint:Tuple[float,float]|Tuple[float,float,float]|Vector,axisEndPoint:Tuple[float,float]|Tuple[float,float,float]|Vector,angleDegrees:float)→T[source]
Returns a copy of all of the items on the stack rotated through and angle around the axisof rotation.
- Parameters:
self (T)
axisStartPoint (a 3-tuple offloats) – The first point of the axis of rotation
axisEndPoint (a 3-tuple offloats) – The second point of the axis of rotation
angleDegrees (float) – the rotation angle, in degrees
- Returns:
a CQ object
- Return type:
T
- rotateAboutCenter(axisEndPoint:Tuple[float,float]|Tuple[float,float,float]|Vector,angleDegrees:float)→T[source]
Rotates all items on the stack by the specified angle, about the specified axis
The center of rotation is a vector starting at the center of the object on the stack,and ended at the specified point.
- Parameters:
self (T)
axisEndPoint (a three-tuple in global coordinates) – the second point of axis of rotation
angleDegrees (float) – the rotation angle, in degrees
- Returns:
a CQ object, with all items rotated.
- Return type:
T
WARNING: This version returns the same CQ object instead of a new one– theold object is not accessible.
- Future Enhancements:
A version of this method that returns a transformed copy, rather than modifyingthe originals
This method doesn’t expose a very good interface, because the axis of rotationcould be inconsistent between multiple objects. This is because the beginningof the axis is variable, while the end is fixed. This is fine when operating onone object, but is not cool for multiple.
- sagittaArc(endPoint:Tuple[float,float]|Tuple[float,float,float]|Vector,sag:float,forConstruction:bool=False)→T[source]
Draw an arc from the current point to endPoint with an arc defined by the sag (sagitta).
- Parameters:
self (T)
endPoint (2-tuple,in workplane coordinates) – end point for the arc
sag (float,perpendicular distance from arc center to arc baseline.) – the sagitta of the arc
forConstruction (bool)
- Returns:
a workplane with the current point at the end of the arc
- Return type:
T
The sagitta is the distance from the center of the arc to the arc base.Given that a closed contour is drawn clockwise;A positive sagitta means convex arc and negative sagitta means concave arc.Seehttps://en.wikipedia.org/wiki/Sagitta_(geometry) for more information.
- section(height:float=0.0)→T[source]
Slices current solid at the given height.
- Parameters:
self (T)
height (float) – height to slice at (default: 0)
- Raises:
ValueError – if no solids or compounds are found
- Returns:
a CQ object with the resulting face(s).
- Return type:
T
- shell(thickness:float,kind:Literal['arc','intersection']='arc')→T[source]
Remove the selected faces to create a shell of the specified thickness.
To shell, first create a solid, andin the same chain select the faces you wish to remove.
- Parameters:
self (T)
thickness (float) – thickness of the desired shell.Negative values shell inwards, positive values shell outwards.
kind (Literal['arc','intersection']) – kind of join, arc or intersection (default: arc).
- Raises:
ValueError – if the current stack contains objects that are not faces of a solidfurther up in the chain.
- Returns:
a CQ object with the resulting shelled solid selected.
- Return type:
T
This example will create a hollowed out unit cube, where the top most face is open,and all other walls are 0.2 units thick:
Workplane().box(1,1,1).faces("+Z").shell(0.2)
You can also select multiple faces at once. Here is an example that creates a three-walledcorner, by removing three faces of a cube:
Workplane().box(10,10,10).faces(">Z or >X or <Y").shell(1)
Note: When sharp edges are shelled inwards, they remain sharp corners, butoutwardshells are automatically filleted (unless kind=”intersection”), because an outward offsetfrom a corner generates a radius.
- shells(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select the shells of objects on the stack, optionally filtering the selection. If there aremultiple objects on the stack, the shells of all objects are collected and a list of all thedistinct shells is returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains all of thedistinct shells ofall objects onthe current stack, filtered by the provided selector.
- Return type:
T
If there are no shells for any objects on the current stack, an empty CQ object is returned
Most solids will have a single shell, which represents the outer surface. A shell willtypically be composed of multiple faces.
- siblings(kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'],level:int=1,tag:str|None=None)→T[source]
Select topological siblings.
- Parameters:
self (T)
kind (Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound']) – kind of linking element, e.g. “Vertex” or “Edge”
level (int) – level of relation - how many elements of kind are in the link
tag (str |None) – if set, search the tagged object instead of self
- Returns:
a Workplane object whose stack contains selected siblings.
- Return type:
T
- sketch()→Sketch[source]
Initialize and return a sketch
- Returns:
Sketch object with the current workplane as a parent.
- Parameters:
self (T)
- Return type:
- slot2D(length:float,diameter:float,angle:float=0)→T[source]
Creates a rounded slot for each point on the stack.
- Parameters:
self (T)
diameter (float) – desired diameter, or width, of slot
length (float) – desired end to end length of slot
angle (float) – angle of slot in degrees, with 0 being along x-axis
- Returns:
a new CQ object with the created wires on the stack
- Return type:
T
Can be used to create arrays of slots, such as in cooling applications:
Workplane().box(10,25,1).rarray(1,2,1,10).slot2D(8,1,0).cutThruAll()
- solids(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select the solids of objects on the stack, optionally filtering the selection. If there aremultiple objects on the stack, the solids of all objects are collected and a list of all thedistinct solids is returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains all of thedistinct solids ofall objects onthe current stack, filtered by the provided selector.
- Return type:
T
If there are no solids for any objects on the current stack, an empty CQ object is returned
The typical use is to select a single object on the stack. For example:
Workplane().box(1,1,1).solids().size()
returns 1, because a cube consists of one solid.
It is possible for a single CQ object ( or even a single CAD primitive ) to containmultiple solids.
- sphere(radius:float,direct:Tuple[float,float]|Tuple[float,float,float]|Vector=(0,0,1),angle1:float=-90,angle2:float=90,angle3:float=360,centered:bool|Tuple[bool,bool,bool]=True,combine:bool|Literal['cut','a','s']=True,clean:bool=True)→T[source]
Returns a 3D sphere with the specified radius for each point on the stack.
- Parameters:
self (T)
radius (float) – The radius of the sphere
direct (A three-tuple) – The direction axis for the creation of the sphere
angle1 (float > 0) – The first angle to sweep the sphere arc through
angle2 (float > 0) – The second angle to sweep the sphere arc through
angle3 (float > 0) – The third angle to sweep the sphere arc through
centered (bool |Tuple[bool,bool,bool]) – If True, the sphere will be centered around the reference point. If False,the corner of a bounding box around the sphere will be on the reference point and itwill extend in the positive x, y and z directions. Can also use a 3-tuple to specifycentering along each axis.
combine (true to combine shapes,false otherwise) – Whether the results should be combined with other solids on the stack(and each other)
clean (bool) – call
clean()afterwards to have a clean shape
- Returns:
A sphere object for each point on the stack
- Return type:
T
One sphere is created for each item on the current stack. If no items are on the stack, onebox using the current workplane center is created.
If combine is true, the result will be a single object on the stack. If a solid was foundin the chain, the result is that solid with all spheres produced fused onto it otherwise,the result is the combination of all the produced spheres.
If combine is false, the result will be a list of the spheres produced.
- spline(listOfXYTuple:Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector],tangents:Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]|None=None,periodic:bool=False,parameters:Sequence[float]|None=None,scale:bool=True,tol:float|None=None,forConstruction:bool=False,includeCurrent:bool=False,makeWire:bool=False)→T[source]
Create a spline interpolated through the provided points (2D or 3D).
- Parameters:
self (T)
listOfXYTuple (Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector]) – points to interpolate through
tangents (Sequence[Tuple[float,float]|Tuple[float,float,float]|Vector]|None) –
vectors specifying the direction of the tangent to thecurve at each of the specified interpolation points.
If only 2 tangents are given, they will be used as the initial andfinal tangent.
If some tangents are not specified (i.e., are None), no tangentconstraint will be applied to the corresponding interpolation point.
The spline will be C2 continuous at the interpolation points whereno tangent constraint is specified, and C1 continuous at the pointswhere a tangent constraint is specified.
periodic (bool) – creation of periodic curves
parameters (Sequence[float]|None) –
the value of the parameter at each interpolation point.(The interpolated curve is represented as a vector-valued function of ascalar parameter.)
If periodic == True, then len(parameters) must belen(interpolation points) + 1, otherwise len(parameters) must be equal tolen(interpolation points).
scale (bool) –
whether to scale the specified tangent vectors beforeinterpolating.
Each tangent is scaled, so it’s length is equal to the derivative ofthe Lagrange interpolated curve.
I.e., set this to True, if you want to use only the direction ofthe tangent vectors specified by
tangents, but not their magnitude.tol (float |None) –
tolerance of the algorithm (consult OCC documentation)
Used to check that the specified points are not too close to eachother, and that tangent vectors are not too short. (In either caseinterpolation may fail.)
Set to None to use the default tolerance.
includeCurrent (bool) – use current point as a starting point of the curve
makeWire (bool) – convert the resulting spline edge to a wire
forConstruction (bool)
- Returns:
a Workplane object with the current point at the end of the spline
- Return type:
T
The spline will begin at the current point, and end with the last point in theXY tuple list.
This example creates a block with a spline for one side:
s=Workplane(Plane.XY())sPnts=[(2.75,1.5),(2.5,1.75),(2.0,1.5),(1.5,1.0),(1.0,1.25),(0.5,1.0),(0,1.0),]r=s.lineTo(3.0,0).lineTo(3.0,1.0).spline(sPnts).close()r=r.extrude(0.5)
WARNING It is fairly easy to create a list of pointsthat cannot be correctly interpreted as a spline.
- splineApprox(points:Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector],tol:float|None=1e-06,minDeg:int=1,maxDeg:int=6,smoothing:Tuple[float,float,float]|None=(1,1,1),forConstruction:bool=False,includeCurrent:bool=False,makeWire:bool=False)→T[source]
Create a spline interpolated through the provided points (2D or 3D).
- Parameters:
self (T)
points (Iterable[Tuple[float,float]|Tuple[float,float,float]|Vector]) – points to interpolate through
tol (float |None) – tolerance of the algorithm (default: 1e-6)
minDeg (int) – minimum spline degree (default: 1)
maxDeg (int) – maximum spline degree (default: 6)
smoothing (Tuple[float,float,float]|None) – optional parameters for the variational smoothing algorithm (default: (1,1,1))
includeCurrent (bool) – use current point as a starting point of the curve
makeWire (bool) – convert the resulting spline edge to a wire
forConstruction (bool)
- Returns:
a Workplane object with the current point at the end of the spline
- Return type:
T
WARNING for advanced users.
- split(keepTop:bool=False,keepBottom:bool=False)→T[source]
- split(splitter:Workplane|Shape)→T
Splits a solid on the stack into two parts, optionally keeping the separate parts.
- Parameters:
self
keepTop (bool) – True to keep the top, False or None to discard it
keepBottom (bool) – True to keep the bottom, False or None to discard it
- Raises:
ValueError – if keepTop and keepBottom are both false.
ValueError – if there is no solid in the current stack or parent chain
- Returns:
CQ object with the desired objects on the stack.
The most common operation splits a solid and keeps one half. This sample createsa split bushing:
# drill a hole in the sidec=Workplane().box(1,1,1).faces(">Z").workplane().circle(0.25).cutThruAll()# now cut it in half sidewaysc=c.faces(">Y").workplane(-0.5).split(keepTop=True)
- sweep(path:Workplane|Wire|Edge,multisection:bool=False,sweepAlongWires:bool|None=None,makeSolid:bool=True,isFrenet:bool=False,combine:bool|Literal['cut','a','s']=True,clean:bool=True,transition:Literal['right','round','transformed']='right',normal:Tuple[float,float]|Tuple[float,float,float]|Vector|None=None,auxSpine:Workplane|None=None)→T[source]
Use all un-extruded wires in the parent chain to create a swept solid.
- Parameters:
self (T)
path (Workplane |Wire |Edge) – A wire along which the pending wires will be swept
multiSection – False to create multiple swept from wires on the chain along path.True to create only one solid swept along path with shape following the list of wires on the chain
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shapetransition (Literal['right','round','transformed']) – handling of profile orientation at C1 path discontinuities. Possible values are {‘transformed’,’round’, ‘right’} (default: ‘right’).
normal (Tuple[float,float]|Tuple[float,float,float]|Vector |None) – optional fixed normal for extrusion
auxSpine (Workplane |None) – a wire defining the binormal along the extrusion path
multisection (bool)
sweepAlongWires (bool |None)
makeSolid (bool)
isFrenet (bool)
- Returns:
a CQ object with the resulting solid selected.
- Return type:
T
- tag(name:str)→T[source]
Tags the current CQ object for later reference.
- Parameters:
self (T)
name (str) – the name to tag this object with
- Returns:
self, a CQ object with tag applied
- Return type:
T
- tangentArcPoint(endpoint:Tuple[float,float]|Tuple[float,float,float]|Vector,forConstruction:bool=False,relative:bool=True)→T[source]
Draw an arc as a tangent from the end of the current edge to endpoint.
- Parameters:
self (T)
endpoint (2-tuple,3-tuple orVector) – point for the arc to end at
relative (bool) – True if endpoint is specified relative to the current point, False if endpoint is in workplane coordinates
forConstruction (bool)
- Returns:
a Workplane object with an arc on the stack
- Return type:
T
Requires the the current first object on the stack is an Edge, as wouldbe the case after a lineTo operation or similar.
- text(txt:str,fontsize:float,distance:float,cut:bool=True,combine:bool|Literal['cut','a','s']=False,clean:bool=True,font:str='Arial',fontPath:str|None=None,kind:Literal['regular','bold','italic']='regular',halign:Literal['center','left','right']='center',valign:Literal['center','top','bottom']='center')→T[source]
Returns a 3D text.
- Parameters:
self (T)
txt (str) – text to be rendered
fontsize (float) – size of the font in model units
distance (float,negative means opposite the normal direction) – the distance to extrude or cut, normal to the workplane plane
cut (bool) – True to cut the resulting solid from the parent solids if found
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shapefont (str) – font name
fontPath (str |None) – path to font file
kind (Literal['regular','bold','italic']) – font type
halign (Literal['center','left','right']) – horizontal alignment
valign (Literal['center','top','bottom']) – vertical alignment
- Returns:
a CQ object with the resulting solid selected
- Return type:
T
The returned object is always a Workplane object, and depends on whether combine is True, andwhether a context solid is already defined:
if combine is False, the new value is pushed onto the stack.
if combine is true, the value is combined with the context solid if it exists,and the resulting solid becomes the new context solid.
Examples:
cq.Workplane().text("CadQuery",5,1)
Specify the font (name), and kind to use an installed system font:
cq.Workplane().text("CadQuery",5,1,font="Liberation Sans Narrow",kind="italic")
Specify fontPath to use a font from a given file:
cq.Workplane().text("CadQuery",5,1,fontPath="/opt/fonts/texgyrecursor-bold.otf")
Cutting text into a solid:
cq.Workplane().box(8,8,8).faces(">Z").workplane().text("Z",5,-1.0)
- threePointArc(point1:Tuple[float,float]|Tuple[float,float,float]|Vector,point2:Tuple[float,float]|Tuple[float,float,float]|Vector,forConstruction:bool=False)→T[source]
Draw an arc from the current point, through point1, and ending at point2
- Parameters:
self (T)
point1 (2-tuple,in workplane coordinates) – point to draw through
point2 (2-tuple,in workplane coordinates) – end point for the arc
forConstruction (bool)
- Returns:
a workplane with the current point at the end of the arc
- Return type:
T
- Future Enhancements:
provide a version that allows an arc using relative measuresprovide a centerpoint arcprovide tangent arcs
- toOCC()→Any[source]
Directly returns the wrapped OCCT object.
- Returns:
The wrapped OCCT object
- Return type:
TopoDS_Shape or a subclass
- toPending()→T[source]
Adds wires/edges to pendingWires/pendingEdges.
- Returns:
same CQ object with updated context.
- Parameters:
self (T)
- Return type:
T
- toSvg(opts:Any=None)→str[source]
Returns svg text that represents the first item on the stack.
for testing purposes.
- Parameters:
opts (dictionary,width and height) – svg formatting options
- Returns:
a string that contains SVG that represents this item.
- Return type:
str
- transformed(rotate:Tuple[float,float]|Tuple[float,float,float]|Vector=(0,0,0),offset:Tuple[float,float]|Tuple[float,float,float]|Vector=(0,0,0))→T[source]
Create a new workplane based on the current one.The origin of the new plane is located at the existing origin+offset vector, where offset isgiven in coordinates local to the current planeThe new plane is rotated through the angles specified by the components of the rotationvector.
- Parameters:
- Returns:
a new work plane, transformed as requested
- Return type:
T
- translate(vec:Tuple[float,float]|Tuple[float,float,float]|Vector)→T[source]
Returns a copy of all of the items on the stack moved by the specified translation vector.
- Parameters:
self (T)
tupleDistance (a 3-tuple offloat) – distance to move, in global coordinates
vec (Tuple[float,float]|Tuple[float,float,float]|Vector)
- Returns:
a CQ object
- Return type:
T
- twistExtrude(distance:float,angleDegrees:float,combine:bool|Literal['cut','a','s']=True,clean:bool=True)→T[source]
Extrudes a wire in the direction normal to the plane, but also twists by the specifiedangle over the length of the extrusion.
The center point of the rotation will be the center of the workplane.
See extrude for more details, since this method is the same except for the the additionof the angle. In fact, if angle=0, the result is the same as a linear extrude.
NOTE This method can create complex calculations, so be careful using it withcomplex geometries
- Parameters:
self (T)
distance (float) – the distance to extrude normal to the workplane
angle – angle (in degrees) to rotate through the extrusion
combine (bool |Literal['cut','a','s']) – True or “a” to combine the resulting solid with parent solids if found,“cut” or “s” to remove the resulting solid from the parent solids if found.False to keep the resulting solid separated from the parent solids.
clean (bool) – call
clean()afterwards to have a clean shapeangleDegrees (float)
- Returns:
a CQ object with the resulting solid selected.
- Return type:
T
- union(toUnion:Workplane|Solid|Compound|None=None,clean:bool=True,glue:bool=False,tol:float|None=None)→T[source]
Unions all of the items on the stack of toUnion with the current solid.If there is no current solid, the items in toUnion are unioned together.
- Parameters:
self (T)
toUnion (Workplane |Solid |Compound |None) – a solid object, or a Workplane object having a solid
clean (bool) – call
clean()afterwards to have a clean shape (default True)glue (bool) – use a faster gluing mode for non-overlapping shapes (default False)
tol (float |None) – tolerance value for fuzzy bool operation mode (default None)
- Raises:
ValueError if there is no solid to add to in the chain
- Returns:
a Workplane object with the resulting object selected
- Return type:
T
- vLine(distance:float,forConstruction:bool=False)→T[source]
Make a vertical line from the current point the provided distance
- Parameters:
self (T)
distance (float) –
distance from current point
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
- vLineTo(yCoord:float,forConstruction:bool=False)→T[source]
Make a vertical line from the current point to the provided y coordinate.
Useful if it is more convenient to specify the end location rather than distance,as in
vLine()- Parameters:
self (T)
yCoord (float) – y coordinate for the end of the line
forConstruction (bool)
- Returns:
the Workplane object with the current point at the end of the new line
- Return type:
T
- val()→Vector|Location|Shape|Sketch[source]
Return the first value on the stack. If no value is present, current plane origin is returned.
- Returns:
the first value on the stack.
- Return type:
A CAD primitive
- vals()→List[Vector|Location|Shape|Sketch][source]
get the values in the current list
- Return type:
list of occ_impl objects
- Returns:
the values of the objects on the stack.
Contrast with
all(), which returns CQ objects for all of the items on the stack
- vertices(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select the vertices of objects on the stack, optionally filtering the selection. If thereare multiple objects on the stack, the vertices of all objects are collected and a list ofall the distinct vertices is returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains thedistinct vertices ofall objects on thecurrent stack, after being filtered by the selector, if provided
- Return type:
T
If there are no vertices for any objects on the current stack, an empty CQ objectis returned
The typical use is to select the vertices of a single object on the stack. For example:
Workplane().box(1,1,1).faces("+Z").vertices().size()
returns 4, because the topmost face of a cube will contain four vertices. While this:
Workplane().box(1,1,1).faces().vertices().size()
returns 8, because a cube has a total of 8 vertices
Note Circles are peculiar, they have a single vertex at the center!
- wedge(dx:float,dy:float,dz:float,xmin:float,zmin:float,xmax:float,zmax:float,pnt:~typing.Tuple[float,float]|~typing.Tuple[float,float,float]|~cadquery.occ_impl.geom.Vector=Vector:(0.0,0.0,0.0),dir:~typing.Tuple[float,float]|~typing.Tuple[float,float,float]|~cadquery.occ_impl.geom.Vector=Vector:(0.0,0.0,1.0),centered:bool|~typing.Tuple[bool,bool,bool]=True,combine:bool|~typing.Literal['cut','a','s']=True,clean:bool=True)→T[source]
Returns a 3D wedge with the specified dimensions for each point on the stack.
- Parameters:
self (T)
dx (float) – Distance along the X axis
dy (float) – Distance along the Y axis
dz (float) – Distance along the Z axis
xmin (float) – The minimum X location
zmin (float) – The minimum Z location
xmax (float) – The maximum X location
zmax (float) – The maximum Z location
pnt (Tuple[float,float]|Tuple[float,float,float]|Vector) – A vector (or tuple) for the origin of the direction for the wedge
dir (Tuple[float,float]|Tuple[float,float,float]|Vector) – The direction vector (or tuple) for the major axis of the wedge
centered (bool |Tuple[bool,bool,bool]) – If True, the wedge will be centered around the reference point.If False, the corner of the wedge will be on the reference point and it willextend in the positive x, y and z directions. Can also use a 3-tuple tospecify centering along each axis.
combine (bool |Literal['cut','a','s']) – Whether the results should be combined with other solids on the stack(and each other)
clean (bool) – True to attempt to have the kernel clean up the geometry, False otherwise
- Returns:
A wedge object for each point on the stack
- Return type:
T
One wedge is created for each item on the current stack. If no items are on the stack, onewedge using the current workplane center is created.
If combine is True, the result will be a single object on the stack. If a solid was foundin the chain, the result is that solid with all wedges produced fused onto it otherwise,the result is the combination of all the produced wedges.
If combine is False, the result will be a list of the wedges produced.
- wire(forConstruction:bool=False)→T[source]
Returns a CQ object with all pending edges connected into a wire.
All edges on the stack that can be combined will be combined into a single wire object,and other objects will remain on the stack unmodified. If there are no pending edges,this method will just return self.
- Parameters:
self (T)
forConstruction (bool) – whether the wire should be used to make a solid, or if it is justfor reference
- Return type:
T
This method is primarily of use to plugin developers making utilities for 2D construction.This method should be called when a user operation implies that 2D construction isfinished, and we are ready to begin working in 3d.
SEE ‘2D construction concepts’ for a more detailed explanation of how CadQuery handlesedges, wires, etc.
Any non edges will still remain.
- wires(selector:str|Selector|None=None,tag:str|None=None)→T[source]
Select the wires of objects on the stack, optionally filtering the selection. If there aremultiple objects on the stack, the wires of all objects are collected and a list of all thedistinct wires is returned.
- Parameters:
self (T)
selector (str |Selector |None) – optional Selector object, or string selector expression(see
StringSyntaxSelector)tag (str |None) – if set, search the tagged object instead of self
- Returns:
a CQ object whose stack contains all of thedistinct wires ofall objects onthe current stack, filtered by the provided selector.
- Return type:
T
If there are no wires for any objects on the current stack, an empty CQ object is returned
The typical use is to select the wires of a single object on the stack. For example:
Workplane().box(1,1,1).faces("+Z").wires().size()
returns 1, because a face typically only has one outer wire
- workplane(offset:float=0.0,invert:bool=False,centerOption:Literal['CenterOfMass','ProjectedOrigin','CenterOfBoundBox']='ProjectedOrigin',origin:Tuple[float,float]|Tuple[float,float,float]|Vector|None=None)→T[source]
Creates a new 2D workplane, located relative to the first face on the stack.
- Parameters:
self (T)
offset (float) – offset for the workplane in its normal direction . Default
invert (bool) – invert the normal direction from that of the face.
centerOption (string orNone='ProjectedOrigin') – how local origin of workplane is determined.
origin (Tuple[float,float]|Tuple[float,float,float]|Vector |None) – origin for plane center, requires ‘ProjectedOrigin’ centerOption.
- Return type:
Workplane object
The first element on the stack must be a face, a set ofco-planar faces or a vertex. If a vertex, then the parentitem on the chain immediately before the vertex must be aface.
The result will be a 2D working planewith a new coordinate system set up as follows:
The centerOption parameter sets how the center is defined.Options are ‘CenterOfMass’, ‘CenterOfBoundBox’, or ‘ProjectedOrigin’.‘CenterOfMass’ and ‘CenterOfBoundBox’ are in relation to the selectedface(s) or vertex (vertices). ‘ProjectedOrigin’ uses by default the current originor the optional origin parameter (if specified) and projects it onto the planedefined by the selected face(s).
The Z direction will be the normal of the face, computedat the center point.
The X direction will be parallel to the x-y plane. If the workplane is parallel tothe global x-y plane, the x direction of the workplane will co-incide with theglobal x direction.
Most commonly, the selected face will be planar, and the workplane lies in the same planeof the face ( IE, offset=0). Occasionally, it is useful to define a face offset froman existing surface, and even more rarely to define a workplane based on a face that isnot planar.
- cadquery.sortWiresByBuildOrder(wireList:List[Wire])→List[List[Wire]][source]
Tries to determine how wires should be combined into faces.
- Assume:
The wires make up one or more faces, which could have ‘holes’Outer wires are listed ahead of inner wiresthere are no wires inside wires inside wires( IE, islands – we can deal with that later on )none of the wires are construction wires
- Compute:
one or more sets of wires, with the outer wire listed first, and innerones
Returns, list of lists.
- classcadquery.occ_impl.shapes.CompSolid(obj:TopoDS_Shape)[source]
a single compsolid
- Parameters:
obj (TopoDS_Shape)
- classcadquery.occ_impl.shapes.Compound(obj:TopoDS_Shape)[source]
a collection of disconnected solids
- Parameters:
obj (TopoDS_Shape)
- ancestors(shape:Shape,kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'])→Compound[source]
Iterate over ancestors, i.e. shapes of same kind within shape that contain elements of self.
- cut(*toCut:Shape,tol:float|None=None)→Compound[source]
Remove the positional arguments from this Shape.
- intersect(*toIntersect:Shape,tol:float|None=None)→Compound[source]
Intersection of the positional arguments and this Shape.
- classmethodmakeCompound(listOfShapes:Iterable[Shape])→Compound[source]
Create a compound out of a list of shapes
- classmethodmakeText(text:str,size:float,height:float,font:str='Arial',fontPath:str|None=None,kind:Literal['regular','bold','italic']='regular',halign:Literal['center','left','right']='center',valign:Literal['center','top','bottom']='center',position:Plane=Plane(origin=(0.0,0.0,0.0),xDir=(1.0,0.0,0.0),normal=(0.0,0.0,1.0)))→Shape[source]
Create a 3D text
- classcadquery.occ_impl.shapes.Edge(obj:TopoDS_Shape)[source]
A trimmed curve that represents the border of a face
- Parameters:
obj (TopoDS_Shape)
- hasPCurve(f:Face)→bool[source]
Check if self has a pcurve defined on f.
- Parameters:
f (Face)
- Return type:
bool
- classmethodmakeBezier(points:List[Vector])→Edge[source]
Create a cubic Bézier Curve from the points.
- classmethodmakeEllipse(x_radius:float,y_radius:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),xdir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(1.0,0.0,0.0),angle1:float=360.0,angle2:float=360.0,sense:~typing.Literal[-1,1]=1)→Edge[source]
Makes an Ellipse centered at the provided point, having normal in the provided direction.
- Parameters:
cls
x_radius (float) – x radius of the ellipse (along the x-axis of plane the ellipse should lie in)
y_radius (float) – y radius of the ellipse (along the y-axis of plane the ellipse should lie in)
pnt (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the center of the ellipse
dir (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the direction of the plane the ellipse should lie in
angle1 (float) – start angle of arc
angle2 (float) – end angle of arc (angle2 == angle1 return closed ellipse = default)
sense (Literal[-1,1]) – clockwise (-1) or counter clockwise (1)
xdir (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
- Returns:
an Edge
- Return type:
- classmethodmakeLine(v1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Edge[source]
Create a line between two points
- Parameters:
- Returns:
A linear edge between the two provided points
- Return type:
- classmethodmakeSpline(listOfVector:List[Vector],tangents:Sequence[Vector]|None=None,periodic:bool=False,parameters:Sequence[float]|None=None,scale:bool=True,tol:float=1e-06)→Edge[source]
Interpolate a spline through the provided points.
- Parameters:
listOfVector (List[Vector]) – a list of Vectors that represent the points
tangents (Sequence[Vector]|None) – tuple of Vectors specifying start and finish tangent
periodic (bool) – creation of periodic curves
parameters (Sequence[float]|None) – the value of the parameter at each interpolation point. (The interpolatedcurve is represented as a vector-valued function of a scalar parameter.) If periodic ==True, then len(parameters) must be len(intepolation points) + 1, otherwise len(parameters)must be equal to len(interpolation points).
scale (bool) – whether to scale the specified tangent vectors before interpolating. Eachtangent is scaled, so it’s length is equal to the derivative of the Lagrange interpolatedcurve. I.e., set this to True, if you want to use only the direction of the tangentvectors specified by
tangents, but not their magnitude.tol (float) – tolerance of the algorithm (consult OCC documentation). Used to check that thespecified points are not too close to each other, and that tangent vectors are not tooshort. (In either case interpolation may fail.)
- Returns:
an Edge
- Return type:
- classmethodmakeSplineApprox(listOfVector:List[Vector],tol:float=0.001,smoothing:Tuple[float,float,float]|None=None,minDeg:int=1,maxDeg:int=6)→Edge[source]
Approximate a spline through the provided points.
- Parameters:
listOfVector (List[Vector]) – a list of Vectors that represent the points
tol (float) – tolerance of the algorithm (consult OCC documentation).
smoothing (Tuple[float,float,float]|None) – optional tuple of 3 weights use for variational smoothing (default: None)
minDeg (int) – minimum spline degree. Enforced only when smothing is None (default: 1)
maxDeg (int) – maximum spline degree (default: 6)
- Returns:
an Edge
- Return type:
- classmethodmakeTangentArc(v1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v3:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Edge[source]
Makes a tangent arc from point v1, in the direction of v2 and ends at v3.
- Parameters:
- Returns:
an edge
- Return type:
- classmethodmakeThreePointArc(v1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],v3:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Edge[source]
Makes a three point arc through the provided points
- Parameters:
- Returns:
an edge object through the three points
- Return type:
- classcadquery.occ_impl.shapes.Face(obj:TopoDS_Shape)[source]
Bases:
Shapea bounded surface that represents part of the boundary of a solid
- Parameters:
obj (TopoDS_Shape)
- extend(d:float,umin:bool=True,umax:bool=True,vmin:bool=True,vmax:bool=True)→Face[source]
Extend a face. Does not work well in periodic directions.
- Parameters:
d (float) – length of the extension.
umin (bool) – extend along the umin isoline.
umax (bool) – extend along the umax isoline.
vmin (bool) – extend along the vmin isoline.
vmax (bool) – extend along the vmax isoline.
- Return type:
- isoline(param:float|int,direction:Literal['u','v']='v')→Edge[source]
Construct an isoline.
- Parameters:
param (float |int)
direction (Literal['u','v'])
- Return type:
- isolines(params:Iterable[float|int],direction:Literal['u','v']='v')→List[Edge][source]
Construct multiple isolines.
- Parameters:
params (Iterable[float |int])
direction (Literal['u','v'])
- Return type:
List[Edge]
- classmethodmakeFromWires(outerWire:Wire,innerWires:List[Wire]=[])→Face[source]
Makes a planar face from one or more wires
- classmethodmakeNSidedSurface(edges:~typing.Iterable[~cadquery.occ_impl.shapes.Edge|~cadquery.occ_impl.shapes.Wire],constraints:~typing.Iterable[~cadquery.occ_impl.shapes.Edge|~cadquery.occ_impl.shapes.Wire|~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]|~OCP.gp.gp_Pnt],continuity:~OCP.GeomAbs.GeomAbs_Shape=<GeomAbs_Shape.GeomAbs_C0:0>,degree:int=3,nbPtsOnCur:int=15,nbIter:int=2,anisotropy:bool=False,tol2d:float=1e-05,tol3d:float=0.0001,tolAng:float=0.01,tolCurv:float=0.1,maxDeg:int=8,maxSegments:int=9)→Face[source]
Returns a surface enclosed by a closed polygon defined by ‘edges’ and ‘constraints’.
- Parameters:
edges (list ofedges orwires) – edges
constraints (list ofpoints oredges) – constraints
continuity (GeomAbs_Shape) – OCC.Core.GeomAbs continuity condition
degree (int) – >=2
nbPtsOnCur (int) – number of points on curve >= 15
nbIter (int) – number of iterations >= 2
anisotropy (bool) – bool Anisotropy
tol2d (float) – 2D tolerance >0
tol3d (float) – 3D tolerance >0
tolAng (float) – angular tolerance
tolCurv (float) – tolerance for curvature >0
maxDeg (int) – highest polynomial degree >= 2
maxSegments (int) – greatest number of segments >= 2
- Return type:
- classmethodmakeRuledSurface(edgeOrWire1:Edge,edgeOrWire2:Edge)→Face[source]
- classmethodmakeRuledSurface(edgeOrWire1:Wire,edgeOrWire2:Wire)→Face
makeRuledSurface(Edge|Wire,Edge|Wire) – Make a ruled surfaceCreate a ruled surface out of two edges or wires. If wires are used thenthese must have the same number of edges
- classmethodmakeSplineApprox(points:List[List[Vector]],tol:float=0.01,smoothing:Tuple[float,float,float]|None=None,minDeg:int=1,maxDeg:int=3)→Face[source]
Approximate a spline surface through the provided points.
- Parameters:
points (List[List[Vector]]) – a 2D list of Vectors that represent the points
tol (float) – tolerance of the algorithm (consult OCC documentation).
smoothing (Tuple[float,float,float]|None) – optional tuple of 3 weights use for variational smoothing (default: None)
minDeg (int) – minimum spline degree. Enforced only when smothing is None (default: 1)
maxDeg (int) – maximum spline degree (default: 6)
- Return type:
- normalAt(u:float|int,v:float|int)→Tuple[Vector,Vector][source]
- normalAt(locationVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]|None=None)→Vector
Computes the normal vector at the desired location on the face.
- Returns:
a vector representing the direction
- Parameters:
locationVector (a vector that lies on the surface.) – the location to compute the normal at. If none, the center of the face is used.
- Return type:
Computes the normal vector at the desired location in the u,v parameter space.
- Returns:
a vector representing the normal direction and the position
- Parameters:
u – the u parametric location to compute the normal at.
v – the v parametric location to compute the normal at.
locationVector (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]|None)
- Return type:
- normals(us:Iterable[float|int],vs:Iterable[float|int])→Tuple[List[Vector],List[Vector]][source]
Computes the normal vectors at the desired locations in the u,v parameter space.
- Returns:
a tuple of list of vectors representing the normal directions and the positions
- Parameters:
us (Iterable[float |int]) – the u parametric locations to compute the normal at.
vs (Iterable[float |int]) – the v parametric locations to compute the normal at.
- Return type:
- paramAt(pt:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Tuple[float,float][source]
Computes the (u,v) pair closest to a given vector.
- Returns:
(u, v) tuple
- Parameters:
pt (a vector that lies on orclose to the surface.) – the location to compute the normal at.
- Return type:
Tuple[float, float]
- params(pts:Iterable[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]],tol:float=1e-09)→Tuple[List[float],List[float]][source]
Computes (u,v) pairs closest to given vectors.
- Returns:
list of (u, v) tuples
- Parameters:
pts (a list ofvectors that lie on the surface.) – the points to compute the normals at.
tol (float)
- Return type:
Tuple[List[float],List[float]]
- positionAt(u:float|int,v:float|int)→Vector[source]
Computes the position vector at the desired location in the u,v parameter space.
- Returns:
a vector representing the position
- Parameters:
u (float |int) – the u parametric location to compute the normal at.
v (float |int) – the v parametric location to compute the normal at.
- Return type:
- positions(uvs:Iterable[Tuple[int|float,int|float]])→List[Vector][source]
Computes position vectors at the desired locations in the u,v parameter space.
- Returns:
list of vectors corresponding to the requested u,v positions
- Parameters:
uvs (Iterable[Tuple[int |float,int |float]]) – iterable of u,v pairs.
- Return type:
List[Vector]
- thicken(thickness:float)→Solid[source]
Return a thickened face
- Parameters:
thickness (float)
- Return type:
- toArcs(tolerance:float=0.001)→Face[source]
Approximate planar face with arcs and straight line segments.
- Parameters:
tolerance (float) – Approximation tolerance.
- Return type:
- toPln()→gp_Pln[source]
Convert this face to a gp_Pln.
Note the Location of the resulting plane may not equal the center of this face,however the resulting plane will still contain the center of this face.
- Return type:
gp_Pln
- trim(outer:Wire,*inner:Wire)→Self[source]
- trim(u0:float|int,u1:float|int,v0:float|int,v1:float|int,tol:float|int=1e-06)→Self
- trim(pt1:Tuple[int|float,int|float],pt2:Tuple[int|float,int|float],pt3:Tuple[int|float,int|float],*pts:Tuple[int|float,int|float])→Self
Trim the face in the (u,v) space to (u0, u1)x(v1, v2).
NB: this operation is done on the base geometry.
Trim the face using a polyline defined in the (u,v) space.
Trim using wires. The provided wires need to have a pcurve on self.
- Parameters:
u0 (float |int)
u1 (float |int)
v0 (float |int)
v1 (float |int)
tol (float |int)
- Return type:
Self
- classcadquery.occ_impl.shapes.Mixin1DProtocol(wrapped:TopoDS_Shape)[source]
Bases:
ShapeProtocol,Protocol- Parameters:
wrapped (TopoDS_Shape)
- classcadquery.occ_impl.shapes.Shape(obj:TopoDS_Shape)[source]
Bases:
objectRepresents a shape in the system. Wraps TopoDS_Shape.
- Parameters:
obj (TopoDS_Shape)
- BoundingBox(tolerance:float|None=None)→BoundBox[source]
Create a bounding box for this Shape.
- Parameters:
tolerance (float |None) – Tolerance value passed to
BoundBox- Returns:
A
BoundBoxobject for this Shape- Return type:
- CenterOfBoundBox(tolerance:float|None=None)→Vector[source]
- Parameters:
tolerance (float |None) – Tolerance passed to the
BoundingBox()method- Returns:
Center of the bounding box of this shape
- Return type:
- staticCombinedCenter(objects:Iterable[Shape])→Vector[source]
Calculates the center of mass of multiple objects.
- staticCombinedCenterOfBoundBox(objects:List[Shape])→Vector[source]
Calculates the center of a bounding box of multiple objects.
- CompSolids()→List[CompSolid][source]
- Returns:
All the compsolids in this Shape
- Return type:
List[CompSolid]
- Compounds()→List[Compound][source]
- Returns:
All the compounds in this Shape
- Return type:
List[Compound]
- Volume(tol:float|None=None)→float[source]
- Returns:
The volume of this Shape
- Parameters:
tol (float |None)
- Return type:
float
- ancestors(shape:Shape,kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'])→Compound[source]
Iterate over ancestors, i.e. shapes of same kind within shape that contain self.
- classmethodcast(obj:TopoDS_Shape,forConstruction:bool=False)→Shape[source]
Returns the right type of wrapper, given a OCCT object
- Parameters:
obj (TopoDS_Shape)
forConstruction (bool)
- Return type:
- staticcomputeMass(obj:Shape,tol:float|None=None)→float[source]
Calculates the ‘mass’ of an object.
- Parameters:
obj (Shape) – Compute the mass of this object
tol (float |None) – Numerical integration tolerance (optional).
- Return type:
float
- copy(mesh:bool=False)→T[source]
Creates a new object that is a copy of this object.
- Parameters:
self (T)
mesh (bool) – should I copy the triangulation too (default: False)
- Returns:
a copy of the object
- Return type:
T
- cut(*toCut:Shape,tol:float|None=None)→Shape[source]
Remove the positional arguments from this Shape.
- distance(other:Shape)→float[source]
Minimal distance between two shapes
- Parameters:
other (Shape)
- Return type:
float
- distances(*others:Shape)→Iterator[float][source]
Minimal distances to between self and other shapes
- Parameters:
others (Shape)
- Return type:
Iterator[float]
- export(fname:str,tolerance:float=0.1,angularTolerance:float=0.1,opt:Dict[str,Any]|None=None)[source]
Export Shape to file.
- Parameters:
self (T)
fname (str)
tolerance (float)
angularTolerance (float)
opt (Dict[str,Any]|None)
- exportBin(f:str|BytesIO)→bool[source]
Export this shape to a binary BREP file.
- Parameters:
f (str |BytesIO)
- Return type:
bool
- exportBrep(f:str|BytesIO)→bool[source]
Export this shape to a BREP file
- Parameters:
f (str |BytesIO)
- Return type:
bool
- exportStep(fileName:str,**kwargs)→IFSelect_ReturnStatus[source]
Export this shape to a STEP file.
kwargs is used to provide optional keyword arguments to configure the exporter.
- Parameters:
fileName (str) – Path and filename for writing.
write_pcurves (bool) –
Enable or disable writing parametric curves to the STEP file. Default True.
If False, writes STEP file without pcurves. This decreases the size of the resulting STEP file.
precision_mode (int) – Controls the uncertainty value for STEP entities. Specify -1, 0, or 1. Default 0.See OCCT documentation.
- Return type:
IFSelect_ReturnStatus
- exportStl(fileName:str,tolerance:float=0.001,angularTolerance:float=0.1,ascii:bool=False,relative:bool=True,parallel:bool=True)→bool[source]
Exports a shape to a specified STL file.
- Parameters:
fileName (str) – The path and file name to write the STL output to.
tolerance (float) – A linear deflection setting which limits the distance between a curve and its tessellation.Setting this value too low will result in large meshes that can consume computing resources.Setting the value too high can result in meshes with a level of detail that is too low.Default is 1e-3, which is a good starting point for a range of cases.
angularTolerance (float) – Angular deflection setting which limits the angle between subsequent segments in a polyline. Default is 0.1.
ascii (bool) – Export the file as ASCII (True) or binary (False) STL format. Default is binary.
relative (bool) – If True, tolerance will be scaled by the size of the edge being meshed. Default is True.Setting this value to True may cause large features to become faceted, or small features dense.
parallel (bool) – If True, OCCT will use parallel processing to mesh the shape. Default is True.
- Return type:
bool
- facesIntersectedByLine(point:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],axis:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],tol:float=0.0001,direction:Literal['AlongAxis','Opposite']|None=None)[source]
Computes the intersections between the provided line and the faces of this Shape
- Parameters:
point (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – Base point for defining a line
axis (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – Axis on which the line rests
tol (float) – Intersection tolerance
direction (Literal['AlongAxis','Opposite']|None) – Valid values: “AlongAxis”, “Opposite”;If specified, will ignore all faces that are not in the specified directionincluding the face where the point lies if it is the case
- Returns:
A list of intersected faces sorted by distance from point
- fuse(*toFuse:Shape,glue:bool=False,tol:float|None=None)→Shape[source]
Fuse the positional arguments with this Shape.
- geomType()→Literal['Vertex','Wire','Shell','Solid','Compound','PLANE','CYLINDER','CONE','SPHERE','TORUS','BEZIER','BSPLINE','REVOLUTION','EXTRUSION','OFFSET','OTHER','LINE','CIRCLE','ELLIPSE','HYPERBOLA','PARABOLA'][source]
Gets the underlying geometry type.
Implementations can return any values desired, but the values the useruses in type filters should correspond to these.
As an example, if a user does:
CQ(object).faces("%mytype")
The expectation is that the geomType attribute will return ‘mytype’
The return values depend on the type of the shape:
Vertex: always ‘Vertex’Edge: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER,BSPLINE, OFFSET, OTHERFace: PLANE, CYLINDER, CONE, SPHERE, TORUS, BEZIER, BSPLINE,REVOLUTION, EXTRUSION, OFFSET, OTHERSolid: ‘Solid’Shell: ‘Shell’Compound: ‘Compound’Wire: ‘Wire’- Returns:
A string according to the geometry type
- Return type:
Literal[‘Vertex’, ‘Wire’, ‘Shell’, ‘Solid’, ‘Compound’, ‘PLANE’, ‘CYLINDER’, ‘CONE’, ‘SPHERE’, ‘TORUS’, ‘BEZIER’, ‘BSPLINE’, ‘REVOLUTION’, ‘EXTRUSION’, ‘OFFSET’, ‘OTHER’, ‘LINE’, ‘CIRCLE’, ‘ELLIPSE’, ‘HYPERBOLA’, ‘PARABOLA’]
- hashCode()→int[source]
Returns a hashed value denoting this shape. It is computed from theTShape and the Location. The Orientation is not used.
- Return type:
int
- classmethodimportBin(f:str|BytesIO)→Shape[source]
Import shape from a binary BREP file.
- Parameters:
f (str |BytesIO)
- Return type:
- classmethodimportBrep(f:str|BytesIO)→Shape[source]
Import shape from a BREP file
- Parameters:
f (str |BytesIO)
- Return type:
- intersect(*toIntersect:Shape,tol:float|None=None)→Shape[source]
Intersection of the positional arguments and this Shape.
- isEqual(other:Shape)→bool[source]
Returns True if two shapes are equal, i.e. if they share the sameTShape with the same Locations and Orientations. Also see
isSame().- Parameters:
other (Shape)
- Return type:
bool
- isNull()→bool[source]
Returns true if this shape is null. In other words, it references nounderlying shape with the potential to be given a location and anorientation.
- Return type:
bool
- isSame(other:Shape)→bool[source]
Returns True if other and this shape are same, i.e. if they share thesame TShape with the same Locations. Orientations may differ. Also see
isEqual()- Parameters:
other (Shape)
- Return type:
bool
- isValid()→bool[source]
Returns True if no defect is detected on the shape S or any of itssubshapes. See the OCCT docs on BRepCheck_Analyzer::IsValid for a fulldescription of what is checked.
- Return type:
bool
- locate(loc:Location)→T[source]
Apply a location in absolute sense to self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- located(loc:Location)→T[source]
Apply a location in absolute sense to a copy of self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- staticmatrixOfInertia(obj:Shape)→List[List[float]][source]
Calculates the matrix of inertia of an object.Since the part’s density is unknown, this result is inertia/density with units of [1/length].:param obj: Compute the matrix of inertia of this object
- Parameters:
obj (Shape)
- Return type:
List[List[float]]
- mesh(tolerance:float,angularTolerance:float=0.1)[source]
Generate triangulation if none exists.
- Parameters:
tolerance (float)
angularTolerance (float)
- mirror(mirrorPlane:Literal['XY','YX','XZ','ZX','YZ','ZY']|Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]='XY',basePointVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]=(0,0,0))→Shape[source]
Applies a mirror transform to this Shape. Does not duplicate objectsabout the plane.
- Parameters:
mirrorPlane (Literal['XY','YX','XZ','ZX','YZ','ZY']|~cadquery.occ_impl.geom.Vector |~typing.Tuple[int |float,int |float]|~typing.Tuple[int |float,int |float,int |float]) – The direction of the plane to mirror about - one of‘XY’, ‘XZ’ or ‘YZ’
basePointVector (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – The origin of the plane to mirror about
- Returns:
The mirrored shape
- Return type:
- move(x:float|int=0,y:float|int=0,z:float|int=0,rx:float|int=0,ry:float|int=0,rz:float|int=0)→T[source]
- move(loc:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T
- move(loc:Location)→T
Apply a location in relative sense (i.e. update current location) to self.
Apply translation and rotation in relative sense (i.e. update current location) to self.
Apply a VectorLike in relative sense (i.e. update current location) to self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- moved(loc:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T[source]
- moved(loc1:Location,loc2:Location,*locs:Location)→T
- moved(loc1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],loc2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],*locs:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T
- moved(locs:Sequence[Location])→T
- moved(loc:Location)→T
- moved(x:float|int=0,y:float|int=0,z:float|int=0,rx:float|int=0,ry:float|int=0,rz:float|int=0)→T
- moved(loc:Sequence[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]])→T
Apply a location in relative sense (i.e. update current location) to a copy of self.
Apply multiple locations.
Apply multiple locations.
Apply translation and rotation in relative sense to a copy of self.
Apply a VectorLike in relative sense to a copy of self.
Apply multiple VectorLikes in relative sense to a copy of self.
Apply multiple VectorLikes in relative sense to a copy of self.
- Parameters:
self (T)
loc (Location)
- Return type:
T
- rotate(startVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],endVector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angleDegrees:float)→T[source]
Rotates a shape around an axis.
- Parameters:
self (T)
startVector (either a 3-tuple ora Vector) – start point of rotation axis
endVector (either a 3-tuple ora Vector) – end point of rotation axis
angleDegrees (float) – angle to rotate, in degrees
- Returns:
a copy of the shape, rotated
- Return type:
T
- scale(factor:float)→Shape[source]
Scales this shape through a transformation.
- Parameters:
factor (float)
- Return type:
- siblings(shape:Shape,kind:Literal['Vertex','Edge','Wire','Face','Shell','Solid','CompSolid','Compound'],level:int=1)→Compound[source]
Iterate over siblings, i.e. shapes within shape that share subshapes of kind with self.
- toSplines(degree:int=3,tolerance:float=0.001,nurbs:bool=False)→T[source]
Approximate shape with b-splines of the specified degree.
- Parameters:
self (T)
degree (int) – Maximum degree.
tolerance (float) – Approximation tolerance.
nurbs (bool) – Use rational splines.
- Return type:
T
- toVtkPolyData(tolerance:float|None=None,angularTolerance:float|None=None,normals:bool=False)→vtkPolyData[source]
Convert shape to vtkPolyData
- Parameters:
tolerance (float |None)
angularTolerance (float |None)
normals (bool)
- Return type:
vtkPolyData
- transformGeometry(tMatrix:Matrix)→Shape[source]
Transforms this shape by tMatrix.
WARNING: transformGeometry will sometimes convert lines and circles tosplines, but it also has the ability to handle skew and stretchingtransformations.
If your transformation is only translation and rotation, it is safer touse
transformShape(), which doesn’t change the underlying typeof the geometry, but cannot handle skew transformations.
- transformShape(tMatrix:Matrix)→Shape[source]
Transforms this Shape by tMatrix. Also see
transformGeometry().
- translate(vector:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→T[source]
Translates this shape through a transformation.
- Parameters:
self (T)
vector (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
- Return type:
T
- classcadquery.occ_impl.shapes.ShapeProtocol(wrapped:TopoDS_Shape)[source]
Bases:
Protocol- Parameters:
wrapped (TopoDS_Shape)
- classcadquery.occ_impl.shapes.Shell(obj:TopoDS_Shape)[source]
Bases:
Shapethe outer boundary of a surface
- Parameters:
obj (TopoDS_Shape)
- classcadquery.occ_impl.shapes.Solid(obj:TopoDS_Shape)[source]
a single solid
- Parameters:
obj (TopoDS_Shape)
- classmethodextrudeLinear(face:Face,vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],taper:float|int=0)→Solid[source]
- classmethodextrudeLinear(outerWire:Wire,innerWires:List[Wire],vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],taper:float|int=0)→Solid
Attempt to extrude the list of wires into a prismatic solid in the provided direction
- Parameters:
- Returns:
a Solid object
- Return type:
The wires must not intersect
Extruding wires is very non-trivial. Nested wires imply very different geometry, andthere are many geometries that are invalid. In general, the following conditions must be met:
all wires must be closed
there cannot be any intersecting or self-intersecting wires
wires must be listed from outside in
more than one levels of nesting is not supported reliably
This method will attempt to sort the wires, but there is much work remaining to make this methodreliable.
- classmethodextrudeLinearWithRotation(outerWire:Wire,innerWires:List[Wire],vecCenter:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angleDegrees:float|int)→Solid[source]
- classmethodextrudeLinearWithRotation(face:Face,vecCenter:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],vecNormal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angleDegrees:float|int)→Solid
Creates a ‘twisted prism’ by extruding, while simultaneously rotating around the extrusion vector.
Though the signature may appear to be similar enough to extrudeLinear to merit combining them, theconstruction methods used here are different enough that they should be separate.
At a high level, the steps followed are:
accept a set of wires
create another set of wires like this one, but which are transformed and rotated
create a ruledSurface between the sets of wires
create a shell and compute the resulting object
- Parameters:
outerWire (Wire) – the outermost wire
innerWires (List[Wire]) – a list of inner wires
vecCenter (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – the center point about which to rotate. the axis of rotation is defined byvecNormal, located at vecCenter.
vecNormal (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – a vector along which to extrude the wires
angleDegrees (float |int) – the angle to rotate through while extruding
- Returns:
a Solid object
- Return type:
- classmethodinterpPlate(surf_edges,surf_pts,thickness,degree=3,nbPtsOnCur=15,nbIter=2,anisotropy=False,tol2d=1e-05,tol3d=0.0001,tolAng=0.01,tolCurv=0.1,maxDeg=8,maxSegments=9)→Solid|Face[source]
Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and going through ‘surf_pts’ points.
- Parameters:
surf_edges – list of [x,y,z] float ordered coordinatesor list of ordered or unordered wires
surf_pts – list of [x,y,z] float coordinates (uses only edges if [])
thickness – thickness may be negative or positive depending on direction, (returns 2D surface if 0)
degree – >=2
nbPtsOnCur – number of points on curve >= 15
nbIter – number of iterations >= 2
anisotropy – bool Anisotropy
tol2d – 2D tolerance >0
tol3d – 3D tolerance >0
tolAng – angular tolerance
tolCurv – tolerance for curvature >0
maxDeg – highest polynomial degree >= 2
maxSegments – greatest number of segments >= 2
- Return type:
- staticisSolid(obj:Shape)→bool[source]
Returns true if the object is a solid, false otherwise
- Parameters:
obj (Shape)
- Return type:
bool
- classmethodmakeBox(length,width,height,[pnt,dir])--Makeaboxlocatedinpntwiththedimensions(length,width,height)[source]
By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
- classmethodmakeCone(radius1:float,radius2:float,height:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees:float=360)→Solid[source]
Make a cone with given radii and heightBy default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360
- classmethodmakeCylinder(radius:float,height:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees:float=360)→Solid[source]
makeCylinder(radius,height,[pnt,dir,angle]) –Make a cylinder with a given radius and heightBy default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360
- classmethodmakeLoft(listOfWire:List[Wire],ruled:bool=False)→Solid[source]
makes a loft from a list of wiresThe wires will be converted into faces when possible– it is presumed that nobody ever actuallywants to make an infinitely thin shell for a real FreeCADPart.
- classmethodmakeSphere(radius:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees1:float=0,angleDegrees2:float=90,angleDegrees3:float=360)→Shape[source]
Make a sphere with a given radiusBy default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=0, angle2=90 and angle3=360
- classmethodmakeTorus(radius1:float,radius2:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angleDegrees1:float=0,angleDegrees2:float=360)→Solid[source]
makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]) –Make a torus with a given radii and anglesBy default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0,angle1=360 and angle=360
- classmethodmakeWedge(dx:float,dy:float,dz:float,xmin:float,zmin:float,xmax:float,zmax:float,pnt:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0))→Solid[source]
Make a wedge located in pntBy default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
- classmethodrevolve(outerWire:Wire,innerWires:List[Wire],angleDegrees:float|int,axisStart:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],axisEnd:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Solid[source]
- classmethodrevolve(face:Face,angleDegrees:float|int,axisStart:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],axisEnd:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Solid
Attempt to revolve the list of wires into a solid in the provided direction
- Parameters:
outerWire (Wire) – the outermost wire
innerWires (List[Wire]) – a list of inner wires
angleDegrees (float,anything less than 360 degrees will leave the shape open) – the angle to revolve through.
axisStart (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – the start point of the axis of rotation
axisEnd (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – the end point of the axis of rotation
- Returns:
a Solid object
- Return type:
The wires must not intersect
all wires must be closed
there cannot be any intersecting or self-intersecting wires
wires must be listed from outside in
more than one levels of nesting is not supported reliably
the wire(s) that you’re revolving cannot be centered
This method will attempt to sort the wires, but there is much work remaining to make this methodreliable.
- classmethodsweep(outerWire:Wire,innerWires:List[Wire],path:Wire|Edge,makeSolid:bool=True,isFrenet:bool=False,mode:Vector|Wire|Edge|None=None,transitionMode:Literal['transformed','round','right']='transformed')→Shape[source]
- classmethodsweep(face:Face,path:Wire|Edge,makeSolid:bool=True,isFrenet:bool=False,mode:Vector|Wire|Edge|None=None,transitionMode:Literal['transformed','round','right']='transformed')→Shape
Attempt to sweep the list of wires into a prismatic solid along the provided path
- Parameters:
outerWire (Wire) – the outermost wire
innerWires (List[Wire]) – a list of inner wires
path (Wire |Edge) – The wire to sweep the face resulting from the wires over
makeSolid (bool) – return Solid or Shell (default True)
isFrenet (bool) – Frenet mode (default False)
mode (Vector |Wire |Edge |None) – additional sweep mode parameters
transitionMode (Literal['transformed','round','right']) – handling of profile orientation at C1 path discontinuities.Possible values are {‘transformed’,’round’, ‘right’} (default: ‘right’).
- Returns:
a Solid object
- Return type:
- classcadquery.occ_impl.shapes.Vertex(obj:TopoDS_Shape,forConstruction:bool=False)[source]
Bases:
ShapeA Single Point in Space
- Parameters:
obj (TopoDS_Shape)
forConstruction (bool)
- classcadquery.occ_impl.shapes.Wire(obj:TopoDS_Shape)[source]
A series of connected, ordered Edges, that typically bounds a Face
- Parameters:
obj (TopoDS_Shape)
- classmethodassembleEdges(listOfEdges:Iterable[Edge])→Wire[source]
Attempts to build a wire that consists of the edges in the provided list
- Parameters:
cls
listOfEdges (Iterable[Edge]) – a list of Edge objects. The edges are not to be consecutive.
- Returns:
a wire with the edges assembled
- Return type:
BRepBuilderAPI_MakeWire::Error() values:
BRepBuilderAPI_WireDone = 0
BRepBuilderAPI_EmptyWire = 1
BRepBuilderAPI_DisconnectedWire = 2
BRepBuilderAPI_NonManifoldWire = 3
- classmethodcombine(listOfWires:Iterable[Wire|Edge],tol:float=1e-09)→List[Wire][source]
Attempt to combine a list of wires and edges into a new wire.
- fillet(radius:float,vertices:Iterable[Vertex]|None=None)→Wire[source]
Apply 2D or 3D fillet to a wire
- classmethodmakeCircle(radius:float,center:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],normal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Wire[source]
Makes a Circle centered at the provided point, having normal in the provided direction
- Parameters:
radius (float) – floating point radius of the circle, must be > 0
center (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the center of the circle
normal (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the direction of the plane the circle should lie in
- Return type:
- classmethodmakeEllipse(x_radius:float,y_radius:float,center:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],normal:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],xDir:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],angle1:float=360.0,angle2:float=360.0,rotation_angle:float=0.0,closed:bool=True)→Wire[source]
Makes an Ellipse centered at the provided point, having normal in the provided direction
- Parameters:
x_radius (float) – floating point major radius of the ellipse (x-axis), must be > 0
y_radius (float) – floating point minor radius of the ellipse (y-axis), must be > 0
center (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the center of the circle
normal (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – vector representing the direction of the plane the circle should lie in
angle1 (float) – start angle of arc
angle2 (float) – end angle of arc
rotation_angle (float) – angle to rotate the created ellipse / arc
xDir (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float])
closed (bool)
- Return type:
- classmethodmakeHelix(pitch:float,height:float,radius:float,center:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,0.0),dir:~cadquery.occ_impl.geom.Vector|~typing.Tuple[int|float,int|float]|~typing.Tuple[int|float,int|float,int|float]=Vector:(0.0,0.0,1.0),angle:float=360.0,lefthand:bool=False)→Wire[source]
Make a helix with a given pitch, height and radiusBy default a cylindrical surface is used to create the helix. Ifthe fourth parameter is set (the apex given in degree) a conical surface is used instead’
- classmethodmakePolygon(listOfVertices:Iterable[Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]],forConstruction:bool=False,close:bool=False)→Wire[source]
Construct a polygonal wire from points.
- cadquery.occ_impl.shapes.box(w:float,l:float,h:float)→Shape[source]
Construct a solid box.
- Parameters:
w (float)
l (float)
h (float)
- Return type:
- cadquery.occ_impl.shapes.cap(s:Shape,ctx:Shape,constraints:Sequence[Shape|Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]]=())→Shape[source]
Fill edges/wire possibly obeying constraints and try to connect smoothly to the context shape.
- cadquery.occ_impl.shapes.chamfer(s:Shape,e:Shape,d:float)→Shape[source]
Chamfer selected edges in a given shell or solid.
- cadquery.occ_impl.shapes.check(s:Shape,results:List[Tuple[List[Shape],Any]]|None=None,tol:float|None=None)→bool[source]
Check if a shape is valid.
- cadquery.occ_impl.shapes.circle(r:float)→Shape[source]
Construct a circle.
- Parameters:
r (float)
- Return type:
- cadquery.occ_impl.shapes.closest(s1:Shape,s2:Shape)→Tuple[Vector,Vector][source]
Closest points between two shapes.
- cadquery.occ_impl.shapes.compound(*s:cadquery.occ_impl.shapes.Shape)→cadquery.occ_impl.shapes.Shape[source]
Build compound from shapes.
compound(s: Sequence[cadquery.occ_impl.shapes.Shape]) -> cadquery.occ_impl.shapes.Shape
Build compound from a sequence of shapes.
- cadquery.occ_impl.shapes.cone(d1:float|int,d2:float|int,h:float|int)→cadquery.occ_impl.shapes.Shape[source]
Construct a partial solid cone.
cone(d: Union[float, int], h: Union[float, int]) -> cadquery.occ_impl.shapes.Shape
Construct a full solid cone.
- Parameters:
d1 (float |int)
d2 (float |int)
h (float |int)
- Return type:
- cadquery.occ_impl.shapes.cut(s1:Shape,s2:Shape,tol:float=0.0,glue:Literal['partial','full',None]=None)→Shape[source]
Subtract two shapes.
- cadquery.occ_impl.shapes.cylinder(d:float,h:float)→Shape[source]
Construct a solid cylinder.
- Parameters:
d (float)
h (float)
- Return type:
- cadquery.occ_impl.shapes.downcast(obj:TopoDS_Shape)→TopoDS_Shape[source]
Downcasts a TopoDS object to suitable specialized type
- Parameters:
obj (TopoDS_Shape)
- Return type:
TopoDS_Shape
- cadquery.occ_impl.shapes.edgeOn(base:cadquery.occ_impl.shapes.Shape,pts:Sequence[Tuple[int|float,int|float]],periodic:bool=False,tol:float=1e-06)→cadquery.occ_impl.shapes.Shape[source]
Build an edge on a face from points in (u,v) space.
_(fbase: cadquery.occ_impl.shapes.Shape, edg: cadquery.occ_impl.shapes.Shape,*edgs: cadquery.occ_impl.shapes.Shape, tol: float = 1e-06, N: int = 20)
Map one or more edges onto a base face in the u,v space.
- cadquery.occ_impl.shapes.edgesToWires(edges:Iterable[Edge],tol:float=1e-06)→List[Wire][source]
Convert edges to a list of wires.
- cadquery.occ_impl.shapes.ellipse(r1:float,r2:float)→Shape[source]
Construct an ellipse.
- Parameters:
r1 (float)
r2 (float)
- Return type:
- cadquery.occ_impl.shapes.extrude(s:Shape,d:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Shape[source]
Extrude a shape.
- cadquery.occ_impl.shapes.face(*s:cadquery.occ_impl.shapes.Shape)→cadquery.occ_impl.shapes.Shape[source]
Build face from edges or wires.
face(s: Sequence[cadquery.occ_impl.shapes.Shape]) -> cadquery.occ_impl.shapes.Shape
Build face from a sequence of edges or wires.
- cadquery.occ_impl.shapes.faceOn(base:Shape,*fcs:Shape,tol=1e-06,N=20)→Shape[source]
Build face(s) on base by mapping planar face(s) onto the (u,v) space of base.
- cadquery.occ_impl.shapes.fill(s:Shape,constraints:Sequence[Shape|Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float]]=())→Shape[source]
Fill edges/wire possibly obeying constraints.
- cadquery.occ_impl.shapes.fillet(s:Shape,e:Shape,r:float)→Shape[source]
Fillet selected edges in a given shell or solid.
- cadquery.occ_impl.shapes.fix(obj:TopoDS_Shape)→TopoDS_Shape[source]
Fix a TopoDS object to suitable specialized type
- Parameters:
obj (TopoDS_Shape)
- Return type:
TopoDS_Shape
- cadquery.occ_impl.shapes.fuse(s1:Shape,s2:Shape,*shapes:Shape,tol:float=0.0,glue:Literal['partial','full',None]=None)→Shape[source]
Fuse at least two shapes.
- cadquery.occ_impl.shapes.imprint(*shapes:Shape,tol:float=0.0,glue:Literal['partial','full',None]='full',history:Dict[Shape|str,Shape]|None=None)→Shape[source]
Imprint arbitrary number of shapes.
- cadquery.occ_impl.shapes.intersect(s1:Shape,s2:Shape,tol:float=0.0,glue:Literal['partial','full',None]=None)→Shape[source]
Intersect two shapes.
- cadquery.occ_impl.shapes.isSubshape(s1:Shape,s2:Shape)→bool[source]
Check if s1 is a subshape of s2.
- cadquery.occ_impl.shapes.loft(s:Sequence[cadquery.occ_impl.shapes.Shape],cap:bool=False,ruled:bool=False,continuity:Literal['C1','C2','C3']='C2',parametrization:Literal['uniform','chordal','centripetal']='uniform',degree:int=3,compat:bool=True,smoothing:bool=False,weights:Tuple[float,float,float]=(1,1,1))→cadquery.occ_impl.shapes.Shape[source]
Loft edges, wires or faces. For faces cap has no effect. Do not mix faces with other types.
loft(*s: cadquery.occ_impl.shapes.Shape, cap: bool = False, ruled: bool = False, continuity: Literal[‘C1’, ‘C2’, ‘C3’] = ‘C2’, parametrization: Literal[‘uniform’, ‘chordal’, ‘centripetal’] = ‘uniform’, degree: int = 3, compat: bool = True, smoothing: bool = False, weights: Tuple[float, float, float] = (1, 1, 1)) -> cadquery.occ_impl.shapes.Shape
Variadic loft overload.
- cadquery.occ_impl.shapes.offset(s:Shape,t:float,cap=True,both:bool=False,tol:float=1e-06)→Shape[source]
Offset or thicken faces or shells.
- cadquery.occ_impl.shapes.plane(w:float|int,l:float|int)→cadquery.occ_impl.shapes.Shape[source]
Construct a finite planar face.
plane() -> cadquery.occ_impl.shapes.Shape
Construct an infinite planar face.
This is a crude approximation. Truly infinite faces in OCCT do not work asexpected in all contexts.
- Parameters:
w (float |int)
l (float |int)
- Return type:
- cadquery.occ_impl.shapes.polygon(*pts:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Shape[source]
Construct a polygon (closed polyline) from points.
- cadquery.occ_impl.shapes.polyline(*pts:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Shape[source]
Construct a polyline from points.
- cadquery.occ_impl.shapes.project(s:Shape,base:Shape,continuity:Literal['C1','C2','C3']='C2',degree:int=3,maxseg:int=30,tol:float=0.0001)[source]
Project s onto base using normal projection.
- cadquery.occ_impl.shapes.rect(w:float,h:float)→Shape[source]
Construct a rectangle.
- Parameters:
w (float)
h (float)
- Return type:
- cadquery.occ_impl.shapes.revolve(s:Shape,p:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],d:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],a:float=360)[source]
Revolve a shape.
- cadquery.occ_impl.shapes.segment(p1:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],p2:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float])→Shape[source]
Construct a segment from two points.
- cadquery.occ_impl.shapes.setThreads(n:int)[source]
Set number of threads to be used by boolean operations.
- Parameters:
n (int)
- cadquery.occ_impl.shapes.shell(*s:cadquery.occ_impl.shapes.Shape,tol:float=1e-06,manifold:bool=True,ctx:Sequence[cadquery.occ_impl.shapes.Shape]|cadquery.occ_impl.shapes.Shape|NoneType=None,history:Dict[cadquery.occ_impl.shapes.Shape|str,cadquery.occ_impl.shapes.Shape]|None=None)→cadquery.occ_impl.shapes.Shape[source]
Build shell from faces. If ctx is specified, local sewing is performed.
shell(s: Sequence[cadquery.occ_impl.shapes.Shape], tol: float = 1e-06, manifold: bool = True, ctx: Union[Sequence[cadquery.occ_impl.shapes.Shape], cadquery.occ_impl.shapes.Shape, NoneType] = None, history: Optional[Dict[Union[cadquery.occ_impl.shapes.Shape, str], cadquery.occ_impl.shapes.Shape]] = None) -> cadquery.occ_impl.shapes.Shape
Build shell from a sequence of faces. If ctx is specified, local sewing is performed.
- cadquery.occ_impl.shapes.solid(s1:cadquery.occ_impl.shapes.Shape,*sn:cadquery.occ_impl.shapes.Shape,tol:float=1e-06,history:Dict[cadquery.occ_impl.shapes.Shape|str,cadquery.occ_impl.shapes.Shape]|None=None)→cadquery.occ_impl.shapes.Shape[source]
Build solid from faces or shells.
solid(s: Sequence[cadquery.occ_impl.shapes.Shape], inner: Optional[Sequence[cadquery.occ_impl.shapes.Shape]] = None, tol: float = 1e-06, history: Optional[Dict[Union[cadquery.occ_impl.shapes.Shape, str], cadquery.occ_impl.shapes.Shape]] = None) -> cadquery.occ_impl.shapes.Shape
Build solid from a sequence of faces.
- cadquery.occ_impl.shapes.sortWiresByBuildOrder(wireList:List[Wire])→List[List[Wire]][source]
Tries to determine how wires should be combined into faces.
- Assume:
The wires make up one or more faces, which could have ‘holes’Outer wires are listed ahead of inner wiresthere are no wires inside wires inside wires( IE, islands – we can deal with that later on )none of the wires are construction wires
- Compute:
one or more sets of wires, with the outer wire listed first, and innerones
Returns, list of lists.
- cadquery.occ_impl.shapes.sphere(d:float)→Shape[source]
Construct a solid sphere.
- Parameters:
d (float)
- Return type:
- cadquery.occ_impl.shapes.spline(*pts:ForwardRef('Vector')|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],tol:float=1e-06,periodic:bool=False)→cadquery.occ_impl.shapes.Shape[source]
Construct a spline from points.
spline(pts: Sequence[Union[ForwardRef(‘Vector’), Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]], tgts: Optional[Sequence[Union[ForwardRef(‘Vector’), Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]]] = None, params: Optional[Sequence[float]] = None, tol: float = 1e-06, periodic: bool = False, scale: bool = True) -> cadquery.occ_impl.shapes.Shape
Construct a spline from a sequence points.
- cadquery.occ_impl.shapes.split(s1:Shape,s2:Shape,tol:float=0.0)→Shape[source]
Split one shape with another.
- cadquery.occ_impl.shapes.sweep(s:cadquery.occ_impl.shapes.Shape,path:cadquery.occ_impl.shapes.Shape,aux:cadquery.occ_impl.shapes.Shape|None=None,cap:bool=False)→cadquery.occ_impl.shapes.Shape[source]
Sweep edge, wire or face along a path. For faces cap has no effect.Do not mix faces with other types.
sweep(s: Sequence[cadquery.occ_impl.shapes.Shape], path: cadquery.occ_impl.shapes.Shape, aux: Optional[cadquery.occ_impl.shapes.Shape] = None, cap: bool = False) -> cadquery.occ_impl.shapes.Shape
Sweep edges, wires or faces along a path, multiple sections are supported.For faces cap has no effect. Do not mix faces with other types.
- cadquery.occ_impl.shapes.text(txt:str,size:float|int,font:str='Arial',path:str|None=None,kind:Literal['regular','bold','italic']='regular',halign:Literal['center','left','right']='center',valign:Literal['center','top','bottom']='center')→cadquery.occ_impl.shapes.Shape[source]
Create a flat text.
text(txt: str, size: Union[float, int], spine: cadquery.occ_impl.shapes.Shape, planar: bool = False, font: str = ‘Arial’, path: Optional[str] = None, kind: Literal[‘regular’, ‘bold’, ‘italic’] = ‘regular’, halign: Literal[‘center’, ‘left’, ‘right’] = ‘center’, valign: Literal[‘center’, ‘top’, ‘bottom’] = ‘center’) -> cadquery.occ_impl.shapes.Shape
Create a text on a spine.
text(txt: str, size: Union[float, int], spine: cadquery.occ_impl.shapes.Shape, base: cadquery.occ_impl.shapes.Shape, font: str = ‘Arial’, path: Optional[str] = None, kind: Literal[‘regular’, ‘bold’, ‘italic’] = ‘regular’, halign: Literal[‘center’, ‘left’, ‘right’] = ‘center’, valign: Literal[‘center’, ‘top’, ‘bottom’] = ‘center’) -> cadquery.occ_impl.shapes.Shape
Create a text on a spine and a base surface.
- Parameters:
txt (str)
size (float |int)
font (str)
path (str |None)
kind (Literal['regular','bold','italic'])
halign (Literal['center','left','right'])
valign (Literal['center','top','bottom'])
- Return type:
- cadquery.occ_impl.shapes.torus(d1:float,d2:float)→Shape[source]
Construct a solid torus.
- Parameters:
d1 (float)
d2 (float)
- Return type:
- cadquery.occ_impl.shapes.vertex(x:float|int,y:float|int,z:float|int)→cadquery.occ_impl.shapes.Shape[source]
Construct a vertex from coordinates.
vertex(p: Union[ForwardRef(‘Vector’), Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])
Construct a vertex from VectorLike.
- Parameters:
x (float |int)
y (float |int)
z (float |int)
- Return type:
- cadquery.occ_impl.shapes.wire(*s:cadquery.occ_impl.shapes.Shape)→cadquery.occ_impl.shapes.Shape[source]
Build wire from edges.
- cadquery.occ_impl.shapes.wireOn(base:Shape,w:Shape,tol=1e-06,N=20)→Shape[source]
Map a wire onto a base face in the u,v space.
- cadquery.occ_impl.shapes.wiresToFaces(wireList:List[Wire])→List[Face][source]
Convert wires to a list of faces.
- classcadquery.occ_impl.shapes.Mixin1D[source]
Bases:
object- bounds()→Tuple[float,float][source]
Parametric bounds of the curve.
- Parameters:
self (Mixin1DProtocol)
- Return type:
Tuple[float, float]
- curvatureAt(d:float,mode:Literal['length','parameter']='length',resolution:float=1e-06)→float[source]
Calculate mean curvature along the underlying curve.
- Parameters:
self (Mixin1DProtocol)
d (float) – distance or parameter value
mode (Literal['length','parameter']) – position calculation mode (default: length)
resolution (float) – resolution of the calculation (default: 1e-6)
- Returns:
mean curvature value at the specified d value.
- Return type:
float
- curvatures(ds:Iterable[float],mode:Literal['length','parameter']='length',resolution:float=1e-06)→List[float][source]
Calculate mean curvatures along the underlying curve.
- Parameters:
self (Mixin1DProtocol)
d – distance or parameter values
mode (Literal['length','parameter']) – position calculation mode (default: length)
resolution (float) – resolution of the calculation (default: 1e-6)
ds (Iterable[float])
- Returns:
mean curvature value at the specified d value.
- Return type:
List[float]
- endPoint()→Vector[source]
- Returns:
a vector representing the end point of this edge.
- Parameters:
self (Mixin1DProtocol)
- Return type:
Note, circles may have the start and end points the same
- locationAt(d:float,mode:Literal['length','parameter']='length',frame:Literal['frenet','corrected']='frenet',planar:bool=False)→Location[source]
Generate a location along the underlying curve.
- Parameters:
self (Mixin1DProtocol)
d (float) – distance or parameter value
mode (Literal['length','parameter']) – position calculation mode (default: length)
frame (Literal['frenet','corrected']) – moving frame calculation method (default: frenet)
planar (bool) – planar mode
- Returns:
A Location object representing local coordinate system at the specified distance.
- Return type:
- locations(ds:Iterable[float],mode:Literal['length','parameter']='length',frame:Literal['frenet','corrected']='frenet',planar:bool=False)→List[Location][source]
Generate locations along the curve.
- Parameters:
self (Mixin1DProtocol)
ds (Iterable[float]) – distance or parameter values
mode (Literal['length','parameter']) – position calculation mode (default: length)
frame (Literal['frenet','corrected']) – moving frame calculation method (default: frenet)
planar (bool) – planar mode
- Returns:
A list of Location objects representing local coordinate systems at the specified distances.
- Return type:
List[Location]
- normal()→Vector[source]
Calculate the normal Vector. Only possible for planar curves.
- Returns:
normal vector
- Parameters:
self (Mixin1DProtocol)
- Return type:
- paramAt(d:float|int|Vector)→float[source]
Compute parameter value at the specified normalized distance or a point.
- Parameters:
self (Mixin1DProtocol)
d (float |int |Vector) – normalized distance [0, 1] or a point
- Returns:
parameter value
- Return type:
float
- params(pts:Iterable[Vector],tol=1e-06)→List[float][source]
Computes u values closest to given vectors.
- Parameters:
self (Mixin1DProtocol)
pts (Iterable[Vector]) – the points to compute the parameters at.
- Returns:
list of u values.
- Return type:
List[float]
- paramsLength(locations:Iterable[float])→List[float][source]
Computes u values at given relative lengths.
- Parameters:
self (Mixin1DProtocol)
locations (Iterable[float]) – list of distances.
pts – the points to compute the parameters at.
- Returns:
list of u values.
- Return type:
List[float]
- positionAt(d:float,mode:Literal['length','parameter']='length')→Vector[source]
Generate a position along the underlying curve.
- Parameters:
self (Mixin1DProtocol)
d (float) – distance or parameter value
mode (Literal['length','parameter']) – position calculation mode (default: length)
- Returns:
A Vector on the underlying curve located at the specified d value.
- Return type:
- positions(ds:Iterable[float],mode:Literal['length','parameter']='length')→List[Vector][source]
Generate positions along the underlying curve.
- Parameters:
self (Mixin1DProtocol)
ds (Iterable[float]) – distance or parameter values
mode (Literal['length','parameter']) – position calculation mode (default: length)
- Returns:
A list of Vector objects.
- Return type:
List[Vector]
- project(face:Face,d:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],closest:bool=True)→T1D|List[T1D][source]
Project onto a face along the specified direction.
- radius()→float[source]
Calculate the radius.
Note that when applied to a Wire, the radius is simply the radius of the first edge.
- Returns:
radius
- Raises:
ValueError – if kernel can not reduce the shape to a circular edge
- Parameters:
self (Mixin1DProtocol)
- Return type:
float
- sample(n:int|float)→Tuple[List[Vector],List[float]][source]
Sample a curve based on a number of points or deflection.
- Parameters:
self (Mixin1DProtocol)
n (int |float) – Number of positions or deflection
- Returns:
A list of Vectors and a list of parameters.
- Return type:
Tuple[List[Vector],List[float]]
- startPoint()→Vector[source]
- Returns:
a vector representing the start point of this edge
- Parameters:
self (Mixin1DProtocol)
- Return type:
Note, circles may have the start and end points the same
- tangentAt(locationParam:float=0.5,mode:Literal['length','parameter']='length')→Vector[source]
Compute tangent vector at the specified location.
- Parameters:
self (Mixin1DProtocol)
locationParam (float) – distance or parameter value (default: 0.5)
mode (Literal['length','parameter']) – position calculation mode (default: length)
- Returns:
tangent vector
- Return type:
- tangents(locations:Iterable[float],mode:Literal['length','parameter']='length')→List[Vector][source]
Compute tangent vectors at the specified locations.
- Parameters:
self (Mixin1DProtocol)
locations (Iterable[float]) – list of distances or parameters.
mode (Literal['length','parameter']) – position calculation mode (default: length).
- Returns:
list of tangent vectors
- Return type:
List[Vector]
- classcadquery.occ_impl.shapes.Mixin3D[source]
Bases:
object- chamfer(length:float,length2:float|None,edgeList:Iterable[Edge])→Any[source]
Chamfers the specified edges of this solid.
- Parameters:
self (Any)
length (float) – length > 0, the length (length) of the chamfer
length2 (float |None) – length2 > 0, optional parameter for asymmetrical chamfer. Should beNone if not required.
edgeList (Iterable[Edge]) – a list of Edge objects, which must belong to this solid
- Returns:
Chamfered solid
- Return type:
Any
- dprism(basis:Face|None,faces:List[Face],depth:float|int|None=None,taper:float|int=0,upToFace:Face|None=None,thruAll:bool=True,additive:bool=True)→Solid[source]
- dprism(basis:Face|None,profiles:List[Wire],depth:float|int|None=None,taper:float|int=0,upToFace:Face|None=None,thruAll:bool=True,additive:bool=True)→Solid
Make a prismatic feature (additive or subtractive)
- Parameters:
- Returns:
a Solid object
- Return type:
- fillet(radius:float,edgeList:Iterable[Edge])→Any[source]
Fillets the specified edges of this solid.
- Parameters:
self (Any)
radius (float) – float > 0, the radius of the fillet
edgeList (Iterable[Edge]) – a list of Edge objects, which must belong to this solid
- Returns:
Filleted solid
- Return type:
Any
- isInside(point:Vector|Tuple[int|float,int|float]|Tuple[int|float,int|float,int|float],tolerance:float=1e-06)→bool[source]
Returns whether or not the point is inside a solid or compoundobject within the specified tolerance.
- Parameters:
self (ShapeProtocol)
point (Vector |Tuple[int |float,int |float]|Tuple[int |float,int |float,int |float]) – tuple or Vector representing 3D point to be tested
tolerance (float) – tolerance for inside determination, default=1.0e-6
- Returns:
bool indicating whether or not point is within solid
- Return type:
bool
- shell(faceList:Iterable[Face]|None,thickness:float,tolerance:float=0.0001,kind:Literal['arc','intersection']='arc')→Any[source]
Make a shelled solid of self.
- Parameters:
self (Any)
faceList (Iterable[Face]|None) – List of faces to be removed, which must be part of the solid. Canbe an empty list.
thickness (float) – Floating point thickness. Positive shells outwards, negativeshells inwards.
tolerance (float) – Modelling tolerance of the method, default=0.0001.
kind (Literal['arc','intersection'])
- Returns:
A shelled solid.
- Return type:
Any
- classcadquery.selectors.AndSelector(left,right)[source]
Bases:
BinarySelectorIntersection selector. Returns objects that is selected by both selectors.
- classcadquery.selectors.AreaNthSelector(n:int,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
_NthSelectorSelects the object(s) with Nth area
- Applicability:
Faces, Shells, Solids - Shape.Area() is used to compute area
closed planar Wires - a temporary face is created to compute area
Will ignore non-planar or non-closed wires.
Among other things can be used to select one ofthe nested coplanar wires or faces.
For example to create a fillet on a shank:
result=(cq.Workplane("XY").circle(5).extrude(2).circle(2).extrude(10).faces(">Z[-2]").wires(AreaNthSelector(0)).fillet(2))
Or to create a lip on a case seam:
result=(cq.Workplane("XY").rect(20,20).extrude(10).edges("|Z or <Z").fillet(2).faces(">Z").shell(2).faces(">Z").wires(AreaNthSelector(-1)).toPending().workplane().offset2D(-1).extrude(1).faces(">Z[-2]").wires(AreaNthSelector(0)).toPending().workplane().cutBlind(2))
- Parameters:
n (int)
directionMax (bool)
tolerance (float)
- classcadquery.selectors.BaseDirSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
SelectorA selector that handles selection on the basis of a single direction vector.
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.selectors.BinarySelector(left,right)[source]
Bases:
SelectorBase class for selectors that operates with two otherselectors. Subclass must implement the :filterResults(): method.
- classcadquery.selectors.BoxSelector(point0,point1,boundingbox=False)[source]
Bases:
SelectorSelects objects inside the 3D box defined by 2 points.
Ifboundingbox is True only the objects that have their boundingbox inside the given box is selected. Otherwise only center pointof the object is tested.
Applicability: all types of shapes
Example:
CQ(aCube).edges(BoxSelector((0,1,0),(1,2,1)))
- classcadquery.selectors.CenterNthSelector(vector:Vector,n:int,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
_NthSelectorSorts objects into a list with order determined by the distance of their center projected onto the specified direction.
- Applicability:
All Shapes.
- Parameters:
vector (Vector)
n (int)
directionMax (bool)
tolerance (float)
- classcadquery.selectors.DirectionMinMaxSelector(vector:Vector,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
CenterNthSelectorSelects objects closest or farthest in the specified direction.
- Applicability:
All object types. for a vertex, its point is used. for all other kindsof objects, the center of mass of the object is used.
You can use the string shortcuts >(X|Y|Z) or <(X|Y|Z) if you want to selectbased on a cardinal direction.
For example this:
CQ(aCube).faces(DirectionMinMaxSelector((0,0,1),True))
Means to select the face having the center of mass farthest in the positivez direction, and is the same as:
CQ(aCube).faces(">Z")
- Parameters:
vector (Vector)
directionMax (bool)
tolerance (float)
- classcadquery.selectors.DirectionNthSelector(vector:Vector,n:int,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
ParallelDirSelector,CenterNthSelectorFilters for objects parallel (or normal) to the specified direction then returns the Nth one.
- Applicability:
Linear EdgesPlanar Faces
- Parameters:
vector (Vector)
n (int)
directionMax (bool)
tolerance (float)
- classcadquery.selectors.DirectionSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
BaseDirSelectorSelects objects aligned with the provided direction.
- Applicability:
Linear EdgesPlanar Faces
Use the string syntax shortcut +/-(X|Y|Z) if you want to select based on a cardinal direction.
Example:
CQ(aCube).faces(DirectionSelector((0,0,1)))
selects faces with the normal in the z direction, and is equivalent to:
CQ(aCube).faces("+Z")
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.selectors.InverseSelector(selector)[source]
Bases:
SelectorInverts the selection of given selector. In other words, selectsall objects that is not selected by given selector.
- classcadquery.selectors.LengthNthSelector(n:int,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
_NthSelectorSelect the object(s) with the Nth length
- Applicability:
All Edge and Wire objects
- Parameters:
n (int)
directionMax (bool)
tolerance (float)
- classcadquery.selectors.NearestToPointSelector(pnt)[source]
Bases:
SelectorSelects object nearest the provided point.
If the object is a vertex or point, the distanceis used. For other kinds of shapes, the center of massis used to to compute which is closest.
Applicability: All Types of Shapes
Example:
CQ(aCube).vertices(NearestToPointSelector((0,1,0)))
returns the vertex of the unit cube closest to the point x=0,y=1,z=0
- classcadquery.selectors.ParallelDirSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
BaseDirSelectorSelects objects parallel with the provided direction.
- Applicability:
Linear EdgesPlanar Faces
Use the string syntax shortcut |(X|Y|Z) if you want to select based on a cardinal direction.
Example:
CQ(aCube).faces(ParallelDirSelector((0,0,1)))
selects faces with the normal parallel to the z direction, and is equivalent to:
CQ(aCube).faces("|Z")
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.selectors.PerpendicularDirSelector(vector:Vector,tolerance:float=0.0001)[source]
Bases:
BaseDirSelectorSelects objects perpendicular with the provided direction.
- Applicability:
Linear EdgesPlanar Faces
Use the string syntax shortcut #(X|Y|Z) if you want to select based on acardinal direction.
Example:
CQ(aCube).faces(PerpendicularDirSelector((0,0,1)))
selects faces with the normal perpendicular to the z direction, and is equivalent to:
CQ(aCube).faces("#Z")
- Parameters:
vector (Vector)
tolerance (float)
- classcadquery.selectors.RadiusNthSelector(n:int,directionMax:bool=True,tolerance:float=0.0001)[source]
Bases:
_NthSelectorSelect the object with the Nth radius.
- Applicability:
All Edge and Wires.
Will ignore any shape that can not be represented as a circle or an arc ofa circle.
- Parameters:
n (int)
directionMax (bool)
tolerance (float)
- classcadquery.selectors.Selector[source]
Bases:
objectFilters a list of objects.
Filters must provide a single method that filters objects.
- classcadquery.selectors.StringSyntaxSelector(selectorString)[source]
Bases:
SelectorFilter lists objects using a simple string syntax. All of the filters available in the string syntaxare also available ( usually with more functionality ) through the creation of full-fledgedselector objects. see
Selectorand its subclassesFiltering works differently depending on the type of object list being filtered.
- Parameters:
selectorString – A two-part selector string, [selector][axis]
- Returns:
objects that match the specified selector
*Modifiers* are
('|','+','-','<','>','%')- |:
parallel to ( same as
ParallelDirSelector). Can return multiple objects.- #:
perpendicular to (same as
PerpendicularDirSelector)- +:
positive direction (same as
DirectionSelector)- -:
negative direction (same as
DirectionSelector)- >:
maximize (same as
DirectionMinMaxSelectorwith directionMax=True)- <:
minimize (same as
DirectionMinMaxSelectorwith directionMax=False )- %:
curve/surface type (same as
TypeSelector)
*axisStrings* are:
X,Y,Z,XY,YZ,XZor(x,y,z)which defines an arbitrary directionIt is possible to combine simple selectors together using logical operations.The following operations are supported
- and:
Logical AND, e.g. >X and >Y
- or:
Logical OR, e.g. |X or |Y
- not:
Logical NOT, e.g. not #XY
- exc(ept):
Set difference (equivalent to AND NOT): |X exc >Z
Finally, it is also possible to use even more complex expressions with nestingand arbitrary number of terms, e.g.
(not >X[0] and #XY) or >XY[0]
Selectors are a complex topic: seeSelectors Reference for more information
- classcadquery.selectors.SubtractSelector(left,right)[source]
Bases:
BinarySelectorDifference selector. Subtract results of a selector from anotherselectors results.
- classcadquery.selectors.SumSelector(left,right)[source]
Bases:
BinarySelectorUnion selector. Returns the sum of two selectors results.
- classcadquery.selectors.TypeSelector(typeString:str)[source]
Bases:
SelectorSelects objects having the prescribed geometry type.
- Applicability:
Faces: PLANE, CYLINDER, CONE, SPHERE, TORUS, BEZIER, BSPLINE, REVOLUTION, EXTRUSION, OFFSET, OTHEREdges: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER, BSPLINE, OFFSET, OTHER
You can use the string selector syntax. For example this:
CQ(aCube).faces(TypeSelector("PLANE"))
will select 6 faces, and is equivalent to:
CQ(aCube).faces("%PLANE")
- Parameters:
typeString (str)
- cadquery.occ_impl.exporters.assembly.exportAssembly(assy:AssemblyProtocol,path:str,mode:Literal['default','fused']='default',**kwargs)→bool[source]
Export an assembly to a STEP file.
kwargs is used to provide optional keyword arguments to configure the exporter.
- Parameters:
assy (AssemblyProtocol) – assembly
path (str) – Path and filename for writing
mode (Literal['default','fused']) – STEP export mode. The options are “default”, and “fused” (a single fused compound).It is possible that fused mode may exhibit low performance.
fuzzy_tol (float) – OCCT fuse operation tolerance setting used only for fused assembly export.
glue (bool) – Enable gluing mode for improved performance during fused assembly export.This option should only be used for non-intersecting shapes or those that are only touching or partially overlapping.Note that when glue is enabled, the resulting fused shape may be invalid if shapes are intersecting in an incompatible way.Defaults to False.
write_pcurves (bool) – Enable or disable writing parametric curves to the STEP file. Default True.If False, writes STEP file without pcurves. This decreases the size of the resulting STEP file.
precision_mode (int) – Controls the uncertainty value for STEP entities. Specify -1, 0, or 1. Default 0.See OCCT documentation.
- Return type:
bool
- cadquery.occ_impl.exporters.assembly.exportCAF(assy:AssemblyProtocol,path:str,binary:bool=False)→bool[source]
Export an assembly to an XCAF xml or xbf file (internal OCCT formats).
- Parameters:
assy (AssemblyProtocol)
path (str)
binary (bool)
- Return type:
bool
- cadquery.occ_impl.exporters.assembly.exportGLTF(assy:AssemblyProtocol,path:str,binary:bool|None=None,tolerance:float=0.001,angularTolerance:float=0.1)[source]
Export an assembly to a gltf file.
- Parameters:
assy (AssemblyProtocol)
path (str)
binary (bool |None)
tolerance (float)
angularTolerance (float)
- cadquery.occ_impl.exporters.assembly.exportStepMeta(assy:AssemblyProtocol,path:str,write_pcurves:bool=True,precision_mode:int=0)→bool[source]
Export an assembly to a STEP file with faces tagged with names and colors. This is done as aseparate method from the main STEP export because this is not compatible with the fused modeand also flattens the hierarchy of the STEP.
Layers are used because some software does not understand the ADVANCED_FACE entity and needsnames attached to layers instead.
- Parameters:
assy (AssemblyProtocol) – assembly
path (str) – Path and filename for writing
write_pcurves (bool) – Enable or disable writing parametric curves to the STEP file. Default True.If False, writes STEP file without pcurves. This decreases the size of the resulting STEP file.
precision_mode (int) – Controls the uncertainty value for STEP entities. Specify -1, 0, or 1. Default 0.See OCCT documentation.
- Return type:
bool
- cadquery.occ_impl.exporters.assembly.exportVRML(assy:AssemblyProtocol,path:str,tolerance:float=0.001,angularTolerance:float=0.1)[source]
Export an assembly to a vrml file using vtk.
- Parameters:
assy (AssemblyProtocol)
path (str)
tolerance (float)
angularTolerance (float)
- cadquery.occ_impl.exporters.assembly.exportVTKJS(assy:AssemblyProtocol,path:str)[source]
Export an assembly to a zipped vtkjs. NB: .zip extensions is added to path.
- Parameters:
assy (AssemblyProtocol)
path (str)
- cadquery.occ_impl.assembly.toJSON(assy:AssemblyProtocol,color:Tuple[float,float,float,float]=(1.0,1.0,1.0,1.0),tolerance:float=0.001)→List[Dict[str,Any]][source]
Export an object to a structure suitable for converting to VTK.js JSON.
- Parameters:
assy (AssemblyProtocol)
color (Tuple[float,float,float,float])
tolerance (float)
- Return type:
List[Dict[str,Any]]
- classcadquery.occ_impl.exporters.dxf.DxfDocument(dxfversion:str='AC1027',setup:bool|List[str]=False,doc_units:int=4,*,metadata:Dict[str,str]|None=None,approx:Literal['spline','arc']|None=None,tolerance:float=0.001)[source]
Create DXF document from CadQuery objects.
A wrapper forezdxf providing methods forconverting
cadquery.Workplaneobjects to DXF entities.The ezdxf document is available as the property
document, allowing mostfeatures of ezdxf to be utilised directly.Example usage
Single layer DXF documentrectangle=cq.Workplane().rect(10,20)dxf=DxfDocument()dxf.add_shape(rectangle)dxf.document.saveas("rectangle.dxf")
Multilayer DXF documentrectangle=cq.Workplane().rect(10,20)circle=cq.Workplane().circle(3)dxf=DxfDocument()dxf=(dxf.add_layer("layer_1",color=2).add_layer("layer_2",color=3).add_shape(rectangle,"layer_1").add_shape(circle,"layer_2"))dxf.document.saveas("rectangle-with-hole.dxf")
- Parameters:
dxfversion (str)
setup (bool |List[str])
doc_units (int)
metadata (Dict[str,str]|None)
approx (Literal['spline','arc']|None)
tolerance (float)
- __init__(dxfversion:str='AC1027',setup:bool|List[str]=False,doc_units:int=4,*,metadata:Dict[str,str]|None=None,approx:Literal['spline','arc']|None=None,tolerance:float=0.001)[source]
Initialize DXF document.
- Parameters:
dxfversion (str) –
DXFversionspecifieras string, default is “AC1027” respectively “R2013”setup (bool |List[str]) – setup default styles,
Falsefor no setup,Trueto set upeverything or a list of topics as strings, e.g.["linetypes","styles"]refer toezdxf.new().doc_units (int) – ezdxf document/modelspaceunits
metadata (Dict[str,str]|None) – documentmetadata a dictionary of name value pairs
approx (Literal['spline','arc']|None) –
Approximation strategy for converting
cadquery.Workplaneobjects to DXF entities:Noneno approximation applied
"spline"all splines approximated as cubic splines
"arc"all curves approximated as arcs and straight segments
tolerance (float) – Approximation tolerance for converting
cadquery.Workplaneobjects to DXF entities.
- add_layer(name:str,*,color:int=7,linetype:str='CONTINUOUS')→Self[source]
Create a layer definition
Refer toezdxf layers andezdxf layer tutorial.
- Parameters:
name (str) – layer definition name
color (int) – color index. Standard colors include:1 red, 2 yellow, 3 green, 4 cyan, 5 blue, 6 magenta, 7 white/black
linetype (str) – ezdxfline type
- Return type:
Self