zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

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

Browse Source 
现象（用户反馈）：导入 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
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+19 -10
View File
@@ -10,7 +10,14 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My
## 状态
**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.3**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.4**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
v0.2.4 修订:
1. **修复缩略图"白模"**:缩略图渲染器原先**刻意不解码贴图**,只用 `baseColorFactor` 上色;而 MMD(PMX 转换)模型的 baseColorFactor 基本都是白色,于是列表页与审核面板里的缩略图全是白色模型。现在渲染器内置极简 PNG 解码器(zlib + 反滤波,8 位非隔行,colorType 0/2/3/4/6)并按 `baseColorFactor x 贴图` 逐像素采样,同时按 `alphaMode`(OPAQUE / MASK / BLEND)处理透明度;解码失败或非 PNG 时回退纯色,绝不抛错;
2. 缩略图取景收紧(FRAMING 1.6 -> 1.3),40px 列表缩略图里主体更清楚;
3. 新增 6 项贴图/透明度/朝向测试(`test/model-thumbnail-texture.spec.ts`);
4. **说明**:GLB 数据本身没问题——贴图逐字节内嵌(18/18)、39 个材质的贴图对应关系与 PMX 完全一致、UV 取到的就是皮肤/五官区域;白模只出在缩略图渲染器。
v0.2.3 修订:
@@ -59,15 +66,15 @@ v0.2.0 主要变更:
3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)
```bash
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.3/opendance-web-v0.2.3.tar.gz
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.3/SHA256SUMS
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.4/opendance-web-v0.2.4.tar.gz
curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.4/SHA256SUMS
sha256sum -c SHA256SUMS # 期望输出 "OK"
```
4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
```bash
tar -xzf opendance-web-v0.2.3.tar.gz && cd opendance-web-v0.2.3
tar -xzf opendance-web-v0.2.4.tar.gz && cd opendance-web-v0.2.4
bash deploy/init-env.sh
```
@@ -137,8 +144,8 @@ FLUSH PRIVILEGES;
### 5. 部署步骤
```bash
tar -xzf opendance-web-v0.2.3.tar.gz
cd opendance-web-v0.2.3
tar -xzf opendance-web-v0.2.4.tar.gz
cd opendance-web-v0.2.4
bash deploy/init-env.sh # 首次启动引导: 逐项问答生成 deploy/.env(见下)
bash deploy/install.sh # 已以 root 登录, 不需要 sudo
```
@@ -279,6 +286,7 @@ bash /opt/opendance/deploy/ctl.sh status | restart | logs
| 服务本机 curl 通、外部访问不了 | `bash deploy/check-access.sh` 一次定位:打印 `HOST`/`PORT`、实际监听地址、对外 IP 自测、80/443 有无反代、防火墙放行情况,并给出修复命令 |
| 管理页面打开是 404 | 说明访问的是软件 API 端口(默认 3000);管理页面在管理端端口(默认 3001) |
| 上传 `.zip` / `.pmx` / `.fbx` 报转换失败(ENOENT / Assimp 不可用) | PMX/FBX 转换依赖外部 Assimp:`apt-get install -y assimp-utils`(RHEL 系 `dnf install -y assimp`,`install.sh` 现在会尝试自动安装)。装好后**不需要重启服务**;若不在服务 PATH 中,在 `deploy/.env` 设 `ASSIMP_BIN` 为绝对路径。只上传 `.glb` / `.vrm` 则不需要它 |
| 列表/审核里的缩略图是"白模"(纯白模型) | v0.2.4 前的缩略图渲染器不采样贴图,而 MMD 模型的 `baseColorFactor` 是白色。升级到 v0.2.4 后重新生成缩略图:`cd /opt/opendance/web-server && node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000 --force` |
| 导入模型返回 **500 Internal server error** | 老库上多为 `models.stats` 超长(骨骼树按骨骼展开,643 骨骼即 70,980 字节 > TEXT 上限):执行 `ALTER TABLE models MODIFY stats MEDIUMTEXT NULL;` 或部署 v0.2.3(`install.sh` 会自动跑迁移)。v0.2.3 起服务端另有兜底,不会再 500 |
| 安装时报 `command not found` / 退出码 127,且提示指向 `deploy/.env` 某一行 | 该行的值含空格或 shell 元字符却没加引号,被 shell 当成命令执行了。按预检提示给这个值加引号(如 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`)后重跑;`deploy/env-lib.sh` 会提前拦住并给出行号 |
| 模型审核界面显示"未分析 / 无预览图" | 该模型是升级前入库的:调 `POST /api/models/<id>/reanalyze`,或批量跑 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000` |
@@ -309,11 +317,12 @@ npm run dev # http://localhost:5173(/api 与 /health 代理到 3000)
cd web-server
npm run contracts:check # 契约版本一致性
npm run typecheck # TypeScript 严格检查
npm run test # 205 项单元测试 / 13 个文件(VMD 31、模型压缩包 27、
npm run test # 211 项单元测试 / 14 个文件(VMD 31、模型压缩包 27、
# 模型检查器 25、缩略图 8、骨骼过滤 8、
# 预处理 25、init-env 16、admin-port 16、
# access-log 9、VRM 检查器 6、.env 预检 12、
# Assimp 定位与安装 13、stats 容量与编码 12)
# Assimp 定位与安装 13、stats 容量与编码 12、
# 缩略图贴图采样 6)
npm run build # 生产构建
npm run start:prod & # 启动
npm run test:smoke # 57 项端到端冒烟(需要数据库可连通)
@@ -434,10 +443,10 @@ node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000
| 能力 | 实现 |
| --- | --- |
| 分析 | `model-inspector.ts` 解析 GLB/VRM:面数 / 顶点 / 网格 / 材质 / 贴图 / 节点 / 形变目标 / 动画 / 蒙皮骨骼数 / 骨骼树 / humanoid 覆盖 / 可驱动性(缺哪些必需骨骼)/ warnings,写入 `models.stats`(迁移 `AddModelStats1789460000000`,新增 `models.stats TEXT`) |
| 缩略图 | `model-thumbnail.ts` 用**纯 TS 软件光栅化**生成 PNG(读 GLB/glTF -> 应用节点层级与蒙皮 -> 包围盒自动构图 -> 透视投影 -> z-buffer 逐三角形平面着色 -> 手写 PNG 编码),**零原生依赖**(不需要 canvas / headless-gl / puppeteer)。默认 512x512,写入 `models.thumbnail_asset_id` / `thumbnailUrl`;失败或非 glTF 容器时留空,列表页退化为格式占位图 |
| 缩略图 | `model-thumbnail.ts` 用**纯 TS 软件光栅化**生成 PNG(读 GLB/glTF -> 应用节点层级与蒙皮 -> 包围盒自动构图 -> 透视投影 -> z-buffer + 平面着色 + **逐像素采样 baseColorTexture**,内置 PNG 解码器 -> 手写 PNG 编码),**零原生依赖**(不需要 canvas / headless-gl / puppeteer);按 `alphaMode` 处理 OPAQUE / MASK / BLEND。默认 512x512,写入 `models.thumbnail_asset_id` / `thumbnailUrl`;失败或非 glTF 容器时留空,列表页退化为格式占位图 |
| 预览 | 管理端 3D 预览放开到 `vrm/glb/gltf`(`.fbx` 仍提示「仅归档,请先转换为 GLB/VRM」);列表页显示 40px 小缩略图,审核面板显示 116px 缩略图 |
实测:512x512 PNG / 15,043 字节,目视确认为居中的 T-pose 角色图;真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms(中位 79ms)。
实测:512x512 PNG / 15-42 KB(带贴图后变大),目视确认为居中的 T-pose 角色图且能看到肤色/眼睛/服装贴图;真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms(中位 79ms),27MB PMX 转换件约 200-400ms。
### 审核流程(模型)