## Documentation

- CadQuery Documentation
- CadQuery Readme
- CadQuery Examples
- CadQuery API Reference

## 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

## Core Classes

Class | Description
--- | ---
CQ(obj) | Provides enhanced functionality for a wrapped CAD primitive.
Plane(origin, xDir, normal) | A 2d coordinate system in space, with the x-y axes on the a plane, and a particular point as the origin.
Workplane(inPlane[origin, obj]) | Defines a coordinate system in space, in which 2-d coordinates can be used.

## 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 Classes

Class | Description
--- | ---
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[directionMax]) | Selects objects closest or farthest in the specified direction.
StringSyntaxSelector(selectorString) | Filter lists objects using a simple string syntax.

## 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