CadQuery String Selectors

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.

String selectors are used as arguments to the various selection methods:

Note

String selectors are shortcuts to concrete selector classes, which you can use or extend. See CadQuery Class Reference for more details

If you find that the built-in selectors are not sufficient, you can easily plug in your own. See Extending CadQuery to see how.

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.

Warning

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.

The axis used in the listing below are for illustration: any axis would work similarly in each case.

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

Filtering Edges

Some filter types are not supported for edges. The selector usually refers to the direction of the edge.

Warning

Non-linear edges are not selected for any selectors except type (%). Non-linear edges are never returned when these filters are applied.

The axis used in the listing below are for illustration: any axis would work similarly in each case.

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
%Line 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

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 Edges farthest in the positive y dir 0 or 1
<Y DirectionMinMaxSelector Edges farthest in the negative y dir 0 or 1

Future Enhancements

  • Support direct vectors inline, such as |(x,y,z)
  • Support multiple selectors separated by spaces, which unions the results, such as “+Z +Y to select both z and y-most faces

Table Of Contents

Previous topic

Primitive Class Reference

Next topic

CadQuery Class Reference