diff --git a/_drafts/cadquery-direct-api.md b/_drafts/cadquery-direct-api.md deleted file mode 100644 index af5ed10..0000000 --- a/_drafts/cadquery-direct-api.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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/ - diff --git a/posts/cadquery-direct-api.qmd b/posts/cadquery-direct-api.qmd new file mode 100644 index 0000000..86c5836 --- /dev/null +++ b/posts/cadquery-direct-api.qmd @@ -0,0 +1,108 @@ +--- +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 +