CadQuery Class Summary¶

This page documents all of the methods and functions of the CadQuery classes, organized alphabatically.

Core Classes¶

`CQ`	alias of `cadquery.cq.Workplane`
`Workplane`()	Defines a coordinate system in space, in which 2-d coordinates can be used.

Topological Classes¶

`Shape`(obj)	Represents a shape in the system.
`Vertex`(obj, forConstruction)	A Single Point in Space
`Edge`(obj)	A trimmed curve that represents the border of a face
`Wire`(obj)	A series of connected, ordered Edges, that typically bounds a Face
`Face`(obj)	a bounded surface that represents part of the boundary of a solid
`Shell`(obj)	the outer boundary of a surface
`Solid`(obj)	a single solid
`Compound`(obj)	a collection of disconnected solids

Geometry Classes¶

`Vector`()	Create a 3-dimensional vector
`Matrix`()	A 3d , 4x4 transformation matrix.
`Plane`(origin, xDir, normal)	A 2D coordinate system in space

Selector Classes¶

`Selector`()	Filters a list of objects
`NearestToPointSelector`(pnt)	Selects object nearest the provided point.
`ParallelDirSelector`(vector[, tolerance])	Selects objects parallel with the provided direction
`DirectionSelector`(vector[, tolerance])	Selects objects aligned with the provided direction
`PerpendicularDirSelector`(vector[, tolerance])	Selects objects perpendicular with the provided direction
`TypeSelector`(typeString)	Selects objects of the prescribed topological type.
`DirectionMinMaxSelector`(vector[, …])	Selects objects closest or farthest in the specified direction Used for faces, points, and edges
`StringSyntaxSelector`(selectorString)	Filter lists objects using a simple string syntax.

Class Details¶

class cadquery.BoundBox(bb: OCP.Bnd.Bnd_Box)[source]¶

A BoundingBox for an object or set of objects. Wraps the OCP one

add(obj: Union[Tuple[float, float, float], cadquery.occ_impl.geom.Vector, BoundBox], tol: float = 1e-08) → cadquery.occ_impl.geom.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 that encloses both.

This bounding box is not changed.

