opendance
60c182f1b2
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则 （analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记， 且 _common 表恒定生效），把说明文档中会被标记的全角标点 （，：；？！（） 等）改为半角，并保证成对括号宽度一致。 中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。 同时删除临时探针目录 _probe/（仅用于确认 Gitea 判定规则）。
99 lines
5.0 KiB
Markdown
99 lines
5.0 KiB
Markdown
# T-WEB-006 BVH/VMD/FBX -> 关键点序列预处理
|
|
|
|
- **状态**: done
|
|
- **依赖**: T-WEB-004
|
|
|
|
## 目标
|
|
|
|
把上传的 3D 动作数据（BVH / VMD / FBX / glTF / keypoints-json）转换为与 Android
|
|
端输出**同构**的 MediaPipe 33 点关键点序列，使 Windows 端 DTW 引擎只有一条输入通路。
|
|
|
|
## load
|
|
|
|
```
|
|
DSH.md
|
|
contracts/model-formats.md # 锚点：2 动作格式、2.1 预处理产物、2.2 关节名映射、2.3 VMD
|
|
contracts/skeleton-topology.md # 锚点：1 33 点、3 父节点表、5 关节角
|
|
web-server/src/preprocess/*
|
|
```
|
|
|
|
## 端点
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|--|--|--|
|
|
| POST | `/api/motions/:id/preprocess` | 执行预处理，返回更新后的 Motion |
|
|
| GET | `/api/motions/:id/keypoints` | 下载 NDJSON 关键点序列 |
|
|
|
|
## 实现分层
|
|
|
|
| 文件 | 职责 |
|
|
|--|--|
|
|
| `bvh-parser.ts` | 纯 TS BVH 词法/语法解析 + 逐帧前向运动学(FK) |
|
|
| `vmd-parser.ts` | VMD 二进制解析：30 字节头 + Shift-JIS 模型名 + 111 字节/条骨骼关键帧 + morph 段；MMD 贝塞尔插值，固定 30fps |
|
|
| `mmd-skeleton.ts` | 标准 MMD 骨架（含全角/半角 `ＩＫ`/`IK` 别名归一）；静止比例从参考 PMX 实测 |
|
|
| `mmd-pose.ts` | MMD FK + 两骨骼解析腿部 IK + 左手系->右手系 Z 镜像，输出逐帧世界坐标 |
|
|
| `math3d.ts` | 向量/矩阵工具、旋转合成、关节角余弦 |
|
|
| `joint-map.ts` | 关节名 -> MediaPipe 点索引的默认映射表 |
|
|
| `retarget.ts` | 导出的 `worldFramesToKeypointFrames()`：任意骨架世界坐标 -> 骨盆归零 -> 自适应缩放 -> 投影 -> 9 个关节角；BVH 与 VMD 共用 |
|
|
| `keypoint-codec.ts` | 239 字节二进制帧编解码、NDJSON 序列化/解析、关键点 JSON 校验 |
|
|
| `assimp.ts` | 可选外部 Assimp 调用(FBX/glTF -> BVH) |
|
|
| `preprocess.service.ts` | 编排、落盘、状态与错误记录 |
|
|
|
|
## 拓扑与缩放（契约冻结）
|
|
|
|
- 33 点顺序与父节点表来自 `contracts/skeleton-topology.md`，虚拟关节
|
|
`neck=33`、`pelvis=34` 只参与关节角计算，**不进入输出序列**。
|
|
- 投影：`x_img = 0.5 + x s`, `y_img = 0.5 - y s`, `z_img = -z s`,
|
|
`s = 0.35 / max(|x|,|y|,|z|)`（按整段动作自适应，保证不出画）。
|
|
- 置信度分层：直接映射 **1.0**、按层级推算 **0.5**、无法推算 **0.0**。
|
|
|
|
## 格式支持
|
|
|
|
| 格式 | 处理 |
|
|
|--|--|
|
|
| `.bvh` | 内置解析器，无外部依赖 |
|
|
| `.vmd` | 内置解析器，无外部依赖；固定 30fps，见「VMD 通路」 |
|
|
| `.json` | 直通校验与规范化(须符合 `mediapipe33@0.1.0`) |
|
|
| `.fbx` `.gltf` `.glb` | 调用可选 Assimp 转 BVH；未安装 Assimp 时写入可读错误并置 `preprocessState=failed` |
|
|
|
|
## VMD 通路
|
|
|
|
```
|
|
.vmd ─▶ vmd-parser.ts ─▶ mmd-skeleton.ts ─▶ mmd-pose.ts ─▶ retarget.ts
|
|
二进制 + Shift-JIS 标准 MMD 骨架 FK + 腿部 IK worldFramesToKeypointFrames()
|
|
+ 贝塞尔插值 + Z 镜像 （与 BVH 共用）
|
|
```
|
|
|
|
- VMD 不含骨骼长度、只有旋转（少数骨骼带位移），必须靠 `mmd-skeleton.ts` 的
|
|
标准骨架做 FK；骨骼名按别名表归一（全角 `ＩＫ` / 半角 `IK`），未纳入标准骨架的
|
|
骨骼（裙摆 / 物理 / 表情等）被忽略但计数。
|
|
- **腿部驱动自动判定**: `足ＩＫ` 轨道存在非零位移 -> 两骨骼解析 IK（膝盖朝角色
|
|
正面弯，目标不可达时收敛为伸直，不产生 NaN）；否则走 FK 旋转（部分动作数据把
|
|
腿烘焙成 FK）。
|
|
- **手性**: MMD 为左手系，统一做 Z 镜像（旋转 `(x,y,z,w) -> (-x,-y,z,w)`、位移 z
|
|
取反）后进入右手系通路。由真实数据对照实验确定：腿部烘焙为 FK 的样本中，
|
|
`zMirrored` 下「膝盖朝前」占 94.1%，不转换仅 5.9%（见 `test/mmd-vmd.spec.ts`）。
|
|
- 重定向**完全复用 BVH 通路**: `worldFramesToKeypointFrames()` 负责骨盆归零 /
|
|
自适应缩放 / 图像空间投影 / 9 个关节角，因此两种来源的产物结构一致。
|
|
- 固定 **30 fps**，上传时填写的 `fps` 被忽略。
|
|
|
|
## 验收
|
|
|
|
```bash
|
|
npm run test # 85 例（含 31 例 VMD）：解析 / FK / 重定向 / 编解码 / 拓扑 / 契约版本
|
|
npm run test:smoke # 冒烟 [3] 段落
|
|
```
|
|
|
|
覆盖：60 帧样例经预处理后 **60 帧 x 33 点 x 9 关节角**、坐标落在
|
|
MediaPipe 归一化范围、置信度分层、时间戳按帧率推进、序列随时间变化、
|
|
NDJSON 往返、解码器拒绝错误长度与 magic。
|
|
|
|
VMD 侧另测：二进制解析与截断报错、贝塞尔/四元数插值、标准骨架比例与镜像、
|
|
FK 与腿部 IK（可达/不可达/退化）、手性对照、合成 VMD 端到端 0 NaN / 0 越界。
|
|
|
|
两个真实样本实测（`../示例文件/`）：`【动作】霜雪千年.vmd` 2901 帧(腿部 IK)
|
|
约 0.4s、`恋爱循环.vmd` 4604 帧（烘焙 FK）约 2.5s，均 0 NaN / 0 越界。
|
|
|
|
样例数据由 `test/fixtures/generate-sample-bvh.mjs` 生成（60 帧挥手 + 深蹲，
|
|
21 关节 / 63 通道），可复现；VMD 诊断可用 `scripts/inspect-vmd.mjs`。
|