查看“CadQuery”的源代码

CadQuery 是一个基于 [[Python]] 的参数化 3D CAD 库，底层使用 OpenCascade（OCCT）内核。支持输出STL、STEP、AMF和3MF的CAD格式。

==简介==
===时间轴===

==快速入门==

==API 参考==
=== 草图初始化 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch(parent, locs, obj)</code> || 2D 草图，用于构建二维几何形状 || <code>s = Sketch()</code><br/>创建一个空的 2D 草图对象
|-
| <code>Sketch.importDXF(filename[, tol, exclude, ...])</code> || 导入 DXF 文件并构建面 || <code>sketch = Sketch.importDXF("profile.dxf")</code><br/>从 DXF 文件导入几何图形并创建草图
|-
| <code>Workplane.sketch()</code> || 初始化并返回一个草图 || <code>s = Workplane().sketch()</code><br/>初始化一个新草图，通常在创建后自动调用
|-
| <code>Sketch.finalize()</code> || 完成草图构造并返回父对象 || <code>result = sketch.finalize()</code><br/>完成草图编辑，返回父对象（通常用于链式调用）
|-
| <code>Sketch.copy()</code> || 创建草图的局部副本 || <code>s2 = s.copy()</code><br/>创建草图 s 的一个独立副本，用于后续修改而不影响原草图。
|-
| <code>Sketch.located(loc)</code> || 创建带有新位置的草图局部副本 || <code>sketch.located(Location(Vector(10, 0, 0)))</code><br/>创建草图副本并平移到新位置
|-
| <code>Sketch.moved(....)</code> || 创建移动后的面的草图局部副本 ||<code>sketch.moved(Vector(5, 5))</code><br/>将草图中的面移动后创建新副本
|}

=== 草图选择 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.tag(name)</code> || 为当前选择添加标签 || <code>sketch.rect(10, 10).tag("outer")</code><br/>创建一个 10x10 矩形并为其添加标签 "outer"，便于后续选择
|-
| <code>Sketch.select(tag)</code> || 根据标签选择元素 || <code>sketch.select("outer")</code><br/>选择之前标记为 "outer" 的几何元素
|-
| <code>Sketch.reset()</code> || 重置当前选择状态 || <code>sketch.reset()</code><br/>清除所有当前选中的元素，恢复到初始未选择状态
|-
| <code>Sketch.delete([mode])</code> || 删除选中的对象 || <code>sketch.circle(5).tag("hole").delete()</code><br/>创建一个圆形后标记并删除它
|-
| <code>Sketch.faces([selector])</code> || 选择面元素 || <code>sketch.rect(10, 10).faces().fillet(1)</code><br/>选择矩形面并添加圆角
|-
| <code>Sketch.edges([selector])</code> || 选择边元素 || <code>sketch.rect(10, 10).edges().chamfer(0.5)</code><br/>选择矩形所有边并添加倒角
|-
| <code>Sketch.vertices([selector])</code> || 选择顶点元素 || <code>sketch.rect(10, 10).vertices().fillet(2)</code><br/>选择矩形所有顶点并添加圆角
|}