static findOutsideBox2D(bb1: cadquery.occ_impl.geom.BoundBox, bb2: cadquery.occ_impl.geom.BoundBox) → Optional[cadquery.occ_impl.geom.BoundBox][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 it doesn’t work correctly plus, there was all kinds of rounding error in the built-in implementation i do not understand.

isInside(b2: cadquery.occ_impl.geom.BoundBox) → bool[source]¶: Is the provided bounding box inside this one?

cadquery.CQ¶: alias of cadquery.cq.Workplane

class cadquery.Compound(obj: OCP.TopoDS.TopoDS_Shape)[source]¶

a collection of disconnected solids

cut(*toCut: cadquery.occ_impl.shapes.Shape) → cadquery.occ_impl.shapes.Shape[source]¶: Remove a shape from another one

fuse(*toFuse: cadquery.occ_impl.shapes.Shape, glue: bool = False, tol: Optional[float] = None) → cadquery.occ_impl.shapes.Shape[source]¶: Fuse shapes together

intersect(*toIntersect: cadquery.occ_impl.shapes.Shape) → cadquery.occ_impl.shapes.Shape[source]¶: Construct shape intersection

classmethod makeCompound(listOfShapes: Iterable[cadquery.occ_impl.shapes.Shape]) → cadquery.occ_impl.shapes.Compound[source]¶: Create a compound out of a list of shapes

classmethod makeText(text: str, size: float, height: float, font: str = 'Arial', kind: typing_extensions.Literal[regular, bold, italic] = 'regular', halign: typing_extensions.Literal[center, left, right] = 'center', valign: typing_extensions.Literal[center, top, bottom] = 'center', position: cadquery.occ_impl.geom.Plane = <cadquery.occ_impl.geom.Plane object>) → cadquery.occ_impl.shapes.Shape[source]¶: Create a 3D text

class cadquery.DirectionMinMaxSelector(vector, directionMax=True, tolerance=0.0001)[source]¶

Selects objects closest or farthest in the specified direction Used for faces, points, and edges

Applicability:: All object types. for a vertex, its point is used. for all other kinds of 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 select based 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 positive z direction, and is the same as:

CQ(aCube).faces( “>Z” )

filter(objectList)[source]¶

Filter the provided list :param objectList: list to filter :type objectList: list of FreeCAD primatives :return: filtered list

The default implementation returns the original list unfiltered

class cadquery.DirectionSelector(vector, tolerance=0.0001)[source]¶

Selects objects aligned with the provided direction

Applicability:: Linear Edges Planar 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 a normals in the z direction, and is equivalent to:

CQ(aCube).faces("+Z")

test(vec)[source]¶: Test a specified vector. Subclasses override to provide other implementations

class cadquery.Edge(obj: OCP.TopoDS.TopoDS_Shape)[source]¶

A trimmed curve that represents the border of a face

Center() → cadquery.occ_impl.geom.Vector[source]¶: Center of mass

endPoint() → cadquery.occ_impl.geom.Vector[source]¶

Returns: a vector representing the end point of this edge.

Note, circles may have the start and end points the same

locationAt(d: float, mode: typing_extensions.Literal[length, parameter] = 'length', frame: typing_extensions.Literal[frenet, corrected] = 'frenet') → cadquery.occ_impl.geom.Location[source]¶: Generate location along the curve :param d: distance or parameter value :param mode: position calculation mode (default: length) :param frame: moving frame calculation method (default: frenet) :return: A Location object representing local coordinate system at the specified distance.

locations(ds: Iterable[float], mode: typing_extensions.Literal[length, parameter] = 'length', frame: typing_extensions.Literal[frenet, corrected] = 'frenet') → List[cadquery.occ_impl.geom.Location][source]¶: Generate location along the curve :param ds: distance or parameter values :param mode: position calculation mode (default: length) :param frame: moving frame calculation method (default: frenet) :return: A list of Location objects representing local coordinate systems at the specified distances.

classmethod makeCircle(radius: float, pnt: Union[cadquery.occ_impl.geom.Vector, Tuple[float, float, float]] = Vector: (0.0, 0.0, 0.0), dir: Union[cadquery.occ_impl.geom.Vector, Tuple[float, float, float]] = Vector: (0.0, 0.0, 1.0), angle1: float = 360.0, angle2: float = 360) → cadquery.occ_impl.shapes.Edge[source]¶

classmethod makeEllipse(x_radius: float, y_radius: float, pnt: Union[cadquery.occ_impl.geom.Vector, Tuple[float, float, float]] = Vector: (0.0, 0.0, 0.0), dir: Union[cadquery.occ_impl.geom.Vector, Tuple[float, float, float]] = Vector: (0.0, 0.0, 1.0), xdir: Union[cadquery.occ_impl.geom.Vector, Tuple[float, float, float]] = Vector: (1.0, 0.0, 0.0), angle1: float = 360.0, angle2: float = 360.0, sense: typing_extensions.Literal[-1, 1] = 1) → cadquery.occ_impl.shapes.Edge[source]¶: Makes an Ellipse centered at the provided point, having normal in the provided direction :param cls: :param x_radius: x radius of the ellipse (along the x-axis of plane the ellipse should lie in) :param y_radius: y radius of the ellipse (along the y-axis of plane the ellipse should lie in) :param pnt: vector representing the center of the ellipse :param dir: vector representing the direction of the plane the ellipse should lie in :param angle1: start angle of arc :param angle2: end angle of arc (angle2 == angle1 return closed ellipse = default) :param sense: clockwise (-1) or counter clockwise (1) :return: an Edge

classmethod makeLine(v1: cadquery.occ_impl.geom.Vector, v2: cadquery.occ_impl.geom.Vector) → cadquery.occ_impl.shapes.Edge[source]¶: Create a line between two points :param v1: Vector that represents the first point :param v2: Vector that represents the second point :return: A linear edge between the two provided points

classmethod makeSpline(listOfVector: List[cadquery.occ_impl.geom.Vector], tangents: Optional[Sequence[cadquery.occ_impl.geom.Vector]] = None, periodic: bool = False, tol: float = 1e-06) → cadquery.occ_impl.shapes.Edge[source]¶: Interpolate a spline through the provided points. :param cls: :param listOfVector: a list of Vectors that represent the points :param tangents: tuple of Vectors specifying start and finish tangent :param periodic: creation of peridic curves :param tol: tolerance of the algorithm (consult OCC documentation) :return: an Edge

classmethod makeTangentArc(v1: cadquery.occ_impl.geom.Vector, v2: cadquery.occ_impl.geom.Vector, v3: cadquery.occ_impl.geom.Vector) → cadquery.occ_impl.shapes.Edge[source]¶: Makes a tangent arc from point v1, in the direction of v2 and ends at v3. :param cls: :param v1: start vector :param v2: tangent vector :param v3: end vector :return: an edge

classmethod makeThreePointArc(v1: cadquery.occ_impl.geom.Vector, v2: cadquery.occ_impl.geom.Vector, v3: cadquery.occ_impl.geom.Vector) → cadquery.occ_impl.shapes.Edge[source]¶: Makes a three point arc through the provided points :param cls: :param v1: start vector :param v2: middle vector :param v3: end vector :return: an edge object through the three points

startPoint() → cadquery.occ_impl.geom.Vector[source]¶

Returns: a vector representing the start poing of this edge

Note, circles may have the start and end points the same

tangentAt(locationParam: float = 0.5) → cadquery.occ_impl.geom.Vector[source]¶: Compute tangent vector at the specified location. :param locationParam: location to use in [0,1] :return: tangent vector

class cadquery.Face(obj: OCP.TopoDS.TopoDS_Shape)[source]¶

a bounded surface that represents part of the boundary of a solid

Center() → cadquery.occ_impl.geom.Vector[source]¶: Center of mass

classmethod makeFromWires(outerWire: cadquery.occ_impl.shapes.Wire, innerWires: List[cadquery.occ_impl.shapes.Wire] = []) → cadquery.occ_impl.shapes.Face[source]¶: Makes a planar face from one or more wires

classmethod makeNSidedSurface(edges: Iterable[cadquery.occ_impl.shapes.Edge], points: Iterable[OCP.gp.gp_Pnt], continuity: OCP.GeomAbs.GeomAbs_Shape = GeomAbs_Shape.GeomAbs_C0, 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) → cadquery.occ_impl.shapes.Face[source]¶: Returns a surface enclosed by a closed polygon defined by ‘edges’ and going through ‘points’. :param points :type points: list of gp_Pnt :param edges :type edges: list of Edge :param continuity=GeomAbs_C0 :type continuity: OCC.Core.GeomAbs continuity condition :param Degree = 3 (OCCT default) :type Degree: Integer >= 2 :param NbPtsOnCur = 15 (OCCT default) :type: NbPtsOnCur Integer >= 15 :param NbIter = 2 (OCCT default) :type: NbIterInteger >= 2 :param Anisotropie = False (OCCT default) :type Anisotropie: Boolean :param: Tol2d = 0.00001 (OCCT default) :type Tol2d: float > 0 :param Tol3d = 0.0001 (OCCT default) :type Tol3dReal: float > 0 :param TolAng = 0.01 (OCCT default) :type TolAngReal: float > 0 :param TolCurv = 0.1 (OCCT default) :type TolCurvReal: float > 0 :param MaxDeg = 8 (OCCT default) :type MaxDegInteger: Integer >= 2 (?) :param MaxSegments = 9 (OCCT default) :type MaxSegments: Integer >= 2 (?)

classmethod makeRuledSurface(edgeOrWire1: Edge, edgeOrWire2: Edge) → ’Face’[source]¶
classmethod makeRuledSurface(edgeOrWire1: Wire, edgeOrWire2: Wire) → ’Face’: ‘makeRuledSurface(Edge|Wire,Edge|Wire) – Make a ruled surface Create a ruled surface out of two edges or wires. If wires are used then these must have the same number of edges

normalAt(locationVector: Optional[cadquery.occ_impl.geom.Vector] = None) → cadquery.occ_impl.geom.Vector[source]¶

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.

class cadquery.Location[source]¶

class cadquery.Location(t: Vector)

class cadquery.Location(t: Plane)

class cadquery.Location(t: Plane, v: Vector)

class cadquery.Location(t: TopLoc_Location)

class cadquery.Location(t: Vector, ax: Vector, angle: float)

Location 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 Shape objects in both relative and absolute manner. It is the preferred type to locate objects in CQ.

class cadquery.Matrix[source]¶

class cadquery.Matrix(matrix: Union[gp_GTrsf, gp_Trsf])

class cadquery.Matrix(matrix: Sequence[Sequence[float]])

A 3d , 4x4 transformation matrix.

Used to move geometry in space.

The provided “matrix” parameter may be None, a gp_GTrsf, or a nested list of values.

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.

transposed_list() → Sequence[float][source]¶: Needed by the cqparts gltf exporter

class cadquery.NearestToPointSelector(pnt)[source]¶

Selects object nearest the provided point.

If the object is a vertex or point, the distance is used. For other kinds of shapes, the center of mass is 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

filter(objectList)[source]¶

Filter the provided list :param objectList: list to filter :type objectList: list of FreeCAD primatives :return: filtered list

The default implementation returns the original list unfiltered

class cadquery.ParallelDirSelector(vector, tolerance=0.0001)[source]¶

Selects objects parallel with the provided direction

Applicability:: Linear Edges Planar 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 a normals in the z direction, and is equivalent to:

CQ(aCube).faces("|Z")

test(vec)[source]¶: Test a specified vector. Subclasses override to provide other implementations

class cadquery.PerpendicularDirSelector(vector, tolerance=0.0001)[source]¶

Selects objects perpendicular with the provided direction

Applicability:: Linear Edges Planar Faces

Use the string syntax shortcut #(X|Y|Z) if you want to select based on a cardinal direction.

Example:

CQ(aCube).faces(PerpendicularDirSelector((0,0,1))

selects faces with a normals perpendicular to the z direction, and is equivalent to:

CQ(aCube).faces("#Z")

test(vec)[source]¶: Test a specified vector. Subclasses override to provide other implementations

class cadquery.Plane(origin, xDir, normal)[source]¶

A 2D coordinate system in space

A 2D coordinate system in space, with the x-y axes on the plane, and a particular point as the origin.

A plane allows the use of 2-d coordinates, which are later converted to global, 3d coordinates when the operations are complete.

Frequently, it is not necessary to create work planes, as they can be created automatically from faces.

classmethod named(stdName: str, origin=0, 0, 0) → cadquery.occ_impl.geom.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 of the origin of the new plane, in global coorindates.) – the desired origin, specified in global coordinates

Available named planes are as follows. Direction references refer to the 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 will always 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 and xDrection 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 2-d 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 global coordinates. Both operations were relative to local coordinates of the plane.

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 most operations based on a plane are all 2-d. Occasionally, though, 3-d points outside of the current plane are transformed. One such example is Workplane.box(), where 3-d corners of a box are transformed to orient the box in space correctly.

toWorldCoords(tuplePoint) → cadquery.occ_impl.geom.Vector[source]¶

Convert a point in local coordinates to global coordinates

Parameters: tuplePoint (a 2 or three tuple of float. The third value is taken to be zero if not supplied.) – point in local coordinates to convert.
Returns: a Vector in global coordinates

class cadquery.Selector[source]¶

Filters a list of objects

Filters must provide a single method that filters objects.

filter(objectList)[source]¶

Filter the provided list :param objectList: list to filter :type objectList: list of FreeCAD primatives :return: filtered list

The default implementation returns the original list unfiltered

class cadquery.Shape(obj: OCP.TopoDS.TopoDS_Shape)[source]¶

Represents a shape in the system. Wrappers the FreeCAD apiSh

Center() → cadquery.occ_impl.geom.Vector[source]¶: Center of mass

static CombinedCenter(objects: Iterable[Shape]) → cadquery.occ_impl.geom.Vector[source]¶

Calculates the center of mass of multiple objects.

Parameters: objects – a list of objects with mass

static CombinedCenterOfBoundBox(objects: List[Shape]) → cadquery.occ_impl.geom.Vector[source]¶: Calculates the center of BoundBox of multiple objects. :param objects: a list of objects with mass 1

classmethod cast(obj: OCP.TopoDS.TopoDS_Shape, forConstruction: bool = False) → cadquery.occ_impl.shapes.Shape[source]¶: Returns the right type of wrapper, given a OCCT object

static centerOfMass(obj: cadquery.occ_impl.shapes.Shape) → cadquery.occ_impl.geom.Vector[source]¶: Calculates the ‘mass’ of an object.

clean() → T[source]¶: Experimental clean using ShapeUpgrade

static computeMass(obj: cadquery.occ_impl.shapes.Shape) → float[source]¶: Calculates the ‘mass’ of an object.

cut(*toCut: cadquery.occ_impl.shapes.Shape) → cadquery.occ_impl.shapes.Shape[source]¶: Remove a shape from another one

exportBrep(fileName: str) → bool[source]¶: Export given shape to a BREP file

fix() → T[source]¶: Try to fix shape if not valid

fuse(*toFuse: cadquery.occ_impl.shapes.Shape, glue: bool = False, tol: Optional[float] = None) → cadquery.occ_impl.shapes.Shape[source]¶: Fuse shapes together

geomType() → typing_extensions.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 :return: a string according to the geometry type.

Implementations can return any values desired, but the values the user uses 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, ARC, CIRCLE, SPLINE Face: PLANE, SPHERE, CONE Solid: ‘Solid’ Shell: ‘Shell’ Compound: ‘Compound’ Wire: ‘Wire’

intersect(*toIntersect: cadquery.occ_impl.shapes.Shape) → cadquery.occ_impl.shapes.Shape[source]¶: Construct shape intersection

locate(loc: cadquery.occ_impl.geom.Location) → cadquery.occ_impl.shapes.Shape[source]¶: Apply a location in absolute sense to self

located(loc: cadquery.occ_impl.geom.Location) → cadquery.occ_impl.shapes.Shape[source]¶: Apply a location in absolute sense to a copy of self

move(loc: cadquery.occ_impl.geom.Location) → cadquery.occ_impl.shapes.Shape[source]¶: Apply a location in relative sense (i.e. update current location) to self

moved(loc: cadquery.occ_impl.geom.Location) → cadquery.occ_impl.shapes.Shape[source]¶: Apply a location in relative sense (i.e. update current location) to a copy of self

rotate(startVector: cadquery.occ_impl.geom.Vector, endVector: cadquery.occ_impl.geom.Vector, angleDegrees: float) → T[source]¶: Rotates a shape around an axis :param startVector: start point of rotation axis either a 3-tuple or a Vector :param endVector: end point of rotation axis, either a 3-tuple or a Vector :param angleDegrees: angle to rotate, in degrees :return: a copy of the shape, rotated

transformGeometry(tMatrix: cadquery.occ_impl.geom.Matrix) → cadquery.occ_impl.shapes.Shape[source]¶

tMatrix is a matrix object.

returns a copy of the object, but with geometry transformed insetad of just rotated.

WARNING: transformGeometry will sometimes convert lines and circles to splines, but it also has the ability to handle skew and stretching transformations.

If your transformation is only translation and rotation, it is safer to use transformShape, which doesnt change the underlying type of the geometry, but cannot handle skew transformations

transformShape(tMatrix: cadquery.occ_impl.geom.Matrix) → cadquery.occ_impl.shapes.Shape[source]¶: tMatrix is a matrix object. returns a copy of the ojbect, transformed by the provided matrix, with all objects keeping their type

class cadquery.Shell(obj: OCP.TopoDS.TopoDS_Shape)[source]¶: the outer boundary of a surface

class cadquery.Solid(obj: OCP.TopoDS.TopoDS_Shape)[source]¶

a single solid

dprism(basis: cadquery.occ_impl.shapes.Face, profiles: List[cadquery.occ_impl.shapes.Wire], depth: Optional[float] = None, taper: float = 0, thruAll: bool = True, additive: bool = True) → cadquery.occ_impl.shapes.Solid[source]¶

Make a prismatic feature (additive or subtractive)

Parameters

basis – face to perfrom the operation on
profiles – list of profiles
depth – depth of the cut or extrusion
thruAll – cut thruAll

Returns

a Solid object

classmethod extrudeLinear(outerWire: cadquery.occ_impl.shapes.Wire, innerWires: List[cadquery.occ_impl.shapes.Wire], vecNormal: cadquery.occ_impl.geom.Vector, taper: float = 0) → cadquery.occ_impl.shapes.Solid[source]¶

Attempt to extrude the list of wires into a prismatic solid in the provided direction

Parameters

outerWire – the outermost wire
innerWires – a list of inner wires
vecNormal – a vector along which to extrude the wires
taper – taper angle, default=0

Returns

a Solid object

The wires must not intersect

Extruding wires is very non-trivial. Nested wires imply very different geometry, and there 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 method reliable.

classmethod extrudeLinearWithRotation(outerWire: cadquery.occ_impl.shapes.Wire, innerWires: List[cadquery.occ_impl.shapes.Wire], vecCenter: cadquery.occ_impl.geom.Vector, vecNormal: cadquery.occ_impl.geom.Vector, angleDegrees: float) → cadquery.occ_impl.shapes.Solid[source]¶

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, the construction methods used here are different enough that they should be separate.

At a high level, the steps followed are: (1) accept a set of wires (2) create another set of wires like this one, but which are transformed and rotated (3) create a ruledSurface between the sets of wires (4) create a shell and compute the resulting object

Parameters

outerWire – the outermost wire, a cad.Wire
innerWires – a list of inner wires, a list of cad.Wire
vecCenter – the center point about which to rotate. the axis of rotation is defined by vecNormal, located at vecCenter. ( a cad.Vector )
vecNormal – a vector along which to extrude the wires ( a cad.Vector )
angleDegrees – the angle to rotate through while extruding

Returns

a cad.Solid object

classmethod interpPlate(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) → Union[cadquery.occ_impl.shapes.Solid, cadquery.occ_impl.shapes.Face][source]¶

Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and going through ‘surf_pts’ points.

:param surf_edges :type 1 surf_edges: list of [x,y,z] float ordered coordinates :type 2 surf_edges: list of ordered or unordered CadQuery wires :param surf_pts = [] (uses only edges if []) :type surf_pts: list of [x,y,z] float coordinates :param thickness = 0 (returns 2D surface if 0) :type thickness: float (may be negative or positive depending on thicknening direction) :param Degree = 3 (OCCT default) :type Degree: Integer >= 2 :param NbPtsOnCur = 15 (OCCT default) :type: NbPtsOnCur Integer >= 15 :param NbIter = 2 (OCCT default) :type: NbIterInteger >= 2 :param Anisotropie = False (OCCT default) :type Anisotropie: Boolean :param: Tol2d = 0.00001 (OCCT default) :type Tol2d: float > 0 :param Tol3d = 0.0001 (OCCT default) :type Tol3dReal: float > 0 :param TolAng = 0.01 (OCCT default) :type TolAngReal: float > 0 :param TolCurv = 0.1 (OCCT default) :type TolCurvReal: float > 0 :param MaxDeg = 8 (OCCT default) :type MaxDegInteger: Integer >= 2 (?) :param MaxSegments = 9 (OCCT default) :type MaxSegments: Integer >= 2 (?)

static isSolid(obj: cadquery.occ_impl.shapes.Shape) → bool[source]¶: Returns true if the object is a solid, false otherwise

classmethod makeBox(length,width,height,[pnt,dir]) -- Make a box located in pnt with the dimensions (length,width,height)[source]¶: By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)’

