Blender3mfFormat：在 Blender 中导入/导出 3MF 增材制造文件的完整指南

• 3D建模
• 桌面应用

3D Manufacturing Format（3MF，.3mf）是面向三角网格的文件格式，旨在作为 3D 打印应用的交换格式：它不仅能传达模型几何，还能从 CAD 软件向 CAM 软件（切片器）传达一次 3D 打印作业的意图与材料。Blender3mfFormat正是这样一个让 Blender 扮演 CAD 角色的官方风格插件（add-on），它在 Blender 的File > Import/Export菜单中提供"3D Manufacturing Format"入口，使 Blender 成为增材制造工作流中更可行的 CAD 备选方案。读完本文，你将掌握：如何从 GitHub Releases 打包 zip 并安装该插件；如何在 GUI 与 Python 脚本（bpy.ops.import_mesh.threemf/bpy.ops.export_mesh.threemf）两个层面使用全部导入/导出参数；以及插件在单位换算、材料、元数据、容错策略上与 3MF Core Specification 的异同。

一、插件定位：让 Blender 成为 3D 打印的 CAD 前端

3MF 文件格式由 3MF Consortium 维护，设计初衷是作为三角网格在 CAD 与 CAM（切片器）之间的交换格式。在一个典型工作流中，Blender 负责建模（扮演 CAD），切片器负责切片与打印准备（扮演 CAM）。插件的目的，就是让 Blender 在增材制造场景中成为一个更可靠的 CAD 软件，能够：

• 导入第三方 CAD 或建模软件产出的.3mf文件，把网格、组件、变换、材料与元数据还原进 Blender 场景；
• 导出当前场景为符合 3MF Core Specification 1.2.3 的.3mf文件，供切片器等下游软件消费。

从仓库结构看，插件的入口是 io_mesh_3mf/init.py：bl_info声明插件名为 "3MF format"、版本(1, 0, 2)、最低要求 Blender 2.80，并将两个算子类注册到 Blender 的文件导入/导出菜单（TOPBAR_MT_file_import与TOPBAR_MT_file_export）。菜单项文案正是 README 所描述的 "3D Manufacturing Format (.3mf)"，由 menu_import/menu_export 两个回调挂载。

版本与兼容性前提

• Blender 版本要求：需要 Blender 2.80 或更新版本。官方在 2.80、2.83、2.93、3.0、3.3 上测试过；CHANGES.md 记录 1.0.2 版本进一步修复了对更新 Blender（直至 4.0）的支持。
• 依赖：代码大量使用 Blender Python API（bpy、bpy.props、bpy_extras），并依赖mathutils（矩阵）、zipfile（读取/写入 3MF 容器）、xml.etree.ElementTree（解析/生成3dmodel.model）等标准库模块。你不需要额外安装第三方 Python 包。

二、安装：从 zip 到启用

由于插件尚未合并进 Blender 官方发行版（社区版候选状态），目前唯一的安装方式是通过.zip归档导入：

1. 从 releases 页面下载最新 release（一个 zip 归档，例如 1.0.2）；
2. 在 Blender 中打开Edit -> Preferences，切到左侧的Add-ons选项卡；
3. 点击顶部Install...按钮，定位到下载的 zip；
4. 在 "Community" 分类下找到名为 "Import-Export: 3MF format" 的插件并勾选启用。注意：若使用搜索框，不要输入 "Import-Export" 这几个字——那是分类名而非插件名，只搜 "3MF" 即可。

提示：bl_info中"category": "Import-Export"正是插件在偏好设置中归类的依据，因此搜索关键字 3MF 最稳妥。

安装成功后，File > Import菜单出现 "3D Manufacturing Format"，File > Export菜单出现同名入口（见init.py）。点击即可选择/保存 3MF 文件。该插件也支持以源码目录方式直接运行调试——__init__.py末尾的if __name__ == "__main__": register()允许不安装直接注册（面向开发者）。

三、导入 3MF：GUI 选项与脚本参数

GUI 导入选项

从File > Import > 3D Manufacturing Format导入 3MF 文件时，界面提供以下选项：

在 import_3mf.py 中，该选项由global_scale: bpy.props.FloatProperty定义，默认值1.0，soft_min=0.001、soft_max=1000.0，硬边界min=1e-6、max=1e6——即 GUI 滑块范围约 0.001～1000，但脚本层允许 1e-6～1e6 的极端值。

脚本导入：bpy.ops.import_mesh.threemf

bpy.ops.import_mesh.threemf(filepath="/path/to/file.3mf")

该导入算子的bl_idname = "import_mesh.threemf"（见 import_3mf.py），支持两个相关参数：

• filepath：要导入的 3MF 文件路径。
• global_scale（默认1）：导入后应用于场景的缩放因子。所有从 3MF 文件加载的网格数据都以坐标系原点为基准按该因子缩放。

底层导入流程（源码级）

导入执行由 Import3MF.execute 驱动，大致链路如下：

