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
+23
-8
@@ -1,5 +1,5 @@
|
||||
================================================================
|
||||
OpenDance Studio -- Web 管理服务端 v0.2.3 使用说明
|
||||
OpenDance Studio -- Web 管理服务端 v0.2.4 使用说明
|
||||
================================================================
|
||||
|
||||
本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
|
||||
@@ -8,6 +8,17 @@ OpenDance Studio -- Web 管理服务端 v0.2.3 使用说明
|
||||
重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
|
||||
连接信息通过 .env 注入。
|
||||
|
||||
v0.2.4 修订
|
||||
1. 修复缩略图"白模": 缩略图渲染器原先刻意不解码贴图, 只用 baseColorFactor
|
||||
上色; 而 MMD(PMX 转换)模型的 baseColorFactor 基本都是白色, 于是列表页与
|
||||
审核面板里的缩略图全是白色模型。现在内置极简 PNG 解码器(zlib + 反滤波,
|
||||
8 位非隔行, colorType 0/2/3/4/6), 按 baseColorFactor x 贴图逐像素采样,
|
||||
并按 alphaMode(OPAQUE / MASK / BLEND)处理透明度; 解码失败回退纯色。
|
||||
2. 缩略图取景收紧(FRAMING 1.6 -> 1.3), 40px 列表缩略图里主体更清楚。
|
||||
3. 新增 6 项贴图/透明度测试(test/model-thumbnail-texture.spec.ts)。
|
||||
4. 说明: GLB 数据本身没问题 - 贴图逐字节内嵌(18/18)、39 个材质的贴图对应
|
||||
关系与 PMX 完全一致; 白模只出在缩略图渲染器。
|
||||
|
||||
v0.2.3 修订
|
||||
1. 修复上传 PMX 返回 500(models.stats 容量): 分析结果里的骨骼树按骨骼逐条
|
||||
展开, 实测一个 643 骨骼的 PMX(【奥黛塔】_by_原神.zip)就有 70,980 字节,
|
||||
@@ -58,11 +69,11 @@ v0.2.1 修订
|
||||
2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
|
||||
本项目不会创建数据库本身
|
||||
3. 取得发布包并校验(地址用你们自己的制品库替换)
|
||||
curl -LO https://<制品库地址>/opendance-web-v0.2.3.tar.gz
|
||||
curl -LO https://<制品库地址>/opendance-web-v0.2.4.tar.gz
|
||||
curl -LO https://<制品库地址>/SHA256SUMS
|
||||
sha256sum -c SHA256SUMS # 期望输出 "OK"
|
||||
4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
|
||||
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
|
||||
5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
|
||||
bash deploy/install.sh
|
||||
@@ -120,8 +131,8 @@ v0.2.1 修订
|
||||
(本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
|
||||
|
||||
部署步骤
|
||||
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
|
||||
|
||||
@@ -252,7 +263,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
|
||||
(RHEL 系 dnf install -y assimp; install.sh 现在会尝试自动安装)。
|
||||
装好后不需要重启服务; 若不在服务 PATH 中, 在 deploy/.env 里把 ASSIMP_BIN
|
||||
设为绝对路径。只上传 .glb / .vrm 则不需要它。
|
||||
- 导入模型返回 500 Internal server error
|
||||
- 列表/审核里的缩略图是"白模"(纯白模型)
|
||||
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 起服务端另有兜底,
|
||||
@@ -287,11 +302,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
|
||||
cd web-server
|
||||
npm run contracts:check # 契约版本一致性
|
||||
npm run typecheck # TypeScript 严格检查
|
||||
npm run test # 205 项单元测试 / 13 个文件(VMD 31、模型压缩包 24、
|
||||
npm run test # 211 项单元测试 / 14 个文件(VMD 31、模型压缩包 24、
|
||||
# 模型检查器 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 项端到端冒烟(需要数据库可连通)
|
||||
|
||||
Reference in New Issue
Block a user