classmethod makeCone(radius1: float, radius2: float, height: float, pnt: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 0.0), dir: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0), angleDegrees: float = 360) → cadquery.occ_impl.shapes.Solid[source]¶: Make a cone with given radii and height By default pnt=Vector(0,0,0), dir=Vector(0,0,1) and angle=360’

classmethod makeCylinder(radius: float, height: float, pnt: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 0.0), dir: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0), angleDegrees: float = 360) → cadquery.occ_impl.shapes.Solid[source]¶: makeCylinder(radius,height,[pnt,dir,angle]) – Make a cylinder with a given radius and height By default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360’

classmethod makeLoft(listOfWire: List[cadquery.occ_impl.shapes.Wire], ruled: bool = False) → cadquery.occ_impl.shapes.Solid[source]¶: makes a loft from a list of wires The wires will be converted into faces when possible– it is presumed that nobody ever actually wants to make an infinitely thin shell for a real FreeCADPart.

classmethod makeSphere(radius: float, pnt: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 0.0), dir: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0), angleDegrees1: float = 0, angleDegrees2: float = 90, angleDegrees3: float = 360) → cadquery.occ_impl.shapes.Shape[source]¶: Make a sphere with a given radius By default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=0, angle2=90 and angle3=360

classmethod makeTorus(radius1: float, radius2: float, pnt: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 0.0), dir: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0), angleDegrees1: float = 0, angleDegrees2: float = 360) → cadquery.occ_impl.shapes.Solid[source]¶: makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]) – Make a torus with agiven radii and angles By default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0 ,angle1=360 and angle=360’

classmethod makeWedge(dx: float, dy: float, dz: float, xmin: float, zmin: float, xmax: float, zmax: float, pnt: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 0.0), dir: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0)) → cadquery.occ_impl.shapes.Solid[source]¶: Make a wedge located in pnt By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)

classmethod revolve(outerWire: cadquery.occ_impl.shapes.Wire, innerWires: List[cadquery.occ_impl.shapes.Wire], angleDegrees: float, axisStart: cadquery.occ_impl.geom.Vector, axisEnd: cadquery.occ_impl.geom.Vector) → cadquery.occ_impl.shapes.Solid[source]¶

Attempt to revolve the list of wires into a solid in the provided direction

Parameters

outerWire – the outermost wire
innerWires – a list of inner wires
angleDegrees (float, anything less than 360 degrees will leave the shape open) – the angle to revolve through.
axisStart (tuple, a two tuple) – the start point of the axis of rotation
axisEnd (tuple, a two tuple) – the end point of the axis of rotation

Returns

a Solid object

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 method reliable.

classmethod sweep(outerWire: cadquery.occ_impl.shapes.Wire, innerWires: List[cadquery.occ_impl.shapes.Wire], path: Union[cadquery.occ_impl.shapes.Wire, cadquery.occ_impl.shapes.Edge], makeSolid: bool = True, isFrenet: bool = False, transitionMode: typing_extensions.Literal[transformed, round, right] = 'transformed') → cadquery.occ_impl.shapes.Shape[source]¶

Attempt to sweep the list of wires into a prismatic solid along the provided path

Parameters

outerWire – the outermost wire
innerWires – a list of inner wires
path – The wire to sweep the face resulting from the wires over
makeSolid (boolean) – return Solid or Shell (defualt True)
isFrenet (boolean) – Frenet mode (default False)
transitionMode – handling of profile orientation at C1 path discontinuities. Possible values are {‘transformed’,’round’, ‘right’} (default: ‘right’).

Returns

a Solid object

classmethod sweep_multi(profiles: List[cadquery.occ_impl.shapes.Wire], path: Union[cadquery.occ_impl.shapes.Wire, cadquery.occ_impl.shapes.Edge], makeSolid: bool = True, isFrenet: bool = False) → cadquery.occ_impl.shapes.Solid[source]¶

Multi section sweep. Only single outer profile per section is allowed.

Parameters

profiles – list of profiles
path – The wire to sweep the face resulting from the wires over

Returns

a Solid object

class cadquery.StringSyntaxSelector(selectorString)[source]¶

Filter lists objects using a simple string syntax. All of the filters available in the string syntax are also available ( usually with more functionality ) through the creation of full-fledged selector objects. see Selector and its subclasses

Filtering 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

*Modfiers* 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 DirectionMinMaxSelector with directionMax=True)

<

minimize (same as DirectionMinMaxSelector with directionMax=False )

%

curve/surface type (same as TypeSelector)

*axisStrings* are: X,Y,Z,XY,YZ,XZ or (x,y,z) which defines an arbitrary direction

It is possible to combine simple selectors together using logical operations. The following operations are suuported

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 nesting and arbitrary number of terms, e.g.

