下面我将从基础到进阶,详细讲解如何实现这一点。

核心概念

1. FreeCAD 的 Python 环境：FreeCAD 自带一个完整的 Python 解释器，当你启动 FreeCAD 时，它就已经在运行一个 Python 会话,你的脚本就是在这个会话中执行的。
2. 两种主要方式：
   • 在 FreeCAD 内部运行脚本：这是最常见的方式，你可以在 FreeCAD 的 Python 控制台直接输入代码，或者将代码保存为 .py 文件（宏），然后通过 FreeCAD 的菜单运行。
   • 从外部系统调用 FreeCAD：你可以从你的操作系统（命令行）或者另一个 Python 环境中启动 FreeCAD 并让它执行一个脚本，这对于自动化流程（作为 CI/CD 的一部分）非常有用。

在 FreeCAD 内部运行脚本

这是学习和开发 FreeCAD 脚本的最佳起点。

使用 FreeCAD 的 Python 控制台

1. 打开 FreeCAD。
2. 在顶部菜单栏中，选择 视图 -> 面板 -> Python 控制台。
3. 一个 Python 交互式终端会出现在 FreeCAD 界面的右侧或底部。

现在你可以直接输入 Python 命令来操作 FreeCAD。

示例：创建一个立方体

# 导入 FreeCAD 模块
import FreeCAD
# 导入基础几何模块
import Part
# 获取当前活动的文档
doc = FreeCAD.ActiveDocument 
# 创建一个新的立方体对象
# Part.makeBox(长度, 宽度, 高度)
box = Part.makeBox(10, 20, 30)
# 将这个立方体对象添加到文档中，这样它才会在 3D 视图中显示出来
doc.addObject("Part::Box", "MyBox") # 创建一个空的盒子对象
doc.MyBox.Shape = box # 将我们创建的几何形状赋给这个对象
# 重新计算文档，以刷新视图
doc.recompute()
print("立方体创建成功！")

创建和运行宏（Macro）

当你有一段需要重复使用的代码时，将其保存为宏文件（.py）会更方便。

1. 编写脚本：使用你喜欢的文本编辑器（如 VS Code, PyCharm, Notepad++）创建一个新文件，create_cylinder.py。

   # create_cylinder.py
   import FreeCAD
   import Part
   # 确保有一个活动的文档
   if FreeCAD.ActiveDocument is None:
       FreeCAD.newDocument()
   doc = FreeCAD.ActiveDocument
   # 创建一个圆柱体
   # Part.makeCylinder(半径, 高度)
   cylinder = Part.makeCylinder(5, 50)
   # 添加到文档
   doc.addObject("Part::Cylinder", "MyCylinder")
   doc.MyCylinder.Shape = cylinder
   # 刷新视图
   doc.recompute()
   print("圆柱体创建成功！")

2. 在 FreeCAD 中运行宏：

   • 打开 FreeCAD。
   • 在顶部菜单栏，选择 宏 -> 宏...。
   • 在弹出的对话框中，点击 加载宏...，然后选择你刚刚创建的 create_cylinder.py 文件。
   • 选中文件后，点击 执行 按钮。

   你就可以通过 宏 -> 宏执行... 来快速运行这个脚本了。

从外部系统调用 FreeCAD

这种方式非常适合将 FreeCAD 集成到更大的自动化工作流中,关键在于使用命令行参数。

命令行参数

FreeCAD 可以从命令行启动,并接受以下常用参数：

• --run-script <path_to_script.py>：启动 FreeCAD 后，立即执行指定的 Python 脚本，脚本执行完毕后，FreeCAD 默认会关闭。
• --console：以命令行模式启动 FreeCAD，不显示图形界面,这对于服务器环境非常有用。
• --execute <python_code>：直接执行一段 Python 代码。

从系统命令行调用

打开你的终端（Windows 的 CMD 或 PowerShell，macOS/Linux 的 Terminal）。

示例：执行一个脚本文件

假设你的脚本文件路径是 C:\Users\YourUser\Documents\freecad_scripts\create_box.py。

# Windows
"C:\Program Files\FreeCAD\bin\FreeCADCmd.exe" --run-script "C:\Users\YourUser\Documents\freecad_scripts\create_box.py"
# macOS (假设 FreeCAD 安装在 /Applications)
/Applications/FreeCAD.app/Contents/MacOS/FreeCAD --run-script "/Users/YourUser/Documents/freecad_scripts/create_box.py"
# Linux
freecad --run-script "/home/youruser/freecad_scripts/create_box.py"

示例：直接执行一段代码

# Windows
"C:\Program Files\FreeCAD\bin\FreeCADCmd.exe" --execute "import Part; p = Part.makeBox(1,1,1); print('Box created')"
# Linux
freecad --execute "import Part; p = Part.makeBox(1,1,1); print('Box created')"

从外部 Python 环境调用

你可以在你自己的 Python 项目中，通过 subprocess 模块来调用 FreeCAD。

示例：使用 subprocess

