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 エクスポート（ウェブ / 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 — エクスポート前にデシメートする（ファイルが大きすぎる場合）

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' を設定します。
• アニメーションで 1 つのアクションしか再生されない → 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 — すべてのアセットを含む ZIP 圧縮 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。

プラットフォームごとのポリゴン数の目標

プラットフォーム	目標	備考
ウェブ（glTF）	≤ 30 000 tris	モバイルでも安全
ウェブの主要アセット	≤ 60 000 tris	デスクトップなら問題なし
Unity / Unreal の主要アセット	50 000–100 000 tris	ハイエンド
モバイルゲーム	≤ 10 000 tris	アセットごと
AR USDZ	≤ 50 000 tris	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 を読み込むタイミング

以下の場合に読み込みます：

• 複数形式での一括エクスポートが必要な場合
• アセットブラウザー / ライブラリオーバーライドのワークフロー
• Apple AR 固有の USDZ 設定
• ゲームエンジンとの往復に関するトラブルシューティング（Unity / Unreal 固有の問題）
• LOD の生成方法

リファレンスの内容：形式ごとの落とし穴、アセットブラウザーのワークフロー、本番環境向けのライブラリオーバーライド、USD のコンポジション、プラットフォームごとのポリゴン数の目標。