(not >X[0] and #XY) or >XY[0]

Selectors are a complex topic: see String Selectors Reference for more information

filter(objectList)[source]¶: Filter give object list through th already constructed complex selector object

class cadquery.TypeSelector(typeString)[source]¶

Selects objects of the prescribed topological type.

Applicability:: Faces: Plane,Cylinder,Sphere Edges: Line,Circle,Arc

You can use the shortcut selector %(PLANE|SPHERE|CONE) for faces, and %(LINE|ARC|CIRCLE) for edges.

For example this:

CQ(aCube).faces ( TypeSelector("PLANE") )

will select 6 faces, and is equivalent to:

CQ(aCube).faces( "%PLANE" )

filter(objectList)[source]¶

Filter the provided list :param objectList: list to filter :type objectList: list of FreeCAD primatives :return: filtered list

The default implementation returns the original list unfiltered

class cadquery.Vector(x: float, y: float, z: float)[source]¶

class cadquery.Vector(x: float, y: float)

class cadquery.Vector(v: ‘Vector’)

class cadquery.Vector(v: Sequence[float])

class cadquery.Vector(v: Union[gp_Vec, gp_Pnt, gp_Dir, gp_XYZ])

class cadquery.Vector

Create a 3-dimensional vector

Parameters: args – a 3-d 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() → cadquery.occ_impl.geom.Vector[source]¶

Return the vector itself

The center of myself is myself. Provided so that vectors, vertexes, and other shapes all support a common interface, when Center() is requested for all objects on the stack.

multiply(scale: float) → cadquery.occ_impl.geom.Vector[source]¶: Return a copy multiplied by the provided scalar

normalized() → cadquery.occ_impl.geom.Vector[source]¶: Return a normalized version of this vector

projectToPlane(plane: cadquery.occ_impl.geom.Plane) → cadquery.occ_impl.geom.Vector[source]¶

Vector is projected onto the plane provided as input.

Parameters: args – Plane object

Returns the projected vector.

class cadquery.Vertex(obj: OCP.TopoDS.TopoDS_Shape, forConstruction: bool = False)[source]¶

A Single Point in Space

Center() → cadquery.occ_impl.geom.Vector[source]¶: The center of a vertex is itself!

class cadquery.Wire(obj: OCP.TopoDS.TopoDS_Shape)[source]¶

A series of connected, ordered Edges, that typically bounds a Face

classmethod assembleEdges(listOfEdges: Iterable[cadquery.occ_impl.shapes.Edge]) → cadquery.occ_impl.shapes.Wire[source]¶: Attempts to build a wire that consists of the edges in the provided list :param cls: :param listOfEdges: a list of Edge objects. The edges are not to be consecutive. :return: a wire with the edges assembled :BRepBuilderAPI_MakeWire::Error() values

:BRepBuilderAPI_WireDone = 0 :BRepBuilderAPI_EmptyWire = 1 :BRepBuilderAPI_DisconnectedWire = 2 :BRepBuilderAPI_NonManifoldWire = 3

classmethod combine(listOfWires: Iterable[Union[Wire, cadquery.occ_impl.shapes.Edge]], tol: float = 1e-09) → List[cadquery.occ_impl.shapes.Wire][source]¶: Attempt to combine a list of wires and egdes into a new wire. :param cls: :param listOfWires: :param tol: default 1e-9 :return: Wire

classmethod makeCircle(radius: float, center: cadquery.occ_impl.geom.Vector, normal: cadquery.occ_impl.geom.Vector) → cadquery.occ_impl.shapes.Wire[source]¶: Makes a Circle centered at the provided point, having normal in the provided direction :param radius: floating point radius of the circle, must be > 0 :param center: vector representing the center of the circle :param normal: vector representing the direction of the plane the circle should lie in :return:

classmethod makeEllipse(x_radius: float, y_radius: float, center: cadquery.occ_impl.geom.Vector, normal: cadquery.occ_impl.geom.Vector, xDir: cadquery.occ_impl.geom.Vector, angle1: float = 360.0, angle2: float = 360.0, rotation_angle: float = 0.0, closed: bool = True) → cadquery.occ_impl.shapes.Wire[source]¶: Makes an Ellipse centered at the provided point, having normal in the provided direction :param x_radius: floating point major radius of the ellipse (x-axis), must be > 0 :param y_radius: floating point minor radius of the ellipse (y-axis), must be > 0 :param center: vector representing the center of the circle :param normal: vector representing the direction of the plane the circle should lie in :param angle1: start angle of arc :param angle2: end angle of arc :param rotation_angle: angle to rotate the created ellipse / arc :return: Wire

classmethod makeHelix(pitch: float, height: float, radius: float, center: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 0.0), dir: cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0), angle: float = 360.0, lefthand: bool = False) → cadquery.occ_impl.shapes.Wire[source]¶: Make a helix with a given pitch, height and radius By default a cylindrical surface is used to create the helix. If the fourth parameter is set (the apex given in degree) a conical surface is used instead’

offset2D(d: float, kind: typing_extensions.Literal[arc, intersection, tangent] = 'arc') → List[cadquery.occ_impl.shapes.Wire][source]¶: Offsets a planar wire

stitch(other: cadquery.occ_impl.shapes.Wire) → cadquery.occ_impl.shapes.Wire[source]¶: Attempt to stich wires

class cadquery.Workplane(obj: CQObject)[source]¶

class cadquery.Workplane(inPlane: Union[Plane, str] = "'XY'", origin: VectorLike = '0, 0, 0', obj: Optional[CQObject] = 'None')

Defines a coordinate system in space, in which 2-d coordinates can be used.

Parameters