=== 基于面的草图绘制 ===
; Sketch Mode 类型说明
* <code>'a'</code> - Add (添加) - 添加区域到草图 - 默认模式，创建实体区域
* <code>'s'</code> - Subtract (减去) - 从现有区域中减去 - 创建孔洞或凹陷
* <code>'i'</code> - Intersect (相交) - 保留与现有区域的交集 - 创建重叠部分
* <code>'c'</code> - Construction (构造) - 创建辅助几何 - 辅助线/圆，不参与实体
* <code>'g'</code> - Guide (引导) - 引导线 - 用于扫掠等操作
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.face(b[, angle, mode, tag, ...])</code> || 从线框或边构建一个面 || <code>s = Sketch().face(wire, mode='a')</code><br/>从闭合线框创建一个面，使用 ADD 模式添加到现有图形
|-
| <code>Sketch.rect(w, h[, angle, mode, tag])</code> || 构建一个矩形面 || <code>cq.Sketch().rect(10, 20).rect(5, 10, mode='s')</code><br/>创建一个 10x20 矩形，然后在其中减去一个 5x10 矩形
|-
| <code>Sketch.circle(r[, mode, tag])</code> || 构建一个圆形面 || <code>s = cq.Sketch().circle(5).circle(3,mode='s')</code><br/>创建一个半径 5 的圆，然后在中心减去一个半径 3 的圆（形成环形）
|-
| <code>Sketch.ellipse(a1, a2[, angle, mode, tag])</code> || 构建一个椭圆面 || <code>s = Sketch().ellipse(10, 5)</code><br/>创建一个长半轴 10、短半轴 5 的椭圆面
|-
| <code>Sketch.trapezoid(w, h, a1[, a2, angle, ...])</code> || 构建一个梯形面 || <code>s = Sketch().trapezoid(10, 5, 2)</code><br/>创建一个顶宽 10、高 5、顶部偏移 2 的梯形
|-
| <code>Sketch.slot(w, h[, angle, mode, tag])</code> || 构建一个槽形面 || <code>s = Sketch().slot(20, 5)</code><br/>绘制一个长度20、宽度5的槽形面（带圆角）
|-
| <code>Sketch.regularPolygon(r, n[, angle, mode, tag])</code> || 构建一个正多边形面 || <code>s = Sketch().regularPolygon(5, 6)</code><br/>创建一个外接圆半径 5、6 条边的正六边形面
|-
| <code>Sketch.polygon(pts[, angle, mode, tag])</code> || 构建一个多边形面 || <code>s = Sketch().polygon([(0,0), (10,0), (5,8)])</code><br/>创建一个由三个点构成的三角形面
|-
| <code>Sketch.rarray(xs, ys, nx, ny)</code> || 生成一个矩形位置阵列 || <code>s = cq.Sketch().rect(50, 40).rarray(4, 3, 12, 10).circle(2, mode='s')</code><br/>创建一个 3x3 矩形，然后在创建12x10的孔阵列。
|-
| <code>Sketch.parray(r, a1, da, n[, rotate])</code> || 生成极坐标阵列位置 || <code>sketch.parray(20, 0, 360, 8)</code><br/>创建围绕中心、半径 20、从 0 度到 360 度均匀分布的 8 个极坐标阵列位置
|-
| <code>Sketch.distribute(n[, start, stop, rotate])</code> || 沿选中的边或线框分布位置 || <code>sketch.rect(20, 10).edges().distribute(5)</code><br/>沿矩形选中边均匀分布 5 个位置点
|-
| <code>Sketch.each(callback[, mode, tag, ...])</code> || 对所有适用实体应用回调函数 || <code>sketch.rarray(5, 5, 3, 2).each(lambda loc: Sketch().circle(2).moved(loc))</code><br/>在每个阵列位置点执行回调，绘制半径为 2 的圆
|-
| <code>Sketch.push(locs[, tag])</code> || 将当前选择设置为给定位置或点 || <code>sketch.push([Vector(0,0), Vector(10,10), Vector(20,0)])</code><br/>将三个位置点推入当前选择栈，作为后续操作的基准点
|-
| <code>Sketch.hull([mode, tag])</code> || 从当前选择或所有对象生成凸包 || <code>s = Sketch().circle(3).circle(5, (10,0)).hull()</code><br/>创建两个圆，然后生成包含它们的最小凸包面
|-
| <code>Sketch.offset(d[, mode, tag])</code> || 偏移选定的线框或边 || <code>s = Sketch().rect(10, 10).offset(1)</code><br/>创建一个 10x10 矩形，然后向外偏移 1 单位（形成更大的矩形）
|-
| <code>Sketch.fillet(r)</code> || 基于当前选择添加圆角 || <code>s = Sketch().rect(10, 10).vertices().fillet(1)</code><br/>创建一个 10x10 矩形，然后对所有顶点添加半径 1 的圆角
|-
| <code>Sketch.chamfer(d)</code> || 基于当前选择添加倒角 || <code>s = Sketch().rect(10, 10).vertices().chamfer(1)</code><br/>创建一个 10x10 矩形，然后对所有顶点添加距离 1 的倒角
|-
| <code>Sketch.clean()</code> || 移除内部线。 || <code>sketch.clean()</code><br>清理草图中内部的非边界线段。
|}

=== 基于边和约束的草图绘制 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Sketch.edge(val[, tag, forConstruction])</code> || 向草图中添加一条边 || <code><nowiki>s = Sketch().edge("|")</nowiki></code><br/>添加一条水平线作为构造线（用于约束）
|-
| <code>Sketch.segment(p1, p2)</code> || 构建一条线段 || <code>s = Sketch().segment((0,0), (10,0))</code><br/>从 (0,0) 到 (10,0) 添加一条线段
|-
| <code>Sketch.arc(p1, p2, p3)</code> || 构建一条弧线 || <code>s = Sketch().arc((0,0), (5,5), (10,0))</code><br/>通过三点添加一条圆弧
|-
| <code>Sketch.spline(pts)</code> || 构造样条曲线边 || <code>sketch.spline([(0,0), (5,10), (10,0)])</code><br/>绘制通过给定点的样条曲线边
|-
| <code>Sketch.close()</code> || 将最后一条边连接到第一条边 || <code>s = Sketch().segment((0,0), (10,0)).segment((10,0), (10,10)).close()</code><br/>添加两条垂直边后闭合，形成 L 形线框
|-
| <code>Sketch.assemble([mode, tag])</code> || 将边组合成面 || <code>s = Sketch().rect(10, 10, mode=Mode.PRIVATE).assemble()</code><br/>创建私有矩形边，然后组合成一个面
|-
| <code>Sketch.constrain(constraint)</code> || 添加一个约束 || <code>s = Sketch().circle(5).constrain(("distance", "origin", 2))</code><br/>创建一个圆，然后添加约束使其圆心距离原点 2 单位
|-
| <code>Sketch.solve()</code> || 求解当前约束并更新边位置 || <code>s = Sketch().rect(10, 10).constrain(("coincident", "vertex0", "vertex1")).solve()</code><br/>添加重合约束后求解，更新几何位置
|}
=== Workplane 初始化 ===

