CadQuery - 版本历史

Eric：/* 3D 操作（无需活动工作平面） */

2026-04-02T02:30:26Z

3D 操作（无需活动工作平面）

←上一版本		2026年4月2日 (四) 02:30的版本
第340行：		第340行：
	\|-		\|-
	\| <code>Workplane.mirror([mirrorPlane, ...])</code> \|\| 镜像单个 CQ 对象 \|\| <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code><br/>创建立方体后，以 YZ 平面为镜像平面进行镜像		\| <code>Workplane.mirror([mirrorPlane, ...])</code> \|\| 镜像单个 CQ 对象 \|\| <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code><br/>创建立方体后，以 YZ 平面为镜像平面进行镜像
			\|-
			\| <code>Workplane.split(plane[, keepTop, keepBottom])</code> \|\| 将栈上的实体按平面或分割器分割成两部分，可选择保留顶部、底部或两者。 \|\| <code>result = cq.Workplane().box(50, 50, 50).faces(">Y").workplane(-10).split(keepTop=True)</code><br/>使用工作平面将盒子沿 Y 方向在偏移 -10 的位置分割，只保留上半部分。<code>keepTop=True</code> 保留法线方向一侧，<code>keepBottom=True</code> 保留另一侧，<code>keepBoth=True</code> 同时保留两部分并返回元组
	\|}		\|}

Eric：/* Workplane初始化及其他 */

2026-04-02T02:25:04Z

Workplane初始化及其他

←上一版本		2026年4月2日 (四) 02:25的版本
第202行：		第202行：
	\| <code>Workplane(, obj)</code> \|\| 在空间中定义一个坐标系，可用于2D坐标操作。 \|\| <code>Workplane()</code><br>创建一个新的Workplane对象，默认在XY平面原点。		\| <code>Workplane(, obj)</code> \|\| 在空间中定义一个坐标系，可用于2D坐标操作。 \|\| <code>Workplane()</code><br>创建一个新的Workplane对象，默认在XY平面原点。
	\|-		\|-
	\| <code>Workplane.tag(name)</code> \|\| 为当前栈顶对象添加标签，便于后续引用 \|\| <code>wp = cq.Workplane().box(10, 10, 10).faces(">Z").workplane().tag("top")</code><br/>为立方体上表面创建的工作平面添加 "top" 标签，便于后续通过标签引用该工作平面		\| <code>Workplane.tag(name)</code> \|\| 为当前栈顶对象添加标签，便于后续引用 \|\| <code>wp = cq.Workplane().box(10, 10, 10).faces(">Z").workplane().tag("top")</code><br/>为立方体上表面创建的工作平面添加 "top" 标签，便于后续通过标签引用该工作平面 <br/><code>cq.Workplane("XY").polygon(3, 5).extrude(4).tag("prism").sphere(10).faces("<X", tag="prism").workplane().circle(1).cutThruAll()</code><br/>Tags也可以与大多数选择器一起使用。
	\|-		\|-
	\| <code>Workplane.workplaneFromTagged(tag)</code> \|\| 从之前标记的标签恢复/复制工作平面 \|\| <code>result = wp.workplaneFromTagged("top").circle(5).extrude(10)</code><br/>从名为 "top" 的标签处恢复工作平面，在该平面上绘制半径为 5 的圆并拉伸 10 个单位（常用于多次从同一面挤出，避免选择器失效）		\| <code>Workplane.workplaneFromTagged(tag)</code> \|\| 从之前标记的标签恢复/复制工作平面 \|\| <code>result = wp.workplaneFromTagged("top").circle(5).extrude(10)</code><br/>从名为 "top" 的标签处恢复工作平面，在该平面上绘制半径为 5 的圆并拉伸 10 个单位（常用于多次从同一面挤出，避免选择器失效）

Eric：/* Workplane 初始化 */

2026-04-02T02:18:14Z

Workplane 初始化

