跳到主要内容

故障排查

构建找不到 OpenCascade​

症状： CMake 报告缺少 OCCT 头文件或库。

构建 CadFlow 前，在同一激活环境中安装固定版本 Runtime：

source .venv/bin/activate
python -m pip install "cadquery-ocp==7.9.3.1"
python -m pip install --no-build-isolation .

确认 python 与 pip 指向同一环境。必须关闭构建隔离，CMake 才能发现已安装的 OCCT 文件。

安装后出现 ModuleNotFoundError​

检查当前 Interpreter 和安装位置：

which python
python -m pip show cadflow
python -c "import cadflow; print(cadflow.__version__, cadflow.__file__)"

CadFlow 支持 Python 3.10 至 3.13。其他 Interpreter 可能缺少依赖或不满足包元数据要求。

Shape 属于不同 Model​

错误： all shapes must belong to this Model 或 Session Mismatch Diagnostic。

所有相互作用的 Shape 必须使用同一个原生 Session：

with cad.Model() as model:
    body = model.box(10, 10, 2)
    tool = model.cylinder(2, 4)
    result = model.cut(body, tool)

不要在另一个 Model 上创建 Tool，也不要在 Model 关闭后使用 Shape。

布尔运算没有改变 Body​

通常原因是 Tool 没有与 Body 重叠、只是相切接触，或方向与预期不同。检查两者包围盒和距离：

print("body", body.bbox)
print("tool", tool.bbox)
print("distance", body.distance_to(tool))

让 Tool 有意穿透一小段，执行操作后再对比体积和 Solid 数。

Fillet、Chamfer 或 Shell 选择失败​

选择使用当前拓扑的确定性零基索引。查询 shape.topology，调用 model.preflight(...)，并先测试较小选择。即使数量相似，前序特征变化也可能改变索引含义。

引用必须跨特征编辑保持稳定时，请使用兼容层语义标签与选择器。

验证警告存在多个 Solid​

当 Solid-like 结果不恰好包含一个 Solid 时，Shape.validate() 会给出警告。应明确工作流要的是装配式结果还是单个融合零件。单零件交付应检查布尔重叠，并在导出前融合目标 Body。

STEP 导出不可用​

原生 STEP 写入要求完整 OCCT 构建，并且不能通过 CADFLOW_WITH_STEP=OFF 关闭。请使用匹配 OCCT 文件重新构建并启用 STEP。兼容 STEP API 可能仍可用，但当测试主张包含原生一致性时，不要悄悄替换路径。

PNG 渲染失败​

渲染示例需要可选包：

python -m pip install vtk pillow matplotlib

无显示环境还可能需要支持 Offscreen 的 VTK 构建。几何导出不依赖 PNG 渲染；渲染不可用时仍应独立验证 STEP/STL/GLB 文件。

提供可操作的证据​

Bug 报告中应包含：

  • CadFlow 版本与 Commit；
  • Python、CMake、编译器、操作系统和架构；
  • OCCT 版本与构建配置；
  • 最小可复现 Python 脚本；
  • 结构化 OperationReport 或 Traceback；
  • 测得的包围盒、拓扑和体积；
  • 输入几何或可共享的精简案例。

可复现问题请提交至 CadFlow Issue Tracker。