plane (a Plane object, or a 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, or None to default to the origin) – the desired origin of the new workplane
obj (a CAD primitive, or None to use the centerpoint of the plane as the initial stack 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 the current point is on the origin.

Note

You can also create workplanes on the surface of existing faces using CQ.workplane()

add(obj: ‘Workplane’) → ’Workplane’[source]¶

add(obj: CQObject) → ’Workplane’

add(obj: Iterable[CQObject]) → ’Workplane’

Adds an object or a list of objects to the stack

Parameters: obj (a CQ object, CAD primitive, or list of CAD primitives) – an object to add
Returns: a CQ object with the requested operation performed

If an CQ object, the values of that object’s stack are added. If a list of cad primitives, they are all added. If a single CAD primitive it is added

Used in rare cases when you need to combine the results of several CQ results into a single CQ object. Shelling is one common example

all() → List[cadquery.cq.Workplane][source]¶

Return a list of all CQ objects on the stack.

useful when you need to operate on the elements individually.

Contrast with vals, which returns the underlying objects for all of the items on the stack

box(length: float, width: float, height: float, centered: Tuple[bool, bool, bool] = True, True, True, combine: bool = True, clean: bool = True) → cadquery.cq.Workplane[source]¶

Return a 3d box with specified dimensions for each object on the stack.

Parameters

length (float > 0) – box size in X direction
width (float > 0) – box size in Y direction
height (float > 0) – box size in Z direction
centered – should the box be centered, or should reference point be at the lower bound of the range?
combine (true to combine shapes, false otherwise.) – should the results be combined with other solids on the stack (and each other)?
clean (boolean) – call clean() afterwards to have a clean shape

Centered is a tuple that describes whether the box should be centered on the x,y, and z axes. If true, the box is centered on the respective axis relative to the workplane origin, if false, the workplane center will represent the lower bound of the resulting box

one box is created for each item on the current stack. If no items are on the stack, one box 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 found in the chain, the result is that solid with all boxes produced fused onto it otherwise, the result 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 origin
s = Workplane().box(1,2,3,centered=(False,False,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: Optional[float] = None, clean: bool = True) → cadquery.cq.Workplane[source]¶

Makes a counterbored hole for each item on the stack.

Parameters

diameter (float > 0) – the diameter of the hole
cboreDiameter (float > 0 and > diameter) – the diameter of the cbore
cboreDepth (float > 0) – depth of the counterbore
depth (float > 0 or None to drill thru the entire part.) – the depth of the hole
clean (boolean) – call clean() afterwards to have a clean shape

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 a construction rectangle to define the centers of a set of holes, like so:

s = Workplane(Plane.XY()).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 quite time consuming to create, but are quite easily defined by users.

see cskHole() to make countersinks instead of counterbores

center(x: float, y: float) → cadquery.cq.Workplane[source]¶

Shift local coordinates to the specified location.

The location is specified in terms of local coordinates.

Parameters

x (float) – the new x location
y (float) – the new y location

Returns

the workplane object, with the center adjusted.

The current point is set to the new center. This method is useful to adjust the center point after it has been created automatically on a 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 of the center of a face, which is the default:

#this workplane is centered at x=0.5,y=0.5, the center of the upper face
s = Workplane().box(1,1,1).faces(">Z").workplane()

s = s.center(-0.5,-0.5) # move the center to the corner
t = s.circle(0.25).extrude(0.2)
assert ( t.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: Optional[float] = None) → cadquery.cq.Workplane[source]¶

Chamfers a solid on the selected edges.

The edges on the stack are chamfered. The solid to which the edges belong must be in the parent chain of the selected edges.

Optional parameter length2 can be supplied with a different value than length for a chamfer that is shorter on one side longer on the other side.

Parameters

length (positive float) – the length of the fillet, must be greater than zero
length2 (positive float) – optional parameter for asymmetrical chamfer

Raises

ValueError if at least one edge is not selected

Raises

ValueError if the solid containing the edge is not in the chain

Returns

cq object with the resulting solid selected.

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) → cadquery.cq.Workplane[source]¶

Make a circle for each item on the stack.

Parameters

radius (float > 0) – radius of the circle
forConstruction (true if the wires are for reference, false if they are creating part geometry) – should the new wires be reference geometry only?

Returns

a new CQ object with the created wires on the stack

A common use case is to use a for-construction rectangle to define the centers of a hole 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 is to use successive circle() calls to create concentric circles. This works because the center 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 forConstruction project points not in the workplane plane onto the workplane plane

clean() → cadquery.cq.Workplane[source]¶

Cleans the current solid by removing unwanted edges from the faces.

Normally you don’t have to call this function. It is automatically called after each related operation. You can disable this behavior with clean=False parameter if method has any. In some cases this can improve performance drastically but is generally dis-advised since it may break some operations such as fillet.

Note that in some cases where lots of solid operations are chained, clean() may actually improve performance since the shape is ‘simplified’ at each step and thus next operation is easier.

Also note that, due to limitation of the underlying engine, clean may fail to produce a clean output in some cases such as spherical faces.

close() → cadquery.cq.Workplane[source]¶

End 2-d construction, and attempt to build a closed wire.

Returns: a CQ object with a completed wire on the stack, if possible.

After 2-d drafting with methods such as lineTo, threePointArc, tangentArcPoint and polyline, it is necessary to convert the edges produced by these into one or more wires.

When a set of edges is closed, cadQuery assumes it is safe to build the group of edges into a wire. This example builds a simple triangular prism:

s = Workplane().lineTo(1,0).lineTo(1,1).close().extrude(0.2)

combine(clean: bool = True) → cadquery.cq.Workplane[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: clean (boolean) – call clean() afterwards to have a clean shape
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

combineSolids(otherCQToCombine: Optional[Workplane] = None) → cadquery.cq.Workplane[source]¶

!!!DEPRECATED!!! use union() Combines all solids on the current stack, and any context object, together into a single object.

After the operation, the returned solid is also the context solid.

Parameters: otherCQToCombine – another CadQuery to combine.
Returns: a cQ object with the resulting combined solid on the stack.

Most of the time, both objects will contain a single solid, which is combined and returned on the stack of the new object.

compounds(selector: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select compounds on the stack, optionally filtering the selection. If there are multiple objects on the stack, they are collected and a list of all the distinct compounds is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) – A selector
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains all of the distinct solids of all objects on the current stack, filtered by the provided selector.

A compound contains multiple CAD primitives that resulted from a single operation, such as a union, cut, split, or fillet. Compounds can contain multiple edges, wires, or solids.

See more about selectors HERE

consolidateWires() → cadquery.cq.Workplane[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

FreeCAD has a bug in Part.Wire([]) which does not create wires/edges properly sometimes Additionally, it has a bug where a profile composed of two wires ( rather than one ) also does not work properly. Together these are a real problem.

copyWorkplane(obj: cadquery.cq.Workplane) → cadquery.cq.Workplane[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

cskHole(diameter: float, cskDiameter: float, cskAngle: float, depth: Optional[float] = None, clean: bool = True) → cadquery.cq.Workplane[source]¶

Makes a countersunk hole for each item on the stack.

Parameters

diameter (float > 0) – the diameter of the hole
cskDiameter (float > 0 and > diameter) – the diameter of the countersink
cskAngle (float > 0) – angle of the countersink, in degrees ( 82 is common )
depth (float > 0 or None to drill thru the entire part.) – the depth of the hole
clean (boolean) – call clean() afterwards to have a clean shape

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 a construction rectangle to define the centers of a set of holes, like so:

s = Workplane(Plane.XY()).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 quite time consuming to create, but are quite easily defined by users.

see cboreHole() to make counterbores instead of countersinks

cut(toCut: Union[Workplane, cadquery.occ_impl.shapes.Solid, cadquery.occ_impl.shapes.Compound], clean: bool = True) → cadquery.cq.Workplane[source]¶

Cuts the provided solid from the current solid, IE, perform a solid subtraction

Parameters

toCut (a solid object, or a CQ object having a solid,) – object to cut
clean (boolean) – call clean() afterwards to have a clean shape

Raises

ValueError if there is no solid to subtract from in the chain

Returns

a CQ object with the resulting object selected

cutBlind(distanceToCut: float, clean: bool = True, taper: Optional[float] = None) → cadquery.cq.Workplane[source]¶

Use all un-extruded wires in the parent chain to create a prismatic cut from existing solid.

Similar to extrude, except that a solid in the parent chain is required to remove material from. cutBlind always removes material from a part.

Parameters

distanceToCut (float, >0 means in the positive direction of the workplane normal, <0 means in the negative direction) – distance to extrude before cutting
clean (boolean) – call clean() afterwards to have a clean shape
taper (float) – 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

see cutThruAll() to cut material from the entire part

Future Enhancements:: Cut Up to Surface

cutEach(fcn: Callable[[cadquery.occ_impl.geom.Location], cadquery.occ_impl.shapes.Shape], useLocalCoords: bool = False, clean: bool = True) → cadquery.cq.Workplane[source]¶: Evaluates the provided function at each point on the stack (ie, eachpoint) and then cuts the result from the context solid. :param fcn: a function suitable for use in the eachpoint method: ie, that accepts a vector :param useLocalCoords: same as for eachpoint() :param boolean clean: call clean() afterwards to have a clean shape :return: a CQ object that contains the resulting solid :raises: an error if there is not a context solid to cut from

cutThruAll(clean: bool = True, taper: float = 0) → cadquery.cq.Workplane[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 material from. cutThruAll always removes material from a part.

Parameters: clean (boolean) – call clean() afterwards to have a clean shape
Raises: ValueError if there is no solid to subtract from in the chain
Returns: a CQ object with the resulting object selected

see cutBlind() to cut material to a limited depth

each(callback: Callable[[Union[cadquery.occ_impl.geom.Vector, cadquery.occ_impl.geom.Location, cadquery.occ_impl.shapes.Shape]], cadquery.occ_impl.shapes.Shape], useLocalCoordinates: bool = False) → cadquery.cq.Workplane[source]¶

Runs the provided function on each value in the stack, and collects the return values into a new CQ object.

Special note: a newly created workplane always has its center point as its only stack item

Parameters

callBackFunction – the function to call for each item on the current stack.
useLocalCoordinates (boolean) – should values be converted from local coordinates first?

The callback function must accept one argument, which is the item on the stack, and return one 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. Objects created are added as-is, and objects passed into the function are sent in using global coordinates

If true, the calling function is assumed to be working in local coordinates. Objects are transformed to local coordinates before they are passed into the callback method, and result objects are transformed to global coordinates after they are returned.

This allows plugin developers to create objects in local coordinates, without worrying about 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(callback: Callable[[cadquery.occ_impl.geom.Location], cadquery.occ_impl.shapes.Shape], useLocalCoordinates: bool = False) → cadquery.cq.Workplane[source]¶

Same as each(), except each item on the stack is converted into a point before it is passed into the callback function.

Returns: CadQuery object which contains a list of vectors (points ) on its stack.
Parameters: useLocalCoordinates (boolean) – should points be in local or global coordinates

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 converted to 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 current workplane/coordinate system

edges(selector: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select the edges of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the edges of all objects are collected and a list of all the distinct edges is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) – A selector
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains all of the distinct edges of all objects on the current stack, filtered by the provided selector.

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:

CQ(aCube).faces("+Z").edges().size()

returns 4, because a cube has one face with a normal in the +Z direction. Similarly:

CQ(aCube).edges().size()

returns 12, because a cube has a total of 12 edges, And:

CQ(aCube).edges("|Z").size()

returns 4, because a cube has 4 edges parallel to the z direction

See more about selectors HERE

ellipse(x_radius: float, y_radius: float, rotation_angle: float = 0.0, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make an ellipse for each item on the stack. :param x_radius: x radius of the ellipse (x-axis of plane the ellipse should lie in) :type x_radius: float > 0 :param y_radius: y radius of the ellipse (y-axis of plane the ellipse should lie in) :type y_radius: float > 0 :param rotation_angle: angle to rotate the ellipse (0 = no rotation = default) :type rotation_angle: float :param forConstruction: should the new wires be reference geometry only? :type forConstruction: true if the wires are for reference, false if they are creating

part geometry

Returns: a new CQ object with the created wires on the stack

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 ellipses use 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: typing_extensions.Literal[- 1, 1] = 1, forConstruction: bool = False, startAtCurrent: bool = True, makeWire: bool = False) → cadquery.cq.Workplane[source]¶

Draw an elliptical arc with x and y radiuses either with start point at current point or or current point being the center of the arc

Parameters

x_radius – x radius of the ellipse (along the x-axis of plane the ellipse should lie in)
y_radius – y radius of the ellipse (along the y-axis of plane the ellipse should lie in)
angle1 – start angle of arc
angle2 – end angle of arc (angle2 == angle1 return closed ellipse = default)
rotation_angle – angle to rotate the created ellipse / arc
sense – clockwise (-1) or counter clockwise (1)
startAtCurrent – True: start point of arc is moved to current point; False: center of arc is on current point
makeWire – convert the resulting arc edge to a wire

end() → cadquery.cq.Workplane[source]¶

Return the parent of this CQ element :rtype: 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")

exportSvg(fileName: str) → None[source]¶

Exports the first item on the stack as an SVG file

For testing purposes mainly.

Parameters: fileName (String, absolute path to the file) – the filename to export

extrude(distance: float, combine: bool = True, clean: bool = True, both: bool = False, taper: Optional[float] = None) → cadquery.cq.Workplane[source]¶

Use all un-extruded wires in the parent chain to create a prismatic solid.

Parameters

distance (float, negative means opposite the normal direction) – the distance to extrude, normal to the workplane plane
combine (boolean) – True to combine the resulting solid with parent solids if found.
clean (boolean) – call clean() afterwards to have a clean shape
both (boolean) – extrude in both directions symmetrically
taper (float) – angle for optional tapered extrusion

Returns

a CQ object with the resulting solid selected.

extrude always adds material to a part.

The returned object is always a CQ object, and depends on wither combine is True, and whether 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.

FutureEnhancement:: Support for non-prismatic extrusion ( IE, sweeping along a profile, not just perpendicular to the plane extrude to surface. this is quite tricky since the surface selected may not be planar

faces(selector: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select the faces of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the faces of all objects are collected and a list of all the distinct faces is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) – A selector
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains all of the distinct faces of all objects on the current stack, filtered by the provided selector.

If there are no vertices for any objects on the current stack, an empty CQ object is returned.

The typical use is to select the faces of a single object on the stack. For example:

CQ(aCube).faces("+Z").size()

returns 1, because a cube has one face with a normal in the +Z direction. Similarly:

CQ(aCube).faces().size()

returns 6, because a cube has a total of 6 faces, And:

CQ(aCube).faces("|Z").size()

returns 2, because a cube has 2 faces having normals parallel to the z direction

See more about selectors HERE

fillet(radius: float) → cadquery.cq.Workplane[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 the parent chain of the selected edges.

Parameters: radius (positive float) – the radius of the fillet, must be > zero
Raises: ValueError if at least one edge is not selected
Raises: ValueError if the solid containing the edge is not in the chain
Returns: cq object with the resulting solid selected.

This example will create a unit cube, with the top edges filleted:

s = Workplane().box(1,1,1).faces("+Z").edges().fillet(0.1)

findFace(searchStack: bool = True, searchParents: bool = True) → cadquery.occ_impl.shapes.Face[source]¶

Finds the first face object in the chain, searching from the current node backwards through parents until one is found.

Parameters

searchStack – should objects on the stack be searched first.
searchParents – should parents be searched?

Raises

ValueError if no face is found in the current object or its parents, and errorOnEmpty is True

findSolid(searchStack: bool = True, searchParents: bool = True) → Union[cadquery.occ_impl.shapes.Solid, cadquery.occ_impl.shapes.Compound][source]¶

Finds the first solid object in the chain, searching from the current node backwards through parents until one is found.

Parameters

searchStack – should objects on the stack be searched first.
searchParents – should parents be searched?

Raises

ValueError if no solid is found in the current object or its parents, and errorOnEmpty is True

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 workplanes or 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 its results with an object already on the stack.

first() → cadquery.cq.Workplane[source]¶: Return the first item on the stack :returns: the first item on the stack. :rtype: a CQ object

hLine(distance: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a horizontal line from the current point the provided distance

Parameters

distance (float) –

distance from current point

Returns

the Workplane object with the current point at the end of the new line

hLineTo(xCoord: float, forConstruction: bool = False) → cadquery.cq.Workplane[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: xCoord (float) – x coordinate for the end of the line
Returns: the Workplane object with the current point at the end of the new line

hole(diameter: float, depth: Optional[float] = None, clean: bool = True) → cadquery.cq.Workplane[source]¶

Makes a hole for each item on the stack.

Parameters

diameter (float > 0) – the diameter of the hole
depth (float > 0 or None to drill thru the entire part.) – the depth of the hole
clean (boolean) – call clean() afterwards to have a clean shape

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 a construction rectangle to define the centers of a set of holes, like so:

s = Workplane(Plane.XY()).box(2,4,0.5).faces(">Z").workplane()                    .rect(1.5,3.5,forConstruction=True)                    .vertices().hole(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 quite time consuming to create, but are quite easily defined by users.

see cboreHole() and cskHole() to make counterbores or countersinks

interpPlate(surf_edges: Union[Sequence[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]], Sequence[cadquery.occ_impl.shapes.Edge]], surf_pts: Sequence[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]] = [], thickness: float = 0, combine: bool = 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) → cadquery.cq.Workplane[source]¶

Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and going through ‘surf_pts’ points. Using pushpoints directly with interpPlate and combine=True, can be very ressources intensive depending on the complexity of the shape. In this case set combine=False.

:param surf_edges :type 1 surf_edges: list of [x,y,z] float ordered coordinates :type 2 surf_edges: list of ordered or unordered CadQuery wires :param surf_pts = [] (uses only edges if []) :type surf_pts: list of [x,y,z] float coordinates :param thickness = 0 (returns 2D surface if 0) :type thickness: float (may be negative or positive depending on thicknening direction) :param combine: should the results be combined with other solids on the stack

(and each other)?

Parameters: clean (boolean) – call clean() afterwards to have a clean shape

:param Degree = 3 (OCCT default) :type Degree: Integer >= 2 :param NbPtsOnCur = 15 (OCCT default) :type: NbPtsOnCur Integer >= 15 :param NbIter = 2 (OCCT default) :type: NbIterInteger >= 2 :param Anisotropie = False (OCCT default) :type Anisotropie: Boolean :param: Tol2d = 0.00001 (OCCT default) :type Tol2d: float > 0 :param Tol3d = 0.0001 (OCCT default) :type Tol3dReal: float > 0 :param TolAng = 0.01 (OCCT default) :type TolAngReal: float > 0 :param TolCurv = 0.1 (OCCT default) :type TolCurvReal: float > 0 :param MaxDeg = 8 (OCCT default) :type MaxDegInteger: Integer >= 2 (?) :param MaxSegments = 9 (OCCT default) :type MaxSegments: Integer >= 2 (?)

intersect(toIntersect: Union[Workplane, cadquery.occ_impl.shapes.Solid, cadquery.occ_impl.shapes.Compound], clean: bool = True) → cadquery.cq.Workplane[source]¶

Intersects the provided solid from the current solid.

Parameters

toIntersect (a solid object, or a CQ object having a solid,) – object to intersect
clean (boolean) – call clean() afterwards to have a clean shape

Raises

ValueError if there is no solid to intersect with in the chain

Returns

a CQ object with the resulting object selected

item(i: int) → cadquery.cq.Workplane[source]¶: Return the ith item on the stack. :rtype: a CQ object

largestDimension() → float[source]¶: Finds the largest dimension in the stack. Used internally to create thru features, this is how you can compute how long or wide a feature must be to make sure to cut through all of the material :return: A value representing the largest dimension of the first solid on the stack

last() → cadquery.cq.Workplane[source]¶: Return the last item on the stack. :rtype: a CQ object

line(xDist: float, yDist: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a line from the current point to the provided point, using dimensions relative to the current point

Parameters

xDist (float) – x distance from current point
yDist (float) – y distance from current point

Returns

the workplane object with the current point at the end of the new line

see lineTo() if you want to use absolute coordinates to make a line instead.

lineTo(x: float, y: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a line from the current point to the provided point

Parameters

x (float) – the x point, in workplane plane coordinates
y (float) – the y point, in workplane plane coordinates

Returns

the Workplane object with the current point at the end of the new line

see line() if you want to use relative dimensions to make a line instead.

loft(filled: bool = True, ruled: bool = False, combine: bool = True) → cadquery.cq.Workplane[source]¶: Make a lofted solid, through the set of wires. :return: a CQ object containing the created loft

mirror(mirrorPlane='XY', basePointVector=0, 0, 0)[source]¶

Mirror a single CQ object. This operation is the same as in the FreeCAD PartWB’s mirroring

Parameters

mirrorPlane (string, one of "XY", "YX", "XZ", "ZX", "YZ", "ZY" the planes) – the plane to mirror about
basePointVector (tuple) – the base point to mirror about

mirrorX() → cadquery.cq.Workplane[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.

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.

Future Enhancements:: mirrorX().mirrorY() should work but doesnt, due to some FreeCAD weirdness

mirrorY() → cadquery.cq.Workplane[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.

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

Future Enhancements:: mirrorX().mirrorY() should work but doesnt, due to some FreeCAD weirdness

move(xDist: float = 0, yDist: float = 0) → cadquery.cq.Workplane[source]¶

Move the specified distance from the current point, without drawing.

Parameters

xDist (float, or none for zero) – desired x distance, in local coordinates
yDist (float, or none for zero.) – desired y distance, in local coordinates

Not to be confused with center(), which moves the center of the entire workplane, this method only moves the current point ( and therefore does not affect objects already drawn ).

See moveTo() to do the same thing but using absolute coordinates

moveTo(x: float = 0, y: float = 0) → cadquery.cq.Workplane[source]¶

Move to the specified point, without drawing.

Parameters

x (float, or none for zero) – desired x location, in local coordinates
y (float, or none for zero.) – desired y location, in local coordinates

Not to be confused with center(), which moves the center of the entire workplane, this method only moves the current point ( and therefore does not affect objects already drawn ).

See move() to do the same thing but using relative dimensions

newObject(objlist: Iterable[Union[cadquery.occ_impl.geom.Vector, cadquery.occ_impl.geom.Location, cadquery.occ_impl.shapes.Shape]]) → cadquery.cq.Workplane[source]¶

Create a new workplane object from this one.

Overrides CQ.newObject, and should be used by extensions, plugins, and subclasses to create new objects.

Parameters: objlist (a list of CAD primitives) – new objects to put on the stack
Returns: a new Workplane object with the current workplane as a parent.

offset2D(d: float, kind: typing_extensions.Literal[arc, intersection, tangent] = 'arc') → cadquery.cq.Workplane[source]¶

Creates a 2D offset wire.

Parameters

d (float) – thickness. Negative thickness denotes offset to inside.
kind – offset kind. Use “arc” for rounded and “intersection” for sharp edges (default: “arc”)

Returns

CQ object with resulting wire(s).

parametricCurve(func: Callable[[float], Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]], N: int = 400, start: float = 0, stop: float = 1) → cadquery.cq.Workplane[source]¶

Create a spline interpolated through the provided points.

Parameters

func (float --> (float,float)) – function f(t) that will generate (x,y) pairs
N – number of points for discretization
start – starting value of the parameter t
stop – final value of the parameter t

Returns

a Workplane object with the current point unchanged

polarArray(radius: float, startAngle: float, angle: float, count: int, fill: bool = True, rotate: bool = True) → cadquery.cq.Workplane[source]¶

Creates an polar array of points and pushes them onto the stack. The 0 degree reference angle is located along the local X-axis.

Parameters

radius – Radius of the array.
startAngle – Starting angle (degrees) of array. 0 degrees is situated along local X-axis.
angle – The angle (degrees) to fill with elements. A positive value will fill in the counter-clockwise direction. If fill is false, angle is the angle between elements.
count – Number of elements in array. ( > 0 )
fill – Interpret the angle as total if True (default: True).
rotate – Rorate every item (default: True).

polarLine(distance: float, angle: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a line of the given length, at the given angle from the current point

Parameters

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

Returns

the Workplane object with the current point at the end of the new line

polarLineTo(distance: float, angle: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a line from the current point to the given polar co-ordinates

Useful if it is more convenient to specify the end location rather than the distance and angle from the current point

Parameters

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

Returns

the Workplane object with the current point at the end of the new line

polygon(nSides: int, diameter: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Creates a polygon inscribed in a circle of the specified diameter for each point on the stack

The first vertex is always oriented in the x direction.

Parameters

nSides – number of sides, must be > 3
diameter – the size of the circle the polygon is inscribed into

Returns

a polygon wire

polyline(listOfXYTuple: Sequence[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]], forConstruction: bool = False, includeCurrent: bool = False) → cadquery.cq.Workplane[source]¶

Create a polyline from a list of points

Parameters

listOfXYTuple (list of 2-tuples) – a list of points in Workplane coordinates
forConstruction (true if the edges are for reference, false if they are for creating geometry part geometry) – whether or not the edges are used for reference
includeCurrent – use current point as a starting point of the polyline

Returns

a new CQ object with a list of edges on the stack

NOTE most commonly, the resulting wire should be closed.

pushPoints(pntList: Iterable[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector, cadquery.occ_impl.geom.Location]]) → cadquery.cq.Workplane[source]¶

Pushes a list of points onto the stack as vertices. The points are in the 2-d coordinate space of the workplane face

Parameters: pntList (list of 2-tuples, in local coordinates) – a list of points to push onto the stack
Returns: a new workplane with the desired points on the stack.

A common use is to provide a list of points for a subsequent operation, such as creating circles 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 three holes. See circle() for how it works.

radiusArc(endPoint: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], radius: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Draw an arc from the current point to endPoint with an arc defined by the radius.

Parameters

endPoint (2-tuple, in workplane coordinates) – end point for the arc
radius (float, the radius of the arc between start point and end point.) – the radius of the arc

Returns

a workplane with the current point at the end of the arc

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 = True) → cadquery.cq.Workplane[source]¶

Creates an array of points and pushes them onto the stack. If you want to position the array at another point, create another workplane that is shifted to the position you would like to use as a reference

Parameters

xSpacing – spacing between points in the x direction ( must be > 0)
ySpacing – spacing between points in the y direction ( must be > 0)
xCount – number of points ( > 0 )
yCount – number of points ( > 0 )
center – if true, the array will be centered at the center of the workplane. if false, the lower left corner will be at the center of the work plane

rect(xLen: float, yLen: float, centered: bool = True, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a rectangle for each item on the stack.

Parameters

xLen (float > 0) – length in xDirection ( in workplane coordinates )
yLen (float > 0) – length in yDirection ( in workplane coordinates )
centered (boolean) – true if the rect is centered on the reference point, false if the lower-left is on the reference point
forConstruction (true if the wires are for reference, false if they are creating part geometry) – should the new wires be reference geometry only?

Returns

a new CQ object with the created wires on the stack

A common use case is to use a for-construction rectangle to define the centers of a hole 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.

Future Enhancements:: better way to handle forConstruction project points not in the workplane plane onto the workplane plane

revolve(angleDegrees: float = 360.0, axisStart: Optional[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]] = None, axisEnd: Optional[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]] = None, combine: bool = True, clean: bool = True) → cadquery.cq.Workplane[source]¶

Use all un-revolved wires in the parent chain to create a solid.

Parameters

angleDegrees (float, anything less than 360 degrees will leave the shape open) – the angle to revolve through.
axisStart (tuple, a two tuple) – the start point of the axis of rotation
axisEnd (tuple, a two tuple) – the end point of the axis of rotation
combine (boolean, combine with parent solid) – True to combine the resulting solid with parent solids if found.
clean (boolean) – call clean() afterwards to have a clean shape

Returns

a CQ object with the resulting solid selected.

The returned object is always a CQ object, and depends on wither combine is True, and whether 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.

rotate(axisStartPoint: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], axisEndPoint: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], angleDegrees: float) → cadquery.cq.Workplane[source]¶

Returns a copy of all of the items on the stack rotated through and angle around the axis of rotation.

Parameters

axisStartPoint (a 3-tuple of floats) – The first point of the axis of rotation
axisEndPoint (a 3-tuple of floats) – The second point of the axis of rotation
angleDegrees (float) – the rotation angle, in degrees

Returns

a CQ object

rotateAboutCenter(axisEndPoint: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], angleDegrees: float) → cadquery.cq.Workplane[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

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.

WARNING: This version returns the same cq object instead of a new one– the old object is not accessible.

Future Enhancements:

A version of this method that returns a transformed copy, rather than modifying the originals
This method doesnt expose a very good interface, because the axis of rotation could be inconsistent between multiple objects. This is because the beginning of the axis is variable, while the end is fixed. This is fine when operating on one object, but is not cool for multiple.

sagittaArc(endPoint: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], sag: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Draw an arc from the current point to endPoint with an arc defined by the sag (sagitta).

Parameters

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

Returns

a workplane with the current point at the end of the arc

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. See “https://en.wikipedia.org/wiki/Sagitta_(geometry)” for more information.

section(height: float = 0.0) → cadquery.cq.Workplane[source]¶

Slices current solid at the given height.

Parameters: height (float) – height to slice at (default: 0)
Returns: a CQ object with the resulting face(s).

shell(thickness: float, kind: typing_extensions.Literal[arc, intersection] = 'arc') → cadquery.cq.Workplane[source]¶

Remove the selected faces to create a shell of the specified thickness.

To shell, first create a solid, and in the same chain select the faces you wish to remove.

Parameters

thickness – a positive float, representing the thickness of the desired shell. Negative values shell inwards, positive values shell outwards.
kind – kind of joints, intersetion or arc (default: arc).

Raises

ValueError if the current stack contains objects that are not faces of a solid further up in the chain.

Returns

a CQ object with the resulting shelled solid selected.

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)

Shelling is one of the cases where you may need to use the add method to select several faces. For example, this example creates a 3-walled corner, by removing three faces of a cube:

s = Workplane().box(1,1,1)
s1 = s.faces("+Z")
s1.add(s.faces("+Y")).add(s.faces("+X"))
self.saveModel(s1.shell(0.2))

This fairly yucky syntax for selecting multiple faces is planned for improvement

Note: When sharp edges are shelled inwards, they remain sharp corners, but outward shells are automatically filleted, because an outward offset from a corner generates a radius.

Future Enhancements:: Better selectors to make it easier to select multiple faces

shells(selector: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select the shells of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the shells of all objects are collected and a list of all the distinct shells is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) – A selector
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains all of the distinct solids of all objects on the current stack, filtered by the provided selector.

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 will typically be composed of multiple faces.

See more about selectors HERE

size() → int[source]¶: Return the number of objects currently on the stack

slot2D(length: float, diameter: float, angle: float = 0) → cadquery.cq.Workplane[source]¶

Creates a rounded slot for each point on the stack.

Parameters

diameter – desired diameter, or width, of slot
length – desired end to end length of slot
angle – angle of slot in degrees, with 0 being along x-axis

Returns

a new CQ object with the created wires on the stack

Can be used to create arrays of slots, such as in cooling applications:

result = cq.Workplane(“XY”).box(10,25,1).rarray(1,2,1,10).slot2D(8,1,0).cutThruAll()

solids(selector: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select the solids of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the solids of all objects are collected and a list of all the distinct solids is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) – A selector
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains all of the distinct solids of all objects on the current stack, filtered by the provided selector.

If there are no solids for any objects on the current stack, an empty CQ object is returned

The typical use is to select the a single object on the stack. For example:

CQ(aCube).solids().size()

returns 1, because a cube consists of one solid.

It is possible for single CQ object ( or even a single CAD primitive ) to contain multiple solids.

See more about selectors HERE

sphere(radius: float, direct: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector] = 0, 0, 1, angle1: float = - 90, angle2: float = 90, angle3: float = 360, centered: Tuple[bool, bool, bool] = True, True, True, combine: bool = True, clean: bool = True) → cadquery.cq.Workplane[source]¶

Returns a 3D sphere with the specified radius for each point on the stack

Parameters

radius (float > 0) – 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 – A three-tuple of booleans that determines whether the sphere is centered on each axis origin
combine (true to combine shapes, false otherwise) – Whether the results should be combined with other solids on the stack (and each other)

Returns

A sphere object for each point on the stack

Centered is a tuple that describes whether the sphere should be centered on the x,y, and z axes. If true, the sphere is centered on the respective axis relative to the workplane origin, if false, the workplane center will represent the lower bound of the resulting sphere.

One sphere is created for each item on the current stack. If no items are on the stack, one box 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 found in the chain, the result is that solid with all spheres produced fused onto it otherwise, the result is the combination of all the produced boxes

If combine is false, the result will be a list of the spheres produced

spline(listOfXYTuple: Iterable[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]], tangents: Optional[Sequence[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]]] = None, periodic: bool = False, forConstruction: bool = False, includeCurrent: bool = False, makeWire: bool = False) → cadquery.cq.Workplane[source]¶

Create a spline interpolated through the provided points.

Parameters

listOfXYTuple (list of 2-tuple) – points to interpolate through
tangents – tuple of Vectors specifying start and finish tangent
periodic – creation of periodic curves
includeCurrent – use current point as a starting point of the curve
makeWire – convert the resulting spline edge to a wire

Returns

a Workplane object with the current point at the end of the spline

The spline will begin at the current point, and end with the last point in the XY 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 points that cannot be correctly interpreted as a spline.

Future Enhancements:

provide access to control points

split(keepTop: bool = False, keepBottom: bool = False) → cadquery.cq.Workplane[source]¶

Splits a solid on the stack into two parts, optionally keeping the separate parts.

Parameters

keepTop (boolean) – True to keep the top, False or None to discard it
keepBottom (boolean) – True to keep the bottom, False or None to discard it

Raises

ValueError if keepTop and keepBottom are both false.

Raises

ValueError if there is not a solid in the current stack or the 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 creates split bushing:

#drill a hole in the side
c = Workplane().box(1,1,1).faces(">Z").workplane().circle(0.25).cutThruAll()F
#now cut it in half sideways
c.faces(">Y").workplane(-0.5).split(keepTop=True)

sweep(path: cadquery.cq.Workplane, multisection: bool = False, sweepAlongWires: Optional[bool] = None, makeSolid: bool = True, isFrenet: bool = False, combine: bool = True, clean: bool = True, transition: typing_extensions.Literal[right, round, transformed] = 'right') → cadquery.cq.Workplane[source]¶

Use all un-extruded wires in the parent chain to create a swept solid.

Parameters

path – A wire along which the pending wires will be swept
sweepAlongWires (boolean) – 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 (boolean) – True to combine the resulting solid with parent solids if found.
clean (boolean) – call clean() afterwards to have a clean shape
transition – handling of profile orientation at C1 path discontinuities. Possible values are {‘transformed’,’round’, ‘right’} (default: ‘right’).

Returns

a CQ object with the resulting solid selected.

tag(name: str) → cadquery.cq.Workplane[source]¶

Tags the current CQ object for later reference.

Parameters: name (string) – the name to tag this object with
Returns: self, a cq object with tag applied

tangentArcPoint(endpoint: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], forConstruction: bool = False, relative: bool = True) → cadquery.cq.Workplane[source]¶

Draw an arc as a tangent from the end of the current edge to endpoint.

Parameters

endpoint (2-tuple, 3-tuple or Vector) – 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

Returns

a Workplane object with an arc on the stack

Requires the the current first object on the stack is an Edge, as would be the case after a lineTo operation or similar.

text(txt: str, fontsize: float, distance: float, cut: bool = True, combine: bool = False, clean: bool = True, font: str = 'Arial', kind: typing_extensions.Literal[regular, bold, italic] = 'regular', halign: typing_extensions.Literal[center, left, right] = 'center', valign: typing_extensions.Literal[center, top, bottom] = 'center') → cadquery.cq.Workplane[source]¶

Create a 3D text

Parameters

txt (str) – text to be rendered
distance (float, negative means opposite the normal direction) – the distance to extrude, normal to the workplane plane
fontsize (float) – size of the font
cut (boolean) – True to cut the resulting solid from the parent solids if found.
combine (boolean) – True to combine the resulting solid with parent solids if found.
clean (boolean) – call clean() afterwards to have a clean shape
font (str) – fontname (default: Arial)
kind (str) – font type (default: Normal)
halign (str) – horizontal alignment (default: center)
valign (str) – vertical alignment (default: center)

Returns

a CQ object with the resulting solid selected.

extrude always adds material to a part.

The returned object is always a CQ object, and depends on wither combine is True, and whether 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.

threePointArc(point1: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], point2: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector], forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Draw an arc from the current point, through point1, and ending at point2

Parameters

point1 (2-tuple, in workplane coordinates) – point to draw through
point2 (2-tuple, in workplane coordinates) – end point for the arc

Returns

a workplane with the current point at the end of the arc

Future Enhancements:: provide a version that allows an arc using relative measures provide a centerpoint arc provide tangent arcs

toOCC() → Any[source]¶: Directly returns the wrapped FreeCAD object to cut down on the amount of boiler plate code needed when rendering a model in FreeCAD’s 3D view. :return: The wrapped FreeCAD object :rtype A FreeCAD object or a SolidReference

toPending() → cadquery.cq.Workplane[source]¶

Adds wires/edges to pendingWires/pendingEdges.

Returns: same CQ object with updated context.

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.

transformed(rotate: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector] = 0, 0, 0, offset: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector] = 0, 0, 0) → cadquery.cq.Workplane[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 is given in coordinates local to the current plane The new plane is rotated through the angles specified by the components of the rotation vector. :param rotate: 3-tuple of angles to rotate, in degrees relative to work plane coordinates :param offset: 3-tuple to offset the new plane, in local work plane coordinates :return: a new work plane, transformed as requested

translate(vec: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]) → cadquery.cq.Workplane[source]¶