{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane(, obj)</code> || 在空间中定义一个坐标系，可用于2D坐标操作。 || <code>Workplane()</code><br>创建一个新的Workplane对象，默认在XY平面原点。
|}

=== 2D 操作 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.center(x, y)</code> || 将局部坐标移动到指定位置 || <code>result = cq.Workplane().center(5, 5).rect(10, 10)</code><br/>将工作平面中心移动到 (5,5) 后创建 10x10 矩形
|-
| <code>Workplane.lineTo(x, y[, forConstruction])</code> || 从当前点到指定点绘制一条线 || <code>result = cq.Workplane().moveTo(0,0).lineTo(10, 10)</code><br/>从原点画线到 (10,10)
|-
| <code>Workplane.line(xDist, yDist[, forConstruction])</code> || 从当前点绘制相对直线 || <code>cq.Workplane().moveTo(0,0).line(5, 5)</code><br/>从当前点相对移动 (5,5) 并绘制直线
|-
| <code>Workplane.vLine(distance[, forConstruction])</code> || 从当前点绘制垂直直线 || <code>cq.Workplane().moveTo(0,0).vLine(10)</code><br/>从当前点垂直向上绘制长度 10 的直线
|-
| <code>Workplane.vLineTo(yCoord[, forConstruction])</code> || 从当前点绘制垂直直线到指定 Y 坐标 || <code>cq.Workplane().moveTo(0,0).vLineTo(15)</code><br/>垂直绘制到 Y=15 的直线
|-
| <code>Workplane.hLine(distance[, forConstruction])</code> || 从当前点绘制水平直线 || <code>cq.Workplane().moveTo(0,0).hLine(10)</code><br/>水平绘制长度 10 的直线
|-
| <code>Workplane.hLineTo(xCoord[, forConstruction])</code> || 从当前点绘制水平直线到指定 X 坐标 || <code>cq.Workplane().moveTo(0,0).hLineTo(15)</code><br/>水平绘制到 X=15 的直线
|-
| <code>Workplane.polarLine(distance, angle[, ...])</code> || 从当前点按角度和长度绘制直线 || <code>cq.Workplane().moveTo(0,0).polarLine(10, 45)</code><br/>以 45 度角绘制长度 10 的直线
|-
| <code>Workplane.polarLineTo(distance, angle[, ...])</code> || 从当前点绘制极坐标直线到指定位置 || <code>cq.Workplane().moveTo(0,0).polarLineTo(10, 90)</code><br/>绘制到极坐标 (10, 90°) 的直线
|-
| <code>Workplane.moveTo(x, y)</code> || 移动到指定点（不绘制） || <code>cq.Workplane().moveTo(5, 5).lineTo(10, 10)</code><br/>将当前点移动到 (5,5)（不绘制），然后从该点画线到 (10,10)
|-
| <code>Workplane.move([xDist, yDist])</code> || 相对移动指定距离（不绘制） || <code>cq.Workplane().move(3, 4).line(5, 0)</code><br/>相对移动 (3,4)（不绘制），然后水平绘制长度 5 的直线
|-
| <code>Workplane.spline(listOfXYTuple[, tangents, ...])</code> || 创建通过给定点的样条曲线（2D或3D） || <code>cq.Workplane().spline([(0,0), (5,10), (10,0)])</code><br/>绘制通过三个点的平滑样条曲线
|-
| <code>Workplane.parametricCurve(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲线 || <code>cq.Workplane().parametricCurve(lambda t: (t, t**2), N=50)</code><br/>绘制参数曲线 y=x² 的逼近样条，使用 50 个采样点
|-
| <code>Workplane.parametricSurface(func[, N, start, ...])</code> || 创建逼近给定函数的样条曲面 || <code>cq.Workplane().parametricSurface(lambda u,v: (u, v, u*v))</code><br/>绘制参数曲面 z=xy 的逼近曲面
|-
| <code>Workplane.threePointArc(point1, point2[, ...])</code> || 通过三个点绘制圆弧 || <code>cq.Workplane().moveTo(0,0).threePointArc((5,0), (10,0))</code><br/>从当前点通过 (5,0) 到 (10,0) 绘制圆弧（形成半圆）
|-
| <code>Workplane.sagittaArc(endPoint, sag[, ...])</code> || 使用矢高（sagitta）定义的圆弧 || <code>cq.Workplane().moveTo(0,0).sagittaArc((10,0), 2)</code><br/>绘制到 (10,0)、矢高 2 的圆弧（拱形）
|-
| <code>Workplane.radiusArc(endPoint, radius[, ...])</code> || 使用半径定义的圆弧 || <code>cq.Workplane().moveTo(0,0).radiusArc((10,0), 5)</code><br/>绘制到 (10,0)、半径 5 的圆弧
|-
| <code>Workplane.tangentArcPoint(endPoint)</code> || 从当前边末端绘制切线圆弧到指定点 || <code>cq.Workplane().moveTo(0,0).lineTo(5,0).tangentArcPoint((10,5))</code><br/>先绘制水平线，然后绘制与前一条边相切的圆弧到 (10,5)
|-
| <code>Workplane.mirrorY()</code> || 沿 Y 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorY()</code><br/>将矩形沿 Y 轴镜像，生成对称图形
|-
| <code>Workplane.mirrorX()</code> || 沿 X 轴镜像实体 || <code>cq.Workplane().rect(5, 10).mirrorX()</code><br/>将矩形沿 X 轴镜像，生成对称图形
|-
| <code>Workplane.wire([forConstruction])</code> || 将所有待定边连接成线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).wire()</code><br/>将两条边连接成 L 形线框对象
|-
| <code>Workplane.rect(xLen, yLen[, centered, ...])</code> || 为栈上每个项构造矩形 || <code>cq.Workplane().rect(10, 20)</code><br/>在工作平面原点绘制 10x20 的矩形（默认 centered=True）
|-
| <code>Workplane.circle(radius[, forConstruction])</code> || 为栈上每个项构造圆 || <code>cq.Workplane().circle(5)</code><br/>在工作平面原点绘制半径 5 的圆
|-
| <code>Workplane.ellipse(x_radius, y_radius[, ...])</code> || 为栈上每个项构造椭圆 || <code>cq.Workplane().ellipse(10, 5)</code><br/>在工作平面原点绘制长轴 10、短轴 5 的椭圆
|-
| <code>Workplane.ellipseArc(x_radius, y_radius[, ...])</code> || 绘制椭圆弧 || <code>cq.Workplane().ellipseArc(10, 5, 0, 90)</code><br/>在工作平面原点绘制从 0° 到 90° 的椭圆弧
|-
| <code>Workplane.polyline(listOfXYTuple[, ...])</code> || 从点列表创建折线 || <code>cq.Workplane().polyline([(0,0), (10,0), (10,10)])</code><br/>绘制连接三个点的折线（L 形）
|-
| <code>Workplane.close()</code> || 结束构建并尝试创建封闭线框 || <code>cq.Workplane().moveTo(0,0).lineTo(10,0).lineTo(10,10).close()</code><br/>闭合当前绘制的轮廓，形成封闭矩形线框
|-
| <code>Workplane.rarray(xSpacing, ySpacing, xCount, ...)</code> || 创建矩形阵列点并推入栈 || <code>cq.Workplane().rarray(10, 10, 3, 2).circle(2)</code><br/>创建 3 列 2 行、间距 10 的矩形阵列点，并在每个点绘制半径 2 的圆
|-
| <code>Workplane.polarArray(radius, startAngle, ...)</code> || 创建极坐标阵列点并推入栈 || <code>cq.Workplane().polarArray(20, 0, 360, 8).circle(2)</code><br/>创建 8 个点的 360° 极坐标阵列，并在每个点绘制半径 2 的圆
|-
| <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.placeSketch(sketch)</code> || 根据栈上项放置草图 || <code>cq.Workplane().placeSketch(mySketch).extrude(5)</code><br/>将 Sketch 对象放置到当前 Workplane 位置，然后拉伸 5 个单位
|}

