blender-export

Blender 导出

使用正确的格式和设置进行导出。格式选错，就可能在目标平台上花数天调试。

格式决策树

Where is this going?
├── Web (Three.js, Babylon.js, model-viewer, AR Quick Look) → glTF / GLB
├── Game engine (Unity, Unreal, Godot)
│   ├── Animated/rigged → FBX (or glTF for modern engines)
│   └── Static → OBJ or FBX or glTF
├── Apple AR (USDZ) → USDZ (special, see Recipe 6)
├── 3D printing → STL (geometry only, must be watertight)
├── VFX pipeline (Maya, Houdini, Nuke) → USD
└── DCC roundtrip → FBX (industry standard)

目标平台未知时的快速规则：使用 glTF / GLB。它是开放标准、现代且获得普遍支持。

操作指南

指南 1 — 导出 glTF / GLB（Web / AR / 通用）

import bpy

bpy.ops.export_scene.gltf(
    filepath='/tmp/output.glb',
    export_format='GLB',                 # single-file binary; preferred
    export_apply=True,                   # apply modifiers before export
    export_materials='EXPORT',
    export_image_format='AUTO',          # PNG; AUTO falls back to JPEG for opaque images
    export_yup=True,                     # Y-up convention (most engines / web expect this)
    export_animations=True,              # toggle off for static models
    export_morph=True,                   # shape keys
    export_skins=True,                   # armatures + weights
    export_normals=True,
    export_tangents=False,               # skip unless target uses tangent-space normals beyond standard
)

# Verify
import os
size_mb = os.path.getsize('/tmp/output.glb') / (1024 * 1024)
print(f"export:gltf {size_mb:.2f} MB")

glTF 注意事项：

• 只有 Principled BSDF 材质能顺利导出。程序化着色器会被丢弃或简化。
• 严格上限：15 MB；建议目标：8 MB。
• 不使用 KTX2 / Draco 压缩（除非目标平台支持相应加载器）。
• 仅支持 PNG 纹理（典型上限为 1024×1024）。

指南 2 — 导出前进行 Decimate（文件过大时）

import bpy

obj = bpy.data.objects['GEO-target']
bpy.context.view_layer.objects.active = obj

mod = obj.modifiers.new('Decimate', type='DECIMATE')
mod.ratio = 0.7    # keep 70% of faces; lower = more reduction
mod.use_collapse_degenerate = True
bpy.ops.object.modifier_apply(modifier=mod.name)

print(f"decimated:{obj.name} verts:{len(obj.data.vertices)}")

然后重新导出。逐步调整比例，直到文件大小符合目标要求。

指南 3 — 导出 FBX（游戏引擎）

import bpy

bpy.ops.export_scene.fbx(
    filepath='/tmp/output.fbx',
    use_selection=False,
    apply_unit_scale=True,
    apply_scale_options='FBX_SCALE_ALL',
    bake_space_transform=True,        # critical: applies rotation to mesh
    object_types={'MESH', 'ARMATURE', 'EMPTY'},
    use_mesh_modifiers=True,
    mesh_smooth_type='FACE',
    use_armature_deform_only=True,
    bake_anim=True,
    bake_anim_use_all_bones=True,
    bake_anim_use_nla_strips=True,
    bake_anim_use_all_actions=True,
    bake_anim_force_startend_keying=True,
    embed_textures=True,              # critical: embed textures into FBX
    path_mode='COPY',
    axis_forward='-Z',
    axis_up='Y',
)
print('export:fbx')

FBX 常见问题：

• 模型在目标平台中旋转了 90° → 检查 axis_up='Y', axis_forward='-Z'
• 模型尺寸放大了 100 倍 → 导出前对物体应用变换
• 纹理缺失 → 使用 embed_textures=True, path_mode='COPY'
• 动画只播放一个动作 → 使用 NLA，并烘焙所有动作

指南 4 — 导出 OBJ（简单 / 通用）

import bpy

bpy.ops.wm.obj_export(
    filepath='/tmp/output.obj',
    export_animation=False,
    apply_modifiers=True,
    export_eval_mode='DAG_EVAL_VIEWPORT',
    export_uv=True,
    export_normals=True,
    export_materials=True,
    export_triangulated_mesh=False,
    forward_axis='NEGATIVE_Z',
    up_axis='Y',
)
print('export:obj')

