第01章：CadQuery概述与入门

1.1 CadQuery简介

1.1.1 什么是CadQuery

CadQuery是一个直观、易用的Python模块，专门用于构建参数化3D CAD模型。使用CadQuery，开发者可以编写简短、简洁的脚本来生成高质量的CAD模型。它的核心理念是”代码即模型”，通过Python代码来描述3D几何形状，使得模型可以轻松地进行参数化定制。

与传统的GUI CAD软件不同，CadQuery采用脚本化的方式进行建模。这种方式有几个显著优势：

1. 参数化设计：通过修改脚本中的参数，可以快速生成不同尺寸和形状的模型
2. 版本控制：代码形式的模型可以使用Git等版本控制系统进行管理
3. 批量生成：可以通过循环和函数批量生成大量相似的模型
4. 可复用性：模型代码可以作为库被其他项目引用

1.1.2 CadQuery的发展历史

CadQuery最初是基于FreeCAD API开发的。FreeCAD提供了Python接口，使得CadQuery能够快速开发并获得跨平台能力。然而，随着项目的发展，开发团队发现FreeCAD API在某些高级操作和选择器方面存在限制。

为了突破这些限制，CadQuery 2.0版本进行了重大重构，直接基于OpenCASCADE Technology（OCCT）的Python包装器OCP进行开发。最新的CadQuery 2.8.0版本（2026年6月发布）延续了这一架构，稳定了自由函数（free function）API，并将底层绑定过渡到 OCP 7.9。这个架构决定带来了以下好处：

• 更强的控制力：直接访问OCCT内核，可以实现更复杂的几何操作
• 更好的灵活性：不再受限于中间层API的功能范围
• 更高的性能：减少了中间层的开销

当然，这也意味着开发团队需要自行处理跨平台部署等问题，但团队认为这是一个值得的权衡。

1.1.3 CadQuery与OpenSCAD的对比

CadQuery经常被拿来与OpenSCAD进行比较，因为两者都是开源的、基于脚本的参数化模型生成器。然而，CadQuery在多个方面具有显著优势：

具体优势详解：

1. 标准编程语言
   • CadQuery使用Python，这意味着可以利用Python丰富的标准库和第三方库
   • 可以使用成熟的IDE（如PyCharm、VSCode）进行开发
   • 便于与其他Python项目集成
2. 强大的CAD内核
   • OCCT原生支持NURBS、样条曲线、曲面缝合、STL修复等复杂操作
   • 支持标准CSG操作之外的高级建模功能
3. STEP格式支持
   • 可以导入/导出无损的STEP格式
   • 可以从其他CAD软件创建的STEP模型开始，添加参数化特征
4. 更简洁的代码
   • 可以基于其他特征、工作平面、顶点的位置来定位新特征
   • 链式调用使得代码更加流畅和易读

1.1.4 CadQuery的核心特性

CadQuery的核心特性包括：

1. 自然语言式建模

# 代码描述与人类语言描述相近
# "在XY平面上创建一个80x60x10的盒子，然后在顶面中心钻一个直径22的孔"
result = (
    cq.Workplane("XY")
    .box(80, 60, 10)
    .faces(">Z")
    .workplane()
    .hole(22)
)

2. 参数化建模

# 参数可以轻松修改
length = 80.0
width = 60.0
height = 10.0
hole_diameter = 22.0

result = (
    cq.Workplane("XY")
    .box(length, width, height)
    .faces(">Z")
    .workplane()
    .hole(hole_diameter)
)

3. 多格式输出

• STEP：无损CAD格式，工业标准
• STL：3D打印常用格式
• AMF：添加制造格式
• 3MF：3D制造格式
• DXF：2D绘图格式
• VRML：虚拟现实建模语言

4. 高级建模功能

• 倒角和圆角
• 曲线拉伸
• 参数曲线
• 放样
• 扫略

5. 装配体支持

• 可以将多个零件组合成装配体
• 支持约束定义
• 支持层次化组装

