尧图网页设计 
FreeCAD Python API 实战指南5 类脚本让建模效率翻倍【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCADFreeCAD 是一款开源的 3D 参数化建模工具内置完整的 Python API可以把重复的建模动作压缩成几行脚本。读完后你将掌握基础几何建体、参数化特征、自动出图、几何体检与批量导出的写法把机械劳动交给脚本把时间留给设计本身。环境与前置准备这一步解决脚本在哪里跑、依赖装了什么的问题。运行位置FreeCAD 菜单 工具 → 宏 → 宏编辑器 或 控制台Python Console两者都运行在 FreeCAD 进程内能直接使用FreeCAD、Part、Draft等模块无需额外安装。版本建议使用 1.0 及以上文中PartDesign草图约束 API 与TechDraw出图功能在该版本上行为最稳定。第三方库核心场景只用标准库csv、os。若要生成数学曲面或做矩阵运算再安装 NumPy。获取源码如需阅读实现执行git clone https://gitcode.com/GitHub_Trending/fr/freecad freecad核心 API 都在src/目录下。一个习惯建议所有脚本第一行写import FreeCAD as App第二行写doc App.newDocument(名字)文档句柄全程传递不依赖活动文档。阶段一基础几何的脚本化创建用 Part 模块 30 秒建出盒体、圆柱与球体需要不进入任何工作台、直接生成实体时用Part模块最稳它不依赖 GUI。import FreeCAD as App import Part doc App.newDocument(基础几何) # makeBox 参数依次为长、宽、高单位毫米 box Part.makeBox(20, 15, 10) # makeCylinder 参数为半径、高度第三参数是轴线起点 cyl Part.makeCylinder(5, 20, App.Vector(30, 0, 0)) # 球体放在 (60, 0, 5) sph Part.makeSphere(8, App.Vector(60, 0, 5)) # 把裸 Shape 挂到文档对象上才能在 3D 视图里看到 doc.addObject(Part::Feature, 盒体).Shape box doc.addObject(Part::Feature, 圆柱).Shape cyl doc.addObject(Part::Feature, 球体).Shape sph doc.recompute()核心 API 是Part.makeBox / makeCylinder / makeSphere注意它们返回的是Shape而非文档对象必须再addObject挂进文档才可见。用 Draft 的极坐标阵列与正交阵列批量复制需要一个零件复制成一组时Draft 的阵列对象比手写循环更省代码且后续可随参数联动。import FreeCAD as App import Draft doc App.newDocument(阵列示例) # 阵列源一个圆柱 src Draft.make_cylinder(2, 15) src.Placement.Base App.Vector(10, 0, 0) # 极坐标阵列绕 Z 轴均布 8 份 polar Draft.make_polar_array(src, number8, angle360) # 正交阵列3 行 × 4 列 rect Draft.make_rect_array(src, 3, 4) doc.recompute()核心 API 是Draft.make_polar_array与Draft.make_rect_array注意angle360表示均布满圈、number控制份数阵列对象会引用源对象删掉源会连带失效。函数实现可看 src/Mod/Draft/draftmake/。阶段二参数化建模与特征批量操作一键生成参数化六角螺栓头需要改一个数字、模型整体跟着变时走 PartDesign 的 Body Sketch Pad 链路。import FreeCAD as App import Part import PartDesign doc App.newDocument(螺栓) body doc.addObject(PartDesign::Body, Body) # 草图挂到 Body 自带的 XY 基准面上保证后续可重建 sk body.newObject(Sketcher::SketchObject, HexSketch) sk.Support (body.Origin.OriginFeatures[3], []) # XY_Plane sk.MapMode FlatFace # 六边形外接圆半径 56 条线段依次闭合 import math pts [App.Vector(5 * math.cos(math.pi * i / 3), 5 * math.sin(math.pi * i / 3), 0) for i in range(6)] for i in range(6): sk.addGeometry(Part.LineSegment(pts[i], pts[(i 1) % 6]), False) sk.addConstraint([Sketcher.Constraint(Equal, i, i 1) for i in range(5)] [Sketcher.Constraint(Equal, 5, 0)]) pad body.newObject(PartDesign::Pad, Head) pad.Profile sk pad.Length 6 # 拉伸长度 doc.recompute()核心 API 是body.newObject注意草图必须绑定SupportMapModeFlatFace才能跟随基准面否则重算后草图会飞走。Body 的内置基准面在body.Origin.OriginFeatures里按 ZY_XY_YZ_XZ 顺序排列PartDesign 完整实现见 src/Mod/PartDesign/。从 CSV 读孔表批量挖出所有工艺孔需要参数在 Excel 里维护、模型自动生成时用csv标准库读表建体最直观。import FreeCAD as App import Part import csv doc App.newDocument(数据驱动) base Part.makeBox(60, 40, 10) doc.addObject(Part::Feature, 底板).Shape base # 孔表列X, Y, 半径, 深度 with open(holes.csv, encodingutf-8) as f: for row in csv.DictReader(f): r float(row[半径]) d float(row[深度]) hole Part.makeCylinder(r, d, App.Vector(float(row[X]), float(row[Y]), 10)) # 用底板减孔得到带孔实体 base base.cut(hole) doc.getObject(底板).Shape base doc.recompute()核心 API 是布尔运算Shape.cut注意 CSV 数值一律先float()再使用表头缺失会直接抛KeyError建议先校验列名。阶段三出图、质量检查与数据流转用 TechDraw 脚本自动出图并加尺寸标注需要模型一改、图纸自动重生成时TechDraw 的页面、视图、标注全部可以脚本创建。import FreeCAD as App import TechDraw import FreeCADGui as Gui doc App.getDocument(螺栓) part doc.getObject(Head) # 模板路径随 FreeCAD 安装的 A4 横向模板 tpl doc.addObject(TechDraw::DrawViewTemplate, Template) tpl.Template App.getResourceDir() Mod/TechDraw/Templates/A4_Landscape_blank.svg page doc.addObject(TechDraw::DrawPage, Page) page.Template tpl view doc.addObject(TechDraw::DrawViewPart, FrontView) page.addView(view) view.Source [part] view.Direction App.Vector(0, -1, 0) # 从 -Y 方向投影 view.X, view.Y 150, 105 view.Scale 2.0 # 标注第一条边视图边编号从 0 开始 dim doc.addObject(TechDraw::DrawViewDimension, Dim) dim.Type Distance dim.References2D [(view, Edge0)] page.addView(dim) doc.recompute() Gui.Selection.addSelection(page) Gui.runCommand(TechDraw_KeepInPage) # 缩放页面适配视图核心 API 是DrawViewPartDrawViewDimension注意References2D里的边号依赖投影方向换Direction后编号会重排脚本里要固定一个投影方向。TechDraw 全部实现位于 src/Mod/TechDraw/。脚本跑一遍几何体检坏模型提前暴露需要交付前批量确认模型干净时用Part.Shape.check()做自动体检比肉眼快得多。import FreeCAD as App doc App.ActiveDocument for obj in doc.Objects: if not hasattr(obj, Shape): continue # 跳过无几何的对象 try: ok obj.Shape.isValid() # BRep 有效性 msgs obj.Shape.check(True) # 返回错误信息列表 print(f{obj.Label}: valid{ok}, issues{len(msgs)}) except Part.OCCError as e: print(f{obj.Label}: 检查失败 - {e})核心 API 是Shape.isValid()与Shape.check()注意check(True)的第二参数是 verbose 开关返回的字符串列表可以直接进报告。几何内核实现可参考 src/Mod/Part/App/。用脚本批量导出 STL 并生成 CSV BOM需要一键交付制造时导出和 BOM 可以合并成一次遍历。import FreeCAD as App import Mesh import csv doc App.ActiveDocument rows [] for obj in doc.Objects: if not hasattr(obj, Shape) or not obj.Shape.Solids: continue # 逐件导出 STL文件名用对象名 Mesh.export([obj], fout/{obj.Name}.stl) # 按钢材密度 7.85 g/cm³ 估算质量 rows.append({名称: obj.Label, 体积_mm3: round(obj.Shape.Volume, 1), 质量_g: round(obj.Shape.Volume * 0.00785, 2)}) with open(BOM.csv, w, newline, encodingutf-8-sig) as f: w csv.DictWriter(f, fieldnames[名称, 体积_mm3, 质量_g]) w.writeheader() w.writerows(rows)核心 API 是Mesh.export注意 BOM 写出时用utf-8-sig编码否则 Excel 打开中文列名会乱码。综合实战一条脚本串起完整流程前面三类脚本组合起来就是建体 → 参数化 → 出图 → 体检 → 导出的流水线。下面把它压成一个函数参数全部抽到顶部import FreeCAD as App import Part import Mesh import csv def build_and_ship(spec_file, out_dirout): spec_file: 列 名称,类型,尺寸1,尺寸2,尺寸的 CSV doc App.newDocument(流水线) with open(spec_file, encodingutf-8) as f: for row in csv.DictReader(f): if row[类型] box: shape Part.makeBox(float(row[尺寸1]), float(row[尺寸2]), 10) else: shape Part.makeCylinder(float(row[尺寸1]), float(row[尺寸2])) feat doc.addObject(Part::Feature, row[名称]) feat.Shape shape doc.recompute() # 体检 导出 BOM复用阶段三的写法 for obj in doc.Objects: print(obj.Name, obj.Shape.isValid()) Mesh.export([obj], f{out_dir}/{obj.Name}.stl) # 调用一行命令完成全部产物 build_and_ship(parts.csv)核心思路是文档即数据所有输入收敛到一个 CSV脚本不写死任何零件名换规格表就能换产品。常见坑与排错速查现象原因处理3D 视图看不到脚本建的物体makeBox等返回的是Shape未挂进文档再执行addObject并赋值.Shapedoc.recompute()后草图位置错乱草图没绑Support/MapMode检查sk.Support与sk.MapModeTechDraw 标注的边号对不上投影方向改变导致边重编号固定Direction标注前打印边号确认数组number改了没反应改了源对象却没重算末尾补doc.recompute()BOM 在 Excel 里中文乱码默认 UTF-8 无 BOM改用utf-8-sig写出控制台脚本报App.Gui is None无头模式运行了 GUI API出图类命令runCommand只在有界面时执行一个通用排错动作报错时先打印doc.Name和各对象obj.State多数莫名失效是上游对象计算失败、下游连坐。延伸资源官方文档源码在 src/Doc/sphinx/其中 Scripting 章节与本文 API 一一对应。想读实现时按模块找基础几何看 src/Mod/Part/App/参数化看 src/Mod/PartDesign/出图看 src/Mod/TechDraw/二维工具与阵列看 src/Mod/Draft/draftmake/。Python 侧绑定入口在 src/App/Document.pyi 与 src/Gui/ 的*.pyi文件类型标注齐全编辑器会自动补全。社区脚本可参考仓库内测试用例 src/Mod/Draft/TestDraft.py 与 src/Mod/TechDraw/TestTechDrawApp.py它们是最贴近真实 API 用法的活教材。三条起步建议从批量导出 STL这类 10 行以内的小脚本写起先跑通addObject → recompute → export闭环。把尺寸参数全部外置成 CSV 或文档属性脚本只负责翻译改模型时不动代码。每个功能先读一遍对应测试文件再动手能避开 80% 的参数坑。【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FreeCAD Python API 实战指南：5 类脚本让建模效率翻倍
FreeCAD Python API 实战指南5 类脚本让建模效率翻倍【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCADFreeCAD 是一款开源的 3D 参数化建模工具内置完整的 Python API可以把重复的建模动作压缩成几行脚本。读完后你将掌握基础几何建体、参数化特征、自动出图、几何体检与批量导出的写法把机械劳动交给脚本把时间留给设计本身。环境与前置准备这一步解决脚本在哪里跑、依赖装了什么的问题。运行位置FreeCAD 菜单 工具 → 宏 → 宏编辑器 或 控制台Python Console两者都运行在 FreeCAD 进程内能直接使用FreeCAD、Part、Draft等模块无需额外安装。版本建议使用 1.0 及以上文中PartDesign草图约束 API 与TechDraw出图功能在该版本上行为最稳定。第三方库核心场景只用标准库csv、os。若要生成数学曲面或做矩阵运算再安装 NumPy。获取源码如需阅读实现执行git clone https://gitcode.com/GitHub_Trending/fr/freecad freecad核心 API 都在src/目录下。一个习惯建议所有脚本第一行写import FreeCAD as App第二行写doc App.newDocument(名字)文档句柄全程传递不依赖活动文档。阶段一基础几何的脚本化创建用 Part 模块 30 秒建出盒体、圆柱与球体需要不进入任何工作台、直接生成实体时用Part模块最稳它不依赖 GUI。import FreeCAD as App import Part doc App.newDocument(基础几何) # makeBox 参数依次为长、宽、高单位毫米 box Part.makeBox(20, 15, 10) # makeCylinder 参数为半径、高度第三参数是轴线起点 cyl Part.makeCylinder(5, 20, App.Vector(30, 0, 0)) # 球体放在 (60, 0, 5) sph Part.makeSphere(8, App.Vector(60, 0, 5)) # 把裸 Shape 挂到文档对象上才能在 3D 视图里看到 doc.addObject(Part::Feature, 盒体).Shape box doc.addObject(Part::Feature, 圆柱).Shape cyl doc.addObject(Part::Feature, 球体).Shape sph doc.recompute()核心 API 是Part.makeBox / makeCylinder / makeSphere注意它们返回的是Shape而非文档对象必须再addObject挂进文档才可见。用 Draft 的极坐标阵列与正交阵列批量复制需要一个零件复制成一组时Draft 的阵列对象比手写循环更省代码且后续可随参数联动。import FreeCAD as App import Draft doc App.newDocument(阵列示例) # 阵列源一个圆柱 src Draft.make_cylinder(2, 15) src.Placement.Base App.Vector(10, 0, 0) # 极坐标阵列绕 Z 轴均布 8 份 polar Draft.make_polar_array(src, number8, angle360) # 正交阵列3 行 × 4 列 rect Draft.make_rect_array(src, 3, 4) doc.recompute()核心 API 是Draft.make_polar_array与Draft.make_rect_array注意angle360表示均布满圈、number控制份数阵列对象会引用源对象删掉源会连带失效。函数实现可看 src/Mod/Draft/draftmake/。阶段二参数化建模与特征批量操作一键生成参数化六角螺栓头需要改一个数字、模型整体跟着变时走 PartDesign 的 Body Sketch Pad 链路。import FreeCAD as App import Part import PartDesign doc App.newDocument(螺栓) body doc.addObject(PartDesign::Body, Body) # 草图挂到 Body 自带的 XY 基准面上保证后续可重建 sk body.newObject(Sketcher::SketchObject, HexSketch) sk.Support (body.Origin.OriginFeatures[3], []) # XY_Plane sk.MapMode FlatFace # 六边形外接圆半径 56 条线段依次闭合 import math pts [App.Vector(5 * math.cos(math.pi * i / 3), 5 * math.sin(math.pi * i / 3), 0) for i in range(6)] for i in range(6): sk.addGeometry(Part.LineSegment(pts[i], pts[(i 1) % 6]), False) sk.addConstraint([Sketcher.Constraint(Equal, i, i 1) for i in range(5)] [Sketcher.Constraint(Equal, 5, 0)]) pad body.newObject(PartDesign::Pad, Head) pad.Profile sk pad.Length 6 # 拉伸长度 doc.recompute()核心 API 是body.newObject注意草图必须绑定SupportMapModeFlatFace才能跟随基准面否则重算后草图会飞走。Body 的内置基准面在body.Origin.OriginFeatures里按 ZY_XY_YZ_XZ 顺序排列PartDesign 完整实现见 src/Mod/PartDesign/。从 CSV 读孔表批量挖出所有工艺孔需要参数在 Excel 里维护、模型自动生成时用csv标准库读表建体最直观。import FreeCAD as App import Part import csv doc App.newDocument(数据驱动) base Part.makeBox(60, 40, 10) doc.addObject(Part::Feature, 底板).Shape base # 孔表列X, Y, 半径, 深度 with open(holes.csv, encodingutf-8) as f: for row in csv.DictReader(f): r float(row[半径]) d float(row[深度]) hole Part.makeCylinder(r, d, App.Vector(float(row[X]), float(row[Y]), 10)) # 用底板减孔得到带孔实体 base base.cut(hole) doc.getObject(底板).Shape base doc.recompute()核心 API 是布尔运算Shape.cut注意 CSV 数值一律先float()再使用表头缺失会直接抛KeyError建议先校验列名。阶段三出图、质量检查与数据流转用 TechDraw 脚本自动出图并加尺寸标注需要模型一改、图纸自动重生成时TechDraw 的页面、视图、标注全部可以脚本创建。import FreeCAD as App import TechDraw import FreeCADGui as Gui doc App.getDocument(螺栓) part doc.getObject(Head) # 模板路径随 FreeCAD 安装的 A4 横向模板 tpl doc.addObject(TechDraw::DrawViewTemplate, Template) tpl.Template App.getResourceDir() Mod/TechDraw/Templates/A4_Landscape_blank.svg page doc.addObject(TechDraw::DrawPage, Page) page.Template tpl view doc.addObject(TechDraw::DrawViewPart, FrontView) page.addView(view) view.Source [part] view.Direction App.Vector(0, -1, 0) # 从 -Y 方向投影 view.X, view.Y 150, 105 view.Scale 2.0 # 标注第一条边视图边编号从 0 开始 dim doc.addObject(TechDraw::DrawViewDimension, Dim) dim.Type Distance dim.References2D [(view, Edge0)] page.addView(dim) doc.recompute() Gui.Selection.addSelection(page) Gui.runCommand(TechDraw_KeepInPage) # 缩放页面适配视图核心 API 是DrawViewPartDrawViewDimension注意References2D里的边号依赖投影方向换Direction后编号会重排脚本里要固定一个投影方向。TechDraw 全部实现位于 src/Mod/TechDraw/。脚本跑一遍几何体检坏模型提前暴露需要交付前批量确认模型干净时用Part.Shape.check()做自动体检比肉眼快得多。import FreeCAD as App doc App.ActiveDocument for obj in doc.Objects: if not hasattr(obj, Shape): continue # 跳过无几何的对象 try: ok obj.Shape.isValid() # BRep 有效性 msgs obj.Shape.check(True) # 返回错误信息列表 print(f{obj.Label}: valid{ok}, issues{len(msgs)}) except Part.OCCError as e: print(f{obj.Label}: 检查失败 - {e})核心 API 是Shape.isValid()与Shape.check()注意check(True)的第二参数是 verbose 开关返回的字符串列表可以直接进报告。几何内核实现可参考 src/Mod/Part/App/。用脚本批量导出 STL 并生成 CSV BOM需要一键交付制造时导出和 BOM 可以合并成一次遍历。import FreeCAD as App import Mesh import csv doc App.ActiveDocument rows [] for obj in doc.Objects: if not hasattr(obj, Shape) or not obj.Shape.Solids: continue # 逐件导出 STL文件名用对象名 Mesh.export([obj], fout/{obj.Name}.stl) # 按钢材密度 7.85 g/cm³ 估算质量 rows.append({名称: obj.Label, 体积_mm3: round(obj.Shape.Volume, 1), 质量_g: round(obj.Shape.Volume * 0.00785, 2)}) with open(BOM.csv, w, newline, encodingutf-8-sig) as f: w csv.DictWriter(f, fieldnames[名称, 体积_mm3, 质量_g]) w.writeheader() w.writerows(rows)核心 API 是Mesh.export注意 BOM 写出时用utf-8-sig编码否则 Excel 打开中文列名会乱码。综合实战一条脚本串起完整流程前面三类脚本组合起来就是建体 → 参数化 → 出图 → 体检 → 导出的流水线。下面把它压成一个函数参数全部抽到顶部import FreeCAD as App import Part import Mesh import csv def build_and_ship(spec_file, out_dirout): spec_file: 列 名称,类型,尺寸1,尺寸2,尺寸的 CSV doc App.newDocument(流水线) with open(spec_file, encodingutf-8) as f: for row in csv.DictReader(f): if row[类型] box: shape Part.makeBox(float(row[尺寸1]), float(row[尺寸2]), 10) else: shape Part.makeCylinder(float(row[尺寸1]), float(row[尺寸2])) feat doc.addObject(Part::Feature, row[名称]) feat.Shape shape doc.recompute() # 体检 导出 BOM复用阶段三的写法 for obj in doc.Objects: print(obj.Name, obj.Shape.isValid()) Mesh.export([obj], f{out_dir}/{obj.Name}.stl) # 调用一行命令完成全部产物 build_and_ship(parts.csv)核心思路是文档即数据所有输入收敛到一个 CSV脚本不写死任何零件名换规格表就能换产品。常见坑与排错速查现象原因处理3D 视图看不到脚本建的物体makeBox等返回的是Shape未挂进文档再执行addObject并赋值.Shapedoc.recompute()后草图位置错乱草图没绑Support/MapMode检查sk.Support与sk.MapModeTechDraw 标注的边号对不上投影方向改变导致边重编号固定Direction标注前打印边号确认数组number改了没反应改了源对象却没重算末尾补doc.recompute()BOM 在 Excel 里中文乱码默认 UTF-8 无 BOM改用utf-8-sig写出控制台脚本报App.Gui is None无头模式运行了 GUI API出图类命令runCommand只在有界面时执行一个通用排错动作报错时先打印doc.Name和各对象obj.State多数莫名失效是上游对象计算失败、下游连坐。延伸资源官方文档源码在 src/Doc/sphinx/其中 Scripting 章节与本文 API 一一对应。想读实现时按模块找基础几何看 src/Mod/Part/App/参数化看 src/Mod/PartDesign/出图看 src/Mod/TechDraw/二维工具与阵列看 src/Mod/Draft/draftmake/。Python 侧绑定入口在 src/App/Document.pyi 与 src/Gui/ 的*.pyi文件类型标注齐全编辑器会自动补全。社区脚本可参考仓库内测试用例 src/Mod/Draft/TestDraft.py 与 src/Mod/TechDraw/TestTechDrawApp.py它们是最贴近真实 API 用法的活教材。三条起步建议从批量导出 STL这类 10 行以内的小脚本写起先跑通addObject → recompute → export闭环。把尺寸参数全部外置成 CSV 或文档属性脚本只负责翻译改模型时不动代码。每个功能先读一遍对应测试文件再动手能避开 80% 的参数坑。【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考