1. 解包归档：read_archive用zipfile.ZipFile打开.3mf（本质是 zip），按 MIME 类型归类内部文件；read_content_types解析[Content_Types].xml的Default/Override规则，即使该文件缺失或损坏，也会兜底补上.rels与.model的默认类型（有对应测试test_read_content_types_missing/test_read_content_types_invalid_xml）。
2. 处理标注（annotations）：读取.rels关系文件与内容类型，识别MustPreserve与PrintTicket关联，将此类文件以 Base85 编码存进 Blender 隐藏文本块（.3mf_preserved/前缀）以便回写（must_preserve）。
3. 解析模型：用 ElementTree 解析3dmodel.model，依次读取元数据（read_metadata）、基础材料（read_materials，解析displaycolor的 RGB/RGBA 十六进制色）、对象资源（read_objects，含顶点、三角形、组件、partnumber 与 object_type 元数据）。
4. 单位换算：unit_scale结合 3MF 文件的unit属性、Blender 场景的单位与scale_length，通过 unit_conversions.py 中threemf_to_metre与blender_to_metre两张换算表折算缩放因子。3MF 支持micron / millimeter / centimeter / inch / foot / meter，Blender 侧支持从 THOU 到 KILOMETERS 共 15 种长度单位（含 ADAPTIVE）。
5. 构建场景：build_items遍历<build>下的<item>，build_object递归创建 Blender 网格与对象：顶点通过mesh.from_pydata写入，三角形逐面指定材质，材料通过PrincipledBSDFWrapper生成带基础色与 alpha 的节点材质；solidsupport/support类型对象会被设为hide_render = True（不参与渲染）；组件递归带"栈追踪"防止循环引用死循环（build_object）。
6. 收尾：合并后的场景元数据写回bpy.context.scene，并尝试在 3D 视图中框选刚导入的对象。

容错导入策略

3MF 规范要求消费者（导入方）在任何字段出错时快速、彻底地失败（整个归档都不加载）。本插件刻意采用相反策略：小错误不阻塞整体加载——某个三角形坏了就跳过该三角形，其余照常导入，同时向 Blender 日志写入警告。这一点贯穿各解析函数：顶点缺坐标补 0（read_vertices）、三角形负索引或非整数引用被丢弃（read_triangles）、畸形变换矩阵逐分量容错（parse_transformation）、坏基元材料降级为默认材料等。从源码注释与test/import_3mf.py中大量"鲁棒性"用例（如test_read_vertices_broken_coordinates）可确认这一设计意图。

四、导出 3MF：GUI 选项与脚本参数

GUI 导出选项

从File > Export > 3D Manufacturing Format导出时，界面提供四个选项：

在 export_3mf.py 中对应四个bpy.props属性：use_selection（默认False）、global_scale（默认1.0，范围同导入）、use_mesh_modifiers（默认True）、coordinate_precision（默认4，范围min=0、max=12）。

脚本导出：bpy.ops.export_mesh.threemf

bpy.ops.export_mesh.threemf(filepath="/path/to/file.3mf")

导出算子bl_idname = "export_mesh.threemf"（export_3mf.py），共五个相关参数：

• filepath：3MF 文件的存储位置。
• use_selection（默认False）：仅导出选中对象，其余对象不写入文件。
• global_scale（默认1）：应用于 3MF 文件中模型的缩放因子，以坐标原点为基准。
• use_mesh_modifiers（默认True）：导出前应用修改器，将其永久嵌入文件；关闭则保存未修改的网格。
• coordinate_precision（默认4）：文件中坐标使用的小数位数，越大文件越大。

底层导出流程（源码级）

Export3MF.execute 的要点：

1. 创建 zip 归档：create_archive以ZIP_DEFLATED、compresslevel=9创建归档（Deflate 压缩），并把此前从导入文件保留下的关系文件与[Content_Types].xml注解写回，再恢复MustPreserve/PrintTicket文件（must_preserve）。
2. 单位换算：unit_scale把 Blender 场景单位折算为 3MF 默认单位毫米（MODEL_DEFAULT_UNIT = "millimeter"），并乘上 Blender 场景的scale_length与用户global_scale。
3. 写材料：write_materials把各对象材质槽中的 Principled BSDF 基础色换算回 sRGB 并格式化为#RRGGBB（alpha 为 1 时省略）或#RRGGBBAA，统一写进一个<basematerials>资源组，返回"材质名 → 组内索引"映射（测试test_write_material_color覆盖了舍入与裁剪行为）。
4. 写对象：write_objects只遍历无父对象的 MESH/EMPTY 对象（子对象递归处理），为每个生成<object>资源并挂到<build>的<item>；write_object_resource处理组件层级：既有子组件又有网格的对象会被拆成两个资源，网格作为组件挂在父对象下；若启用修改器，通过evaluated_depsgraph_get()取评估后的网格。
5. 三角化与写网格：mesh.calc_loop_triangles()把所有面转为三角形（3MF 只支持三角形面）；write_vertices用coordinate_precision控制小数位，format_number保证绝不使用科学计数法并去掉尾随零；write_triangles以"出现最多的材质"作为对象级pid/pindex默认值，仅对偏离默认材质的三角形写p1覆盖属性，从而压缩文件体积。
6. 元数据：对象的Title、自定义属性以及3mf:partnumber、3mf:object_type等元数据会写入对应的<metadata>/<metadatagroup>；object_type为 "model"（默认）时不写出，为 "other" 时按普通 model 处理。

