blockbench-albedo-to-pbr

Blockbench 用のアルベドから法線および MER を生成

PBR チャンネルは描くのではなく、導出して作成します。アルベド → 高さフィールド → タンジェント空間法線の順に生成し、アルベド、高さ、法線の曲率からメタルネス、エミッシブ、ラフネスを推定して、1 枚の MER 画像にまとめます。2 つのスクリプトは同じ CLI と数式を共有しているため、実行環境に合わせて選んでください。検出と検証を行うには、先に blockbench-use を読み込み、生成した結果を割り当てるには blockbench-pbr-materials を読み込んでください。このスキルで生成するのは画像ファイルのみです。

実行環境	スクリプト	インストール	高さの推定
Python	scripts/albedo_to_normal.py	pip install pypbr（深度推定には transformers も必要）	transformers 経由の Depth Anything V2。利用可能な場合は CUDA を使用
Node.js	scripts/albedo_to_normal.mjs	npm install vgpu pngjs（深度推定には @huggingface/transformers も必要）	transformers.js 経由の Depth Anything V2 ONNX。CPU または WebGPU

どちらも <name>_height.png（グレースケール、明るいほど高い）、<name>_normal.png（RGB、不透明）、<name>_mer.png（R＝メタルネス、G＝エミッシブ、B＝ラフネス）を書き出し、JSON レポートを出力します。実行環境のセットアップ、API に関する注意事項、トラブルシューティングについては、references/python-pypbr.md と references/node-vgpu.md を参照してください。Node では、依存関係がインストールされたプロジェクトから、スクリプトの scripts/ フォルダーにアクセスできる必要があります。Python ではパッケージのみが必要です。

ワークフロー

1. カラーテクスチャをファイルとして取得する

list_textures を実行し、対象テクスチャの UUID、bitmap_size、uv_size を控えてください。ファイルパスは報告されません。テクスチャが自分で作成したファイル（たとえば GPT 画像ワークフローで生成した縮小済みアトラス）からインポートされた場合は、そのファイルを使ってください。それ以外の場合は、get_texture で画像を取得して、返された PNG をディスクに保存するか、Blockbench でテクスチャを保存してください。拡大した生成キャンバスではなく、ネイティブのテクセルサイズのアトラスを使い、マップがカラーマップと同じテクセルグリッドを共有するようにしてください。

何かを導出する前に、アトラスを確認してください。面ごとに起伏のスケールが一貫している必要があるため、まずカラーマップに UV スケールと歪みに関するガイダンス を適用してください。法線マップには、UV レイアウトの伸びがすべて反映されます。

2. 高さのソースを選ぶ

ソース	フラグ	用途
輝度（デフォルト）	--height-source luminance	ピクセルアートや、フラットシェーディングで描かれたテクスチャに使用します。明るい部分が高い部分として扱われます。暗い塗装部分を盛り上がった部分にする場合は --invert-height を追加してください（暗い目地は低いままにします）。
Depth Anything V2	--height-source depth	レンガ、板材、石畳、植物、機械など、実際の構造を持つ写真風または絵画風のテクスチャに使用します。2 色のチェッカーには役立ちません。深度モデルは初回使用時にダウンロードされます。
高さファイル	--height-source file --height-file h.png	Blockbench で描いた高さ、別のツールで作成した高さ、または形状を調整するための既存の _height.png に使用します。

深度推定ではタイルではなく写真として認識されるため、前景から背景へのグラデーションが生成され、タイル化が崩れます。スクリプトでは深度推定時に --flatten 1 と正規化が有効になります。非線形の偏りを加えるには --high-pass <texels>（タイル幅の約 4 分の 1）を、シームレスなタイルにするには --seam offset を追加してください。小さいテクスチャはモデルに入力する前に最近傍法で少なくとも 1024 px まで拡大され、ブロック平均化で元に戻されるため、16×のアートでもエッジが維持されます。詳しくは references/height-processing.md を参照してください。

3. 実行

# tiling 16x block, pronounced pixel relief
python scripts/albedo_to_normal.py block.png --out ./pbr --wrap --strength 1
node   scripts/albedo_to_normal.mjs block.png --out ./pbr --wrap --strength 1

# entity/prop atlas with transparent gutters (islands isolated automatically)
python scripts/albedo_to_normal.py goal_atlas.png --out ./pbr --strength 0.5

# HD tile from a painterly texture, depth-estimated, softened for smooth relief
node scripts/albedo_to_normal.mjs planks.png --out ./pbr --height-source depth --high-pass 32 --seam offset --wrap --soften 1