←上一版本		2026年4月2日 (四) 02:18的版本
第195行：		第195行：
	\| <code>Sketch.solve()</code> \|\| 求解当前约束并更新边位置 \|\| <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code><br/>添加重合约束后求解，更新几何位置		\| <code>Sketch.solve()</code> \|\| 求解当前约束并更新边位置 \|\| <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code><br/>添加重合约束后求解，更新几何位置
	\|}		\|}
	=== ~~Workplane 初始化~~ ===		=== Workplane初始化及其他 ===

	{\| class="wikitable"		{\| class="wikitable"
第201行：		第201行：
	\|-		\|-
	\| <code>Workplane(, obj)</code> \|\| 在空间中定义一个坐标系，可用于2D坐标操作。 \|\| <code>Workplane()</code><br>创建一个新的Workplane对象，默认在XY平面原点。		\| <code>Workplane(, obj)</code> \|\| 在空间中定义一个坐标系，可用于2D坐标操作。 \|\| <code>Workplane()</code><br>创建一个新的Workplane对象，默认在XY平面原点。
			\|-
			\| <code>Workplane.tag(name)</code> \|\| 为当前栈顶对象添加标签，便于后续引用 \|\| <code>wp = cq.Workplane().box(10, 10, 10).faces(">Z").workplane().tag("top")</code><br/>为立方体上表面创建的工作平面添加 "top" 标签，便于后续通过标签引用该工作平面
			\|-
			\| <code>Workplane.workplaneFromTagged(tag)</code> \|\| 从之前标记的标签恢复/复制工作平面 \|\| <code>result = wp.workplaneFromTagged("top").circle(5).extrude(10)</code><br/>从名为 "top" 的标签处恢复工作平面，在该平面上绘制半径为 5 的圆并拉伸 10 个单位（常用于多次从同一面挤出，避免选择器失效）
			\|-
			\| <code>Workplane.copyWorkplane(other)</code> \|\| 复制另一个 Workplane 的平面信息到当前对象 \|\| <code>new_wp = cq.Workplane().copyWorkplane(other_wp)</code><br/>创建新的工作平面，并将另一个工作平面 other_wp 的坐标系信息复制到新对象上
	\|}		\|}

Eric：/* 2D 操作 */

2026-04-02T02:07:10Z

2D 操作

←上一版本		2026年4月2日 (四) 02:07的版本
第267行：		第267行：
	\| <code>Workplane.slot2D(length, diameter[, angle])</code> \|\| 创建带圆角的槽形 \|\| <code>cq.Workplane().slot2D(20, 5)</code><br/>在工作平面原点创建长度 20、宽度 5 的跑道形槽		\| <code>Workplane.slot2D(length, diameter[, angle])</code> \|\| 创建带圆角的槽形 \|\| <code>cq.Workplane().slot2D(20, 5)</code><br/>在工作平面原点创建长度 20、宽度 5 的跑道形槽
	\|-		\|-
	\| <code>Workplane.offset2D(d[, kind, forConstruction])</code> \|\| 创建 2D 偏移线框 \|\| <code>cq.Workplane().rect(10, 10).offset2D(2)</code><br/>将 10x10 矩形线框向外偏移 2 ~~个单位，生成更大的矩形~~		\| <code>Workplane.offset2D(d[, kind, forConstruction])</code> \|\| 创建 2D 偏移线框 \|\| <code>cq.Workplane().rect(10, 10).offset2D(2)</code><br/>将 10x10 矩形线框向外偏移 2 个单位，生成更大的矩形。<br/><code>cq.Workplane().box(4, 2, 0.5).faces(">Z").edges().toPending().offset2D(-0.25, forConstruction=True).vertices().cboreHole(0.125, 0.25, 0.125, depth=None)</code><br/>在顶面向里偏离0.25，再在四个顶点打螺栓孔。

	\|-		\|-
	\| <code>Workplane.placeSketch(sketch)</code> \|\| 根据栈上项放置草图 \|\| <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code><br/>将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位		\| <code>Workplane.placeSketch(sketch)</code> \|\| 根据栈上项放置草图 \|\| <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code><br/>将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位

Eric：/* 3D 操作（需要活动工作平面） */

2026-04-02T01:51:22Z

3D 操作（需要活动工作平面）