Returns a copy of all of the items on the stack moved by the specified translation vector.

Parameters: tupleDistance (a 3-tuple of float) – distance to move, in global coordinates
Returns: a CQ object

twistExtrude(distance: float, angleDegrees: float, combine: bool = True, clean: bool = True) → cadquery.cq.Workplane[source]¶

Extrudes a wire in the direction normal to the plane, but also twists by the specified angle 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 addition of 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 with complex geometries

Parameters

distance – the distance to extrude normal to the workplane
angle – angline ( in degrees) to rotate through the extrusion
combine (boolean) – True to combine the resulting solid with parent solids if found.
clean (boolean) – call clean() afterwards to have a clean shape

Returns

a CQ object with the resulting solid selected.

union(toUnion: Optional[Union[Workplane, cadquery.occ_impl.shapes.Solid, cadquery.occ_impl.shapes.Compound]] = None, clean: bool = True, glue: bool = False, tol: Optional[float] = None) → cadquery.cq.Workplane[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

toUnion (a solid object, or a CQ object having a solid,) –
clean (boolean) – call clean() afterwards to have a clean shape (default True)
glue (boolean) – use a faster gluing mode for non-overlapping shapes (default False)
tol (float) – tolerance value for fuzzy bool operation mode (default None)

Raises

ValueError if there is no solid to add to in the chain

Returns

a CQ object with the resulting object selected

vLine(distance: float, forConstruction: bool = False) → cadquery.cq.Workplane[source]¶

Make a vertical line from the current point the provided distance

Parameters

distance (float) –

distance from current point

Returns

the workplane object with the current point at the end of the new line

vLineTo(yCoord: float, forConstruction: bool = False) → cadquery.cq.Workplane[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: yCoord (float) – y coordinate for the end of the line
Returns: the Workplane object with the current point at the end of the new line

val() → Union[cadquery.occ_impl.geom.Vector, cadquery.occ_impl.geom.Location, cadquery.occ_impl.shapes.Shape][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[Union[cadquery.occ_impl.geom.Vector, cadquery.occ_impl.geom.Location, cadquery.occ_impl.shapes.Shape]][source]¶

get the values in the current list

Return type: list of FreeCAD 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: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select the vertices of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the vertices of all objects are collected and a list of all the distinct vertices is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) –
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains the distinct vertices of all objects on the current stack, after being filtered by the selector, if provided

If there are no vertices for any objects on the current stack, an empty CQ object is 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 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!

StringSyntaxSelector

wedge(dx: float, dy: float, dz: float, xmin: float, zmin: float, xmax: float, zmax: float, pnt: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector] = Vector: (0.0, 0.0, 0.0), dir: Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector] = Vector: (0.0, 0.0, 1.0), centered: Tuple[bool, bool, bool] = (True, True, True), combine: bool = True, clean: bool = True) → cadquery.cq.Workplane[source]¶

