blockbench-albedo-to-pbr

面向 Blockbench 的反照率转法线和 MER

PBR 通道是推导出来的，而不是绘制出来的：反照率 → 高度场 → 切线空间法线，随后根据反照率、高度和法线曲率推断金属度、自发光和粗糙度，并打包到一张 MER 图像中。两个脚本共用一个 CLI 和相同的数学方法；根据运行环境选择即可。请先加载 blockbench-use，以便发现和验证，再加载 blockbench-pbr-materials 来分配结果。本技能仅生成图像文件。

运行环境	脚本	安装	高度估算
Python	scripts/albedo_to_normal.py	pip install pypbr（深度估算还需安装 transformers）	通过 transformers 使用 Depth Anything V2；有可用 CUDA 时使用 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.js 需要从已安装依赖项的项目访问脚本的 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	具有真实结构的摄影或绘画风格纹理：砖块、木板、鹅卵石、树叶、机械。对双色棋盘格毫无用处。首次使用时会下载深度模型。
高度文件	--height-source file --height-file h.png	在 Blockbench 中绘制、由其他工具生成，或使用之前的 _height.png 调整形状的高度图。

深度估算看到的是照片，而不是平铺图案：它会生成从前景到背景的渐变，导致无法平铺。对于深度模式，脚本会保留 --flatten 1 并启用归一化；添加 --high-pass <texels>（约为图块宽度的四分之一）可获得非线性偏移，添加 --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 表示强像素浮雕；纹理密度每翻倍，数值减半。
--operator	sobel	sobel、prewitt（更柔和）、scharr（平滑的高清高度图）。
--convention	directx	directx 表示绿色向下（Bedrock RTX 假设），opengl 表示绿色向上（Blender、glTF、labPBR）。
--alpha-threshold	8	Albedo 的 alpha 值低于此值的区域视为岛屿外区域：浮雕不会渗入边缘间隙；间隙会使用平坦法线。
--soften M	0	对高度图应用密度缩放的高斯模糊（≈短边/64 · M 像素）。纹理尺寸 ≥64× 时使用 1；16× 时保持 0。
--levels B,W,G	0,1,1	在应用卷积核前调整高度图输入的黑场、白场和伽马。
--flatten、--high-pass、--normalize/--no-normalize、--invert-height	深度：1、0、开启	深度塑形，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. 阅读报告

stdout 上的 JSON 以 report 和 merReport 结尾。对于法线，要求 verdict: "ok" 且 classification: "standard"；meanXYBias 接近 0，negativeZCount 为 0。heightfield 分类表示 albedo 参数是灰度图；对于平铺图，若 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 查看受光模型：

• 凸起的特征必须看起来是凸起的。上下方向的明暗颠倒表示绿色通道约定有误：使用另一个 --convention 重新生成。所有效果都反转（凹坑像凸起）表示高度方向有误：使用 --invert-height 重新生成。
• 每个面上的浮雕尺寸必须一致。通过 --strength 全局调整；结果不均匀时，应修正 UV 布局或颜色图集，而不是手动编辑法线贴图。
• 平铺方块：放置多个副本并检查接缝；修正方法是在高度图上使用 --wrap 和 --seam offset，而不是涂抹覆盖接缝。
• 图集岛周围不能出现边缘。如果出现，说明反照率 Alpha 不干净；提高 --alpha-threshold 或清理边缘留白后重新生成。
• 金属区域必须对应实际金属部分（在 RTX 下会变暗并产生反光），发光效果只能出现在光源上，粗糙度也不能让布料或油漆变得发亮。使用统一值、调色板覆盖或粗糙度项进行修正，并重新生成 MER，而不是手动绘制。
• 渲染预览只能证明 Blockbench 的着色效果；交付前请在目标游戏或渲染器中确认。

预期效果

• 亮度高度图是艺术化的近似：绘制的高光会变成凸起，阴影会变成凹坑。它适用于风格化和像素画，不适用于照片来源的纹理。
• 纹理深度估算得到的是看起来合理的浮雕，并非测量结果。PyTorch 和 ONNX 模型转换后的结果每次运行都可能有所不同；对于平铺纹理，应将 --flatten／--high-pass／--seam 视为必要的清理步骤。
• 对于相同的亮度输入，两种运行时生成的高度图逐字节相同；根据相同高度图生成的法线贴图最多相差两个级别；使用相同金属遮罩时，MER 的粗糙度最多相差三个级别。
• MER 推断基于颜色和形状启发式规则，而非材质识别。浅色低饱和区域可能被误判为金属，明亮高饱和区域可能被误判为发光；报告会显示这两类问题，覆盖设置无需绘制即可修正。
• PyPBR 自带的 compute_normal_from_height（0.1.0b5）会将边界补零并翻转 X，因此 Python 脚本自行推导法线，并使用 PyPBR 处理材质对象、文件夹 I/O 和后续操作。
• 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 处理阶段；也可作为数学参考阅读。