=== 3D 操作（需要活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.cboreHole(diameter, cboreDiameter, cboreDepth[, depth, clean])</code> || 创建沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cboreHole(5, 10, 3, depth=8)</code><br/>在盒子顶面上创建直径 5、沉头直径 10、沉头深度 3、总深 8 的沉头孔
|-
| <code>Workplane.cskHole(diameter, cskDiameter, cskAngle[, depth, clean])</code> || 创建锥形沉头孔 || <code>cq.Workplane().box(50, 50, 10).faces(">Z").workplane().cskHole(5, 10, 90, depth=8)</code><br/>在盒子顶面上创建直径 5、锥头直径 10、锥角 90° 的锥形沉头孔
|-
| <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.cut(toCut[, clean, tol])</code> || 从当前实体切除另一个实体 || <code>result = cq.Workplane().box(50, 50, 10).cut(cq.Workplane().sphere(8))</code><br/>从盒子中减去半径为 8 的球体（布尔差集运算）
|-
| <code>Workplane.cutBlind(until[, clean, both, taper])</code> || 盲切（有限深度挤出切除） || <code>result = cq.Workplane().rect(10, 20).cutBlind(15)</code><br/>将当前轮廓沿法线方向挤出切除深度 15 的槽
|-
| <code>Workplane.cutThruAll([clean, taper])</code> || 贯穿切除 || <code>result = cq.Workplane().rect(10, 20).cutThruAll()</code><br/>将当前轮廓贯穿整个实体进行切除
|-
| <code>Workplane.box(length, width, height[, centered, combine])</code> || 创建立方体 || <code>result = cq.Workplane().box(10, 20, 30)</code><br/>创建长 10、宽 20、高 30 的长方体（默认 centered=True，中心位于原点）
|-
| <code>Workplane.sphere(radius[, direct, angle1, angle2, combine])</code> || 创建球体 || <code>result = cq.Workplane().sphere(10)</code><br/>在当前工作平面位置创建半径 10 的球体
|-
| <code>Workplane.wedge(dx, dy, dz, xmin, zmin, xmax, zmax[, combine])</code> || 创建楔形体 || <code>result = cq.Workplane().wedge(10, 20, 30, 0, 0, 10, 20)</code><br/>创建指定尺寸的楔形实体（类似三棱柱形状）
|-
| <code>Workplane.cylinder(height, radius[, direct, angle, combine])</code> || 创建圆柱体 || <code>result = cq.Workplane().cylinder(30, 10)</code><br/>创建高度 30、半径 10 的圆柱体
|-
| <code>Workplane.union([toUnion, clean, glue, tol])</code> || 合并实体 || <code>result = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5))</code><br/>将球体与当前实体合并（布尔并集运算）
|-
| <code>Workplane.combine([clean, glue, tol])</code> || 合并栈上所有实体 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5)).combine()</code><br/>将当前栈中的多个实体合并为一个实体
|-
| <code>Workplane.intersect(toIntersect[, clean, tol])</code> || 与当前实体进行布尔交集运算 || <code>result = cq.Workplane().box(10, 10, 10).intersect(cq.Workplane().sphere(8))</code><br/>创建一个 10x10x10 的立方体，然后与半径 8 的球体进行布尔交集，保留两者重叠的部分
|-
| <code>Workplane.loft([ruled, combine, clean])</code> || 放样多个截面 || <code>result = cq.Workplane().rect(10, 10).workplane(offset=5).rect(5, 5).loft()</code><br/>将两个不同尺寸的矩形截面放样成 3D 实体
|-
| <code>Workplane.sweep(path[, multisection, transition, combine, clean])</code> || 沿路径扫掠截面 || <code>path = cq.Workplane().spline([(0,0,0), (0,0,10)])<br/>result = cq.Workplane().circle(2).sweep(path)</code><br/>沿样条曲线路径扫掠圆形截面，生成弯曲管道
|-
| <code>Workplane.twistExtrude(distance, angleDegrees)</code> || 在拉伸的同时扭转指定角度 || <code>result = cq.Workplane().rect(5, 5).twistExtrude(20, 90)</code><br/>将 5x5 矩形沿法线方向拉伸 20 个单位，同时从底部到顶部扭转 90°
|-
| <code>Workplane.revolve([angleDegrees, axisStart, axisEnd, combine, clean])</code> || 绕轴旋转生成实体 || <code>result = cq.Workplane().rect(5, 10).revolve(360, (0,0), (0,1))</code><br/>将矩形轮廓绕 Y 轴旋转 360° 生成回转体（类似圆环体或圆柱）
|-
| <code>Workplane.text(txt, fontsize, distance[, ...])</code> || 返回 3D 文本实体 || <code>result = cq.Workplane().text("CadQuery", 5, 2)</code><br/>创建内容为 "CadQuery"、字体高度 5、拉伸深度 2 的 3D 文本实体
|}

