Blender3mfFormat 版本演进全解:从最小可用导入到 3MF 核心规范完整实现的架构变迁

原创2026-10-15 17:47:261,725 阅读
文章标签:3D建模桌面应用

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 各版本修复的关键缺陷。

Blender 中由 3MF 插件提供的 File 菜单导入/导出入口

一、版本脉络总览:五个版本承载的三大阶段

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,可以提炼出该项目一以贯之的设计决策:

  1. 双向对称的管线:导入与导出围绕同一套 3MF 数据模型(resources + build)组织,单位换算表共用一份 unit_conversions.py,方向相反但公式互逆。
  2. 信息保留优先于信息丢弃:元数据、关系、内容类型、partnumber、MustPreserve、PrintTickets 全部被保留,即使跨 .blend 共享场景也不例外;遇到冲突时取"最简公约数",不导出可能误导下游的错误值。
  3. 容错而非崩溃:主动偏离 3MF 规范"快速失败"的要求,最大化地从损坏文件中抢救可用数据,同时用日志记录问题。
  4. 数值输出可控:固定位数、无科学计数法、可配置精度的格式化策略,保证了输出文件的互操作性与体积可控。

对于想要基于该插件二次开发或研究 3MF 实现的读者,建议从 constants.py(格式常量)→ unit_conversions.py(单位换算)→ annotations.py(OPC 层注解)→ import_3mf.py 与 export_3mf.py(主流程)的顺序阅读,并以 python3 -m unittest test 跑通全部测试作为基线。CHANGES.md 既是版本历史,也是理解这套架构演进的最佳路线图。

登录后查看全文
Blender3mfFormat