フラグ	デフォルト	効果
--wrap	オフ	境界をまたいでサンプリングします。シームレスなタイルではオン、アトラスやタイル化しないアートではオフにします。
--strength F	0.5	グラデーションの倍率です。0.25は控えめ、0.5はデフォルト、1～2は強いピクセルの凹凸です。テクスチャ密度が2倍になるごとに半分にします。
--operator	sobel	sobel、prewitt（よりソフト）、scharr（滑らかなHD高さ）を指定します。
--convention	directx	directx は緑が下向き（Bedrock RTXの想定）、opengl は緑が上向き（Blender、glTF、labPBR）です。
--alpha-threshold	8	これ未満のアルベドのアルファ値は島の外として扱われます。溝をまたいで凹凸がにじまず、溝にはフラットな法線が設定されます。
--soften M	0	高さに密度スケールのガウシアンを適用します（≈ shortSide/64 · M ピクセル）。64×以上のテクスチャでは1を使い、16×では0のままにします。
--levels B,W,G	0,1,1	カーネル処理の前に、高さに入力の黒レベル／白レベル／ガンマを適用します。
--flatten、--high-pass、--normalize/--no-normalize、--invert-height	depth: 1, 0, on	高さの形状を調整します。file と luminance ソースでも使用できます。
--seam offset --seam-amount A	オフ、0.15	タイルの高さに対し、ラップして継ぎ目を補正するブレンドを適用します。
--no-height、--no-mer	オフ	_height.png / _mer.png の書き出しを省略します。
--metal、--emissive、--roughness	自動	auto はチャンネルを推定します。0～1の値を指定すると均一になります（金属以外には --metal 0 を指定します）。
--palette "#RRGGBB=m,e,r;..."	なし	正確な色に対するMERの上書きです。- は推定されたチャンネルを維持します。ピクセルアートのパレットに最適なツールです。
--rough-curvature W、--rough-height I、--rough-weights V,E,S、--rough-scale、--rough-bias	0.25, 0, 0.4/0.3/0.3, 1, 0	ラフネスの項目です。法線の曲率（くぼみは粗く、尾根は滑らかに）、高さの影響度、分散／エッジ／彩度の重み、出力のリマップを指定します。
--metal-brightness、--metal-saturation、--gold-hue、--copper-hue、--no-metal-clean	0.6, 0.15, 0.11–0.17, 0.03–0.10, クリーン化オン	金属のヒューリスティック判定のしきい値です。クリーン化では、3×3の多数決により斑点を除去します。
--emissive-brightness、--emissive-saturation、--emissive-overbright、--emissive-softness	0.8, 0.5, 1（オフ）、0	発光のしきい値、明るすぎる場合のフォールバック、発光の縁のアンチエイリアスを指定します。
Python の --depth-device、--material-folder；Node の --depth-device、--depth-dtype、--gpu		実行時の詳細については、リファレンスを参照してください。

MERの推定はヒューリスティックです。調整する前にreferences/mer-inference.mdを読んでください。明るく彩度の低い色は金属として、明るく彩度の高い色は発光として認識されますが、羊毛、骨、雪、色白の肌、黄色いくちばし、塗装された看板では誤判定になります。まず素材を決めてから、各チャンネルに auto、均一な値、またはパレットの上書きを選んでください。

4. レポートを確認する

標準出力のJSONは report と merReport で終わります。法線については、verdict: "ok" と classification: "standard" を必須とし、meanXYBias は0に近く、negativeZCount は0であることを確認してください。heightfield 分類は、アルベド引数がグレースケール画像だったことを示します。タイルで大きなバイアスを伴う warn が出た場合は、高さに平坦化されていないランプがあります。flatPct は参考値です（フラットなアートや、大きな溝があるアトラスでは高くなります）。

MERについては、metalPct と emissivePct を実際の素材と、roughnessMean を目指すマットさと比較してください。木箱の metalPct が0.4なら、明るい色の板が鋼鉄として誤認されています。--metal 0 またはパレットを指定して再実行してください。パレットを指定しているのに paletteTexels が0なら、色が完全一致していません。レポートが示すのはエンコードが正しいことであり、凹凸の方向や強さ、素材の割り当てが正しいことではありません。それらはステップ6で確認します。

5. Blockbench でインポートして割り当てる

create_texture: name="<name>_normal", data="<absolute path to <name>_normal.png>"
create_texture: name="<name>_mer",    data="<absolute path to <name>_mer.png>"
create_pbr_material: name="<material>", color_texture="<albedo>", normal_texture="<name>_normal", mer_texture="<name>_mer"
# or on an existing material:
assign_texture_channel: material="<material>", texture="<name>_normal", channel="normal"
assign_texture_channel: material="<material>", texture="<name>_mer", channel="mer"
get_material_info: material="<material>"