=== 3D 操作（无需活动工作平面） ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.shell(thickness[, kind])</code> || 移除选定的面以创建指定厚度的壳体 || <code>result = cq.Workplane().box(10, 10, 5).faces(">Z").shell(0.5)</code><br/>创建一个盒子，移除顶面后形成壁厚 0.5 的壳体
|-
| <code>Workplane.fillet(radius)</code> || 在选定的边上添加圆角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").fillet(2)</code><br/>在立方体所有垂直边上添加半径 2 的圆角
|-
| <code>Workplane.chamfer(length[, length2])</code> || 在选定的边上添加倒角 || <code>result = cq.Workplane().box(10, 10, 10).edges("|Z").chamfer(2)</code><br/>在立方体所有垂直边上添加距离 2 的倒角
|-
| <code>Workplane.rotate(axisStartPoint, axisEndPoint, angleDegrees)</code> || 返回旋转后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).rotate((0,0,0), (1,0,0), 45)</code><br/>绕 X 轴旋转立方体 45 度
|-
| <code>Workplane.rotateAboutCenter(axisEndPoint, ...)</code> || 绕指定轴旋转栈中所有项 || <code>result = cq.Workplane().box(10, 10, 10).rotateAboutCenter((0,0,0), (1,0,0), 45)</code><br/>创建 10x10x10 立方体，然后绕 X 轴（通过原点沿 X 方向）旋转 45 度
|-
| <code>Workplane.translate(vec)</code> || 返回平移后的所有项的副本 || <code>result = cq.Workplane().box(10, 10, 10).translate((5, 0, 0))</code><br/>将立方体沿 X 轴平移 5 个单位
|-
| <code>Workplane.mirror([mirrorPlane, ...])</code> || 镜像单个 CQ 对象 || <code>result = cq.Workplane().box(10, 10, 10).mirror("YZ")</code><br/>创建立方体后，以 YZ 平面为镜像平面进行镜像
|}

