fix(thumbnail): 缩略图采样 baseColorTexture,修复 MMD 模型显示为白模

现象(用户反馈):导入 PMX 转换出的 GLB 后,列表页/审核面板里的模型是白模,
脸部颜色信息全部丢失。

定位过程(本地装真 Assimp 6.0.4 + 该模型完整复现):
1. 转换本身正常:23.7MB GLB、643 骨骼、93,350 面;
2. 18 张贴图逐字节与压缩包原图一致;用一个权威 PMX 解析器比对后确认
   39 个材质 -> 贴图的对应关系与 PMX 完全一致(不是映射错);
3. UV 采样也正确:脸部材质取到的就是皮肤色 (246,221,216);
4. 真正的问题在**我们自己的缩略图渲染器**:它刻意不解码 baseColorTexture,
   只用 baseColorFactor 上色(见文件头取舍说明);而 MMD 模型的
   baseColorFactor 基本都是白色 -> 缩略图必然全白。管理端 3D 预览有贴图,
   只有列表/审核的缩略图是白的。

修复:
1. model-thumbnail.ts 内置极简 PNG 解码器(zlib inflate + 逐行反滤波,
   8 位非隔行,colorType 0/2/3/4/6),按 baseColorFactor x 贴图逐像素采样,
   透视校正 UV;解码失败/非 PNG/隔行扫描回退纯色,绝不抛错;
2. 按 alphaMode 处理透明度:OPAQUE 忽略贴图 alpha(MMD 语义)、
   MASK 按 alphaCutoff 丢弃、BLEND 做 source-over;
3. 取景收紧 FRAMING 1.6 -> 1.3,40px 列表缩略图主体更清楚;
4. 新增 test/model-thumbnail-texture.spec.ts 6 项(含白模回归:
   baseColorFactor 全白 + 红贴图必须输出偏红,以及 MASK/OPAQUE/坏图回退);
5. 版本 0.2.4,README(.md/.txt)/DSH.md 补修订说明与 FAQ(含重新生成缩略图
   的 reanalyze-models.mjs --force 命令)。
This commit is contained in:
opendance
2026-09-16 04:02:35 +08:00
parent 8e8cc0475b
commit ae8a68e98f
11 changed files with 605 additions and 37 deletions
+2 -2
View File
@@ -101,7 +101,7 @@ opendance-web/
│ ├── admin/ # React 管理端
│ │ ├── src/components/ModelReviewPanel.tsx # 模型审核面板 + 骨骼详细界面
│ │ └── src/lib/bone-tree.ts # 骨骼树过滤(搜索保留祖先链)
│ ├── test/ # 单元测试 + 端到端冒烟(13 文件 / 205 项)
│ ├── test/ # 单元测试 + 端到端冒烟(14 文件 / 211 项)
│ │ # mmd-vmd 31 / model-archive 24 / model-inspector 25
│ │ # / model-thumbnail 8 / admin-bone-filter 8
│ │ # / preprocess 25 / init-env 16 / admin-port 16
@@ -335,7 +335,7 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile() 直接导
T-pose 角色图;真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms(中位 79ms)。
- 管理端 3D 预览放开到 `vrm/glb/gltf`(`fbx` 仍提示"仅归档,请先转换为 GLB/VRM");
列表页显示 40px 缩略图。
- 测试:`npx vitest run` -> **13 个文件 / 205 项通过**
- 测试:`npx vitest run` -> **14 个文件 / 211 项通过**
(`model-inspector` 25、`model-thumbnail` 8、`admin-bone-filter` 8、
`model-archive` 24、`mmd-vmd` 31、`preprocess` 25、`init-env` 16、
`admin-port` 16、`access-log` 9、`vrm-inspector` 6)。