1.2 CadQuery的技术架构

1.2.1 整体架构概览

CadQuery的技术架构可以分为以下几个层次：

┌─────────────────────────────────────────────┐
│           用户脚本 / 应用程序               │
├─────────────────────────────────────────────┤
│              CadQuery API                   │
│  (Workplane, Selectors, Assembly, etc.)     │
├─────────────────────────────────────────────┤
│           OCP (Open CASCADE Python)          │
│         Python bindings for OCCT            │
├─────────────────────────────────────────────┤
│     Open CASCADE Technology (OCCT)          │
│          C++ CAD 内核                        │
└─────────────────────────────────────────────┘

各层职责：

1. 用户脚本/应用程序层
   • 用户编写的CadQuery脚本
   • 集成CadQuery的应用程序
2. CadQuery API层
   • Workplane：工作平面，核心建模接口
   • Selectors：选择器，用于选择几何元素
   • Assembly：装配体管理
   • Sketch：2D草图功能
   • 导入导出功能
3. OCP层
   • OCCT的Python绑定
   • 提供对OCCT功能的Python访问
4. OCCT层
   • 底层CAD内核
   • 提供几何建模、布尔运算等核心功能

1.2.2 核心概念

Workplane（工作平面）

Workplane是CadQuery最核心的概念。它代表一个2D工作平面，可以在上面进行草图绘制和3D操作。

# 创建一个在XY平面上的工作平面
wp = cq.Workplane("XY")

# 工作平面可以偏移
wp_offset = cq.Workplane("XY").workplane(offset=10)

# 工作平面可以在任意面上创建
box = cq.Workplane("XY").box(10, 10, 10)
top_face_wp = box.faces(">Z").workplane()

Selector（选择器）

选择器用于从模型中选择特定的几何元素（面、边、顶点等）。

# 选择Z方向最高的面
.faces(">Z")

# 选择所有圆形边
.edges("%Circle")

# 选择最近的顶点
.vertices("<X")

Shape（形状）

Shape是OCCT中的基本几何对象，包括：

• Vertex（顶点）
• Edge（边）
• Wire（线框）
• Face（面）
• Shell（壳）
• Solid（实体）
• Compound（复合体）

1.2.3 数据流

CadQuery的典型数据流如下：

草图定义 → 2D几何 → 3D操作 → 实体模型 → 导出
   │          │          │          │
   │          │          │          └─ STEP/STL/等
   │          │          └─ 拉伸/旋转/扫略/放样
   │          └─ 点、线、圆、矩形等
   └─ Workplane创建

1.2.4 自由函数（Free Function）API

从 v2.5 开始，CadQuery 引入了自由函数（Free Function）API，并在 v2.8 中正式稳定，不再是实验性功能。这种新风格的 API 提供了一种更加函数式、声明式的建模方式，与现代 Python 社区的习惯更加一致。

两种风格的对比

传统的 Workplane 链式调用风格：

import cadquery as cq

result = (
    cq.Workplane("XY")
    .box(80, 60, 10)
    .faces(">Z")
    .workplane()
    .hole(22)
)

自由函数风格（v2.8 推荐写法）：

import cadquery as cq

box = cq.box(80, 60, 10)
plane = cq.Workplane(box.faces(">Z").val())
result = cq.cut(box, cq.cylinder(11, 10))

更简洁的混合写法：

import cadquery as cq

result = (
    cq.box(80, 60, 10)
    .faces(">Z")
    .workplane()
    .hole(22)
)

常用自由函数

风格选择建议

CadQuery 2.8 推荐将自由函数作为首选建模风格。自由函数风格的优点包括：

• 更直观的 Python 函数调用方式
• 便于 IDE 自动补全和类型检查
• 更容易编写单元测试
• 与函数式编程范式兼容

传统的 Workplane 链式调用仍然完全支持，现有代码无需修改即可运行。两种风格可以自由混用。

1.3 环境搭建与安装

1.3.1 系统要求

