Blender3mfFormat 版本演进全解:从最小可用导入到 3MF 核心规范完整实现的架构变迁
Blender3mfFormat 版本演进全解:从最小可用导入到 3MF 核心规范完整实现的架构变迁
3MF(3D Manufacturing Format)是为 3D 打印场景设计的三角网格交换格式,它不仅能传递模型几何,还能携带材质、打印意图等元信息。Blender3mfFormat 是一个将 Blender 接入 3MF 生态的 Blender 插件(Blender add-on),本篇文章以仓库中的 CHANGES.md 变更记录为主线,结合 io_mesh_3mf 源码与 test 测试体系,逐版本拆解它从"只求能导入几何"的 MVP,到完整实现 3MF Core Specification 1.2.3 的演进路径。读完本文,你将掌握该插件的导入/导出架构、材质与元数据保留机制、单位换算原理、容错设计取舍,以及 1.0.x 各版本修复的关键缺陷。
一、版本脉络总览:五个版本承载的三大阶段
CHANGES.md 完整记录了该插件从 0.1.0 到 1.0.2 的五个版本,按功能目标可划分为三个阶段:
| 版本 | 代号 | 阶段目标 | 核心能力 |
|---|---|---|---|
| 0.1.0 | Come On In | 最小可用产品 | 可靠地导入 3MF 几何数据 |
| 0.2.0 | Get Out | 预发布 | 从 Blender 导出 3MF 文件 |
| 1.0.0 | Big Bang | 首个稳定版 | 完整实现 3MF 核心规范 |
| 1.0.1 | Bug Fixes | 缺陷修复 | 修复导出材质资源 ID 类型 |
| 1.0.2 | Bug Fixes | 兼容与测试 | 支持 Blender 4.0,测试迁移至 Python 3.10 |
从版本代号也能看出项目的推进节奏:Come On In(导入方向打通)→ Get Out(导出方向打通)→ Big Bang(一次性的完整规范实现)。1.0.0 之所以被称为"Big Bang",是因为它在一次发布中同时补全了材质、元数据、关系(Relationships)、内容类型(Content Types)、模型类型、压缩打包等十余项能力,之后 1.0.1 与 1.0.2 仅做收敛性修复。
当前仓库的插件清单信息位于 io_mesh_3mf/init.py,其 bl_info 中的版本号 (1, 0, 2)、最低 Blender 版本 (2, 80, 0) 与变更记录完全吻合,register()/unregister() 则负责把导入、导出算子挂载到 File > Import 与 File > Export 菜单(bpy.types.TOPBAR_MT_file_import / TOPBAR_MT_file_export)。
二、0.1.0「Come On In」:先把几何数据可靠地搬进来
0.1.0 的目标非常朴素:可靠地导入至少几何数据。这一阶段奠定的导入管线在后续版本中被完整继承,其主流程集中在 io_mesh_3mf/import_3mf.py。
2.1 从 ZIP 档案到模型 XML
3MF 文件本质上是 ZIP 压缩包,内部按 OPC(Open Packaging Conventions)约定组织:3D/3dmodel.model 存放模型 XML,<a href="https://link.gitcode.com/i/a166c614b5c57d9b1d10f8b10cab8578" target="_blank">Content_Types].xml 声明各文件的 MIME 类型,_rels/ 目录存放关系文件。这些约定被固化在 [io_mesh_3mf/constants.py 中,例如:
MODEL_LOCATION = "3D/3dmodel.model"—— 模型的约定存放位置;CONTENT_TYPES_LOCATION = "[Content_Types].xml";MODEL_NAMESPACE = "http://schemas.microsoft.com/3dmanufacturing/core/2015/02";MODEL_DEFAULT_UNIT = "millimeter"—— 当 model 根节点缺失unit属性时默认毫米。
导入流程(Import3MF.execute,见 io_mesh_3mf/import_3mf.py)依次完成:读取归档并按内容类型归类文件(read_archive)→ 解析模型 XML → 换算单位(unit_scale)→ 读取元数据、材质、对象资源(read_materials / read_objects)→ 依据 <build> 中的 <item> 构建场景(build_items)。
2.2 对象资源、顶点、三角形、组件与构建项
0.1.0 声称支持的"对象资源、顶点、三角形、组件、构建项、变换"正是 3MF 资源/构建(resources/build)数据模型的六要素。从源码结构看,导入器用命名元组把这些要素组织为内存模型(io_mesh_3mf/import_3mf.py):
ResourceObject = collections.namedtuple("ResourceObject", [
"vertices", "triangles", "materials", "components", "metadata"])
Component = collections.namedtuple("Component", ["resource_object", "transformation"])
ResourceMaterial = collections.namedtuple("ResourceMaterial", ["name", "color"])
read_vertices(import_3mf.py)逐 <vertex> 读取 x/y/z;read_triangles(import_3mf.py)读取 v1/v2/v3 顶点索引,并对"负索引""缺失顶点""非整数索引"等损坏情况做容错处理——这一容错姿态从 0.1.0 延续至今;read_components(import_3mf.py)把 <component> 连同其 transform 解析为 Component。最终 build_object(import_3mf.py)递归地把资源对象转换为 Blender 的 mesh 与 object,并借助 objectid_stack_trace 防止组件互相引用造成的死循环。
2.3 单位换算:从 3MF 单位到 Blender 单位
3MF 的坐标单位在 <model> 根节点的 unit 属性中声明,而 Blender 场景有自己独立的单位设置。unit_scale(import_3mf.py)的换算公式为:
scale = global_scale
scale /= scene.unit_settings.scale_length # 抵消 Blender 场景缩放
scale *= threemf_to_metre[threemf_unit] # 3MF 单位 → 米
scale /= blender_to_metre[blender_unit] # 米 → Blender 单位
两张单位换算表集中在 io_mesh_3mf/unit_conversions.py:3MF 侧支持 micron、millimeter、centimeter、inch、foot、meter;Blender 侧覆盖从 THOU、INCHES 到 ADAPTIVE、KILOMETERS 的完整单位集。test/import_3mf.py 中的 test_unit_scale_* 系列测试逐一验证了换算正确性(含 'ADAPTIVE': 1 的映射)。
三、0.2.0「Get Out」:导出管线落地与单位修正
0.2.0 的目标是"从 Blender 导出 3MF",对应 io_mesh_3mf/export_3mf.py 中的 Export3MF 算子(bl_idname = "export_mesh.threemf")。这一版本补全了导出侧的对称能力:导出菜单项、OPC 归档、对象资源、顶点、三角形、组件、构建项、变换、单位换算与缩放。
3.1 导出主流程与 Deflate 压缩
Export3MF.execute(export_3mf.py)是导出的高层编排:创建归档 → 写入材质资源 → 递归写入对象资源 → 组装 <build> → 关闭归档。归档由 create_archive(export_3mf.py)创建,压缩算法为 zipfile.ZIP_DEFLATED 且压缩级别取 9:
archive = zipfile.ZipFile(filepath, 'w', compression=zipfile.ZIP_DEFLATED, compresslevel=9)
这正是 CHANGES.md 1.0.0 中"导出的 3MF 归档使用 Deflate 算法压缩"的实现位置(0.2.0 阶段已具备雏形)。注意 create_archive 同时写入 _rels/.rels 与 [Content_Types].xml,所以即使一个空场景导出的归档也包含这两个 OPC 元文件——test/export_3mf.py::test_create_archive 断言归档中恰好只有这两个文件。
3.2 单位换算与"缩放"选项
导出侧的 unit_scale(export_3mf.py)与导入侧对称但方向相反:Blender 单位先换算成米、再换算成 3MF 默认单位(毫米),同时乘上 global_scale 与场景 scale_length。test/export_3mf.py 用一张"各 Blender 单位 → 毫米"的真值表(test_unit_scale_conversion,如 INCHES → 25.4、METERS → 1000)锁定了换算行为。
值得注意 0.2.0 唯一一条 Bug Fix:"单位现在在 3MF 文件自身变换之后应用,使模型落在正确位置"。这条修复直接决定了 build_items(import_3mf.py)与 write_objects(export_3mf.py)中"单位缩放矩阵与对象变换矩阵相乘"的顺序——transform @= self.parse_transformation(...),缩放必须后作用于变换结果,否则模型的摆放位置会整体偏移。
四、1.0.0「Big Bang」:完整核心规范与工程化改造
1.0.0 是分水岭:完整的 3MF Core Specification 1.2.3 核心实现(对应 README.md 中"支持完整核心规范 1.2.3"的声明),同时带来了一批面向真实生产环境的功能与修复。以下逐项结合源码展开。
4.1 材质:导入应用到三角形、导出携带漫反射色
- 导出:
write_materials(export_3mf.py)把场景中所有物体引用的材质汇总进一个<basematerials>资源组,每个材质写为<base name="..." displaycolor="#RRGGBB[AA]"/>。颜色取自材质的漫反射色,通过bpy_extras.node_shader_utils.PrincipledBSDFWrapper读取base_color与alpha,并转换到 sRGB 后格式化为十六进制;完全不透明的材质省略 alpha 通道。函数返回"材质名 → 组内索引"的映射,供对象与三角形回填pid/pindex/p1。 - 导入:
read_materials(import_3mf.py)解析<base>的displaycolor,把 6 位十六进制按 RGB、8 位按 RGBA 拆成 0~1 浮点;build_object中再用PrincipledBSDFWrapper把这些颜色写回 Blender 材质的base_color/alpha(import_3mf.py),并逐三角形分配material_index。 - 对应 1.0.1 的修复点:导出材质的资源 ID 必须为整数(见后文)。
4.2 元数据、关系、内容类型的无损保留
这一组特性是"编辑已有 3MF 文件不丢信息"的工程核心,实现集中在 io_mesh_3mf/annotations.py 与 io_mesh_3mf/metadata.py:
- 关系(Relationships):
Annotations.add_rels把.rels文件解析为Relationship(namespace, source)注解,write_rels在导出时按来源目录重新生成_rels/.rels,并跳过插件自己会重写的 3D 模型关系(MODEL_REL)。 - 内容类型(Content Types):
add_content_types/write_content_types实现"按扩展名取最常见 MIME 类型作为 Default 规则,个别例外写 Override"的紧凑策略;对已被插件重写的.rels/.model文件不存储。 - 元数据:
Metadata类(metadata.py)以字典式接口管理MetadataEntry(name, preserve, datatype, value),store/retrieve负责在 Blender 对象的属性中序列化/反序列化,使元数据能随.blend文件跨会话、跨机器保留。
值得注意的是冲突消解策略:CHANGES.md 明确"当多个 3MF 文件加载进同一场景、元数据/关系/内容类型冲突时,保留最简公约数(most common denominator)"。在 metadata.py 中体现为:同名条目若值与 datatype 不一致,则该条目被标记为冲突并从存储中"擦除"(self.metadata[key] = None)——宁可不导出,也不导出错误信息;annotations.py 中内容类型冲突则标记为 ConflictingContentType 哨兵对象,导出时跳过该文件。
4.3 MustPreserve 文件与 PrintTickets 保留
3MF 中有些文件(如打印票 PrintTickets、标记 MustPreserve 关系的文件)既不属于模型也不该被丢弃。导入侧的 must_preserve(import_3mf.py)识别 mustpreserve 关系、printticket 关系及 application/vnd.ms-printing.printticket+xml 内容类型,将文件以 Base85 编码存入 Blender 场景的隐藏文本对象(.3mf_preserved/ 前缀);导出侧的 must_preserve(export_3mf.py)再解码写回归档。若同名文件在不同档案中内容不一致,则写入 conflicting_mustpreserve_contents 标记并放弃保留,绝不偏向任意一方(constants.py)。Base85 编码使文件体积约增 25%,这是换取"任意二进制文件可存入 Blender 文本"的明确取舍。
4.4 模型类型 support / solidsupport / surface 与渲染隐藏
3D 打印场景中支撑(support)与支撑实体(solidsupport)通常不应出现在最终渲染/导出结果里。导入器把对象 type 属性存入 3mf:object_type 元数据(import_3mf.py),并在 build_object 中为 solidsupport/support 类型设置 blender_object.hide_render = True(import_3mf.py);导出侧则只在 type != "model" 时写回该属性,并刻意不写 other 类型(因为规范不允许引用它),相关行为由 test/export_3mf.py 的 test_write_objects_object_types 覆盖。
4.5 数值稳定性:紧凑变换、紧凑坐标、禁科学计数法、精度可配置
- 紧凑变换矩阵:
format_transformation(export_3mf.py)按 3MF 规范把 4×4 矩阵转置后取出前 3 列,以 12 个空格分隔的数值序列输出,且每个数值固定 6 位小数、绝不使用科学计数法;单位矩阵也会被省略不写(write_objects中mesh_transformation != Matrix.Identity(4)才写transform)。 - 紧凑顶点坐标:
write_vertices使用format_number(export_3mf.py),按用户设定的coordinate_precision位小数格式化并去掉尾部零。 - 精度可配置:导出算子的
coordinate_precision属性范围为 0~12、默认 4(export_3mf.py),精度越高文件越大;format_number的实现("{:.{d}f}".format(...).rstrip("0").rstrip("."),空串回退为"0")同时规避了大数/小数被写成3.14e-5之类科学计数法的问题——这正是 CHANGES.md 两条 Bug Fix 的落点,test_export_3mf.py::test_format_number有专项断言。
4.6 容错解析:与规范"快速失败"的有意背离
README.md 明确说明:3MF 规范要求消费方在遇到任何错误时"快速、灾难性地失败"(整个档案拒绝加载),而本插件采取相反的立场——小错误不阻断整体加载,跳过损坏的三角形、用 0 补位缺失的坐标、忽略畸形的关系条目,同时把警告写进 Blender 日志。这在源码中俯拾皆是:read_vertices 中坐标解析失败回退 0;read_triangles 中负索引、缺失顶点、非整数引用分别以 log.warning 记录后跳过;read_content_types 在 [Content_Types].xml 缺失或损坏时兜底追加 .rels/.model 的默认规则。
对应地,CHANGES.md 中的"Actions are being logged in Blender's log stream"与"errors and warnings are being logged"贯穿所有模块:导入完成打印 Imported {n} objects,导出完成打印 Exported {n} objects,异常路径(无文件读写权限等)以 log.error 记录并返回 {'CANCELLED'}。
4.7 打包与安装方式
1.0.0 支持 通过 .zip 安装:把整个 io_mesh_3mf 包打成 zip,在 Blender 的 Edit > Preferences > Add-ons 中 Install 即可(详见 README.md 的安装步骤)。模块顶部的 <pep8 compliant> 注释与 bl_info 声明(category 为 "Import-Export")保证了它符合 Blender 官方插件的规范要求——即 CHANGES.md 中"代码符合 Blender 代码风格要求"。
4.8 1.0.0 的 Bug Fix 清单解读
| 修复项 | 源码佐证 |
|---|---|
| 负顶点索引崩溃 | read_triangles 中 if v1 < 0 or v2 < 0 or v3 < 0: continue(import_3mf.py) |
| 连续导入旧文件资源泄漏 | execute 每次导入前重置 self.resource_objects/self.resource_materials(import_3mf.py) |
| 连续导出资源 ID 计数不复位 | execute 每次导出前重置 self.next_resource_id = 1(export_3mf.py) |
| 无读写权限崩溃 | create_archive/read_archive 捕获 EnvironmentError 并返回失败 |
| 带组件的资源对象错误写变换 | write_object_resource 用 mesh_transformation.inverted_safe() @ child_transformation 计算子组件相对变换 |
| 组件对象不得自带网格 | 有 child_objects 时新建独立 mesh 对象资源,原对象只保留组件 |
| 无顶点/面的对象不建网格 | 仅当 len(mesh.vertices) > 0 才写 <mesh> |
| 不使用科学计数法 | format_number / format_transformation 统一格式化 |
五、1.0.1:修复导出材质资源 ID 类型
1.0.1 只包含一条修复:导出材质的资源 ID 必须为整数。这条看似微小,但关系到 3MF 消费者对 pid 属性的解析严格性。在 export_3mf.py 中,basematerials 的资源 ID 由递增计数器 self.next_resource_id 生成并转为字符串写入 XML 属性,导入侧则用 int() 解析并作为字典键索引 self.resource_materials(import_3mf.py)。保证生成侧是规范整数、解析侧不因类型不匹配而触发 KeyError/ValueError 的容错路径,正是该版本的意义所在。从测试看,test/export_3mf.py 的 test_write_object_resource_id 与导入侧的 test_read_materials_* 系列对 ID 的类型与唯一性均有约束。
六、1.0.2:新版本 Blender 兼容与测试现代化
1.0.2 的两条变更分别对应:
- 支持至 Blender 4.0:从源码看,导入器对 Blender 3.2 前后两代
bpy.ops.view3d.view_selected调用方式(temp_override与旧式 override)都做了兼容分支(import_3mf.py),这是跨版本兼容的直接证据;bl_info中"blender": (2, 80, 0)意味着向下兼容 2.80 及以上。 - 测试改用 Python 3.10 运行:仓库测试完全基于标准库
unittest,运行方式见 test/init.py 的说明——在仓库根目录执行python3 -m unittest test即可。由于 Blender API 在纯 Python 环境下不可用,测试通过 test/init.py 将bpy、bpy.ops、bpy_extras等模块替换为unittest.mock.MagicMock(),并以 test/mock/bpy.py 中手写的MockOperator、MockImportHelper、MockExportHelper、MockPrincipledBSDFWrapper替代真实基类。MockPrincipledBSDFWrapper直接透传diffuse_color,从而把单元测试与 Blender 的颜色空间转换解耦。
测试体量本身也是工程化的体现:test/import_3mf.py(约 1755 行)、test/export_3mf.py(约 1005 行)、test/annotations.py、test/metadata.py 合计数千行,覆盖归档解析、内容类型优先级、单位换算真值表、材质写入、变换格式化、元数据冲突消解等关键路径——这正是 CHANGES.md 中"自动化测试提升插件稳定性"的落点。
七、从变更历史看架构与设计哲学
回看整份 CHANGES.md,可以提炼出该项目一以贯之的设计决策:
- 双向对称的管线:导入与导出围绕同一套 3MF 数据模型(resources + build)组织,单位换算表共用一份 unit_conversions.py,方向相反但公式互逆。
- 信息保留优先于信息丢弃:元数据、关系、内容类型、partnumber、MustPreserve、PrintTickets 全部被保留,即使跨
.blend共享场景也不例外;遇到冲突时取"最简公约数",不导出可能误导下游的错误值。 - 容错而非崩溃:主动偏离 3MF 规范"快速失败"的要求,最大化地从损坏文件中抢救可用数据,同时用日志记录问题。
- 数值输出可控:固定位数、无科学计数法、可配置精度的格式化策略,保证了输出文件的互操作性与体积可控。
对于想要基于该插件二次开发或研究 3MF 实现的读者,建议从 constants.py(格式常量)→ unit_conversions.py(单位换算)→ annotations.py(OPC 层注解)→ import_3mf.py 与 export_3mf.py(主流程)的顺序阅读,并以 python3 -m unittest test 跑通全部测试作为基线。CHANGES.md 既是版本历史,也是理解这套架构演进的最佳路线图。
