---
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].
Uins CadQuery feels much closer to using a "normal" CAD package, in my opinion,
than using OpenSCAD, in the sense that with CadQuery and normal CAD packages you
think in terms of operations on sketches or faces that compose into the final part.
At least the little bit of OpenSCAD didn't feel like that, though my experience with
OpenSCAD is extremely limited.

CadQuery has three API layers (in order from highest to lowest level: fluent, direct, 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),
and I've found that it clicks, what's going on isn't that hard to work out.

What is a pain to work out is ehen something goes wrong, its very hard to introspect what's happening
at each step.
You don't have to write everything in basically one line like I did above, but based on the examples,
that's basically the suggested the way.
Even if you didn't write everything on one line, 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/shape
reuse.
Specifically, I've worked on two projects where I've wanted to reuse idenctically dimensioned 2d shape in
multiple parts.
The direct mode API make this much easier.


[cadquery-homepage]: https://cadquery.readthedocs.io/en/latest/index.html
[openscad-homepage]: https://openscad.org/