CadQuery Direct API

Author

James Pace

Published

February 6, 2024

CadQuery is a “CAD via Python” library. Instead of using a WYSIWYG editor to generate CAD models, when using CadQuery you write Python code that does the same operations.

The most popular code based CAD tool is OpenSCAD. Using CadQuery feels much closer to using a “normal” CAD package, in my opinion, than using OpenSCAD. With CadQuery and normal CAD packages you think in terms of operations on sketches or faces that compose into the final part. OpenSCAD doesn’t feel like that, at least in the little bit I’ve tried.

CadQuery has three API layers (in order from highest to lowest level: fluent, direct, and OCCT). Fluent is the suggested level with the most documentation. It feels the closest to normal CAD. The mental model is you start with a workplane which is a root of a tree and then perform operations which add elements to the tree with the modifications needed to build the desired part. For example:

import cadquery as cq

result = (
     cq.Workplane("front")
     .circle(2.0)
     .pushPoints([(1.5, 0), (0, 1.5), (-1.5, 0), (0, -1.5)])
     .circle(0.25)
     .extrude(0.125)
    )

will:

Make a workplane.
Add a single 2D circle.
Add four points to the stack of the tree.
Operate on those four points by drawing smaller circles at each point.
Extrude the result.

This may seem confusing, but if you’ve worked with Fusion360 or Creo, you’ve basically done the same thing (see the timeline in the bottom of the window in Fusion360 or the history in Creo). I’ve found that once the idea clicks what’s going on isn’t that hard to work out.

What is a pain to work out is when something goes wrong. It is very hard to introspect what’s happening at each step. Particularly when so much is written on basically one line, which isn’t a requirment per se, but definitely the suggested workflow. Regardless, the actions in each of the lines is extremely dependent on state hidden in the workplane that is basically impossible to tease out.

It is also really hard to organize things in a way that allows for code reuse. Specifically, I’ve worked on two projects where I’ve wanted to reuse sketches in multiple places, and in neither case could I really find a nice way to do that while using the Fluent API.

I’ve found the Direct API to make this much easier. The Direct API is much closer to “normal” OOP programming, where objects are made by calling constructors, and therefore is more amenable to be organized using normal software engineering practices. Unfortunately, the documentation and examples for the Direct API are lacking.

One of the things I found confusing was the class hiearchy.

My understanding from looking at examples is roughly:

“Edges” are generated by connecting points, and are combined into “Wires”.
“Wires” are combined into “Faces”,
“Faces” can be extruded directly into “Solids” OR
“Faces” can be combined into “Shells” which can then be turned in “Solids”.

Or graphically (and a little more completely):

flowchart LR
    points ---> Edge
    Edge ---> Wire
    Wire ---> Face
    Face ---> Solid
    Face ---> Shell
    Shell ---> Solid
    Wire ---> Solid

The best example I found for using the Direct API was in a Gitlab issue linked here.

An example that I wrote which forms a cube by extruding a square from the “YZ” plane is below.

import cadquery as cq

edge1 = cq.Edge.makeLine((0.0, 0.0, 0.0), (0.0, 0.0, 1.0))
edge2 = cq.Edge.makeLine((0.0, 0.0, 1.0), (0.0, 1.0, 1.0))
edge3 = cq.Edge.makeLine((0.0, 1.0, 1.0), (0.0, 1.0, 0.0))
edge4 = cq.Edge.makeLine((0.0, 1.0, 0.0), (0.0, 0.0, 0.0))
edges = [edge1, edge2, edge3, edge4]
wires = cq.Wire.assembleEdges(edges)
face = cq.Face.makeFromWires(wires)
result = cq.Solid.extrudeLinear(face, (1.0, 0.0, 0.0))