CadQuery Library for Parametric CAD

• CadQuery is an open-source Python library for parametric CAD modeling that utilizes a fluent, method-chaining API to construct 3D geometries.
• It structures design around a workplane concept, enabling the sequential addition of 2D sketch primitives and 3D operations to form complex models.
• The library integrates seamlessly into Jupyter notebooks and CI pipelines, facilitating automated workflows and efficient model export to formats like STL and STEP.

CadQuery is an open-source, pure-Python library for parametric 3D computer-aided design (CAD) modeling, providing a fluent and concise scripting interface that closely mirrors traditional CAD operations while emphasizing compositional and programmatic model definition. By operating entirely within standard Python environments without requiring an external GUI or C++ dependencies, CadQuery facilitates integration into Jupyter notebooks, continuous integration (CI) pipelines, automated scripting contexts, and other scientific computing workflows. At its core, CadQuery structures geometric construction around the concept of a "workplane" (e.g., the XY plane), supporting chaining of 2D sketch primitives such as circles, lines, and arcs, followed by 3D operations including extrusion, revolution, filleting, unions, and cuts. The resulting models can be programmatically exported to widely accepted formats like STL and STEP for downstream engineering or manufacturing use (Xie et al., 10 May 2025).

1. Library Structure and API

CadQuery exposes a concise, method-chaining API that enables users to efficiently describe parametric models. Modeling sequences typically begin with instantiation of a "Workplane" object, which specifies the reference plane for subsequent sketches and geometry operations. Sequential calls add primitives or modify geometry. For example, creating a rectangular prism (box) of dimensions 10×20×5 is achieved by:

import cadquery as cq box = cq.Workplane("XY").box(10, 20, 5)

Complex shapes are constructed via combinations of sketching (e.g., .circle, .moveTo, .lineTo, .threePointArc, .close) and solid modeling operators (e.g., .extrude, .revolve, .fillet). For example, a cylinder extruded from a circle with a scaled radius demonstrates parametric construction:

cylinder = cq.Workplane("XY").circle(0.375 * 0.75).extrude(0.1046)

Export routines, accessible through cadquery.exporters, facilitate conversion to STL or STEP formats, supporting interoperability with external simulation, fabrication, or rendering tools.

2. Integration with LLM-Driven CAD Generation

CadQuery is employed as the target representation in the "Text-to-CadQuery" paradigm, in which LLMs are fine-tuned to directly generate CadQuery scripts from natural language descriptions, bypassing the need for intermediate command sequences or hand-engineered representations (Xie et al., 10 May 2025). The key rationale is that pretrained LLMs, especially those optimized for Python code, can capitalize on both code synthesis priors and inherent spatial reasoning abilities to robustly output executable models without costly bespoke training pipelines.

The data pipeline for this approach is structured as follows:

• Starting from extensive base datasets (DeepCAD and Text2CAD, together containing ~170,000 CAD models and 600,000+ prompts), each CAD instance is minimally described in JSON (faces, curves, parameters).
• Google Gemini 2.0 Flash is tasked with translating JSON representations to CadQuery code, operating in a self-refinement loop. Code execution is attempted, and errors are routed back for automatic correction. Passed scripts are validated by rendering output in Blender and using vision-language judgment for geometric fidelity. Final human checks ensure overall validity.
• This process yields approximately 170,000 validated text-to-CadQuery pairs in ∼9 hours with a first-pass execution success of about 85%.

3. Model Fine-Tuning and Evaluation Protocols

Six open-source decoder-only LLMs of varying scale (0.12B–7B parameters) and coding priors—including CodeGPT-small, GPT-2 medium/large, Gemma3-1B, Qwen2.5-3B, and Mistral-7B—were fine-tuned using a combined instruction–response format with up to 1024 tokens. For models up to 3B parameters, full-parameter supervised fine-tuning (SFT) was employed; for larger models (Mistral-7B), parameter-efficient fine-tuning (PEFT) via LoRA (rank 16, α=32, 4-bit quantization) was applied.

