---
title: "CadQuery Direct API"
author: "James Pace"
date: "2024/02/06"
---

[CadQuery][cadquery-homepage] 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][openscad-homepage].
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:
```python
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:

1. Make a workplane.
2. Add a single 2D circle.
3. Add four points to the stack of the tree.
4. Operate on those four points by drawing smaller circles at each point.
5. 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 it 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.
Its very hard to introspect what's happening at each step.
Particularly when so much is wirtten 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.

What I've found more challenging is it is 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 Fluid 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):
```{mermaid}
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][github-link].

An example that I wrote which forms a cube by extruding a square from the "YZ" plane
is below.
``` python
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))
```


[cadquery-homepage]: https://cadquery.readthedocs.io/en/latest/index.html
[openscad-homepage]: https://openscad.org/
[github-link]: https://github.com/CadQuery/cadquery/issues/497