=== 迭代方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.each(callback[, useLocalCoordinates, ...])</code> || 对栈中的每个值运行提供的函数，并将返回值收集到新的 CQ 对象中 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).each(lambda loc: cq.Workplane().circle(2).moved(loc))</code><br/>在矩形阵列的每个位置点执行回调函数，在每个点处创建半径为 2 的圆，并收集所有结果
|-
| <code>Workplane.eachpoint(callback[, useLocalCoordinates, ...])</code> || 与 each() 类似，但回调函数的参数会根据栈中位置进行平移 || <code>result = cq.Workplane().rarray(10, 10, 3, 2).eachpoint(lambda pos: cq.Workplane().circle(2).translate(pos))</code><br/>在每个位置点处创建圆，回调函数接收位置向量作为参数，便于创建相对于每个点的几何体
|}

=== 栈与选择器方法 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.all()</code> || 返回栈中所有 CQ 对象的列表 || <code>objects = cq.Workplane().box(10, 10, 10).faces().all()</code><br/>获取立方体所有面的列表，返回包含每个面对象的列表
|-
| <code>Workplane.size()</code> || 返回栈中当前对象的数量 || <code>count = cq.Workplane().box(10, 10, 10).faces().size()</code><br/>获取立方体面的数量（返回 6）
|-
| <code>Workplane.vals()</code> || 获取当前列表中的值 || <code>values = cq.Workplane().box(10, 10, 10).faces().vals()</code><br/>获取所有面对象的原始值（TopoDS_Shape 列表）
|-
| <code>Workplane.add(obj)</code> || 向栈中添加一个对象或对象列表 || <code>result = cq.Workplane().box(10, 10, 10).add(cq.Workplane().sphere(5))</code><br/>创建立方体后添加球体到栈中，栈中现在包含两个实体
|-
| <code>Workplane.val()</code> || 返回栈中的第一个值 || <code>first = cq.Workplane().box(10, 10, 10).faces().val()</code><br/>获取立方体的第一个面对象
|-
| <code>Workplane.first()</code> || 返回栈中的第一个项 || <code>first_item = cq.Workplane().box(10, 10, 10).faces().first()</code><br/>获取立方体的第一个面（与 val() 类似）
|-
| <code>Workplane.item(i)</code> || 返回栈中的第 i 个项 || <code>third_face = cq.Workplane().box(10, 10, 10).faces().item(2)</code><br/>获取立方体的第三个面（索引从 0 开始）
|-
| <code>Workplane.last()</code> || 返回栈中的最后一个项 || <code>last_face = cq.Workplane().box(10, 10, 10).faces().last()</code><br/>获取立方体的最后一个面
|-
| <code>Workplane.end([n])</code> || 返回此 CQ 元素的第 n 级父对象 || <code>parent = cq.Workplane().box(10, 10, 10).faces().vertices().end(2)</code><br/>从顶点选择返回两级父对象（返回到实体层级）
|-
| <code>Workplane.vertices([selector, tag])</code> || 选择栈中对象的顶点，可选择过滤 || <code>vertices = cq.Workplane().box(10, 10, 10).vertices()</code><br/>选择立方体的所有 8 个顶点
|-
| <code>Workplane.faces([selector, tag])</code> || 选择栈中对象的面，可选择过滤 || <code>top_face = cq.Workplane().box(10, 10, 10).faces(">Z")</code><br/>选择立方体上表面（法线方向为正 Z 的面）
|-
| <code>Workplane.edges([selector, tag])</code> || 选择栈中对象的边，可选择过滤 || <code><nowiki>vertical_edges = cq.Workplane().box(10, 10, 10).edges("|Z")</nowiki></code><br/>选择立方体所有垂直边（平行于 Z 轴）
|-
| <code>Workplane.wires([selector, tag])</code> || 选择栈中对象的线框，可选择过滤 || <code>wires = cq.Workplane().box(10, 10, 10).faces(">Z").wires()</code><br/>选择立方体顶面的外轮廓线框
|-
| <code>Workplane.solids([selector, tag])</code> || 选择栈中对象的实体，可选择过滤 || <code>solids = cq.Workplane().box(10, 10, 10).solids()</code><br/>选择立方体实体（通常只有一个）
|-
| <code>Workplane.shells([selector, tag])</code> || 选择栈中对象的壳体，可选择过滤 || <code>shells = cq.Workplane().box(10, 10, 10).shell(0.5).shells()</code><br/>创建壳体后选择壳体对象
|-
| <code>Workplane.compounds([selector, tag])</code> || 选择栈中的复合体，可选择过滤 || <code>compounds = cq.Workplane().box(10, 10, 10).union(cq.Workplane().sphere(5)).compounds()</code><br/>合并立方体和球体后，选择复合体对象
|}