Supervision employed cross-entropy loss at the token level, with no geometry-aware loss during training.

Evaluation comprised:

• Top-1 Exact Match Rate: $$\text{ExactMatch} = \frac{1}{N} \sum_{i=1}^N \mathbf{1}(\hat c_i = c_i)$$
• Chamfer Distance (CD): Quantifying geometric mesh error relative to ground truth:

$$\mathrm{CD}(P,Q) = \frac{1}{|P|}\sum_{p\in P}\min_{q \in Q}\|p-q\|_2^2 + \frac{1}{|Q|}\sum_{q\in Q}\min_{p \in P}\|q-p\|_2^2$$

• Invalid Rate (IR): Fraction of scripts failing execution.
• Vision-language consistency: Rendered-image comparison via Gemini 2.0.
• Supplementary: point-based F1 score ($\tau = 0.02$), volumetric IoU.

4. Empirical Results and Failure Modes

Scaling analysis finds that all fine-tuned models with CadQuery targets outperform prior task-specific command-sequence baselines. Key observed results:

Model	Gemini 2.0 Acc. (%)	Median CD ($\times10^3$)	IR (%)
CodeGPT-small	60.3	0.234	9.4
GPT-2 medium	60.3	0.223	15.6
GPT-2 large	63.6	0.221	13.8
Gemma3-1B	66.9	0.204	8.4
Qwen2.5-3B	69.3	0.191	6.5
Mistral-7B (LoRA)	65.4	0.219	1.32

Statistical trends indicate increasing model scale correlates with monotonic improvements in F1/IoU up to 3B parameters, while the 7B model exhibits lower invalid rates but underfits due to dataset size constraints.

Frequent qualitative failure modes include numerically unstable .threePointArc constructs (with nearly colinear arguments triggering OpenCascade kernel errors), floating-point instabilities at small feature scales ($10^{-2}$–$10^{-3}$), and hallucinated or undefined methods in outputs from lower-capacity models. These are partially mitigated by augmenting training data with degenerate examples, scaling sketches, and substituting problematic methods with alternatives like .radiusArc or splines.

5. Workflow Embedding and Applications

CadQuery’s executable Python format admits direct integration into parametric design, CI/CD pipelines, and interactive computational environments. Automated workflows can proceed directly from natural language text prompts to editable CAD scripts, which yield 3D geometry outputs via standard Python execution:

• Textual prompt $\rightarrow$ LLM $\rightarrow$ CadQuery script $\rightarrow$ STL/STEP output.

This seamless substitution enables automated part library generation from catalogs, educational tooling for explaining API/model relationships to CAD students, and closed-loop optimization where geometry is iteratively generated and validated (e.g., for topology or shape optimization pipelines).

A plausible implication is that, by abstracting CAD synthesis to LLMs operating on CadQuery, non-expert users can describe complex parametric geometries without direct scripting, broadening accessibility and enabling new forms of generative design exploration.

6. Future Directions

Ongoing research trends and planned extensions include:

• Incorporation of multimodal inputs (sketches, images, point clouds) with translation to CadQuery, further generalizing the data pipeline.
• Scaling beyond the current 170,000 pairs and fine-tuning larger LLMs ($>13$B parameters) to enhance geometric accuracy and code robustness.
• Introduction of geometry-aware loss metrics, such as Chamfer Distance or mesh similarity, potentially via differentiation-through-rendering, to directly optimize model outputs for fidelity rather than strictly token-level accuracy.
• Augmentation of training data to address robustness against degenerate geometry and numerical edge cases, aiming for improved generalization in both common and pathological modeling scenarios.

These directions are poised to consolidate the role of CadQuery as a pivotal bridge between parametric CAD workflows and modern code- and language-model-driven automation strategies (Xie et al., 10 May 2025).