Bedrock のテクスチャセットでは、normal または heightmap を指定します。両方は指定できません。対象が 16× のバニラ風ピクセルアートで、パックの規約でハイトマップが優先される場合は、代わりに _height.png を height_texture として割り当てます。それ以外の場合はノーマルを使用します。MER テクスチャには、同じマテリアル上にカラーテクスチャが必要です。表面全体で金属・発光・粗さの値が共通の場合は、マップを使うより、マテリアルの mer_value を使うほうが簡単です（--no-mer で生成します）。テクスチャごとに UV サイズを指定する形式では、create_texture の uv_width／uv_height をカラーテクスチャに合わせてください。チャンネルの規則、均一な MER 値、save_material_config については、blockbench-pbr-materials を参照してください。

6. 向きとスケールを確認する

capture_screenshot で、少なくとも 2 つの角度から、想定される表示距離でライティングされたモデルを確認します。

• 隆起した特徴が隆起として見える必要があります。上から下への陰影が反転している場合は、緑チャンネルの規約が間違っています。もう一方の --convention で再生成してください。すべてが反転して見える（くぼみが隆起して見える）場合は、高さの向きが間違っています。--invert-height で再生成してください。
• すべての面でレリーフが同じサイズに見える必要があります。全体の調整には --strength を使います。ばらつきがある場合は、ノーマルを手作業で編集せず、UV レイアウトまたはカラーアトラスを修正します。
• タイリングブロックの場合：複数個を配置して継ぎ目を確認します。継ぎ目の修正には、高さに対して --wrap と --seam offset を使います。継ぎ目の上から塗りつぶすのではありません。
• アトラスのアイランドの周囲に縁があってはいけません。縁がある場合、アルベドのアルファが適切に処理されていません。--alpha-threshold を上げるか、ガターをきれいにして再生成してください。
• 金属の領域は実際に金属である部分に限られている必要があります（RTX では暗く、反射するようになります）。発光は光源だけに適用し、粗さによって布や塗装が光沢を帯びないようにします。均一な値、パレットのオーバーライド、または粗さの項目で修正し、塗り直すのではなく MER を再生成してください。
• レンダリングプレビューで確認できるのは Blockbench のシェーディングだけです。納品前に、対象のゲームまたはレンダラーで確認してください。

期待される結果

• 輝度から求める高さは、アーティスティックな近似値です。描画されたハイライトは隆起になり、影はくぼみになります。様式化されたテクスチャやピクセルアートには適していますが、写真由来のテクスチャには適しません。
• テクスチャの深度推定は、レリーフとして妥当な値であり、実測値ではありません。PyTorch と ONNX のモデル変換では実行ごとに差が生じる可能性があります。タイルでは --flatten／--high-pass／--seam によるクリーンアップが必要だと考えてください。
• 両方のランタイムでは、同じ輝度入力からはバイト単位で同一の高さが生成され、同じ高さから生成されるノーマルの差は 2 レベル以内、同じ金属マスクでの MER の粗さの差は 3 レベル以内です。
• MER の推論は、色と形状に基づくヒューリスティックであり、マテリアルを認識するものではありません。彩度の低い明るい領域を誤って金属と判定したり、彩度の高い明るい領域を誤って発光と判定したりすることがあります。レポートでどちらも確認でき、塗り直すことなくオーバーライドで修正できます。
• PyPBR 独自の compute_normal_from_height（0.1.0b5）は境界をゼロパディングして X 軸を反転するため、Python スクリプトはノーマルを独自に生成し、マテリアルオブジェクト、フォルダー I/O、後続の処理には PyPBR を使用します。
• Node はスクリプトの場所を基準に vgpu、pngjs、シェーダーを解決します。GPU がない場合は、npx vgpu install-software-renderer を一度実行し、--gpu software を指定してください。

リソース

• references/height-processing.md：高さと法線の各処理段階、深度の調整、カーネルの計算、規約、レポートのフィールド、実行時の同等性について説明します。
• references/mer-inference.md：メタリック、発光、粗さの推定方法、すべての MER フラグ、オーバーライド、MER レポート、実行すべきチェックについて説明します。
• references/python-pypbr.md：インストール、PyPBR のマテリアル API と注意点、transformers を使った Depth Anything について説明します。
• references/node-vgpu.md：インストール、スクリプトで使用する vgpu の計算／テクスチャ API、WGSL に関する注意点、Node での transformers.js を使った深度処理について説明します。
• scripts/albedo_to_normal.py：Python パイプライン（torch + PyPBR、オプションで transformers）。
• scripts/albedo_to_normal.mjs：Node パイプライン（vgpu + Dawn、pngjs、オプションで transformers.js）。
• scripts/shaders/height-map.wgsl、normal-map.wgsl、mer-map.wgsl：GPU パス。リファレンス用の計算式としても参照できます。