Documentation

BREP Terminology


vertex A single point in space
edge A connection between two or more vertices along a particular path (called a curve)
wire A collection of edges that are connected together
face A set of edges or wires that enclose a surface
shell A collection of faces that are connected together along some of their edges
solid A shell that has a closed interior
compound A collection of solids

Named Planes


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
XZ +x +z -y
front +x +y +z
back -x +y -z
left +z +y -x
right -z +y +x
top +x -z +y
bottom +x +z -y

Selector Methods


CadQuery selector strings allow filtering various types of object lists. Most commonly, Edges, Faces, and Vertices are used, but all objects types can be filtered.
Selector Method Description
CQ.faces(selector=None) Select the faces of objects on the stack, optionally filtering the selection.
CQ.edges(selector=None) Select the edges of objects on the stack, optionally filtering the selection.
CQ.vertices(selector=None) Select the vertices of objects on the stack, optionally filtering the selection.
CQ.solids(selector=None) Select the solids of objects on the stack, optionally filtering the selection.
CQ.shells(selector=None) Select the shells of objects on the stack, optionally filtering the selection.

Selector String Modifiers


Selectors are a complex topic: see CadQuery String Selectors for more information.
Axis Strings are: X, Y, Z, XY, YZ, XZ
Modifier Description
| 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)

Examples of Filtering Faces


All types of filters work on faces. In most cases, the selector refers to the direction of the normal vector of the face. If a face is not planar, selectors are evaluated at the center of mass of the face. This can lead to results that are quite unexpected.
Selector Selector Class Selects # Objects Returned
+Z DirectionSelector Faces with normal in +z direction 0 or 1
|Z ParallelDirSelector Faces parallel to xy plane 0..many
-X DirectionSelector Faces with normal in neg x direction 0..many
#Z PerpendicularDirSelector Faces perpendicular to z direction 0..many
%Plane TypeSelector Faces of type plane 0..many
>Y DirectionMinMaxSelector Face farthest in the positive y dir 0 or 1
<Y DirectionMinMaxSelector Face farthest in the negative y dir 0 or 1

Examples of Filtering Edges


Some filter types are not supported for edges. The selector usually refers to the direction of the edge. Non-linear edges are not selected for any selectors except type (%). Non-linear edges are never returned when these filters are applied.
Selector Selector Class Selects # Objects Returned
+Z DirectionSelector Edges aligned in the Z direction 0..many
|Z ParallelDirSelector Edges parallel to z direction 0..many
-X DirectionSelector Edges aligned in neg x direction 0..many
#Z PerpendicularDirSelector Edges perpendicular to z direction 0..many
%Plane TypeSelector Edges type line 0..many
>Y DirectionMinMaxSelector Edges farthest in the positive y dir 0 or 1
<Y DirectionMinMaxSelector Edges farthest in the negative y dir 0 or 1

Examples of Filtering Vertices


Only a few of the filter types apply to vertices. The location of the vertex is the subject of the filter.
Selector Selector Class Selects # Objects Returned
>Y DirectionMinMaxSelector Vertices farthest in the positive y dir 0 or 1
<Y DirectionMinMaxSelector Vertices farthest in the negative y dir 0 or 1