The examples on this page can help you learn how to build objects with CadQuery.
They are organized from simple to complex, so working through them in order is the best way to absorb them.
Each example lists the api elements used in the example for easy reference. Items introduced in the example are marked with a !
Note
You may want to work through these examples by pasting the text into a scratchpad on the live website. If you do, make sure to take these steps so that they work:
- paste the content into the build() method, properly intented, and
- add the line 'return result' at the end. The samples below are autogenerated, but they use a different syntax than the models on the website need to be.
Note
We strongly recommend installing FreeCAD, and the cadquery-freecad-module, so that you can work along with these examples interactively. See installation for more info.
Warning
- You have to have an svg capable browser to view these!
List of Examples
Just about the simplest possible example, a rectangular box
Api References
- :py
Workplane! - :py
Workplane.box!
A rectangular box, but with a hole added.
">Z" selects the top most face of the resulting box. The hole is located in the center because the default origin of a working plane is at the center of the face. The default hole depth is through the entire part.
Api References
- :py
Workplane.hole! - :py
Workplane.box - :py
Workplane.box
Build a prismatic solid using extrusion. After a drawing operation, the center of the previous object is placed on the stack, and is the reference for the next operation. So in this case, the rect() is drawn centered on the previously draw circle.
By default, rectangles and circles are centered around the previous working point.
Api References
- :py
Workplane.circle! - :py
Workplane.rect! - :py
Workplane.extrude! - :py
Workplane
Sometimes you need to build complex profiles using lines and arcs. This example builds a prismatic solid from 2-d operations.
2-d operations maintain a current point, which is initially at the origin. Use close() to finish a closed curve.
Api References
- :py
Workplane.threePointArc! - :py
Workplane.lineTo! - :py
Workplane.extrude - :py
Workplane
In this example, a closed profile is required, with some interior features as well.
This example also demonstrates using multiple lines of code instead of longer chained commands, though of course in this case it was possible to do it in one long line as well.
A new work plane center can be established at any point.
Api References
- :py
Workplane.center! - :py
Workplane - :py
Workplane.circle - :py
Workplane.rect - :py
Workplane.extrude
Sometimes you need to create a number of features at various locations, and using :pyWorkplane.center is too cumbersome.
You can use a list of points to construct multiple objects at once. Most construction methods, like :pyWorkplane.circle and :pyWorkplane.rect, will operate on multiple points if they are on the stack
Api References
- :py
Workplane.points! - :py
Workplane - :py
Workplane.circle - :py
Workplane.extrude
You can create polygons for each stack point if you would like. Useful in 3d printers whos firmware does not correct for small hole sizes.
Api References
- :py
Workplane.polygon! - :py
Workplane.pushPoints - :py
Workplane.box
:pyWorkplane.polyline allows creating a shape from a large number of chained points connected by lines.
This example uses a polyline to create one half of an i-beam shape, which is mirrored to create the final profile.
Api References
- :py
Workplane.polyline! - :py
Workplane - :py
Workplane.mirrorY - :py
Workplane.extrude
This example defines a side using a spline curve through a collection of points. Useful when you have an edge that needs a complex profile
Api References
- :py
Workplane.spline! - :py
Workplane - :py
Workplane.close - :py
Workplane.lineTo - :py
Workplane.extrude
You can mirror 2-d geometry when your shape is symmetric. In this example we also introduce horizontal and vertical lines, which make for slightly easier coding.
Api References
- :py
Workplane.hLine! - :py
Workplane.vLine! - :py
Workplane.hLineTo! - :py
Workplane.mirrorY! - :py
Workplane.mirrorX! - :py
Workplane - :py
Workplane.extrude
Api References
- :py
Workplane.moveTo - :py
Workplane.lineTo - :py
Workplane.threePointArc - :py
Workplane.extrude - :py
Workplane.mirror - :py
Workplane.union - :py
CQ.rotate
This example shows how to locate a new workplane on the face of a previously created feature.
Note
Using workplanes in this way are a key feature of CadQuery. Unlike typical 3d scripting language, using work planes frees you from tracking the position of various features in variables, and allows the model to adjust itself with removing redundant dimensions
The :pyWorkplane.faces() method allows you to select the faces of a resulting solid. It accepts a selector string or object, that allows you to target a single face, and make a workplane oriented on that face.
Keep in mind that the origin of new workplanes are located at the center of a face by default.
Api References
- :py
Workplane.faces! - :py
StringSyntaxSelector! selector_reference!- :py
Workplane.workplane - :py
Workplane.box - :py
Workplane
Normally, the :pyWorkplane.workplane method requires a face to be selected. But if a vertex is selected immediately after a face, :pyWorkplane.workplane will locate the workplane on the face, with the origin at the vertex instead of at the center of the face
The example also introduces :pyWorkplane.cutThruAll, which makes a cut through the entire part, no matter how deep the part is
Api References
- :py
Workplane.cutThruAll! selector_reference!- :py
Workplane.vertices! - :py
Workplane.box - :py
Workplane - :py
StringSyntaxSelector!
Workplanes do not have to lie exactly on a face. When you make a workplane, you can define it at an offset from an existing face.
This example uses an offset workplane to make a compound object, which is perfectly valid!
Api References
- :py
Workplane.extrude selector_reference!- :py
Workplane.box - :py
Workplane
You can create a rotated work plane by specifying angles of rotation relative to another workplane
Api References
- :py
Workplane.transformed! - :py
Workplane.box - :py
Workplane.rect - :py
Workplane.faces
You can draw shapes to use the vertices as points to locate other features. Features that are used to locate other features, rather than to create them, are called Construction Geometry
In the example below, a rectangle is drawn, and its vertices are used to locate a set of holes.
Api References
- :py
Workplane.rect(forConstruction=True) selector_reference- :py
Workplane.workplane - :py
Workplane.box - :py
Workplane.hole - :py
Workplane
Shelling converts a solid object into a shell of uniform thickness. To shell an object, one or more faces are removed, and then the inside of the solid is 'hollowed out' to make the shell.
Api References
- :py
Workplane.shell! - :py
Workplane.box - :py
Workplane.faces - :py
Workplane
A loft is a solid swept through a set of wires. This example creates lofted section between a rectangle and a circular section.
Api References
- :py
Workplane.loft! - :py
Workplane.box - :py
Workplane.faces - :py
Workplane.circle - :py
Workplane.rect
Counterbored and countersunk holes are so common that CadQuery creates macros to create them in a single step.
Similar to :pyWorkplane.hole , these functions operate on a list of points as well as a single point.
Api References
- :py
Workplane.cboreHole! - :py
Workplane.cskHole! - :py
Workplane.box - :py
Workplane.rect - :py
Workplane.workplane - :py
Workplane.vertices - :py
Workplane.faces - :py
Workplane
Filleting is done by selecting the edges of a solid, and using the fillet function.
Here we fillet all of the edges of a simple plate.
Api References
- :py
Workplane.fillet! - :py
Workplane.box - :py
Workplane.edges - :py
Workplane
Combining a few basic functions, its possible to make a very good parametric bearing pillow block, with just a few lines of code.
You can split an object using a workplane, and retain either or both halves
Api References
- :py
Workplane.split! - :py
Workplane.box - :py
Workplane.circle - :py
Workplane.cutThruAll - :py
Workplane.workplane - :py
Workplane
CadQuery is based on the OpenCascade.org (OCC) modeling Kernel. Those who are familiar with OCC know about the famous 'bottle' example. http://www.opencascade.org/org/gettingstarted/appli/
- A pythonOCC version is listed here
Of course one difference between this sample and the OCC version is the length. This sample is one of the longer ones at 13 lines, but that's very short compared to the pythonOCC version, which is 10x longer!
Api References
- :py
Workplane.extrude - :py
Workplane.mirrorX - :py
Workplane.threePointArc - :py
Workplane.workplane - :py
Workplane.vertices - :py
Workplane.vLine - :py
Workplane.faces - :py
Workplane
Api References
- :py
Workplane.circle - :py
Workplane.rect - :py
Workplane.extrude - :py
Workplane.box - :py
CQ.all - :py
CQ.faces - :py
CQ.vertices - :py
CQ.edges - :py
CQ.workplane - :py
Workplane.fillet - :py
Workplane.cut - :py
Workplane.combineSolids - :py
Workplane.rotateAboutCenter - :py
Workplane.cboreHole - :py
Workplane.cskHole - :py
Workplane.hole
This script will produce any size regular rectangular Lego(TM) brick. Its only tricky because of the logic regarding the underside of the brick.