After a few failed attempts, I got CadQuery’s default UI CQ-editor up and running which means it’s time to dive in! Here are some notes after reading CadQuery Concepts overview page.

Workplane vs. workplane

My biggest confusion came from two identically named things that I could only occasionally differentiate from context and capitalization. There is the Workplane class, whose name is always capitalized, and it is the Python object type serving as the main entry point for majority of CadQuery’s top level API. Then there is the general CAD workplane concept, usually defined by two parallel global axes (“XY”). If someone understands that there are two different things going on and understand their context, the next paragraph will make perfect sense. If they don’t, they’ll be hopelessly lost:

A sequence of CadQuery operations is represented by a chain/tree of Workplane objects, each with a reference to its parent except for the root Workplane. Each Workplane has a reference to a workplane and a workplane may be referenced by multiple Workplane objects.

Selectors

I like the theory of CadQuery selectors. It should be a more robust way to specify objects for various operations. Rather than specifying a target via, say, “Face #12” I can specify “Face with the greatest Z coordinate”. “Face #12” is closest to mechanisms within underlying Open Cascade Technology platform, but it is also the root of all FreeCAD “Topological Naming Problem” evil. From my brief look at Cascade Studio I didn’t see it offer a solution to the problem, but a brief look at Replicad found “Finders” which have some superficial similarity to CadQuery selectors. I’m looking forward to learning how well CadQuery selectors work in practice.

API Layers

CadQuery’s top level API, the one with all its user-friendly features like Selectors, is called the “Fluent API” in CadQuery documentation. It’s what I plan to learn, but I’m happy to see I won’t be restricted to the Fluent API. Architecturally underneath is the “Direct API”, which organizes underlying Open Cascade capabilities into Python classes. And underneath that is the “OCCT API” which are minimalist Python translations of the basic C++ API.

There are methods to translate data structures from one layer to another, and it is valid for CadQuery code to move between those layers. Such capabilities greatly reduce any concern of being limited by any one API.

---

With a quick general concepts overview in mind, I moved onward to learning about 2D sketching in CadQuery.