=== 选择器 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>NearestToPointSelector(pnt)</code> || 选择离指定点最近的对象 || <code>nearest = cq.Workplane().box(10, 10, 10).faces(NearestToPointSelector((0,0,5)))</code><br/>选择距离点 (0,0,5) 最近的面（通常为上表面）
|-
| <code>BoxSelector(point0, point1[, boundingbox])</code> || 选择由两点定义的 3D 框内的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(BoxSelector((-5,-5,-5), (5,5,5)))</code><br/>选择位于立方体边界框内的所有面
|-
| <code>BaseDirSelector(vector[, tolerance])</code> || 基于单个方向向量进行选择的基础选择器 || <code>edges = cq.Workplane().box(10, 10, 10).edges(BaseDirSelector((0,0,1), 0.01))</code><br/>选择方向与 Z 轴对齐的边
|-
| <code>ParallelDirSelector(vector[, tolerance])</code> || 选择与指定方向平行的对象 || <code>edges = cq.Workplane().box(10, 10, 10).edges(ParallelDirSelector((0,0,1)))</code><br/>选择平行于 Z 轴的边（即所有垂直边）
|-
| <code>DirectionSelector(vector[, tolerance])</code> || 选择与指定方向对齐的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(DirectionSelector((0,0,1)))</code><br/>选择法线方向为 Z 轴方向的面（上表面和下表面）
|-
| <code>DirectionNthSelector(vector, n[, ...])</code> || 过滤与指定方向平行（或垂直）的对象，返回第 N 个 || <code>edge = cq.Workplane().box(10, 10, 10).edges(DirectionNthSelector((0,0,1), 2))</code><br/>选择平行于 Z 轴的第 3 条边（索引从 0 开始）
|-
| <code>LengthNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个长度的对象 || <code>edge = cq.Workplane().box(10, 10, 10).edges(LengthNthSelector(0))</code><br/>选择长度最短的边
|-
| <code>AreaNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个面积的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(AreaNthSelector(0))</code><br/>选择面积最小的面（10x10 的面中最小为 100）
|-
| <code>RadiusNthSelector(n[, directionMax, tolerance])</code> || 选择第 N 个半径的对象 || <code>edge = cq.Workplane().cylinder(10, 5).edges(RadiusNthSelector(0))</code><br/>选择半径最小的边（圆柱体上下圆边半径 5）
|-
| <code>PerpendicularDirSelector(vector[, tolerance])</code> || 选择与指定方向垂直的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(PerpendicularDirSelector((0,0,1)))</code><br/>选择法线方向与 Z 轴垂直的面（四个侧面）
|-
| <code>TypeSelector(typeString)</code> || 选择具有指定几何类型的对象 || <code>faces = cq.Workplane().box(10, 10, 10).faces(TypeSelector("PLANE"))</code><br/>选择所有平面类型的面（立方体所有面都是平面）
|-
| <code>DirectionMinMaxSelector(vector, minOrMax)</code> || 选择在指定方向上最近或最远的对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(DirectionMinMaxSelector((0,0,1), "MAX"))</code><br/>选择在 Z 轴方向上最远的面（即上表面）
|-
| <code>CenterNthSelector(vector, n[, directionMax, ...])</code> || 按中心在指定方向上投影的距离排序，选择第 N 个对象 || <code>face = cq.Workplane().box(10, 10, 10).faces(CenterNthSelector((0,0,1), 1))</code><br/>按面中心在 Z 轴投影距离排序，选择第 2 个面
|-
| <code>AndSelector(left, right)</code> || 交集选择器（同时满足两个选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(AndSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code><br/>选择法线为 Z 轴方向的平面（即上表面和下表面）
|-
| <code>SumSelector(left, right)</code> || 并集选择器（满足任一选择器） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SumSelector(DirectionSelector((0,0,1)), DirectionSelector((1,0,0))))</code><br/>选择法线为 Z 轴或 X 轴方向的面
|-
| <code>SubtractSelector(left, right)</code> || 差集选择器（满足 left 但不满足 right） || <code>faces = cq.Workplane().box(10, 10, 10).faces(SubtractSelector(DirectionSelector((0,0,1)), TypeSelector("PLANE")))</code><br/>选择法线为 Z 轴方向但非平面的面（立方体中无结果）
|-
| <code>InverseSelector(selector)</code> || 反转给定选择器的选择结果 || <code>faces = cq.Workplane().box(10, 10, 10).faces(InverseSelector(DirectionSelector((0,0,1))))</code><br/>选择所有法线方向不是 Z 轴的面（即四个侧面）
|-
| <code>StringSyntaxSelector(selectorString)</code> || 使用简单字符串语法过滤对象列表 || <code>faces = cq.Workplane().box(10, 10, 10).faces(StringSyntaxSelector(">Z"))</code><br/>使用字符串语法选择法线方向为正 Z 的面（等价于 ">Z"）
|}

