5个步骤掌握FreeCAD Python API：从基础到自动化建模全攻略

你是否曾因重复的建模操作而感到枯燥？是否希望通过编程实现设计流程的自动化？FreeCAD Python API为你提供了强大的解决方案，让你能够通过代码控制3D建模过程，显著提升设计效率。本文将带你从零开始，掌握如何利用FreeCAD Python API实现参数化设计、批量建模和工程图生成，让你的设计流程更高效、更灵活。

基础认知：FreeCAD Python API核心模块解析

FreeCAD作为一款开源的3D参数化建模软件，其Python API允许用户通过编程方式控制几乎所有功能。要开始使用API，首先需要了解几个核心模块：

• FreeCAD：提供文档管理、对象创建等核心功能，是所有操作的基础
• Part：负责几何体的创建和编辑，提供丰富的形状操作功能
• Draft：专注于2D绘图和基础几何体创建，适合快速原型设计
• PartDesign：参数化零件设计模块，支持草图绘制和特征添加

这些模块的实现代码主要位于项目的src/Mod/目录下，例如PartDesign模块的源码可以在src/Mod/PartDesign/中找到。

环境准备与第一个脚本

启动FreeCAD后，通过菜单栏的"工具>Python控制台"打开交互式编程环境。以下是一个简单的入门脚本，创建一个基础立方体：

import FreeCAD as App
import Part

# 创建新文档
doc = App.newDocument("MyFirstModel")

# 创建立方体
cube = Part.makeBox(10, 10, 10)  # 长、宽、高
cube_obj = doc.addObject("Part::Feature", "Cube")
cube_obj.Shape = cube

# 设置位置
cube_obj.Placement.Base = App.Vector(0, 0, 0)

# 刷新视图
doc.recompute()

这段代码演示了FreeCAD Python API的基本工作流程：创建文档、生成几何体、添加到文档并设置属性。

核心功能：参数化设计与自动化建模

如何创建参数化模型并动态调整尺寸

参数化设计是FreeCAD的核心优势，通过Python API可以轻松实现参数驱动的模型创建。以下示例展示如何创建一个参数化的螺栓模型：

import FreeCAD as App
import PartDesign

# 创建新文档和零件主体
doc = App.newDocument("ParametricBolt")
body = doc.addObject("PartDesign::Body", "BoltBody")

# 定义参数
bolt_diameter = 8.0
bolt_length = 50.0
thread_pitch = 1.25

# 创建螺栓杆
sketch = body.newObject("Sketcher::SketchObject", "BoltShaft")
sketch.Support = (doc.getObject("XY_Plane"), [""])
sketch.MapMode = "FlatFace"
# 绘制圆并添加直径约束
sketch.addGeometry(Part.Circle(App.Vector(0, 0, 0), App.Vector(0, 0, 1), bolt_diameter/2))
sketch.addConstraint(Sketcher.Constraint('Diameter', 0, bolt_diameter))
# 退出草图并拉伸
pad = body.newObject("PartDesign::Pad", "BoltShaftPad")
pad.Profile = sketch
pad.Length = bolt_length
pad.Reversed = False

doc.recompute()

通过修改bolt_diameter、bolt_length等参数，即可快速生成不同规格的螺栓模型。这种方法特别适合系列化产品设计。

批量创建与阵列特征的实现方法

当需要创建多个相同或相似的特征时，手动操作效率低下且容易出错。FreeCAD的Draft模块提供了强大的阵列功能：

import FreeCAD as App
import Draft

doc = App.newDocument("ArrayExample")

# 创建基础圆柱体
cylinder = Draft.make_cylinder(radius=5, height=20)
cylinder.Placement.Base = App.Vector(20, 0, 0)
cylinder.Label = "BaseCylinder"

# 创建矩形阵列
rect_array = Draft.make_ortho_array(
    base_object=cylinder,
    v_x=5,  # X方向数量
    v_y=3,  # Y方向数量
    l_x=30,  # X方向间距
    l_y=30   # Y方向间距
)
rect_array.Label = "RectangularArray"

doc.recompute()

除了矩形阵列，还可以使用Draft.make_polar_array创建极坐标阵列，或使用Draft.make_path_array沿自定义路径创建阵列。这些功能的实现代码位于src/Mod/Draft/draftmake/目录中。

场景应用：从建模到工程文档的完整流程

机械装配体设计与约束添加

FreeCAD的装配模块允许你将多个零件组合成完整的装配体，并添加运动约束。以下是一个简单的装配示例：

import FreeCAD as App
import Assembly