在安装CadQuery之前，请确保系统满足以下要求：

操作系统：

• Windows 10/11（64位）
• macOS（Intel和Apple Silicon）
• Linux（主要发行版）

Python版本：

• Python 3.10 - 3.12（推荐3.11或3.12）

硬件要求：

• 至少4GB RAM（推荐8GB以上）
• 1GB以上磁盘空间

1.3.2 使用Conda安装（推荐）

Conda是推荐的安装方式，因为它可以更好地处理CadQuery复杂的依赖关系。

步骤1：安装Miniforge

如果还没有安装Conda，推荐安装Miniforge，这是一个轻量级的Conda发行版：

从 https://github.com/conda-forge/miniforge 下载适合您系统的安装包并安装。

步骤2：创建新环境

# 创建一个名为cadquery的新环境
conda create -n cadquery python=3.11

# 激活环境
conda activate cadquery

步骤3：安装CadQuery

推荐使用mamba代替conda进行安装，因为mamba更快且内存占用更少：

# 如果还没有mamba，先安装它
conda install mamba -n base -c conda-forge

# 安装CadQuery
mamba install -c conda-forge cadquery

如果要安装开发版本（包含最新功能但可能不稳定）：

mamba install -c conda-forge -c cadquery cadquery=master

1.3.3 使用pip安装

pip安装方式更简单，但在某些系统上可能会遇到问题。

步骤1：创建虚拟环境（强烈推荐）

# 创建虚拟环境
python -m venv cadquery-env

# 激活虚拟环境
# Windows:
cadquery-env\Scripts\activate
# Linux/macOS:
source cadquery-env/bin/activate

步骤2：升级pip

python -m pip install --upgrade pip

步骤3：安装CadQuery

pip install cadquery  # 当前最新版本为2.8.0

安装最新开发版本：

pip install git+https://github.com/CadQuery/cadquery.git

1.3.4 使用Docker快速启动

如果不想在本地配置 Python 环境，可以使用 Docker 快速运行 CadQuery。CadQuery 官方在 Docker Hub 上提供了预构建的镜像，开箱即用。

拉取并运行容器：

# 拉取官方镜像并启动交互式终端，挂载当前目录为工作区
docker run -it --rm -v "${PWD}:/workspace" -w /workspace cadquery/cadquery

参数说明：

• -it：交互式终端模式
• --rm：容器退出后自动删除
• -v "${PWD}:/workspace"：将当前目录挂载到容器的 /workspace，方便读写本地文件
• -w /workspace：设置容器内的工作目录

在容器中直接运行脚本：

# 无需进入交互终端，直接执行 CadQuery 脚本
docker run --rm -v "${PWD}:/workspace" -w /workspace cadquery/cadquery python my_script.py

运行 CQ-editor（需要 X11 转发）：

在 Linux 上配合 X11 转发可以启动 CQ-editor 图形界面：

docker run --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v "${PWD}:/workspace" cadquery/cadquery cq-editor

Docker 方式适合需要快速体验 CadQuery、不想处理本地依赖冲突，或在 CI/CD 环境中批量生成模型的用户。

1.3.5 安装CQ-editor（可视化IDE）

CQ-editor是CadQuery的官方图形化IDE，提供实时预览、调试等功能。

使用Conda安装（推荐）：

mamba install -c conda-forge -c cadquery cq-editor

运行CQ-editor：

cq-editor

CQ-editor的主要功能：

• 代码编辑器：语法高亮、自动补全
• 3D预览：实时查看模型
• 调试器：逐步执行脚本
• 栈检查器：查看CadQuery对象栈
• 导出功能：直接导出STEP、STL等格式

1.3.6 在Jupyter中使用CadQuery

CadQuery可以在Jupyter Notebook/Lab中直接使用：

安装jupyter-cadquery：

pip install jupyter-cadquery

在Jupyter中显示模型：

import cadquery as cq
from jupyter_cadquery import show

