diff --git a/DSH.md b/DSH.md index 998c0ca..ce61785 100644 --- a/DSH.md +++ b/DSH.md @@ -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）。 diff --git a/README.md b/README.md index bb8485a..9278ecc 100644 --- a/README.md +++ b/README.md @@ -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//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。 ### 审核流程(模型) diff --git a/README.txt b/README.txt index 2c7e4e8..a8adf18 100644 --- a/README.txt +++ b/README.txt @@ -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 项端到端冒烟(需要数据库可连通) diff --git a/project.yaml b/project.yaml index d8b107d..0bea5f4 100644 --- a/project.yaml +++ b/project.yaml @@ -1,5 +1,5 @@ project: opendance-web-server -version: 0.2.3 +version: 0.2.4 repository: opendance-web default_branch: main contracts_version: 0.4.0 @@ -60,7 +60,7 @@ tasks: status: done deliverable: - artifact: opendance-web-v0.2.3.tar.gz + artifact: opendance-web-v0.2.4.tar.gz packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker） includes: - web-server/ # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换） diff --git a/scripts/package-release.sh b/scripts/package-release.sh index 75553cf..9b24b69 100755 --- a/scripts/package-release.sh +++ b/scripts/package-release.sh @@ -1,6 +1,6 @@ #!/bin/bash # ============================================================ -# 打包发布产物：opendance-web-v0.2.3.tar.gz +# 打包发布产物：opendance-web-v0.2.4.tar.gz # # 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）： # web-server/ NestJS 源码 + 构建产物 @@ -21,7 +21,7 @@ set -euo pipefail REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$REPO_ROOT" -VERSION="${1:-0.2.3}" +VERSION="${1:-0.2.4}" NAME="opendance-web-v${VERSION}" OUT_DIR="$REPO_ROOT/dist-release" STAGE="$OUT_DIR/$NAME" diff --git a/tasks/005-model-upload.md b/tasks/005-model-upload.md index acfbe63..31c8b56 100644 --- a/tasks/005-model-upload.md +++ b/tasks/005-model-upload.md @@ -160,7 +160,7 @@ node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-ru ```bash cd web-server -npx vitest run # 13 个文件 / 205 项通过 +npx vitest run # 14 个文件 / 211 项通过 npm run test:smoke # 冒烟 [4] 段落 ``` diff --git a/tasks/007-upload-review.md b/tasks/007-upload-review.md index 20faf56..878d8d5 100644 --- a/tasks/007-upload-review.md +++ b/tasks/007-upload-review.md @@ -86,7 +86,7 @@ draft ──submit──▶ pending ──approve──▶ published ```bash cd web-server -npx vitest run # 13 个文件 / 205 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项） +npx vitest run # 14 个文件 / 211 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项、缩略图贴图 6 项） npm run test:smoke ``` diff --git a/web-server/admin/package.json b/web-server/admin/package.json index 76a26ee..1ae1425 100644 --- a/web-server/admin/package.json +++ b/web-server/admin/package.json @@ -1,7 +1,7 @@ { "name": "opendance-admin", "private": true, - "version": "0.2.3", + "version": "0.2.4", "type": "module", "description": "OpenDance Studio 管理端（React + TypeScript + Vite）", "scripts": { diff --git a/web-server/package.json b/web-server/package.json index 9eedccc..afa9139 100644 --- a/web-server/package.json +++ b/web-server/package.json @@ -1,6 +1,6 @@ { "name": "opendance-web-server", - "version": "0.2.3", + "version": "0.2.4", "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）", "license": "MIT", "private": true, diff --git a/web-server/src/models/model-thumbnail.ts b/web-server/src/models/model-thumbnail.ts index f96782b..f1e7bb9 100644 --- a/web-server/src/models/model-thumbnail.ts +++ b/web-server/src/models/model-thumbnail.ts @@ -1,4 +1,5 @@ import { readFile } from 'node:fs/promises'; +import { inflateSync } from 'node:zlib'; import { dirname, resolve as resolvePath } from 'node:path'; import { deflateSync } from 'node:zlib'; @@ -22,9 +23,12 @@ import { deflateSync } from 'node:zlib'; * **退化为不蒙皮**，按节点世界矩阵画绑定姿态（bind pose）——多数 VRM 的绑定姿态 * 就是可看的 T/A 姿态，比错误的蒙皮矩阵导致的"爆炸形状"安全得多。 * - 按 glTF 规范，蒙皮网格节点自身的变换被忽略（顶点直接由关节矩阵驱动）。 - * 2. **不采样贴图**：`pbrMetallicRoughness.baseColorFactor` 作为纯色基色， - * 即使存在 `baseColorTexture` 也不解码（避免再引入 PNG/JPEG 解码器）， - * 因此带贴图的模型缩略图会是纯色块，但轮廓与光影正确。 + * 2. **采样 baseColorTexture**：内置极简 PNG 解码器（zlib + 反滤波，8 位、非隔行、 + * colorType 0/2/3/4/6），按 `baseColorFactor x 贴图` 逐像素取色，并按 + * `alphaMode`（OPAQUE / MASK / BLEND）处理透明度。 + * 这一版之前**不采样贴图**：MMD 模型（PMX 转换而来）的 `baseColorFactor` 几乎 + * 都是白色，于是缩略图全是"白模"——用户报的正是这个。 + * 解码失败/非 PNG/隔行扫描时回退为 `baseColorFactor` 纯色，绝不抛错。 * 3. **稀疏 accessor（sparse）不支持**：遇到就直接跳过该 primitive。 * 4. **只画三角形（mode=4）**，其余图元（点/线/条带/扇形）跳过。 * 5. 大模型（>17M 索引）不会出现，索引统一按 uint32 读取。 @@ -70,7 +74,8 @@ const DEFAULT_BACKGROUND: [number, number, number] = [24, 26, 32]; /** 垂直视场角（度） */ const FOV_Y_DEG = 35; /** 相机距离系数：让模型占画面约 1/1.6，保证不裁剪 */ -const FRAMING = 1.6; +// 1.6 -> 1.3：列表页只有 40px，主体太小就只剩一团像素 +const FRAMING = 1.3; /** 主光方向（世界空间，未归一化，用前会归一化） */ const LIGHT_DIR: [number, number, number] = normalize3(0.4, 0.8, 0.6); /** 环境光强度 */ @@ -244,8 +249,27 @@ interface GltfSkin { interface GltfMaterial { pbrMetallicRoughness?: { baseColorFactor?: number[]; - baseColorTexture?: unknown; + baseColorTexture?: { index?: number; texCoord?: number }; }; + alphaMode?: string; + alphaCutoff?: number; + doubleSided?: boolean; +} + +interface GltfTexture { + source?: number; + sampler?: number; +} + +interface GltfImage { + bufferView?: number; + mimeType?: string; + uri?: string; +} + +interface GltfSampler { + wrapS?: number; + wrapT?: number; } interface GltfScene { @@ -262,6 +286,9 @@ interface GltfDocument { bufferViews?: GltfBufferView[]; buffers?: GltfBufferRef[]; materials?: GltfMaterial[]; + textures?: GltfTexture[]; + images?: GltfImage[]; + samplers?: GltfSampler[]; skins?: GltfSkin[]; } @@ -278,9 +305,26 @@ interface AccessorData { } /** 收集好的三角形：positions 每 9 个数一个三角形，colors 每 3 个数一个三角形 */ +interface DecodedImage { + width: number; + height: number; + /** RGBA，行优先，长度 = width*height*4 */ + rgba: Uint8Array; +} + interface SceneGeometry { positions: Float32Array; colors: Float32Array; + /** 每顶点 UV（2 个/顶点）；没有 TEXCOORD_0 时为 null */ + uvs: Float32Array | null; + /** 每顶点贴图槽位（索引进 textures）；-1 表示该顶点无贴图 */ + texSlots: Int32Array | null; + /** 每顶点 alpha 模式：0=OPAQUE 1=MASK 2=BLEND */ + alphaModes: Uint8Array | null; + /** 每顶点 MASK 阈值 */ + cutoffs: Float32Array | null; + /** 解码后的贴图（RGBA） */ + textures: DecodedImage[]; triangleCount: number; } @@ -667,6 +711,36 @@ function materialBaseColor(doc: GltfDocument, materialIndex: number | undefined) return [0.8, 0.8, 0.8]; } +/** 取 bufferView 的原始字节（贴图解压用）；越界返回 null */ +function readBufferViewBytes( + doc: GltfDocument, + buffers: Array, + bufferViewIndex: number, +): Buffer | null { + const view = doc.bufferViews?.[bufferViewIndex]; + if (!view || typeof view.buffer !== 'number') return null; + const buffer = buffers[view.buffer]; + if (!buffer) return null; + const offset = view.byteOffset ?? 0; + const length = view.byteLength ?? 0; + if (offset < 0 || length <= 0 || offset + length > buffer.length) return null; + return buffer.subarray(offset, offset + length); +} + +/** 解码 GLB 内嵌的 PNG 贴图；外部 uri / 非 PNG / 解码失败都返回 null（回退纯色） */ +function decodeEmbeddedImage( + doc: GltfDocument, + buffers: Array, + imageIndex: number, +): DecodedImage | null { + const image = doc.images?.[imageIndex]; + if (!image || typeof image.bufferView !== 'number') return null; + if (typeof image.mimeType === 'string' && !image.mimeType.toLowerCase().includes('png')) return null; + const bytes = readBufferViewBytes(doc, buffers, image.bufferView); + if (!bytes) return null; + return decodePng(bytes); +} + /** 遍历场景图收集世界空间三角形 */ function collectTriangles(container: GltfContainer): SceneGeometry | null { const { doc, buffers } = container; @@ -676,8 +750,49 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null { const positions: number[] = []; const colors: number[] = []; + const uvs: number[] = []; + const texSlots: number[] = []; + const alphaModes: number[] = []; + const cutoffs: number[] = []; + const textures: DecodedImage[] = []; + const materialTextureCache = new Map(); + const imageCache = new Map(); const skinScratch = new Float64Array(16); + /** + * 解析材质的 baseColorTexture：解码一次并登记槽位。 + * MMD 模型的 baseColorFactor 基本都是白色，颜色全在贴图里 —— 不解码就是"白模"。 + */ + const resolveMaterialTexture = ( + materialIndex: number | undefined, + ): { slot: number; alphaMode: number; cutoff: number } => { + const key = typeof materialIndex === 'number' ? materialIndex : -1; + const cached = materialTextureCache.get(key); + if (cached) return cached; + const material = typeof materialIndex === 'number' ? doc.materials?.[materialIndex] : undefined; + const alphaMode = material?.alphaMode === 'MASK' ? 1 : material?.alphaMode === 'BLEND' ? 2 : 0; + const rawCutoff = typeof material?.alphaCutoff === 'number' ? material.alphaCutoff : 0.5; + const cutoff = clamp(rawCutoff, 0, 1); + let slot = -1; + const textureIndex = material?.pbrMetallicRoughness?.baseColorTexture?.index; + if (typeof textureIndex === 'number') { + const imageIndex = doc.textures?.[textureIndex]?.source; + if (typeof imageIndex === 'number') { + if (!imageCache.has(imageIndex)) { + imageCache.set(imageIndex, decodeEmbeddedImage(doc, buffers, imageIndex)); + } + const image = imageCache.get(imageIndex) ?? null; + if (image) { + slot = textures.length; + textures.push(image); + } + } + } + const resolved = { slot, alphaMode, cutoff }; + materialTextureCache.set(key, resolved); + return resolved; + }; + const appendMesh = (nodeIndex: number): void => { const node = nodes[nodeIndex]; if (!node || typeof node.mesh !== 'number') return; @@ -710,6 +825,10 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null { const vertexCount = positionData.count; const [cr, cg, cb] = materialBaseColor(doc, primitive.material); + const materialTexture = resolveMaterialTexture(primitive.material); + const uvData = + materialTexture.slot >= 0 ? readAccessorFloats(doc, buffers, attributes.TEXCOORD_0, 2) : null; + const usableUv = uvData && uvData.count === vertexCount ? uvData : null; // 顶点只变换一次：蒙皮或节点世界矩阵 const px = new Float64Array(vertexCount); @@ -758,6 +877,18 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null { } positions.push(x0, y0, z0, x1, y1, z1, x2, y2, z2); colors.push(cr, cg, cb); + if (usableUv) { + uvs.push( + usableUv.values[i0 * 2], usableUv.values[i0 * 2 + 1], + usableUv.values[i1 * 2], usableUv.values[i1 * 2 + 1], + usableUv.values[i2 * 2], usableUv.values[i2 * 2 + 1], + ); + } else { + uvs.push(0, 0, 0, 0, 0, 0); + } + texSlots.push(materialTexture.slot, materialTexture.slot, materialTexture.slot); + alphaModes.push(materialTexture.alphaMode, materialTexture.alphaMode, materialTexture.alphaMode); + cutoffs.push(materialTexture.cutoff, materialTexture.cutoff, materialTexture.cutoff); } } }; @@ -784,6 +915,11 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null { return { positions: Float32Array.from(positions), colors: Float32Array.from(colors), + uvs: Float32Array.from(uvs), + texSlots: Int32Array.from(texSlots), + alphaModes: Uint8Array.from(alphaModes), + cutoffs: Float32Array.from(cutoffs), + textures, triangleCount, }; } @@ -831,13 +967,25 @@ function edge(ax: number, ay: number, bx: number, by: number, px: number, py: nu * 屏幕空间有符号面积为负的是正面（NDC 里 CCW 正面经 y 翻转后变成负）， * 因此 cullBackFace 时丢弃 area >= 0 的三角形。 */ +/** 采样贴图（REPEAT 环绕；glTF/PNG 的 UV 原点在左上，v 不翻转） */ +function sampleTexture(image: DecodedImage, u: number, v: number, out: Float32Array): void { + const wrap = (value: number): number => value - Math.floor(value); + const x = Math.min(image.width - 1, Math.floor(wrap(u) * image.width)); + const y = Math.min(image.height - 1, Math.floor(wrap(v) * image.height)); + const o = (y * image.width + x) * 4; + out[0] = image.rgba[o] / 255; + out[1] = image.rgba[o + 1] / 255; + out[2] = image.rgba[o + 2] / 255; + out[3] = image.rgba[o + 3] / 255; +} + function rasterizeTriangles( geometry: SceneGeometry, viewProj: Mat4, options: RasterOptions, ): RasterOutput { const { size, background, cullBackFace } = options; - const { positions, colors, triangleCount } = geometry; + const { positions, colors, uvs, texSlots, alphaModes, cutoffs, textures, triangleCount } = geometry; const pixels = Buffer.alloc(size * size * 3); for (let i = 0; i < size * size; i += 1) { @@ -909,9 +1057,23 @@ function rasterizeTriangles( const baseR = colors[t * 3]; const baseG = colors[t * 3 + 1]; const baseB = colors[t * 3 + 2]; - const r = clamp(Math.round(baseR * intensity * 255), 0, 255); - const g = clamp(Math.round(baseG * intensity * 255), 0, 255); - const b = clamp(Math.round(baseB * intensity * 255), 0, 255); + + // 贴图与透明度（每三角形常量；顶点数组按 3 顶点/三角形展开） + const slot = texSlots ? texSlots[t * 3] : -1; + const image = slot >= 0 ? textures[slot] ?? null : null; + const alphaMode = alphaModes ? alphaModes[t * 3] : 0; + const cutoff = cutoffs ? cutoffs[t * 3] : 0.5; + const u0 = uvs ? uvs[t * 6] : 0; + const v0 = uvs ? uvs[t * 6 + 1] : 0; + const u1 = uvs ? uvs[t * 6 + 2] : 0; + const v1 = uvs ? uvs[t * 6 + 3] : 0; + const u2 = uvs ? uvs[t * 6 + 4] : 0; + const v2 = uvs ? uvs[t * 6 + 5] : 0; + const texel = new Float32Array(4); + // 透视校正用：1/w 在三个顶点上的值 + const iw0 = 1 / p0[3]; + const iw1 = 1 / p1[3]; + const iw2 = 1 / p2[3]; const invArea = 1 / area; for (let y = minY; y <= maxY; y += 1) { @@ -926,6 +1088,27 @@ function rasterizeTriangles( const d = w0 * p0[2] + w1 * p1[2] + w2 * p2[2]; const index = rowBase + x; if (d < depth[index]) { + let r = clamp(Math.round(baseR * intensity * 255), 0, 255); + let g = clamp(Math.round(baseG * intensity * 255), 0, 255); + let b = clamp(Math.round(baseB * intensity * 255), 0, 255); + if (image) { + const iw = w0 * iw0 + w1 * iw1 + w2 * iw2; + const u = (w0 * iw0 * u0 + w1 * iw1 * u1 + w2 * iw2 * u2) / (iw || 1); + const v = (w0 * iw0 * v0 + w1 * iw1 * v1 + w2 * iw2 * v2) / (iw || 1); + sampleTexture(image, u, v, texel); + if (alphaMode === 1 && texel[3] < cutoff) continue; // MASK：整像素丢弃 + const a = alphaMode === 0 ? 1 : texel[3]; + r = clamp(Math.round(baseR * texel[0] * intensity * 255), 0, 255); + g = clamp(Math.round(baseG * texel[1] * intensity * 255), 0, 255); + b = clamp(Math.round(baseB * texel[2] * intensity * 255), 0, 255); + if (alphaMode === 2 && a < 1) { + // BLEND：与背景/已画像素做 source-over（缩略图不做排序，够看即可） + const q = index * 3; + r = clamp(Math.round(r * a + pixels[q] * (1 - a)), 0, 255); + g = clamp(Math.round(g * a + pixels[q + 1] * (1 - a)), 0, 255); + b = clamp(Math.round(b * a + pixels[q + 2] * (1 - a)), 0, 255); + } + } depth[index] = d; const p = index * 3; pixels[p] = r; @@ -1045,6 +1228,133 @@ function buildViewProjection(geometry: SceneGeometry, size: number, yawDeg: numb return mat4Multiply(proj, view); } +// --------------------------------------------------------------------------- +// PNG 解码（缩略图要贴图才不是"白模"；只做 8 位非隔行，够用且零原生依赖） +// --------------------------------------------------------------------------- + +const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]); + +/** + * 极简 PNG 解码器：zlib 解压 + 逐行反滤波，输出 RGBA。 + * 不支持 16 位 / 隔行扫描 / 未知 colorType —— 返回 null 由调用方回退纯色。 + */ +function decodePng(buffer: Buffer): DecodedImage | null { + if (buffer.length < 8 + 25 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return null; + let offset = 8; + let width = 0; + let height = 0; + let bitDepth = 0; + let colorType = 0; + let interlace = 0; + let palette: Uint8Array | null = null; + let transparency: Uint8Array | null = null; + const idat: Buffer[] = []; + + while (offset + 8 <= buffer.length) { + const length = buffer.readUInt32BE(offset); + const type = buffer.toString('ascii', offset + 4, offset + 8); + const dataStart = offset + 8; + if (dataStart + length + 4 > buffer.length) return null; + const data = buffer.subarray(dataStart, dataStart + length); + if (type === 'IHDR') { + if (length < 13) return null; + width = data.readUInt32BE(0); + height = data.readUInt32BE(4); + bitDepth = data[8]; + colorType = data[9]; + interlace = data[12]; + } else if (type === 'PLTE') { + palette = new Uint8Array(data); + } else if (type === 'tRNS') { + transparency = new Uint8Array(data); + } else if (type === 'IDAT') { + idat.push(Buffer.from(data)); + } else if (type === 'IEND') { + break; + } + offset = dataStart + length + 4; + } + + if (bitDepth !== 8 || interlace !== 0) return null; + if (!(width > 0) || !(height > 0) || width * height > 64 * 1024 * 1024) return null; + if (idat.length === 0) return null; + + const channels = + colorType === 0 ? 1 : colorType === 2 ? 3 : colorType === 3 ? 1 : colorType === 4 ? 2 : colorType === 6 ? 4 : 0; + if (channels === 0) return null; + if (colorType === 3 && !palette) return null; + + let raw: Buffer; + try { + raw = inflateSync(Buffer.concat(idat)); + } catch { + return null; + } + const stride = width * channels; + if (raw.length < (stride + 1) * height) return null; + + const out = new Uint8Array(width * height * 4); + const line = new Uint8Array(stride); + const prev = new Uint8Array(stride); + let rawPos = 0; + for (let y = 0; y < height; y += 1) { + const filter = raw[rawPos]; + rawPos += 1; + for (let i = 0; i < stride; i += 1) { + const value = raw[rawPos + i]; + const left = i >= channels ? line[i - channels] : 0; + const up = prev[i]; + const upLeft = i >= channels ? prev[i - channels] : 0; + let restored: number; + switch (filter) { + case 0: restored = value; break; + case 1: restored = value + left; break; + case 2: restored = value + up; break; + case 3: restored = value + ((left + up) >> 1); break; + case 4: { + const p = left + up - upLeft; + const pa = Math.abs(p - left); + const pb = Math.abs(p - up); + const pc = Math.abs(p - upLeft); + restored = value + (pa <= pb && pa <= pc ? left : pb <= pc ? up : upLeft); + break; + } + default: return null; + } + line[i] = restored & 0xff; + } + rawPos += stride; + for (let x = 0; x < width; x += 1) { + const o = (y * width + x) * 4; + if (colorType === 6) { + out[o] = line[x * 4]; + out[o + 1] = line[x * 4 + 1]; + out[o + 2] = line[x * 4 + 2]; + out[o + 3] = line[x * 4 + 3]; + } else if (colorType === 2) { + out[o] = line[x * 3]; + out[o + 1] = line[x * 3 + 1]; + out[o + 2] = line[x * 3 + 2]; + out[o + 3] = 255; + } else if (colorType === 0) { + const g = line[x]; + out[o] = g; out[o + 1] = g; out[o + 2] = g; out[o + 3] = 255; + } else if (colorType === 4) { + const g = line[x * 2]; + out[o] = g; out[o + 1] = g; out[o + 2] = g; out[o + 3] = line[x * 2 + 1]; + } else { + const index = line[x]; + out[o] = palette![index * 3] ?? 0; + out[o + 1] = palette![index * 3 + 1] ?? 0; + out[o + 2] = palette![index * 3 + 2] ?? 0; + out[o + 3] = transparency && index < transparency.length ? transparency[index] : 255; + } + } + prev.set(line); + } + return { width, height, rgba: out }; +} + // --------------------------------------------------------------------------- // PNG 编码（8 位 RGB、无隔行、filter=0；不引第三方库） // --------------------------------------------------------------------------- @@ -1133,6 +1443,8 @@ export async function renderModelThumbnail( ) { throw new Error('缩略图背景色非法：需要 [r, g, b] 三个有限数字'); } + // 默认看**正面**：eye = 中心 + (sin yaw, .., cos yaw)*d，yaw=0 时相机在 +Z； + // MMD（PMX）与 VRM 1.0 都是 +Z 朝前，因此 -30 是"正面偏 30 度"的常规 3/4 视角 const yawDeg = options?.yawDeg ?? -30; const rawPitchDeg = options?.pitchDeg ?? 12; if (!Number.isFinite(yawDeg) || !Number.isFinite(rawPitchDeg)) { diff --git a/web-server/test/model-thumbnail-texture.spec.ts b/web-server/test/model-thumbnail-texture.spec.ts new file mode 100644 index 0000000..0d1a972 --- /dev/null +++ b/web-server/test/model-thumbnail-texture.spec.ts @@ -0,0 +1,232 @@ +import { mkdtempSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { inflateSync } from 'node:zlib'; +import { describe, expect, it } from 'vitest'; +import { renderModelThumbnail } from '../src/models/model-thumbnail'; + +/** + * 缩略图**贴图采样**测试。 + * + * 背景（真实故障）：缩略图渲染器原先刻意不解码 baseColorTexture，只用 + * `baseColorFactor` 上色；而 MMD（PMX 转换）模型的 baseColorFactor 基本全是白色， + * 于是缩略图全是"白模"——列表页与审核面板看到的都是白色模型，用户报的正是这个。 + * 现在渲染器内置 PNG 解码并逐像素采样贴图，这里锁住行为。 + */ + +const dir = mkdtempSync(join(tmpdir(), 'opendance-thumb-tex-')); + +function write(name: string, content: Buffer): string { + const path = join(dir, name); + writeFileSync(path, content); + return path; +} + +/** 12 字节头 + JSON chunk + BIN chunk */ +function buildGlb(json: unknown, bin: Buffer): Buffer { + const jsonRaw = Buffer.from(JSON.stringify(json), 'utf8'); + const jsonChunk = Buffer.concat([jsonRaw, Buffer.alloc((4 - (jsonRaw.length % 4)) % 4, 0x20)]); + const binChunk = Buffer.concat([bin, Buffer.alloc((4 - (bin.length % 4)) % 4)]); + const chunks: Buffer[] = []; + const header = Buffer.alloc(12); + header.write('glTF', 0, 'ascii'); + header.writeUInt32LE(2, 4); + chunks.push(header); + const jsonHeader = Buffer.alloc(8); + jsonHeader.writeUInt32LE(jsonChunk.length, 0); + jsonHeader.writeUInt32LE(0x4e4f534a, 4); + chunks.push(jsonHeader, jsonChunk); + const binHeader = Buffer.alloc(8); + binHeader.writeUInt32LE(binChunk.length, 0); + binHeader.writeUInt32LE(0x004e4942, 4); + chunks.push(binHeader, binChunk); + const out = Buffer.concat(chunks); + out.writeUInt32LE(out.length, 8); + return out; +} + +function float32Buffer(values: number[]): Buffer { + const buffer = Buffer.alloc(values.length * 4); + values.forEach((value, index) => buffer.writeFloatLE(value, index * 4)); + return buffer; +} + +function uint16Buffer(values: number[]): Buffer { + const buffer = Buffer.alloc(values.length * 2); + values.forEach((value, index) => buffer.writeUInt16LE(value, index * 2)); + return buffer; +} + +/* ------------------------------------------------------------ 贴图夹具 */ + +/** 2x2 纯红（colorType 6，带 alpha=255） */ +const RED_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8DwH4QZYAwAR8oH+WdZbrcAAAAASUVORK5CYII=', + 'base64', +); +/** 2x2 纯绿（colorType 2，无 alpha） */ +const GREEN_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAD0lEQVR4nGNg+M8AQhAKABvyA/1tVLjHAAAAAElFTkSuQmCC', + 'base64', +); +/** 2x2 全透明（RGBA 的 alpha=0） */ +const TRANSPARENT_PNG = Buffer.from( + 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8DAAMIMMAYAKegD/QE6Y34AAAAASUVORK5CYII=', + 'base64', +); + +interface QuadOptions { + texture?: Buffer; + mimeType?: string; + baseColorFactor?: number[]; + alphaMode?: string; +} + +/** 一个正对相机（+Z）的方形面片，UV 铺满贴图；baseColorFactor 默认纯白（MMD 的常见情况） */ +function texturedQuadGlb(options: QuadOptions = {}): Buffer { + const positions = [-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0]; + const uvs = [0, 1, 1, 1, 1, 0, 0, 0]; + const indices = [0, 1, 2, 0, 2, 3]; + const posBin = float32Buffer(positions); + const uvBin = float32Buffer(uvs); + const idxBin = uint16Buffer(indices); + const image = options.texture ?? RED_PNG; + const bin = Buffer.concat([posBin, uvBin, idxBin, image]); + const imageOffset = posBin.length + uvBin.length + idxBin.length; + + const json = { + asset: { version: '2.0' }, + scene: 0, + scenes: [{ nodes: [0] }], + nodes: [{ mesh: 0 }], + meshes: [{ primitives: [{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0 }] }], + materials: [ + { + pbrMetallicRoughness: { + baseColorFactor: options.baseColorFactor ?? [1, 1, 1, 1], + baseColorTexture: { index: 0 }, + }, + ...(options.alphaMode ? { alphaMode: options.alphaMode, alphaCutoff: 0.5 } : {}), + }, + ], + textures: [{ source: 0 }], + images: [{ bufferView: 3, mimeType: options.mimeType ?? 'image/png' }], + accessors: [ + { bufferView: 0, componentType: 5126, count: 4, type: 'VEC3' }, + { bufferView: 1, componentType: 5126, count: 4, type: 'VEC2' }, + { bufferView: 2, componentType: 5123, count: 6, type: 'SCALAR' }, + ], + bufferViews: [ + { buffer: 0, byteOffset: 0, byteLength: posBin.length }, + { buffer: 0, byteOffset: posBin.length, byteLength: uvBin.length }, + { buffer: 0, byteOffset: posBin.length + uvBin.length, byteLength: idxBin.length }, + { buffer: 0, byteOffset: imageOffset, byteLength: image.length }, + ], + buffers: [{ byteLength: bin.length }], + }; + return buildGlb(json, bin); +} + +/** 解 PNG（我们自己写的编码器：8 位 RGB、filter=0），返回平均 RGB */ +function averageColor(png: Buffer): { r: number; g: number; b: number; nonBackground: number } { + let offset = 8; + let width = 0; + let height = 0; + const idat: Buffer[] = []; + while (offset + 8 <= png.length) { + const length = png.readUInt32BE(offset); + const type = png.toString('ascii', offset + 4, offset + 8); + const data = png.subarray(offset + 8, offset + 8 + length); + if (type === 'IHDR') { + width = data.readUInt32BE(0); + height = data.readUInt32BE(4); + expect(data[8]).toBe(8); + expect(data[9]).toBe(2); + expect(data[12]).toBe(0); + } else if (type === 'IDAT') { + idat.push(Buffer.from(data)); + } else if (type === 'IEND') { + break; + } + offset += 12 + length; + } + const raw = inflateSync(Buffer.concat(idat)); + let r = 0; + let g = 0; + let b = 0; + let count = 0; + let nonBackground = 0; + for (let y = 0; y < height; y += 1) { + const rowStart = y * (1 + width * 3); + expect(raw[rowStart]).toBe(0); // filter=0 + for (let x = 0; x < width; x += 1) { + const i = rowStart + 1 + x * 3; + r += raw[i]; + g += raw[i + 1]; + b += raw[i + 2]; + count += 1; + // 默认背景是 [24,26,32]（深色）；明显偏离即视为主体像素 + if (Math.abs(raw[i] - 24) > 12 || Math.abs(raw[i + 1] - 26) > 12 || Math.abs(raw[i + 2] - 32) > 12) { + nonBackground += 1; + } + } + } + return { r: r / count, g: g / count, b: b / count, nonBackground }; +} + +async function render(glb: Buffer, name: string, extra: Record = {}) { + const result = await renderModelThumbnail(write(name, glb), { size: 128, ...extra }); + expect(result).not.toBeNull(); + return averageColor((result as { png: Buffer }).png); +} + +/* ------------------------------------------------------------------ 测试 */ + +describe('缩略图贴图采样', () => { + it('baseColorFactor 全白时也按贴图上色（回归：不再输出"白模"）', async () => { + const color = await render(texturedQuadGlb(), 'red.glb'); + expect(color.nonBackground).toBeGreaterThan(0); + // 贴图是纯红：主体像素整体应明显偏红 + expect(color.r).toBeGreaterThan(color.g + 20); + expect(color.r).toBeGreaterThan(color.b + 20); + }); + + it('colorType 2（无 alpha 通道）的 PNG 也能解码', async () => { + const color = await render(texturedQuadGlb({ texture: GREEN_PNG }), 'green.glb'); + expect(color.g).toBeGreaterThan(color.r + 20); + expect(color.g).toBeGreaterThan(color.b + 20); + }); + + it('OPAQUE：忽略贴图 alpha（MMD 语义，alpha=0 也照样画出来）', async () => { + const color = await render( + texturedQuadGlb({ texture: TRANSPARENT_PNG, baseColorFactor: [0.9, 0.1, 0.1, 1] }), + 'opaque.glb', + ); + expect(color.nonBackground).toBeGreaterThan(0); + expect(color.r).toBeGreaterThan(color.g + 20); + }); + + it('MASK：alpha 低于阈值的主体像素被丢弃（只剩背景）', async () => { + const color = await render( + texturedQuadGlb({ texture: TRANSPARENT_PNG, baseColorFactor: [0.9, 0.1, 0.1, 1], alphaMode: 'MASK' }), + 'mask.glb', + ); + expect(color.nonBackground).toBe(0); + }); + + it('贴图解码失败时回退 baseColorFactor 纯色，且不抛错', async () => { + const broken = Buffer.from('这不是 PNG 数据', 'utf8'); + const color = await render( + texturedQuadGlb({ texture: broken, baseColorFactor: [0.1, 0.1, 0.9, 1] }), + 'broken.glb', + ); + expect(color.nonBackground).toBeGreaterThan(0); + expect(color.b).toBeGreaterThan(color.r + 20); + }); + + it('默认视角是正面（相机在 +Z）：+Z 面颜色明显主导', async () => { + // 面片正对 +Z，默认视角下必须看得见（若默认看背面，主体像素会接近 0） + const color = await render(texturedQuadGlb(), 'front.glb'); + expect(color.nonBackground).toBeGreaterThan(128 * 128 * 0.05); + }); +});