# 创建装配文档
doc = App.newDocument("AssemblyExample")
assembly = doc.addObject("Assembly::Assembly", "MainAssembly")

# 加载零件
part1 = doc.loadPart("part1.FCStd")
part2 = doc.loadPart("part2.FCStd")

# 添加到装配
assembly.addObject(part1)
assembly.addObject(part2)

# 添加约束
constraint = assembly.addConstraint("Assembly::Constraint")
constraint.Type = "Coincident"
constraint.Object1 = part1
constraint.SubObject1 = ["Face1"]
constraint.Object2 = part2
constraint.SubObject2 = ["Face2"]

doc.recompute()

有限元分析与工程图生成

完成建模后，通常需要进行有限元分析和工程图生成。FreeCAD的FEM模块和TechDraw模块提供了这些功能：

import FreeCAD as App
import Fem
import TechDraw

# 创建有限元分析
doc = App.ActiveDocument
analysis = Fem.newAnalysis("Analysis")
mechanical_analysis = Fem.newMechanicalAnalysis(analysis, "MechanicalAnalysis")

# 添加材料
material = Fem.newMaterial("Material")
material.Material = "Steel"
mechanical_analysis.addObject(material)

# 添加约束和载荷
fixed_constraint = Fem.newConstraintFixed("FixedConstraint")
fixed_constraint.References = [(doc.getObject("Part"), "Face1")]
mechanical_analysis.addObject(fixed_constraint)

force_constraint = Fem.newConstraintForce("ForceConstraint")
force_constraint.References = [(doc.getObject("Part"), "Face2")]
force_constraint.Force = 1000.0
mechanical_analysis.addObject(force_constraint)

# 生成工程图
page = TechDraw.newPage("Page", "A4_Landscape")
view = TechDraw.newView("View", doc.getObject("Part"))
page.addView(view)

# 添加尺寸标注
dim = TechDraw.makeDimension(page, view, 'Edge1', 'Edge7')

doc.recompute()

高级技巧：提升脚本效率与可维护性

错误处理与日志记录

编写健壮的脚本需要考虑错误处理，以下是一个示例：

def create_cube(length, width, height):
    """创建立方体并处理可能的错误"""
    try:
        if length <= 0 or width <= 0 or height <= 0:
            raise ValueError("尺寸必须为正数")
            
        cube = Part.makeBox(length, width, height)
        return cube
    except Exception as e:
        App.Console.PrintError(f"创建立方体失败: {str(e)}\n")
        return None

外部数据集成与批量处理

从外部文件导入数据可以显著提高设计效率：

import csv

def import_parameters_from_csv(filename):
    """从CSV文件导入参数并创建模型"""
    parameters = []
    with open(filename, 'r') as f:
        reader = csv.DictReader(f)
        for row in reader:
            parameters.append({
                'name': row['name'],
                'length': float(row['length']),
                'width': float(row['width']),
                'height': float(row['height'])
            })
    
    doc = App.newDocument("BatchModels")
    for param in parameters:
        cube = Part.makeBox(param['length'], param['width'], param['height'])
        obj = doc.addObject("Part::Feature", param['name'])
        obj.Shape = cube
    
    doc.recompute()

资源导航：深入学习FreeCAD Python API

核心模块源码位置

• 基础几何体创建：src/Mod/Draft/draftmake/
• 参数化设计：src/Mod/PartDesign/
• 工程图生成：src/Mod/TechDraw/
• Python API实现：src/App/DocumentPy.cpp
• 脚本编辑器：src/Gui/PythonEditor.cpp

学习路径建议

1. 入门阶段：熟悉FreeCAD界面和基础Python API，尝试创建简单几何体
2. 进阶阶段：学习参数化设计和特征操作，掌握PartDesign模块
3. 高级阶段：探索装配、有限元分析等高级功能，实现完整工作流自动化
4. 专家阶段：开发自定义插件，扩展FreeCAD功能

常用API参考

• 文档操作：App.newDocument()、App.getDocument()、doc.recompute()
• 对象创建：doc.addObject()、Part.makeBox()、Draft.make_cylinder()
• 属性设置：obj.Placement、obj.Label、obj.Shape
• 选择操作：App.Gui.Selection.getSelection()
• 导出功能：Part.export()、Mesh.export()

通过本文介绍的知识和技巧，你已经具备了使用FreeCAD Python API进行自动化建模的基础。随着实践的深入，你将能够创建更复杂的脚本，实现更高效的设计流程。无论是机械设计、建筑建模还是3D打印前处理，FreeCAD Python API都能成为你提升工作效率的强大工具。