建模基础

CadFlow 通过显式 Model Session 构建精确边界表示几何。大多数零件遵循同一条路径：

基本体或轮廓 → 特征 → 布尔运算 → 变换 → 检查 → 导出

单位与坐标

现代前端接受普通数值，并要求调用方始终使用同一单位系统。仓库示例通常采用毫米：

WIDTH_MM = 80.0
DEPTH_MM = 50.0
THICKNESS_MM = 8.0

世界坐标系是右手系，默认构造轴为 +Z。长方体从原点向 X、Y、Z 正方向延伸；圆柱默认沿 +Z，除非随后旋转。

保持统一单位

Model 不会自动转换原始数值。如果工作流使用毫米，几何尺寸、公差、网格偏差和验证阈值也应全部使用毫米。

创建基本体

with cad.Model() as model:
    block = model.box(width=80, depth=50, height=8)
    pin = model.cylinder(radius=6, height=20)
    ball = model.sphere(radius=10)
    taper = model.cone(radius1=12, radius2=6, height=25)

每个基本体都返回当前 Model Session 内的 Shape 句柄。

构造轮廓与特征

将闭合 Wire 转换为 Face，然后拉伸：

with cad.Model() as model:
    outline = model.polyline(
        ((0, 0, 0), (40, 0, 0), (40, 25, 0), (0, 25, 0)),
        closed=True,
    )
    face = model.face(outline)
    body = model.extrude(face, 0, 0, 6)

其他特征操作包括：

• revolve(profile, degrees, axis, origin)
• loft(profiles, solid=True, ruled=False)
• sweep(profile, path, solid=True, frenet=False)
• fillet(shape, radius, edges=[...])
• chamfer(shape, distance, edges=[...])
• shell(shape, thickness, faces=[...])

非平面工作流还可以使用原生 bezier_surface、fit_surface、ruled_surface、filling_surface 和 gordon_surface。

增加与移除材料

布尔运算要求参与 Shape 属于同一个 Model：

with cad.Model() as model:
    base = model.box(80, 50, 8)
    boss = model.translate(model.cylinder(14, 14), 40, 25, 6)
    body = model.union(base, boss)

    bore = model.translate(model.cylinder(5, 20), 40, 25, 4)
    body = model.cut(body, bore)

    assert body.validate().ok
    assert body.topology["solids"] == 1

完整后端中的 union、cut 和 intersect 执行精确 OCCT 布尔运算。正确性要求较高时，应检查操作是否改变了预期指标：

before = body.volume
result = model.cut(body, tool)
if result.volume >= before:
    raise RuntimeError("cut did not remove material")

变换 Shape

变换返回新的 Shape，不会修改输入：

moved = model.translate(shape, x=10, y=0, z=5)
turned = model.rotate(moved, degrees=90, axis=(0, 1, 0))
paired = model.mirror(turned, normal=(1, 0, 0))
scaled = model.scale(paired, factor=0.5, center=(0, 0, 0))

这种函数式风格让中间几何保持可检查，也让特征构造更易重放。

明确选择拓扑

原生前端通过 model.faces(shape) 提供确定性的零基 Face 句柄；圆角、倒角和抽壳支持索引选择。依赖索引前应先查询拓扑：

print(body.topology)
report = model.preflight("fillet", body, 2.0, edges=[0, 3])
if report.ok:
    rounded = model.fillet(body, 2.0, edges=[0, 3])
else:
    print(report.to_dict())

索引适合受控特征历史。若引用需要跨编辑和重放保持稳定，应使用兼容层的语义标签和选择器。