=== 装配体 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Assembly([obj, loc, name, color, material, ...])</code> || 嵌套的 Workplane 和 Shape 对象装配体，定义它们的相对位置 || <code>assy = cq.Assembly()</code><br/>创建一个空的装配体对象，用于组织和定位多个零件
|-
| <code>Assembly.add(obj[, loc, name, color, ...])</code> || 向当前装配体添加子装配体或零件 || <code>assy.add(cq.Workplane().box(10, 10, 5), name="base")<br/>assy.add(cq.Workplane().sphere(3), loc=cq.Location((0,0,5)), name="top")</code><br/>向装配体添加底座（立方体）和顶部球体，并指定位置和名称
|-
| <code>Assembly.save(path[, exportType, mode, ...])</code> || 将装配体保存到文件 || <code>assy.save("assembly.step")</code><br/>将装配体保存为 STEP 文件，支持 STEP、STL、VRML 等格式
|-
| <code>Assembly.constrain(constraint)</code> || 定义一个新的约束 || <code>assy.constrain("base", "top", "Axis", (0,0,1), (0,0,1))</code><br/>约束底座和顶部的 Z 轴对齐，使球体位于底座正上方
|-
| <code>Assembly.solve([verbosity])</code> || 求解所有已定义的约束 || <code>assy.solve()</code><br/>求解所有约束，自动调整零件位置以满足约束条件，verbosity=1 可输出求解详情
|-
| <code>Color(r, g, b[, a])</code> || OCCT 颜色对象 Quantity_ColorRGBA 的包装器 || <code>red = cq.Color(1, 0, 0)<br/>assy.add(part, color=red)</code><br/>创建红色颜色对象，并将其应用于装配体中的零件
|}

=== 导出与导入 ===
{| class="wikitable"
! 内容 !! 描述 !! 示例
|-
| <code>Workplane.toSvg([opts])</code> || 返回表示栈中第一个项的 SVG 文本 || <code>svg_text = cq.Workplane().rect(10, 10).toSvg()</code><br/>创建矩形并将其转换为 SVG 文本字符串，可用于网页显示或保存
|-
| <code>Workplane.exportSvg(fileName)</code> || 将栈中第一个项导出为 SVG 文件 || <code>cq.Workplane().rect(10, 10).exportSvg("rectangle.svg")</code><br/>创建矩形并导出为 "rectangle.svg" 文件
|-
| <code>importers.importStep(fileName)</code> || 加载 STEP 文件到 CadQuery Workplane || <code>part = cq.importers.importStep("model.step")</code><br/>从 "model.step" 文件导入 3D 模型，返回 Workplane 对象
|-
| <code>importers.importDXF(filename[, tol, exclude, ...])</code> || 加载 DXF 文件到 Workplane || <code>sketch = cq.importers.importDXF("profile.dxf", tol=0.01)</code><br/>从 DXF 文件导入 2D 轮廓，容差设为 0.01
|-
| <code>exporters.export(w, fname[, exportType, ...])</code> || 将 Workplane 或 Shape 导出到文件 || <code>cq.exporters.export(part, "output.step")</code><br/>将 Workplane 对象导出为 STEP 文件，支持 STL、STEP、SVG 等格式
|-
| <code>occ_impl.exporters.dxf.DxfDocument([...])</code> || 从 CadQuery 对象创建 DXF 文档 || <code>doc = cq.occ_impl.exporters.dxf.DxfDocument()<br/>doc.addShape(sketch)<br/>doc.save("output.dxf")</code><br/>创建 DXF 文档对象，添加几何形状后保存为 DXF 文件
|}

==资源==
===官网===

===网站===