OBJ 不支持动画和绑定，材质支持也很基础。适用于简单的几何体交换。

指南 5 — 导出 STL（3D 打印）

import bpy

bpy.ops.wm.stl_export(
    filepath='/tmp/output.stl',
    ascii_format=False,    # binary STL (smaller, faster)
    apply_modifiers=True,
)
print('export:stl')

STL 的关键要求：

• 网格必须水密（没有孔洞、法线翻转或内部面）。
• 导出前：在编辑模式下，运行 Mesh → Clean Up → Make Manifold。
• STL 不包含单位——大多数切片软件默认使用 mm。建模前将 Blender 场景单位设为 mm。
• STL 不包含颜色或材质——只能使用单色灰色。

指南 6 — 导出 USD（VFX 工作流）

import bpy

bpy.ops.wm.usd_export(
    filepath='/tmp/scene.usdc',
    export_animation=True,
    export_uvmaps=True,
    export_normals=True,
    export_materials=True,
    use_instancing=True,
    export_textures=True,
    overwrite_textures=True,
)
print('export:usd')

USD 变体：

• .usd — 基于文本（便于调试，文件较大）
• .usdc — 二进制（紧凑、快速——默认选择）
• .usda — ASCII（便于阅读，文件较大）
• .usdz — 包含所有资源的压缩 USD（Apple AR / iOS）

指南 7 — 导出前检查清单（每次导出前运行）

import bpy

# 1. Apply transforms (rotation + scale baked into geometry)
obj = bpy.data.objects['GEO-target']
bpy.context.view_layer.objects.active = obj
bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)

# 2. Recompute normals
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.normals_make_consistent(inside=False)
bpy.ops.mesh.remove_doubles(threshold=0.0001)
bpy.ops.object.mode_set(mode='OBJECT')

# 3. Apply modifiers (some exporters keep them, but for portability apply before export)
# Already done via export_apply=True / use_mesh_modifiers=True flags

# 4. Verify mesh stats
mesh = obj.data
print(f"export_check:{obj.name} verts:{len(mesh.vertices)} faces:{len(mesh.polygons)}")

指南 8 — 验证导出的文件

import os

filepath = '/tmp/output.glb'
if not os.path.exists(filepath):
    print(f"ERROR:not_found {filepath}")
else:
    size_mb = os.path.getsize(filepath) / (1024 * 1024)
    print(f"verified:{filepath} {size_mb:.2f}MB")

导出后务必进行验证。使用 Bash 工具：ls -la /tmp/output.glb。

各平台的多边形数量目标

平台	目标	备注
Web（glTF）	≤ 30 000 个三角面	适用于移动设备
Web 主视觉资源	≤ 60 000 个三角面	桌面端可用
Unity / Unreal 主视觉资源	50 000–100 000 个三角面	高端设备
移动游戏	≤ 10 000 个三角面	每个资源
AR USDZ	≤ 50 000 个三角面	iOS 建议值
3D 打印	不限	但导出文件大小仍很重要

常见问题

现象	解决方法
FBX 没有纹理	设置 embed_textures=True, path_mode='COPY'
glTF 中缺少程序化材质	先烘焙为图像纹理；只使用 Principled BSDF
游戏引擎中模型旋转了 90°	FBX：axis_up='Y', axis_forward='-Z'；glTF：export_yup=True
游戏引擎中模型尺寸放大了 100 倍	应用变换；检查单位比例
OBJ 无法在其他软件中导入	使用 ASCII 文件名
STL 无法打印	执行 Make Manifold；重新计算法线
GLB 大于 15 MB	应用 Decimate（指南 2）；将纹理缩小到 1024×1024
骨骼数量超出限制	将每个顶点的权重限制为 4 个；减少骨骼数量
动画未导出	glTF：export_animations=True；FBX：bake_anim=True

何时加载 references/overview.md

在以下情况加载：

• 需要批量导出多种格式
• 使用 Asset Browser / 库覆盖工作流
• 需要了解 Apple AR 的 USDZ 特定事项
• 排查游戏引擎往返流程问题（Unity / Unreal 特定问题）
• 制定 LOD 生成策略

参考文档涵盖：各格式的常见问题、Asset Browser 工作流、生产环境中的库覆盖、USD 合成，以及各平台的多边形数量目标。