zijunchiang
9f7b926a9a
- README.md / README.txt 新增初次部署章节：前置条件、获取代码、首次运行、 配置服务端地址（API 3000 / 管理端 3001 分离）、与 Android 的 WebSocket 联通、 打包导出、自检清单、常见问题 - 三库同源契约：':=' 写法修回、去掉真实 MariaDB 版本串 - 全文去除易被 Gitea 判为「模棱两可 Unicode」的字符（- - ... -> 取代 — – … § →） - 真实内网地址与库名改占位符
47 lines
1.3 KiB
Markdown
47 lines
1.3 KiB
Markdown
# T-WIN-004 239 字节帧反序列化
|
||
|
||
- **状态**：done
|
||
- **依赖**：T-WIN-001
|
||
|
||
## 目标
|
||
|
||
按契约实现 239 字节关键点帧的编解码。
|
||
|
||
## load
|
||
|
||
```
|
||
DSH.md
|
||
contracts/websocket-keypoints.md # 锚点：2 二进制帧（冻结）
|
||
contracts/skeleton-topology.md # 锚点：4 坐标系
|
||
src/net/keypoint_frame.gd
|
||
```
|
||
|
||
## 帧布局（契约冻结）
|
||
|
||
```
|
||
偏移 长度 字段
|
||
0 2 magic u16 = 0x4F44 ('OD')
|
||
2 1 version u8 = 1
|
||
3 1 flags u8 bit0 镜像 bit1 低置信度 bit2 上半身
|
||
4 4 frame_id u32 LE
|
||
8 231 keypoints 33 × 7B：s16 x, s16 y, s16 z, u8 conf
|
||
合计 239
|
||
```
|
||
|
||
## 交付物
|
||
|
||
`src/net/keypoint_frame.gd`：`PoseFrame` 内部类 + `decode` / `encode` / `validate` / `from_json_dict`。
|
||
|
||
## 关键实现
|
||
|
||
- 归一化系数统一 32767，与 opendance-web 的 TypeScript 参考实现逐位对齐
|
||
- 编解码往返误差 < 1e-4（定点精度 1/32767 ≈ 3.05e-5）
|
||
- `unmirrored_points()` 按 flags.bit0 翻转 x
|
||
- 低置信度阈值 0.5：`is_reliable()` 与 `compute_low_confidence()`
|
||
- 极值（±1.0）不溢出 int16
|
||
|
||
## 验收
|
||
|
||
`tests/test_keypoint_frame.gd`：常量与契约一致、239 字节、magic/version/flags/frame_id、
|
||
往返精度、错误长度/magic/版本拒绝、极值、镜像翻转、置信度阈值、JSON 调试帧。
|