导出循环与资源 ID

从test/export_3mf.py的test_write_object_resource_id可见，资源 ID 从 1 开始递增（next_resource_id），每次导出重置计数，确保同一导出会话内 ID 唯一且为正整数；多次连续导出互不污染（CHANGES.md 1.0.0 修复记录印证）。

五、与 3MF 规范的兼容性：支持范围与刻意偏离

该插件当前支持完整的3MF Core Specification 1.2.3，并在设计上刻意偏离规范三处：

1. 容错导入（不快速失败）：规范要求消费者遇到任何错误都必须快速、灾难性失败；插件相反——小错误只丢弃受影响的最小单元（如单个三角形），其余继续加载，并向 Blender 日志输出警告（见上文第三节）。

2. 多文件合并语义：规范未设计同时加载多个 3MF 文件或把文件并入已有场景。插件会尽量加载，但若文件各部分冲突，则冲突部分"两边都不加载"。典型例子是场景元数据（如场景标题）：两个文件标题相同时保留该标题；多个文件标题互不相同，则标题不加载。从 metadata.py 的Metadata类实现可见其机制——同名条目若值或数据类型不一致，条目会被标记为冲突并整体剔除，保证只保留"一致的那部分"。

3. 3MF 扩展：目前不支持任何 3MF 格式扩展（extension），这是未来开发目标。constants.py中SUPPORTED_EXTENSIONS = set()为空集即佐证；若文档requiredextensions声明了不认识的命名空间，导入时会记录警告3MF document in ... requires unknown extensions.，但仍尽量解析已知内容（is_supported判定）。

材料颜色往返与保留性（1.0.0 之后的能力）

自 1.0.0 起，插件支持导入基础材料并应用到三角形面、从 Blender 导出带漫反射色的材料；材料颜色在 Blender 中以 BSDF 节点渲染，导出时转回 sRGB（write_materials）。此外，编辑既有 3MF 文件时，以下内容会被保留：元数据、关系文件（.rels）、内容类型、3MF partnumber、MustPreserve标记的文件、PrintTicket，以及对象名称（作为元数据存储）。多文件加载时若元数据、关系、内容类型冲突，取"最大公约数"（最常见的一致项）。

六、运行测试与开发者视角

仓库附带一套可脱离 Blender 运行的单元测试（通过 mock 掉bpy等 API），覆盖导入/导出各解析与写入函数、元数据合并冲突语义、注解（relationships/content types）序列化等。运行方式（见 CONTRIBUTING.md 与 test/init.py）：

python3 -m unittest test

从源码结构看，test/mock/bpy.py提供MockOperator、MockImportHelper、MockExportHelper、MockPrincipledBSDFWrapper等基础替身；test/resources/下有corrupt_archive.3mf、empty_archive.zip、only_3dmodel_file.3mf等固定夹具，用于验证损坏归档、空归档与默认位置模型文件的读取行为。CHANGES.md 1.0.0 还提到测试基于 Python 3.10 运行（1.0.2 起）。

七、使用建议与已知边界

• 精度与体积权衡：coordinate_precision默认 4 位小数对多数打印模型足够；需要更高精度可调大（最多 12 位），但文件会显著变大，因为每个顶点坐标都要写更多字符。
• 修改器烘焙：若导出时启用 Apply Modifiers，修改器效果被永久烘焙进网格；这符合"导出即所见"的直觉，但也会丢失参数化编辑能力——建议保留.blend源文件。
• 单位一致性：导入时插件自动将 3MF 文件单位换算成 Blender 场景单位；导出时则统一折算为毫米。若你的场景使用米或英寸，注意Scale参数与场景scale_length会叠加影响最终结果。
• 多文件导入：适合把多个 3MF 拼进同一场景做对比或装配，但冲突元数据会被丢弃，且扩展文件（如纹理、打印票根之外的扩展特性）暂不支持。
• 故障排查：任何解析异常都会以 warning 写入 Blender 日志（log.warning），导入后先在系统控制台/日志窗口查看警告，判断是否有三角形或材质被降级/跳过。

结语

Blender3mfFormat 用"务实容错 + 完整核心规范 + 保留性优先"的设计，把 Blender 推进了增材制造工作流：既能可靠承接第三方 3MF 几何与材料，又能导出切片器可直接消费的毫米制归档。结合本文给出的 GUI 选项、bpy.ops.import_mesh.threemf/bpy.ops.export_mesh.threemf脚本接口与源码级实现链路，你可以把 3MF 双向交换稳定集成到自己的建模与打印管线中。更进一步，可深入阅读 io_mesh_3mf/import_3mf.py、io_mesh_3mf/export_3mf.py、io_mesh_3mf/constants.py、io_mesh_3mf/unit_conversions.py 以及对应测试，掌握每一处细节。

• 3D建模
• 桌面应用