# 创建一个简单的盒子
box = cq.Workplane("XY").box(10, 10, 10)

# 显示模型
show(box)

1.3.7 验证安装

安装完成后，可以通过以下代码验证安装是否成功：

import cadquery as cq

# 创建一个简单的模型
result = cq.Workplane("XY").box(10, 20, 30)

# 检查结果
print(f"CadQuery版本: {cq.__version__}")
print(f"模型体积: {result.val().Volume()}")
print("安装成功！")

1.4 第一个CadQuery程序

1.4.1 Hello World - 创建一个盒子

让我们从最简单的例子开始：

import cadquery as cq

# 创建一个10x20x5的盒子
result = cq.Workplane("XY").box(10, 20, 5)

# 导出为STEP文件
cq.exporters.export(result, "hello_box.step")

print("盒子创建成功！")

代码解析：

1. import cadquery as cq - 导入CadQuery库，使用cq作为别名
2. cq.Workplane("XY") - 创建一个在XY平面上的工作平面
3. .box(10, 20, 5) - 在工作平面上创建一个长10、宽20、高5的盒子
4. cq.exporters.export() - 将结果导出为文件

1.4.2 带孔的盒子

让我们创建一个更有趣的模型——带孔的盒子：

import cadquery as cq

# 定义参数
length = 80.0
width = 60.0
thickness = 10.0
hole_diameter = 22.0

# 创建带孔的盒子
result = (
    cq.Workplane("XY")
    .box(length, width, thickness)  # 创建基础盒子
    .faces(">Z")                     # 选择顶面
    .workplane()                     # 在顶面创建新工作平面
    .hole(hole_diameter)             # 钻孔
)

# 导出模型
cq.exporters.export(result, "box_with_hole.step")

代码解析：

1. 定义参数使模型可以轻松调整
2. .faces(">Z") - 选择Z轴正方向最远的面（即顶面）
3. .workplane() - 在选中的面上创建新的工作平面
4. .hole(hole_diameter) - 创建一个贯穿孔

1.4.3 带圆角的零件

添加圆角让零件更加美观和实用：

import cadquery as cq

# 创建带圆角的盒子
result = (
    cq.Workplane("XY")
    .box(30, 20, 10)
    .edges("|Z")      # 选择所有平行于Z轴的边
    .fillet(2)        # 对选中的边进行圆角处理
)

# 导出模型
cq.exporters.export(result, "filleted_box.step")

边选择器说明：

• |Z - 选择平行于Z轴的边
• |X - 选择平行于X轴的边
• |Y - 选择平行于Y轴的边

1.4.4 组合多个特征

一个完整的零件示例：

import cadquery as cq

# 参数定义
base_width = 100
base_depth = 80
base_height = 10
boss_diameter = 30
boss_height = 20
hole_diameter = 8

# 创建零件
result = (
    cq.Workplane("XY")
    # 创建基础板
    .box(base_width, base_depth, base_height)
    # 选择顶面，创建凸台
    .faces(">Z")
    .workplane()
    .circle(boss_diameter / 2)
    .extrude(boss_height)
    # 在凸台顶部钻孔
    .faces(">Z")
    .workplane()
    .hole(hole_diameter)
    # 对基础板的竖直边倒圆角
    .faces("<Z")
    .workplane()
    .edges()
    .fillet(3)
)

# 导出模型
cq.exporters.export(result, "complete_part.step")

1.5 CadQuery基本工作流程

1.5.1 典型建模流程

CadQuery的典型建模流程遵循以下步骤：

1. 创建工作平面（Workplane）
        ↓
2. 绘制2D草图
        ↓
3. 转换为3D（拉伸/旋转等）
        ↓
4. 选择特征（面/边/顶点）
        ↓
5. 添加/修改特征
        ↓
6. 重复4-5直到完成
        ↓
7. 导出模型

1.5.2 链式调用

CadQuery使用链式调用（Method Chaining）风格，每个方法返回一个CadQuery对象，可以继续调用下一个方法：

