第14章：Python 脚本、宏与自动化

1. Python 在 FreeCAD 中的地位

FreeCAD README 明确指出 FreeCAD 提供广泛的 Python API。Python 不是附加脚本语言，而是 FreeCAD 自动化和扩展的核心方式。大量工作台包含 Python 初始化文件，例如 Init.py、InitGui.py，用户操作也常能在 Python 控制台中看到对应命令。

Python 可用于：

• 批量创建模型。
• 修改对象属性。
• 执行重计算。
• 导入导出文件。
• 创建宏命令。
• 开发工作台。
• 构建自定义参数化对象。

2. Python 控制台

打开 Python 控制台后，可以查看当前文档、选择对象和创建简单几何。常见对象：

• FreeCAD：核心应用模块，常缩写为 App。
• FreeCADGui：图形界面模块，常缩写为 Gui。
• ActiveDocument：当前文档。
• Selection：当前选择。

学习方法：先手工执行一个命令，再观察控制台输出，然后改写为可复用脚本。

3. 宏

宏是记录或编写的一段 Python 脚本。适合自动执行重复任务：

• 批量导出选中对象。
• 一键设置视图颜色和透明度。
• 创建常用参数化零件。
• 清理对象命名。
• 生成报告或 BOM。

宏应存放在用户宏目录，并使用版本控制备份。复杂宏建议逐步演化为插件或工作台。

4. 文档与对象操作

典型脚本流程：

1. 新建或获取文档。
2. 添加对象。
3. 设置属性。
4. 调用重计算。
5. 保存或导出。

对象创建后如果视图没有更新，通常需要执行文档重计算。对 GUI 相关操作，还需要确保在图形环境中运行，而不是 FreeCADCmd 无界面环境。

5. Part 脚本建模

Part 模块适合直接创建几何。例如创建盒、圆柱、执行布尔，再把 Shape 赋给文档对象。脚本建模适合规则模型和批量模型。建议：

• 封装尺寸参数。
• 使用清晰变量名。
• 在每一步检查 Shape 是否有效。
• 对导出结果做自动命名。

6. 参数化对象 FeaturePython

FeaturePython 允许创建自定义参数化对象。对象拥有属性和代理类，重计算时执行代理逻辑生成 Shape。它适合把常用业务对象封装为 FreeCAD 原生对象，例如型材、连接件、支架、管件。

核心概念：

• 对象属性用于保存参数。
• Proxy 的 execute 方法生成或更新几何。
• ViewProvider 控制显示和交互。
• 属性变化后触发重计算。

7. GUI 自动化注意事项

GUI 脚本可以操作选择、命令、视图和对话框，但更脆弱。优先使用 App 层 API 直接修改对象，只有必要时使用 Gui 层。

原因：

• GUI 状态依赖当前工作台和选择。
• 无界面运行时 Gui 不可用。
• 对话框和任务面板难以稳定批处理。
• API 直接操作更可测试。

8. 批量导出示例思路

批量导出可按以下逻辑设计：

1. 遍历文档中需要导出的对象。
2. 检查对象是否有 Shape。
3. 根据 Label 生成安全文件名。
4. 导出 STEP 或 STL。
5. 记录成功和失败对象。

不要把导出路径写死在宏中，应通过配置变量或文件选择器设置。

9. 脚本调试

调试方法：

• 使用报告视图查看异常。
• 在宏中分段打印对象属性。
• 从简单模型开始验证。
• 避免一次生成过多对象。
• 将核心几何逻辑写成纯函数，便于复用。

10. API 学习策略

FreeCAD API 很大，不建议死记。有效策略：

• 从 Python 控制台观察命令。
• 查看官方 Wiki Scripting 文档。
• 阅读 src/Mod 中工作台 Python 文件。
• 搜索对象属性和方法。
• 用小宏验证每个 API。