CadQuery Examples

Wrapper Classes for FreeCAD These classes provide a stable interface for 3d objects, independent of the FreeCAD interface.

Future work might include use of pythonOCC, OCC, or even another CAD kernel directly, so this interface layer is quite important.

Funny, in java this is one of those few areas where i’d actually spend the time to make an interface and an implementation, but for new these are just rolled together

This interface layer provides three distinct values:

  1. It allows us to avoid changing key api points if we change underlying implementations. It would be a disaster if script and plugin authors had to change models because we changed implmentations
  2. Allow better documentation. One of the reasons FreeCAD is no more popular is because its docs are terrible. This allows us to provie good documentation via docstrings for each wrapper
  3. Work around bugs. there are a quite a feb bugs in free this layer allows fixing them
  4. allows for enhanced functionality. Many objects are missing features we need. For example we need a ‘forConstruciton’ flag on the Wire object. this allows adding those kinds of things
  5. allow changing interfaces when we’d like. there are few cases where the freecad api is not very userfriendly: we like to change those when necesary. As an example, in the freecad api, all factory methods are on the ‘Part’ object, but it is very useful to know what kind of object each one returns, so these are better grouped by the type of object they return. (who would know that Part.makeCircle() returns an Edge, but Part.makePolygon() returns a Wire ?

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:

  1. paste the content into the build() method, properly intented, and
  2. 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.

Warning

  • You have to have an svg capable browser to view these!
  • For brevity, these examples do not include the MetaData and Header sections required for a fully functional parametric part. See the ModelScript QuickStart for a guide that includes those portions

Simple Rectangular Plate

Just about the simplest possible example, a rectangular box

X Y Z
result = Workplane("front").box(2.0,2.0,0.5)

Api References

  • Workplane() !
  • Workplane.box() !

Plate with Hole

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.

X Y Z
result = Workplane("front").box(2.0,2.0,0.5).faces(">Z").hole(0.5)

Api References

  • Workplane.hole() !
  • Workplane.box()
  • Workplane.box()

An extruded prismatic solid

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.

X Y Z
result = Workplane("front").circle(2.0).rect(0.5,0.75).extrude(0.5)

Api References

  • Workplane.circle() !
  • Workplane.rect() !
  • Workplane.extrude() !
  • Workplane()

Building Profiles using lines and arcs

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.

X Y Z
result = Workplane("front").lineTo(2.0,0).lineTo(2.0,1.0).threePointArc((1.0,1.5),(0.0,1.0))\
    .close().extrude(0.25)

Api References

  • Workplane.threePointArc() !
  • Workplane.lineTo() !
  • Workplane.extrude()
  • Workplane()

Moving The Current working point

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.

X Y Z
result = Workplane("front").circle(3.0) #current point is the center of the circle, at (0,0)
result = result.center(1.5,0.0).rect(0.5,0.5) # new work center is  (1.5,0.0)

result = result.center(-1.5,1.5).circle(0.25) # new work center is ( 0.0,1.5).
#the new center is specified relative to the previous center, not global coordinates!

result = result.extrude(0.25)

Api References

  • Workplane.center() !
  • Workplane()
  • Workplane.circle()
  • Workplane.rect()
  • Workplane.extrude()

Using Point Lists

Sometimes you need to create a number of features at various locations, and using Workplane.center() is too cumbersome.

You can use a list of points to construct multiple objects at once. Most construction methods, like Workplane.circle() and Workplane.rect(), will operate on multiple points if they are on the stack

X Y Z
r = Workplane("front").circle(2.0)                       # make base
r = r.pushPoints( [ (1.5,0),(0,1.5),(-1.5,0),(0,-1.5) ] )     # now four points are on the stack
r = r.circle( 0.25 )                                      # circle will operate on all four points
result = r.extrude(0.125 )                               # make prism

Api References

  • Workplane.points() !
  • Workplane()
  • Workplane.circle()
  • Workplane.extrude()

Polygons

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.

X Y Z
result = Workplane("front").box(3.0,4.0,0.25).pushPoints ( [ ( 0,0.75 ),(0,-0.75) ]) \
    .polygon(6,1.0).cutThruAll()

Api References

  • Workplane.polygon() !
  • Workplane.pushPoints()
  • Workplane.box()

Polylines

Workplane.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.

X Y Z
(L,H,W,t) = ( 100.0,20.0,20.0,1.0)
pts = [
    (0,H/2.0),
    (W/2.0,H/2.0),
    (W/2.0,(H/2.0 - t)),
    (t/2.0,(H/2.0-t)),
    (t/2.0,(t - H/2.0)),
    (W/2.0,(t -H/2.0)),
    (W/2.0,H/-2.0),
    (0,H/-2.0)
]
result = Workplane("front").polyline(pts).mirrorY().extrude(L)

Api References

  • Workplane.polyline() !
  • Workplane()
  • Workplane.mirrorY()
  • Workplane.extrude()

Defining an Edge with a Spline

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

X Y Z
s = Workplane("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()
result = r.extrude(0.5)

Api References

  • Workplane.spline() !
  • Workplane()
  • Workplane.close()
  • Workplane.lineTo()
  • Workplane.extrude()

Mirroring Symmetric Geometry

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.

X Y Z
r = Workplane("front").hLine(1.0)                            # 1.0 is the distance, not coordinate
r = r.vLine(0.5).hLine(-0.25).vLine(-0.25).hLineTo(0.0)      # hLineTo allows using xCoordinate not distance
result =r.mirrorY().extrude(0.25 )                           # mirror the geometry and extrude

Api References

  • Workplane.hLine() !
  • Workplane.vLine() !
  • Workplane.hLineTo() !
  • Workplane.mirrorY() !
  • Workplane.mirrorX() !
  • Workplane()
  • Workplane.extrude()

Creating Workplanes on Faces

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 Workplane.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.

X Y Z
result = Workplane("front").box(2,3,0.5)            #make a basic prism
result = result.faces(">Z").workplane().hole(0.5)   #find the top-most face and make a hole

Api References

  • Workplane.workplane()
  • Workplane.box()
  • Workplane()

Locating a Workplane on a vertex

Normally, the Workplane.workplane() method requires a face to be selected. But if a vertex is selected immediately after a face, Workplane.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 Workplane.cutThruAll(), which makes a cut through the entire part, no matter how deep the part is

X Y Z
result = Workplane("front").box(3,2,0.5)                 #make a basic prism
result = result.faces(">Z").vertices("<XY").workplane()  #select the lower left vertex and make a workplane
result = result.circle(1.0).cutThruAll()                 #cut the corner out

Api References

  • Workplane.box()
  • Workplane()
  • StringSyntaxSelector() !

Offset Workplanes

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!

X Y Z
result = Workplane("front").box(3,2,0.5)                 #make a basic prism
result = result.faces("<X").workplane(offset=0.75)       #workplane is offset from the object surface
result = result.circle(1.0).extrude(0.5)                 #disc

Api References

  • Workplane.box()
  • Workplane()

Rotated Workplanes

You can create a rotated work plane by specifying angles of rotation relative to another workplane

X Y Z
result = Workplane("front").box(4.0,4.0,0.25).faces(">Z").workplane()  \
     .transformed(offset=cad.Vector(0,-1.5,1.0),rotate=cad.Vector(60,0,0)) \
     .rect(1.5,1.5,forConstruction=True).vertices().hole(0.25)

Api References

  • Workplane.transformed() !
  • Workplane.box()
  • Workplane.rect()
  • Workplane.faces()

Using construction Geometry

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.

X Y Z
result = Workplane("front").box(2,2,0.5).faces(">Z").workplane() \
    .rect(1.5,1.5,forConstruction=True).vertices().hole(0.125 )

Api References

  • Workplane.box()
  • Workplane.hole()
  • Workplane()

Shelling To Create Thin features

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.

X Y Z
result = Workplane("front").box(2,2,2).faces("+Z").shell(0.05)

Api References

  • Workplane.shell() !
  • Workplane.box()
  • Workplane.faces()
  • Workplane()

Making Lofts

A loft is a solid swept through a set of wires. This example creates lofted section between a rectangle and a circular section.

X Y Z
result = Workplane("front").box(4.0,4.0,0.25).faces(">Z").circle(1.5) \
    .workplane(offset=3.0).rect(0.75,0.5).loft(combine=True)

Api References

  • Workplane.loft() !
  • Workplane.box()
  • Workplane.faces()
  • Workplane.circle()
  • Workplane.rect()

Making Counter-bored and counter-sunk holes

Counterbored and countersunk holes are so common that CadQuery creates macros to create them in a single step.

Similar to Workplane.hole() , these functions operate on a list of points as well as a single point.

X Y Z
result = Workplane(Plane.XY()).box(4,2,0.5).faces(">Z").workplane().rect(3.5,1.5,forConstruction=True)\
.vertices().cboreHole(0.125, 0.25,0.125,depth=None)

Api References

  • Workplane.cboreHole() !
  • Workplane.cskHole() !
  • Workplane.box()
  • Workplane.rect()
  • Workplane.workplane()
  • Workplane.vertices()
  • Workplane.faces()
  • Workplane()

Rounding Corners with Fillet

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.

X Y Z
result = Workplane("XY" ).box(3,3,0.5).edges("|Z").fillet(0.125)

Api References

  • Workplane.fillet() !
  • Workplane.box()
  • Workplane.edges()
  • Workplane()

Splitting an Object

You can split an object using a workplane, and retain either or both halves

X Y Z
c = Workplane("XY").box(1,1,1).faces(">Z").workplane().circle(0.25).cutThruAll()

#now cut it in half sideways
result = c.faces(">Y").workplane(-0.5).split(keepTop=True)

Api References

  • Workplane.split() !
  • Workplane.box()
  • Workplane.circle()
  • Workplane.cutThruAll()
  • Workplane.workplane()
  • Workplane()

The Classic OCC Bottle

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
http://code.google.com/p/pythonocc/source/browse/trunk/src/examples/Tools/InteractiveViewer/scripts/Bottle.py?r=1046

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!

X Y Z
(L,w,t) = (20.0,6.0,3.0)
s = Workplane("XY")

#draw half the profile of the bottle and extrude it
p = s.center(-L/2.0,0).vLine(w/2.0) \
    .threePointArc((L/2.0, w/2.0 + t),(L,w/2.0)).vLine(-w/2.0) \
    .mirrorX().extrude(30.0,True)

#make the neck
p.faces(">Z").workplane().circle(3.0).extrude(2.0,True)

#make a shell
result = p.faces(">Z").shell(0.3)

Api References

  • Workplane.extrude()
  • Workplane.mirrorX()
  • Workplane.threePointArc()
  • Workplane.workplane()
  • Workplane.vertices()
  • Workplane.vLine()
  • Workplane.faces()
  • Workplane()

A Parametric Enclosure

X Y Z
#parameter definitions
p_outerWidth = 100.0 #Outer width of box enclosure
p_outerLength = 150.0 #Outer length of box enclosure
p_outerHeight = 50.0 #Outer height of box enclosure

p_thickness =  3.0 #Thickness of the box walls
p_sideRadius =  10.0 #Radius for the curves around the sides of the bo
p_topAndBottomRadius =  2.0 #Radius for the curves on the top and bottom edges of the box

p_screwpostInset = 12.0 #How far in from the edges the screwposts should be place.
p_screwpostID = 4.0 #nner Diameter of the screwpost holes, should be roughly screw diameter not including threads
p_screwpostOD = 10.0 #Outer Diameter of the screwposts.\nDetermines overall thickness of the posts

p_boreDiameter = 8.0 #Diameter of the counterbore hole, if any
p_boreDepth = 1.0 #Depth of the counterbore hole, if
p_countersinkDiameter = 0.0 #Outer diameter of countersink.  Should roughly match the outer diameter of the screw head
p_countersinkAngle = 90.0 #Countersink angle (complete angle between opposite sides, not from center to one side)
p_flipLid = True #Whether to place the lid with the top facing down or not.
p_lipHeight =  1.0 #Height of lip on the underside of the lid.\nSits inside the box body for a snug fit.

#outer shell
oshell = Workplane("XY").rect(p_outerWidth,p_outerLength).extrude(p_outerHeight + p_lipHeight)

#weird geometry happens if we make the fillets in the wrong order
if p_sideRadius > p_topAndBottomRadius:
    oshell.edges("|Z").fillet(p_sideRadius)
    oshell.edges("#Z").fillet(p_topAndBottomRadius)
else:
    oshell.edges("#Z").fillet(p_topAndBottomRadius)
    oshell.edges("|Z").fillet(p_sideRadius)

#inner shell
ishell = oshell.faces("<Z").workplane(p_thickness,True)\
    .rect((p_outerWidth - 2.0* p_thickness),(p_outerLength - 2.0*p_thickness))\
    .extrude((p_outerHeight - 2.0*p_thickness),False) #set combine false to produce just the new boss
ishell.edges("|Z").fillet(p_sideRadius - p_thickness)

#make the box outer box
box = oshell.cut(ishell)

#make the screwposts
POSTWIDTH = (p_outerWidth - 2.0*p_screwpostInset)
POSTLENGTH = (p_outerLength  -2.0*p_screwpostInset)

postCenters = box.faces(">Z").workplane(-p_thickness)\
    .rect(POSTWIDTH,POSTLENGTH,forConstruction=True)\
    .vertices()

for v in postCenters.all():
   v.circle(p_screwpostOD/2.0).circle(p_screwpostID/2.0)\
        .extrude((-1.0)*(p_outerHeight + p_lipHeight -p_thickness ),True)

#split lid into top and bottom parts
(lid,bottom) = box.faces(">Z").workplane(-p_thickness -p_lipHeight ).split(keepTop=True,keepBottom=True).all()  #splits into two solids

#translate the lid, and subtract the bottom from it to produce the lid inset
lowerLid = lid.translate((0,0,-p_lipHeight))
cutlip = lowerLid.cut(bottom).translate((p_outerWidth + p_thickness ,0,p_thickness - p_outerHeight + p_lipHeight))

#compute centers for counterbore/countersink or counterbore
topOfLidCenters = cutlip.faces(">Z").workplane().rect(POSTWIDTH,POSTLENGTH,forConstruction=True).vertices()

#add holes of the desired type
if p_boreDiameter > 0 and p_boreDepth > 0:
    topOfLid = topOfLidCenters.cboreHole(p_screwpostID,p_boreDiameter,p_boreDepth,(2.0)*p_thickness)
elif p_countersinkDiameter > 0 and p_countersinkAngle > 0:
    topOfLid = topOfLidCenters.cskHole(p_screwpostID,p_countersinkDiameter,p_countersinkAngle,(2.0)*p_thickness)
else:
    topOfLid= topOfLidCenters.hole(p_screwpostID,(2.0)*p_thickness)

#flip lid upside down if desired
if p_flipLid:
    topOfLid.rotateAboutCenter((1,0,0),180)

#return the combined result
result =topOfLid.combineSolids(bottom)

Api References

  • Workplane.circle()
  • Workplane.rect()
  • Workplane.extrude()
  • Workplane.box()
  • CQ.all()
  • CQ.faces()
  • CQ.vertices()
  • CQ.edges()
  • CQ.workplane()
  • Workplane.fillet()
  • Workplane.cut()
  • Workplane.combineSolids()
  • Workplane.rotateAboutCenter()
  • Workplane.cboreHole()
  • Workplane.cskHole()
  • Workplane.hole()