←上一版本		2026年4月2日 (四) 01:51的版本
第282行：		第282行：
	\| <code>Workplane.hole(diameter[, depth, clean])</code> \|\| 创建通孔或盲孔 \|\| <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code><br/>在盒子顶面上创建直径 5、深度 8 的盲孔		\| <code>Workplane.hole(diameter[, depth, clean])</code> \|\| 创建通孔或盲孔 \|\| <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().hole(5, depth=8)</code><br/>在盒子顶面上创建直径 5、深度 8 的盲孔
	\|-		\|-
	\| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> \|\| ~~将线框挤出为棱柱体~~ \|\| <code>result = cq.Workplane().rect(10, 20).extrude(30)</code><br/>将 10x20 矩形沿法线方向挤出高度 30 的实体		\| <code>Workplane.extrude(until[, combine, clean, both, taper])</code> \|\| 将线框挤出为棱柱体，可以给定数值，或'next','last ',或输入一个对象的Face。 \|\| <code>result = cq.Workplane().rect(10, 20).extrude(30)</code><br/>将 10x20 矩形沿法线方向挤出高度 30 的实体<br/> <code>result = cq.Workplane(origin=(20, 0, 0)).circle(2).revolve(180, (-20, 0, 0), (-20, -1, 0)).center(-20, 0).workplane().rect(10, 4).extrude("last")</code><br/>

	\|-		\|-
	\| <code>Workplane.cut(toCut[, clean, tol])</code> \|\| 从当前实体切除另一个实体 \|\| <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code><br/>从盒子中减去半径为 8 的球体（布尔差集运算）		\| <code>Workplane.cut(toCut[, clean, tol])</code> \|\| 从当前实体切除另一个实体 \|\| <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code><br/>从盒子中减去半径为 8 的球体（布尔差集运算）

2026年4月2日 (四) 01:30 Eric

2026-04-02T01:30:59Z

←上一版本		2026年4月2日 (四) 01:30的版本
第25行：		第25行：
	show_object(result)		show_object(result)
	</syntaxhighlight>		</syntaxhighlight>
			如果出现错误，不显示模型，在VS Code左侧栏点击OCP图标，在点击ocp_vscode行右侧的Open viewer按钮，就会显示RUNNING并运行，再次运行代码即可。

	https://cadquery.readthedocs.io/en/latest/installation.html		https://cadquery.readthedocs.io/en/latest/installation.html

2026年4月2日 (四) 01:15 Eric

2026-04-02T01:15:12Z

←上一版本		2026年4月2日 (四) 01:15的版本
第4行：		第4行：
	===时间轴===		===时间轴===

			==安装==
			最简单方式使用CQ-Editor（官方的 GUI 编辑器），或者使用常用的编辑器+插件，如VS Code编辑器和OCP CAD Viewer插件。
			===CQ-Editor===
			安装CQ-editor编辑器，会自动安装cadquery，通过pip安装：
			pip install CQ-editor
			安装后，通过命令行启动：
			CQ-editor

			https://github.com/CadQuery/CQ-editor/wiki/Installation

			===VS Code===
			VS Code中，先安装cadquery，在安装OCP CAD Viewer插件。
			pip install cadquery
			安装cadquery后，在[[VS Code]]插件中查找OCP CAD Viewer安装，方便在VS Code查看模型，安装后在VS Code运行查看下。
			<syntaxhighlight lang="python" >
			import cadquery as cq
			from ocp_vscode import show, show_object

			result = cq.Workplane("XY").box(2,2,2).shell(0.2)
			show_object(result)
			</syntaxhighlight>

			https://cadquery.readthedocs.io/en/latest/installation.html
			https://github.com/bernhard-42/vscode-ocp-cad-viewer
	==快速入门==		==快速入门==

2026年4月1日 (三) 16:21 Eric

2026-04-01T16:21:05Z

←上一版本		2026年4月1日 (三) 16:21的版本
第36行：		第36行：
	result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)		result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
	</syntaxhighlight>		</syntaxhighlight>

			Sketch 和 Workplane 的 2D 操作区别：
			*Workplane 的 2D 操作：过程式建模，按顺序执行命令：画圆 → 移动 → 画矩形，尺寸硬编码数值，适用简单、固定的轮廓场景。
			*Sketch ：约束驱动建模，定义几何约束如圆与矩形同心、相切等，尺寸约束 + 变量控制，适用复杂、参数化、需要设计意图的轮廓。
			传统 CAD 中，设计意图（如"这个孔始终与板的中心对齐"）是通过约束实现的。Workplane 的过程式方式需要手动计算位置，参数变化时容易出错。Sketch约束后自动计算。当轮廓包含多个相互关联的图形时（如齿轮轮廓、法兰盘），约束系统能保证所有元素的关系正确。

	==== 直接 API ====		==== 直接 API ====