Parameters

dx – Distance along the X axis
dy – Distance along the Y axis
dz – Distance along the Z axis
xmin – The minimum X location

:param zmin:The minimum Z location :param xmax:The maximum X location :param zmax: The maximum Z location :param pnt: A vector (or tuple) for the origin of the direction for the wedge :param dir: The direction vector (or tuple) for the major axis of the wedge :param combine: Whether the results should be combined with other solids on the stack

(and each other)

Parameters: clean – true to attempt to have the kernel clean up the geometry, false otherwise
Returns: A wedge object for each point on the stack

One wedge is created for each item on the current stack. If no items are on the stack, one wedge 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 found in 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) → cadquery.cq.Workplane[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

Parameters: forConstruction (boolean. true if the object is only for reference) – whether the wire should be used to make a solid, or if it is just for reference

This method is primarily of use to plugin developers making utilities for 2-d construction. This method should be called when a user operation implies that 2-d construction is finished, and we are ready to begin working in 3d

SEE ‘2-d construction concepts’ for a more detailed explanation of how CadQuery handles edges, wires, etc

Any non edges will still remain.

wires(selector: Optional[cadquery.selectors.Selector] = None, tag: Optional[str] = None) → cadquery.cq.Workplane[source]¶

Select the wires of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the wires of all objects are collected and a list of all the distinct wires is returned.

Parameters

selector (None, a Selector object, or a string selector expression.) – A selector
tag (string) – if set, search the tagged CQ object instead of self

Returns

a CQ object who’s stack contains all of the distinct wires of all objects on the current stack, filtered by the provided selector.

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:

CQ(aCube).faces("+Z").wires().size()

returns 1, because a face typically only has one outer wire

See more about selectors HERE

workplane(offset: float = 0.0, invert: bool = False, centerOption: typing_extensions.Literal[CenterOfMass, ProjectedOrigin, CenterOfBoundBox] = 'CenterOfMass', origin: Optional[Union[Tuple[float, float], Tuple[float, float, float], cadquery.occ_impl.geom.Vector]] = None) → cadquery.cq.Workplane[source]¶

Creates a new 2-D workplane, located relative to the first face on the stack.

Parameters

offset (float or None=0.0) – offset for the work plane in the Z direction. Default
invert (boolean or None=False) – invert the Z direction from that of the face.
centerOption (string or None='CenterOfMass') – how local origin of workplane is determined.
origin (Vector or None) – origin for plane center, requires ‘ProjectedOrigin’ centerOption.

Return type

Workplane object ( which is a subclass of CQ )

The first element on the stack must be a face, a set of co-planar faces or a vertex. If a vertex, then the parent item on the chain immediately before the vertex must be a face.

The result will be a 2-d working plane with a new coordinate system set up as follows:

The origin will be located in the center of the face/faces, if a face/faces was selected. If a vertex was selected, the origin will be at the vertex, and located on the face. The centerOption paramter sets how the center is defined. Options are ‘CenterOfMass’, ‘CenterOfBoundBox’, or ‘ProjectedOrigin’. ‘CenterOfMass’ and ‘CenterOfBoundBox’ are in relation to the selected face/faces. ‘ProjectedOrigin’ uses the current planes origin by default or can be specified as an arbitrary point using the optional origin parameter.

The Z direction will be normal to the plane of the face,computed at the center point.

The X direction will be parallel to the x-y plane. If the workplane is parallel to the global x-y plane, the x direction of the workplane will co-incide with the global x direction.

Most commonly, the selected face will be planar, and the workplane lies in the same plane of the face ( IE, offset=0). Occasionally, it is useful to define a face offset from an existing surface, and even more rarely to define a workplane based on a face that is not planar.

To create a workplane without first having a face, use the Workplane() method.

Future Enhancements:

Allow creating workplane from planar wires
Allow creating workplane based on an arbitrary point on a face, not just the center. For now you can work around by creating a workplane and then offsetting the center afterwards.

workplaneFromTagged(name: str) → cadquery.cq.Workplane[source]¶

Copies the workplane from a tagged parent.

Parameters: name (string) – tag to search for
Returns: a CQ object with name’s workplane

cadquery.sortWiresByBuildOrder(wireList: List[cadquery.occ_impl.shapes.Wire]) → List[List[cadquery.occ_impl.shapes.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 wires there 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 inner ones

Returns, list of lists.