高模减面与贴图烘焙 + XPbr 打包
复刻自 ClientTrunk ModelTools，并接入 AIC#Project ModelTranslator 的 XPbr 收尾。
高模（FBX / GLB / glTF）
-> model_decimate：减面 + 重展 UV -> <名>_low.fbx
-> model_bake：Cycles 烘焙 -> 五通道 PNG + 低模 FBX
-> model_translator：打包为 XPbr 两张图 + .mat/.meta
_base.png RGB=Albedo A=AO/透明
_mix.png RG=球面法线 B=Metallic A=Roughness
写出时 PNG 无损压缩（体积更小，像素不变）
环境
- Blender 5.0：默认
D:\tools\Blender\blender-5.0.0-windows-x64\blender.exe- 或
BLENDER_EXE/BLENDER_PATH/--blender
- 或
- Pillow（UV 观察图）：
pip install Pillow - UVPackmaster 4 可选
FBX 轴向约定
项目标准为 Y-up、底面中心原点、局部 +Z 为正面，配置见 Config/Art/ModelConvention.json。
朝向直接使用 Unity transform.forward / Quaternion.LookRotation(direction)。
axis_forward="-Z" 是 Blender FBX 坐标转换参数，继续保留；它不等于角色解剖正面。
旧 -Z 资产、固定骨架和历史验收记录按自身约定兼容，不批量旋转已绑定网格或动画。
Studio 五步的 GLB 使用标准 glTF Y-up；Blender 默认导入后应在 Z-up 场景中站立。
prepare_game_export 为历史调用保留 Y-up 顶点缓冲；最终必须由
export_fbx_source_yup 在临时副本上恢复 Blender Z-up，再烘焙为 Y-up FBX。
不要直接把准备后的 Y-up 顶点交给默认 FBX 导出器，否则会重复转换，留下 X=-90° 节点旋转。
版本 2 导出器会校验场景 +Y-up、节点旋转 0 和缩放 1；静态导出回执写入 fbxAxes.exportVersion。
lmgirl_tpose_mesh.py 只复用版本匹配的 FBX 缓存，历史资源不会在此次修复中批量重导。
Blender 回归入口：Tools/model_tools/tests/bl_test_fbx_axes.py。验收读取完整节点变换后的世界几何，
同时检查脚底中心原点、UV、源网格不变及重复导入导出，不以顶点包围盒或 axis_up 参数单独判定成功。
一键（推荐）
python Tools/model_tools/model_lowpoly_bake.py prop.glb -o Tools/output/prop_game --tris 5000 --size 2048
# 默认会继续生成 Tools/output/prop_game/prop_xpbr/（base+mix+.mat）
# 跳过 XPbr：加 --no-xpbr
分步
python Tools/model_tools/model_decimate.py prop.glb --tris 5000 -o Tools/output/prop_low
python Tools/model_tools/model_bake.py prop.glb Tools/output/prop_low/prop_low.fbx -o Tools/output/prop_bake --size 2048
python Tools/model_tools/model_translator.py Tools/output/prop_bake/prop/prop.fbx -o Tools/output/prop_xpbr
装入 Unity + 预设
python Tools/install_character_bundles.py -a CaoCao --kind Human -b Tools/output/caocao_game/caocao_xpbr -c Doc/Design/Character/CaoCao/caocao.png
# Unity Pipeline：run_script AgentScripts/SetupCharacter.cs --entry SetupCharacter.SetupCaoCao
# 寻址 Prefab=`CaoCao`，目录 Characters/Human/CaoCao
与 AIC#Project/ModelTranslator 减面烘焙对比
| 能力 | 本仓库 Tools/model_tools（现） |
AIC#Project ModelTranslator |
|---|---|---|
| 高模格式 | FBX/GLB/glTF | 主路径偏 FBX（减面 CLI 文案） |
| 减面后端 | Decimate collapse | 默认 Quad Remesher，失败回退 collapse |
| UV 质量门 | 翻转/重叠 + 最大单岛占比（已对齐） | 翻转/重叠/最大单岛 + 更深 seam 扫描 |
| 烘焙射线 | 自适应分离距离（已对齐） | 自适应分离距离 |
| 收尾 | XPbr base/mix + .mat（已接入） | 同左（源头） |
| QR 引擎 | 未捆绑（无 xremesh 依赖） | 需本机 Quad Remesher 引擎 |
结论：AIC#Project 在「有机角色拓扑」上更优（Quad Remesher + 更深 UV 门）；本仓库已并入其自适应射线、大岛门限与 XPbr 打包，并保留 GLB 输入。若本机已装 QR 引擎，可再把 qr_bridge / --reducer quad 完整迁入作为可选增强。
肩部黑影诊断（2026-10-27）
先用同机位拆分检查：底色无光照、关闭 Normal、关闭 AO、纯灰材质。bl_audit_bake_quality.py --job <Studio任务目录> --output <绝对输出目录> 在 Blender 中运行，可生成上述对比。--quick --normal-strength 0.35 可导出减弱法线的隔离预览；它会牺牲部分细节，不代表投射已修复。
已用 lm_bear 任务完成受控对比，记录在 Tools/output/bake_quality_audit/findings.json：黑块主要由法线贴图引入，EMIT底色和不挂AO的GLB仍可排除相应通道。仅取消烘焙后的向外法线偏置不足以消除问题；将cage从0.06014m缩到0.007156m改善肩部／腿间，但增加头发细节漏投射。因此不能仅凭包围盒固定比例或全局P99距离决定最终参数。
推荐的生产改进（本轮未修改共享后端）：
- 烘焙前固定最终三角化、UV和角点法线，烘焙后保持一致；如第五步减面改变了网格，需在最终网格原UV上补烘法线。
- 分区域cage、小范围到大范围重试，结合命中距离、法线方向和部位对应关系选择结果；肩／领巾／头发等复杂区域可用匹配分件或手调cage。
- 生成独立UV覆盖／投射命中mask；不要把黑色底色、零金属度当作未命中。单位长度合格的法线也可能投射到了错误表面。
- 可为卡通预览提供Normal Strength约0.3～0.5的可调回退，并保留原贴图。
投射试验入口 bl_trial_studio_bake.py --job <任务目录> --output <绝对输出目录> --ray-mode legacy|adaptive：只在独立目录执行当前共享烘焙器的受控副本，保留源网格与Studio UV。Blender烘焙设置说明：Render Baking。