2026年4月1日 (三) 16:07 Eric

2026-04-01T16:07:09Z

←上一版本		2026年4月1日 (三) 16:07的版本
第5行：		第5行：

	==快速入门==		==快速入门==

			== 核心概念 ==
			CadQuery 是一个基于 Python 的 3D CAD 建模库，其底层是 OpenCascade 几何内核。

			=== BREP 拓扑 ===
			CadQuery 使用'''边界表示法（BREP）'''来定义 3D 物体，即物体由其表面来定义。基本的拓扑元素从简单到复杂依次为：

			* '''顶点 (Vertex)'''：空间中的一个点
			* '''边 (Edge)'''：连接两个或多个顶点的曲线段
			* '''线框 (Wire)'''：一组相互连接的边
			* '''面 (Face)'''：由线框围成的平面或曲面
			* '''实体 (Solid)'''：由面围成的封闭三维体
			* '''复合体 (Compound)'''：多个实体的集合

			=== API 层次结构 ===
			CadQuery 提供了三个层次的 API，从上到下越来越灵活，但也越来越复杂。
			==== 流畅 API ====
			流畅 API是通过链式调用进行建模的接口，入门首选，简单易用。主要分为2类
			* Workplane类，传统 3D 建模，最常用。示例：<code>part = Workplane("XY").box(1,2,3).faces(">Z").circle(0.5).cutThruAll()</code>
			* Sketch类，二维草图专用，更符合传统 CAD 绘图习惯，CadQuery 2.x版本引入。

			两者可以协同工作，如从二维草图开始创建三维模型Sketch → Workplane.placeSketch() → .extrude()，在现有模型上添加特征Workplane → 选面 → .sketch() → 修改 → .cutBlind()。典型工作流示例：
			<syntaxhighlight lang="python" >
			# 创建一个带孔和圆角的平板
			sketch_base = Sketch().rect(20, 15).constrain().solve() # 底板轮廓
			base = Workplane().placeSketch(sketch_base).extrude(3) # 拉伸底板

			# 在底板上表面画圆孔
			hole_sketch = base.faces(">Z").sketch().circle(2).constrain().solve()
			result = base.faces(">Z").placeSketch(hole_sketch).cutBlind(2)
			</syntaxhighlight>

			==== 直接 API ====
			* 当流畅 API 不够用时使用，直接操作拓扑元素（顶点、边、面等）。
			* 可以“自底向上”构建几何体，控制更精细。
			* 示例：`wire = Wire.makeCircle(10); face = Face.makeFromWires(wire, [])`

			==== OCCT API ====
			* 最底层，直接调用 OpenCascade 的 C++ 函数（通过 Python 绑定 `OCP`）。
			* 极其强大但也极其繁琐，适合需要完全控制的场景。
			* 示例：`from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox`

			=== 在 API 之间切换 ===
			你可以根据需要混合使用不同层次的 API：

			* '''从流畅 API 获取直接 API 对象'''：使用 `.val()` 或 `.findSolid()` 方法。
			* '''从直接 API 对象回到流畅 API'''：将直接 API 对象作为参数传入新的 `Workplane`。
			* '''获取底层的 OCCT 对象'''：直接 API 对象通过 `.wrapped` 属性即可获得。

			=== 选择器 ===
			选择器用于在已有模型上快速定位特征，相当于传统 CAD 中的鼠标选取。你可以通过字符串表达式选择面、边、顶点等。
			* 例如：`faces(">Z")` 选择最上方的面，`edges(">X")` 选择 X 轴正方向的边。


	==API 参考==		==API 参考==

2026年4月1日 (三) 15:34 Eric

2026-04-01T15:34:00Z

显示更改

CadQuery - 版本历史

Eric：​/* 3D 操作（无需活动工作平面） */

Eric：​/* Workplane初始化及其他 */

Eric：​/* Workplane 初始化 */

Eric：​/* 2D 操作 */

Eric：​/* 3D 操作（需要活动工作平面） */