result = (
    cq.Workplane("XY")
    .box(10, 10, 5)
    .faces(">Z")
    .workplane()
    .hole(3)
    .faces("<Z")
    .workplane(invert=True)
    .rect(5, 5)
    .cutBlind(-2)
)

这种风格使代码更加紧凑和易读，每一行代表一个操作步骤。

1.5.3 对象栈概念

CadQuery维护一个对象栈（Object Stack），用于存储当前操作的几何元素：

# 初始栈为空
wp = cq.Workplane("XY")  # 栈：[工作平面原点]

# 绘制圆后，栈中是圆
wp = wp.circle(5)  # 栈：[Circle]

# 拉伸后，栈中是实体
wp = wp.extrude(10)  # 栈：[Solid]

# 选择面后，栈中是面
wp = wp.faces(">Z")  # 栈：[Face]

理解对象栈对于编写正确的CadQuery代码非常重要。

1.5.4 坐标系统

CadQuery使用右手坐标系：

        Z (上)
        │
        │
        │
        └───────── Y (右)
       /
      /
     X (前)

工作平面选项：

• "XY" - 水平面，Z轴向上
• "XZ" - 正面，Y轴向外
• "YZ" - 侧面，X轴向外
• "front" - 等同于XZ
• "back" - XZ的反面
• "top" - 等同于XY
• "bottom" - XY的反面
• "left" - YZ的反面
• "right" - 等同于YZ

1.5.5 材料系统

CadQuery v2.7 引入了基础材料功能，允许为模型附加材料信息，包括密度、颜色和名称等属性，便于工程计算和数据交换。

创建材料：

import cadquery as cq

# 定义铝合金材料
aluminum = cq.Material(
    name="Aluminum 6061",
    density=2.7,              # 密度，单位 g/cm³
    color=(0.8, 0.8, 0.85)    # RGB 颜色
)

# 定义钢材
steel = cq.Material(
    name="Steel 1045",
    density=7.85,
    color=(0.6, 0.6, 0.65)
)

将材料应用到模型：

import cadquery as cq

bracket = (
    cq.Workplane("XY")
    .box(50, 30, 5)
    .faces(">Z")
    .workplane()
    .hole(8)
)

aluminum = cq.Material(name="Aluminum 6061", density=2.7)
bracket.material = aluminum

# 利用材料属性计算质量
volume = bracket.val().Volume()  # mm³
mass = volume * 0.001 * aluminum.density  # g
print(f"材料: {bracket.material.name}")
print(f"体积: {volume:.1f} mm³, 质量: {mass:.1f} g")

材料与 STEP 联动

材料信息可以在导入导出 STEP 文件时保留和传递：

import cadquery as cq

# 导出时，材料信息会写入 STEP 文件
steel = cq.Material(name="Steel 1045", density=7.85)
part = cq.box(100, 50, 10)
part.material = steel
cq.export_step(part, "steel_part.step")

# 导入时可读取 STEP 中的材料信息
imported = cq.import_step("steel_part.step")
print(imported.material.name)  # 输出: Steel 1045

材料系统使 CadQuery 模型更接近实际工程需求，特别适合需要重量计算和材料追踪的机械设计场景。

1.5.6 非阻塞可视化（cadquery.fig）

v2.6 引入的 cadquery.fig.Figure API 提供了非阻塞的 3D 可视化能力。与传统的 show_object() 不同，Figure API 使用 trame/VTK 后台渲染，显示模型时不会阻塞脚本执行，在 Jupyter 与 CQ-editor 中均可使用。

对比：传统 show_object() vs Figure API

传统方式（阻塞，仅限 CQ-editor 环境）：

import cadquery as cq

# show_object() 仅适用于 CQ-editor，会阻塞脚本
show_object(cq.Workplane("XY").box(10, 10, 10))

新的 Figure API（非阻塞，跨环境通用）：

import cadquery as cq
from cadquery.fig import Figure

fig = Figure()

