FreeCAD Python API 的基础用法与实战技巧。内容包括环境配置、核心模块（FreeCAD、Part、Draft、PartDesign）介绍，以及创建几何体、极坐标阵列、参数化建模和生成工程图的代码示例。此外还涵盖了错误处理、CSV 数据导入及常见问题解答，旨在帮助开发者利用 Python 脚本实现自动化设计流程，提升建模效率。
FreeCAD 作为开源的多平台 3D 参数化建模软件，其 Python API 功能强大且灵活。通过脚本编程，你可以实现自动化重复任务、参数化设计、集成外部数据及创建自定义工具。
在开始编写脚本之前，你需要了解 FreeCAD 的基本 Python 环境。启动 FreeCAD 后，打开 Python 控制台，就可以直接执行 Python 代码。
核心模块介绍：
FreeCAD：核心功能模块，负责文档管理、对象创建等Part：几何体操作模块，提供形状创建和编辑功能Draft：2D 绘图和基础几何体模块PartDesign：参数化零件设计模块让我们从一个简单的例子开始，创建基础几何体：
import FreeCAD as App
import Draft
# 创建新文档
doc = App.newDocument("基础几何体示例")
# 创建立方体
cube = Draft.make_cube(length=10, width=10, height=10)
cube.Placement.Base = App.Vector(0, 0, 0)
cube.Label = "立方体"
# 创建圆柱体
cylinder = Draft.make_cylinder(radius=5, height=20)
cylinder.Placement.Base = App.Vector(20, 0, 0)
cylinder.Label = "圆柱体"
doc.recompute()
这个小例子展示了如何创建基础几何体并设置其属性。通过 Placement.Base 可以精确控制模型位置，Label 用于设置对象名称。
当你需要创建多个相同特征时，手动操作既耗时又容易出错。使用极坐标阵列可以轻松解决这个问题：
import FreeCAD as App
import Draft
doc = App.newDocument("极坐标阵列示例")
# 创建原始圆柱体
cylinder = Draft.make_cylinder(radius=2, height=15)
cylinder.Placement.Base = App.Vector(10, 0, 0)
cylinder.Label = "原始圆柱"
# 创建极坐标阵列
polar_array = Draft.make_polar_array(
base_object=cylinder,
number=8, # 阵列数量
angle=360, # 阵列总角度
center=App.Vector(0, 0, 0) # 阵列中心
)
polar_array.Label = "极坐标阵列"
doc.recompute()
实用小贴士：
Draft.make_ortho_array 创建矩形阵列Draft.make_path_array 沿路径创建阵列参数化设计是 FreeCAD 的核心优势。以下是一个参数化螺栓的创建过程：
首先创建螺栓头部草图，绘制六边形并添加约束。然后通过拉伸操作创建螺栓头部，接着创建螺栓杆草图并拉伸形成完整螺栓。
参数化建模的优势：
设计完成后，通常需要生成工程图和物料清单。TechDraw 模块提供了强大的工程图生成功能：
import TechDraw
from TechDraw import TechDrawGui
# 创建工程图页面
page = TechDraw.newPage("Page", "A4_Landscape")
# 创建视图并添加到页面
view = TechDraw.newView("View", cube)
page.addView(view)
# 添加尺寸标注
dim_length = TechDraw.makeDimension(page, view, 'Edge1', 'Edge7')
dim_width = TechDraw.makeDimension(page, view, 'Edge2', 'Edge4')
TechDrawGui.fitPage(page) # 调整页面适应视图
编写脚本时难免会遇到错误，良好的错误处理机制至关重要：
def safe_geometry_check(obj):
"""安全地检查对象几何错误"""
try:
if not hasattr(obj, "Shape"):
return "对象没有形状"
shape = obj.Shape
# 执行几何检查...
return "检查完成"
except Exception as e:
return f"检查失败：{str(e)}"
从外部文件导入数据可以大大提高设计效率：
import csv
def import_from_csv(filename):
"""从 CSV 文件导入数据创建模型"""
doc = App.ActiveDocument or App.newDocument("CSV 导入")
with open(filename, 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
for row in reader:
# 解析数据并创建模型...
pass
让我们通过一个完整的项目来巩固所学知识。假设我们要设计一个简单的机械装置：
# 创建新文档和主体
doc = App.newDocument("机械装置")
body = PartDesign.Body(doc)
doc.addObject(body)
在基础结构上添加孔、槽等特征，实现装置的完整功能。
创建工程图页面，添加视图和标注，最后导出物料清单。
selected_objects = App.Gui.Selection.getSelection()
# 导出为 STL 格式
Mesh.export([obj], "output.stl")
# 导出为 STEP 格式
Part.export([obj], "output.step")
def check_geometry_issues(obj):
"""检查常见几何问题"""
shape = obj.Shape
# 检查非流形边、自由边等
通过本文的学习，你已经掌握了 FreeCAD Python API 的核心技能。建议从简单脚本开始，逐步扩展功能，并针对具体设计需求编写定制脚本。每个复杂的自动化流程都是从简单的脚本开始的。下一步可深入学习 PartDesign 模块的高级功能，探索 TechDraw 模块的复杂标注功能，或尝试集成外部 Python 库扩展 FreeCAD 功能。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online