blender-texture-baking

テクスチャベイク（Cycles）

実行モデルは blender-core にあります。UV は blender-retopology-uv、マテリアルは blender-pbr-materials から取得します。

1 回の呼び出し

scripts/bake_maps.py -- --low SM_Crate --high Crate_high Crate_bolts --maps normal ao curvature id \
   --res 2048 --samples 64 --margin-px 16 --pack-orm --out //textures

セルフベイク（プロシージャル → テクスチャ、--high なし）：--low SM_Crate --maps basecolor roughness metallic normal --pack-orm。 スクリプトは GPU（OptiX/CUDA/HIP/Metal/oneAPI）を選択し、使用できない場合は CPU にフォールバックします。適切なカラー空間でターゲット画像を作成し、一時ノードをクリーンアップして、T_<name>_<N|AO|CURV|BC|R|M|ORM...>.png を保存します。

準備チェックリスト（ベイクの不具合の多くは以下が原因です）

1. ローポリ：UV を展開し、重なりがないこと（スタック／ミラーされたアイランドは U 方向に +1 移動）、ベイク解像度でパディングを 8 px 以上にし、スケールを適用します。
2. ハードエッジ = ローポリの UV シーム。ベイク時にグラデーションを処理するスムーズシェーディングを使うか、シームで分割されたハードエッジを使います。UV アイランド内にハードエッジを置かないでください。
3. ローポリをエンジンと同じ方法で三角形分割するか、三角形分割したメッシュをエクスポートします。三角形分割の不一致はシェーディングのシームとして現れます。
4. ハイポリはローポリ全体を覆い、ローポリからわずかにはみ出す程度にします。浮遊パーツ（ボルト、パネルのディテール）は表面のすぐ上に配置できますが、押し出し距離の範囲内に収める必要があります。
5. 名前：X_low / X_high のペアにします。パーツごとにベイクするか、隣接パーツ同士が互いに投影されないように各ペアを軸に沿って移動して分離し、その後元に戻します。
6. 必要に応じてハイポリにモディファイアーを適用します（マルチレゾリューションとサブディビジョンは自動的に評価されます）。

レイ：押し出しとケージ

• --extrusion（メートル）は、ローポリの表面からレイの原点を外側に押し出します。ハイポリがローポリからはみ出す最大距離より大きくする必要があります。デフォルトはローポリの対角線の 2% で、max_ray_distance は押し出し距離の 2 倍です。
• ケージ（--cage Crate_cage）：ローポリと同じトポロジーを持ち、膨張させたコピーです（Displace／「Push」）。均一な押し出しでうまくいかない場合（鋭い凹角、薄いパーツ）に使用します。レイが外れる箇所は、ケージを局所的に編集します。
• 小さすぎる場合：穴やディテールの欠落が生じます。大きすぎる場合：メッシュの別のパーツが投影されます（交差、「ゴースティング」）。

マップガイド

マップ	空間	備考
normal	Non-Color、タンジェント、OpenGL（Unreal 用には --directx）	16 サンプルの AA で十分です。ゲームでは 8-bit PNG で問題ありません
ao	Non-Color	64～256 サンプル。接触 AO が必要な場合を除き、ハイポリのみでベイクします（地面なし）
curvature	Non-Color、0.5 = 平坦	ベイク済み法線から派生します（凸面は白／凹面は暗）。エッジ摩耗の制御に使います
id	sRGB	ハイポリのマテリアルごとに単色を割り当てます。マスクとしてマテリアルを使います
thickness	Non-Color	内向きのレイを使う AO です。暗いほど薄く、SSS／透過マスクに使います
basecolor/metallic/opacity	emission オーバーライド経由	ソースマテリアルの Principled 入力を読み取ります（プロシージャルチェーンも対象）
roughness, emit, combined	Cycles のネイティブパス	combined = ライティング済みの結果（ライトマップ、スタイライズド表現）
position	float	グラデーションマスク

ORM = R：AO、G：Roughness、B：Metallic。glTF/Unreal の標準です。Unity では異なるパッキング方式を使います（blender-pbr-materials）。

よくあるアーティファクトの修正

症状	原因	修正方法
円柱に波状の線が出る	ローポリのポリゴン数が少なすぎる、スムージングのグラデーション	セグメントを追加する、ケージを使う、またはローポリにサポートを追加する
ディテールが歪む（ボルトが傾く）	レイの方向が平均化されたローポリの法線に沿っている	ハードエッジとシームを設定する、ケージを使う、またはフローターを個別にベイクする
黒い領域／乱れた領域	レイが外れる、または裏面に当たっている	押し出し量を増やす、反転した法線を修正する（blender-asset-qa）、ハイポリのカバー範囲を確認する
エンジンでシームが見える	マージンが小さすぎる、ハードエッジにシームがない、タンジェントが異なる	2kでマージンを16 px以上にする、ハードエッジにシームを設定する、タンジェント（MikkTSpace）をエクスポートする
隣接パーツのディテールが混入する	パーツ同士が近すぎる	ベイク時にパーツを分離する、またはオブジェクトペアごとにベイクする
エンジンで緑チャンネルが反転して見える	OpenGL／DirectXの不一致	Unrealでは--directxを使う、またはテクスチャインポーターでGを反転する
階段状のノイズ／バンディング	大きく平坦なグラデーションを8-bitで扱っている	16-bit（float_buffer）でベイクし、エクスポート時にディザリングする

非PBRデータのベイク

• 頂点カラー：アクティブなカラー属性を設定してbake.target = "VERTEX_COLORS"を指定します（モバイルやRobloxを使わないシェーディングに便利です）。
• ライトマップ：シーンのライトを使って、UV2にcombinedをベイクします（--uv-layer UVMap_Lightmap）。
• マルチレゾ（別個のハイオブジェクトがない場合）：bake.use_multires=True、bake.type="NORMALS"|"DISPLACEMENT"|"VECTOR_DISPLACEMENT"、bake.use_lores_mesh=Trueを設定し、その後bpy.ops.object.bake_image()を実行します。ビューポートレベルがローポリ、スカルプトレベルがハイポリになります。

注意点

• ターゲット画像は、ローポリオブジェクトのすべてのマテリアルで、アクティブな Image Texture ノードである必要があります（スクリプトが処理します）。
• Cyclesでのベイクでは、アクティブなUVマップが使われます（選択するには--uv-layerを指定します）。
• 画像は自動保存されません：img.save()またはsave_renderを使ってください。パックされた画像や内部画像は、再読み込み時に消失します。
• 5.2：Cyclesのテクスチャキャッシュ（.tx）はレンダリングメモリ用で、ベイク結果には影響しません。
• 反転した法線や浮いたチャンクがベイクの乱れの主な原因となるため、まずローポリとハイポリに対してblender-asset-qaを実行してください。