box = cq.Workplane("XY").box(10, 10, 10)
cylinder = cq.Workplane("XY").cylinder(5, 20)

# 添加多个模型到同一视图，可分别设置颜色和名称
fig.add(box, color=(0.5, 0.7, 1.0), name="盒子")
fig.add(cylinder, color=(1.0, 0.5, 0.5), name="圆柱")

# 显示模型——脚本随即继续执行，不会阻塞
fig.show()
print("模型已显示，脚本继续运行中...")

基本操作：

from cadquery.fig import Figure

fig = Figure()
fig.add(cq.box(10, 10, 10), name="demo")

fig.show()   # 显示视图（非阻塞）
fig.clear()  # 清空当前场景中的模型
fig.close()  # 关闭视图窗口

Figure API 的优势：

• 非阻塞：fig.show() 后脚本立即继续执行，适合批量渲染和自动化流程
• 跨环境：Jupyter Notebook、JupyterLab、CQ-editor 均可使用
• 多模型叠加：在同一视图中显示多个模型，分别设置颜色与标签
• trame/VTK 渲染：现代化渲染管线，支持后台异步渲染

1.6 常用工具与资源

1.6.1 官方资源

官方文档：

• 完整文档：https://cadquery.readthedocs.io/
• 快速参考手册：https://cadquery.readthedocs.io/en/latest/_static/cadquery_cheatsheet.html

GitHub资源：

• 主仓库：https://github.com/CadQuery/cadquery
• CQ-editor：https://github.com/CadQuery/CQ-editor
• OCP绑定：https://github.com/CadQuery/OCP

社区支持：

• GitHub Discussions：https://github.com/CadQuery/cadquery/discussions
• Google Group：https://groups.google.com/g/cadquery
• Discord服务器：https://discord.com/invite/Bj9AQPsCfx

1.6.2 学习资源

示例代码：

• 官方示例：https://cadquery.readthedocs.io/en/latest/examples.html
• 社区Cookbook：https://github.com/khaledelhady44/CadQuery-Cookbook

视频教程：

• Linux安装教程：https://youtu.be/sjLTePOq8bQ
• Windows安装教程：https://youtu.be/3Tg_RJhqZRg

1.6.3 实用项目参考

FxBricks乐高火车系统： FxBricks使用CadQuery构建产品开发流水线，他们开源了CAD流程文档和cq-kit工具库：

• 流程文档：https://github.com/fx-bricks/fx-cad-notes
• cq-kit：https://github.com/michaelgale/cq-kit

社区插件：

• cadquery-plugins：https://github.com/CadQuery/cadquery-plugins

1.7 本章小结

本章我们全面介绍了CadQuery的基础知识：

1. CadQuery简介
   • CadQuery是Python编写的参数化3D CAD库
   • 基于OCCT内核，功能强大
   • 与OpenSCAD相比具有多项优势
2. 技术架构
   • 分层架构：用户脚本 → CadQuery API → OCP → OCCT
   • 核心概念：Workplane、Selector、Shape
   • 自由函数API：v2.8 推荐的新建模风格
3. 环境搭建
   • 推荐使用Conda安装
   • Docker 快速启动，无需本地配置
   • 可选安装CQ-editor可视化IDE
   • 支持Jupyter集成
4. 基础编程
   • 创建简单模型
   • 链式调用风格
   • 对象栈概念
   • 材料系统：v2.7 引入，支持密度、颜色等属性
   • 非阻塞可视化：v2.6 引入的 cadquery.fig.Figure API
5. 资源与工具
   • 官方文档和社区支持
   • 学习资源和项目参考

通过本章的学习，您应该已经能够：

• 理解CadQuery的核心概念和工作原理
• 成功安装和配置CadQuery开发环境
• 编写简单的CadQuery脚本创建基本3D模型
• 使用自由函数API和材料系统进行现代建模

在下一章中，我们将深入学习CadQuery的Workplane和草图系统，这是进行复杂建模的基础。