import subprocess
import os
# 1. 定义脚本内容
script_content = """
import FreeCAD
import Part
doc = FreeCAD.newDocument('MyNewDoc')
box = Part.makeBox(10, 20, 30)
doc.addObject("Part::Box", "MyBox")
doc.MyBox.Shape = box
doc.recompute()
# 保存文档
doc.saveAs('/tmp/my_created_model.FCStd')
print("脚本执行完毕，文档已保存。")
"""
# 2. 将脚本内容写入一个临时文件
temp_script_path = 'temp_freecad_script.py'
with open(temp_script_path, 'w') as f:
    f.write(script_content)
# 3. 获取 FreeCAD 的可执行文件路径
# !!! 注意：这里需要根据你的系统修改 !!!
# Windows: "C:\\Program Files\\FreeCAD\\bin\\FreeCADCmd.exe"
# macOS: "/Applications/FreeCAD.app/Contents/MacOS/FreeCAD"
# Linux: "freecad"
freecad_cmd_path = "freecad" # 在 Linux/macOS 上，系统 PATH 中应该有 freecad
# freecad_cmd_path = r"C:\Program Files\FreeCAD\bin\FreeCADCmd.exe" # Windows 示例
# 4. 构建并执行命令
command = [freecad_cmd_path, '--run-script', os.path.abspath(temp_script_path)]
print(f"执行命令: {' '.join(command)}")
try:
    # 使用 check_run 可以在脚本出错时抛出异常
    subprocess.run(command, check=True, capture_output=True, text=True)
    print("FreeCAD 脚本成功执行！")
except subprocess.CalledProcessError as e:
    print(f"执行失败！错误代码: {e.returncode}")
    print(f"错误信息: {e.stderr}")
finally:
    # 5. 清理临时文件
    if os.path.exists(temp_script_path):
        os.remove(temp_script_path)

常用模块和代码示例

基础操作

• 文档操作

  import FreeCAD
  # 获取当前活动文档
  doc = FreeCAD.ActiveDocument
  # 如果没有活动文档，就创建一个新的
  if doc is None:
      doc = FreeCAD.newDocument()
  # 关闭文档
  # FreeCAD.closeDocument("DocumentName")
  # 保存文档
  # doc.saveAs("/path/to/your/document.FCStd")

• 对象操作

  # 获取文档中的所有对象
  for obj in doc.Objects:
      print(f"对象名称: {obj.Name}, 类型: {obj.TypeId}")
  # 通过名称获取特定对象
  my_box = doc.getObject("MyBox")
  if my_box:
      # 修改对象的属性
      my_box.Label = "我的重命名盒子" # Label 是用户看到的名称
      print(f"盒子的高度: {my_box.Shape.BoundBox.ZLength}")

创建几何形状

• 基本形状

  import Part
  # 立方体
  box = Part.makeBox(10, 20, 30)
  # 球体
  sphere = Part.makeSphere(10)
  # 圆柱体
  cylinder = Part.makeCylinder(5, 50)
  # 圆锥体
  cone = Part.makeCone(10, 5, 20)
  # 拉伸
  wire = Part.makeCircle(10) # 创建一个圆形线框
  face = Part.Face(wire)     # 将线框创建为面
  prism = Part.extrude(face, Vector(0,0,10)) # 沿Z轴拉伸10个单位

• 布尔运算

  # 假设 doc 中已经有名为 "Box" 和 "Sphere" 的对象
  box_obj = doc.Box
  sphere_obj = doc.Sphere
  # 执行减法操作 (从盒子中挖去球体)
  cut_result = box_obj.Shape.cut(sphere_obj.Shape)
  # 创建一个新对象来显示结果
  cut_object = doc.addObject("Part::Feature", "CutResult")
  cut_object.Shape = cut_result
  doc.recompute()

创建和修改零件

import PartDesign
import FreeCAD
doc = FreeCAD.ActiveDocument or FreeCAD.newDocument()
# 创建一个新的零件设计体
body = doc.addObject("PartDesign::Body", "MyBody")
# 将这个体设置为当前活动体，后续操作会在这个体内进行
PartDesign.makeBody(body)
# 在零件体内创建一个拉伸特征
sketch = PartDesign.makeSketch(body, [("Sketch", "XY")]) # 在XY平面创建一个草图
# 给草图添加几何图形和约束 (这里简化，实际中你需要在草图编辑器中操作)
# ... 修改草图 ...
# 拉伸草图
extrusion = PartDesign.makeExtrusion(body, sketch, 20) # 拉伸20mm
doc.recompute()

调试技巧

1. 善用 print()：在脚本的各个关键位置添加 print() 语句,可以帮你查看变量的值和执行流程。
2. 使用 FreeCAD 内置的 Python 控制台：这是最好的调试工具，你可以逐行执行代码，检查对象状态,并立即看到结果。
3. 查看日志：FreeCAD 的输出信息（包括错误）会打印在 Python 控制台中。
4. 记录操作：在 FreeCAD 中，你可以通过 工具 -> 宏 -> 记录宏... 来记录你的手动操作，然后查看生成的 Python 代码，这是学习 API 的绝佳方法。

希望这份详细的指南能帮助你顺利开始在 Python 中调用 FreeCAD！