# contracts/skeleton-topology.md — 骨骼拓扑契约 v0.1.0

**唯一拓扑：MediaPipe Pose 33 点。禁止引入 SMPL 及其衍生拓扑（许可风险）。**

## 1. 33 点定义与索引

| idx | name | 中文 | 说明 |
|---|---|---|---|
| 0 | nose | 鼻 | |
| 1 | left_eye_inner | 左眼内 | |
| 2 | left_eye | 左眼 | |
| 3 | left_eye_outer | 左眼外 | |
| 4 | right_eye_inner | 右眼内 | |
| 5 | right_eye | 右眼 | |
| 6 | right_eye_outer | 右眼外 | |
| 7 | left_ear | 左耳 | |
| 8 | right_ear | 右耳 | |
| 9 | mouth_left | 左嘴角 | |
| 10 | mouth_right | 右嘴角 | |
| 11 | left_shoulder | 左肩 | |
| 12 | right_shoulder | 右肩 | |
| 13 | left_elbow | 左肘 | |
| 14 | right_elbow | 右肘 | |
| 15 | left_wrist | 左腕 | |
| 16 | right_wrist | 右腕 | |
| 17 | left_pinky | 左小指 | |
| 18 | right_pinky | 右小指 | |
| 19 | left_index | 左食指 | |
| 20 | right_index | 右食指 | |
| 21 | left_thumb | 左拇指 | |
| 22 | right_thumb | 右拇指 | |
| 23 | left_hip | 左髋 | |
| 24 | right_hip | 右髋 | |
| 25 | left_knee | 左膝 | |
| 26 | right_knee | 右膝 | |
| 27 | left_ankle | 左踝 | |
| 28 | right_ankle | 右踝 | |
| 29 | left_heel | 左足跟 | |
| 30 | right_heel | 右足跟 | |
| 31 | left_foot_index | 左足尖 | |
| 32 | right_foot_index | 右足尖 | |

## 2. 虚拟关节（由 33 点派生，索引 33/34，仅用于层级与角度特征）

| idx | name | 计算 |
|---|---|---|
| 33 | neck | `midpoint(left_shoulder(11), right_shoulder(12))` |
| 34 | pelvis | `midpoint(left_hip(23), right_hip(24))` |

## 3. 父节点表（`parent[i]`，-1 表示世界根）

对称树，便于骨骼重定向与关节角计算：

```
34 pelvis             -> -1 (world root)
33 neck               -> 34
23 left_hip           -> 34
24 right_hip          -> 34
11 left_shoulder      -> 33
12 right_shoulder     -> 33
0  nose               -> 33
1  left_eye_inner     -> 0
2  left_eye           -> 0
3  left_eye_outer     -> 0
4  right_eye_inner    -> 0
5  right_eye          -> 0
6  right_eye_outer    -> 0
7  left_ear           -> 3
8  right_ear          -> 6
9  mouth_left         -> 0
10 mouth_right        -> 0
25 left_knee          -> 23
26 right_knee         -> 24
27 left_ankle         -> 25
28 right_ankle        -> 26
29 left_heel          -> 27
30 right_heel         -> 28
31 left_foot_index    -> 29
32 right_foot_index   -> 30
13 left_elbow         -> 11
14 right_elbow        -> 12
15 left_wrist         -> 13
16 right_wrist         -> 14
17 left_pinky         -> 15
18 right_pinky         -> 16
19 left_index         -> 15
20 right_index        -> 16
21 left_thumb         -> 15
22 right_thumb        -> 16
```

## 4. 坐标系

- **归一化图像坐标**：`x, y ∈ [0, 1]`，原点左上角，`y` 向下；`x` 相对图像宽，`y` 相对图像高。
- **深度**：`z` 与 `x` 同尺度，原点位于髋中心，**负值朝向相机**。
- **镜像**：Android 前置摄像头默认输出镜像画面；是否镜像由帧头 `flags.bit0` 声明，
  接收端据此决定是否翻转 `x`（`x' = 1 - x`）。
- **置信度**：`visibility ∈ [0, 1]`，落盘/传输为 `uint8`（`round(v * 255)`）。
  归一化比例统一使用 `32767`（见 `websocket-keypoints.md`）。

## 5. 派生特征（DTW 输入，Windows 端实现，服务端预处理产物同构）

服务端 T-WEB-006 预处理产出的关键点序列与 Android 端输出的帧**结构完全一致**，
因此 Windows 端 DTW 引擎只有一条输入通路。

关节角特征（弧度，余弦值便于插值）：

```
shoulder_L = angle(left_elbow,  left_shoulder,  left_hip)
shoulder_R = angle(right_elbow, right_shoulder, right_hip)
elbow_L    = angle(left_shoulder,  left_elbow,  left_wrist)
elbow_R    = angle(right_shoulder, right_elbow, right_wrist)
hip_L      = angle(left_shoulder,  left_hip,    left_knee)
hip_R      = angle(right_shoulder, right_hip,   right_knee)
knee_L     = angle(left_hip,   left_knee,  left_ankle)
knee_R     = angle(right_hip,  right_knee, right_ankle)
neck       = angle(nose, neck, pelvis)
spine      = angle(neck, pelvis, midpoint(left_ankle, right_ankle))
```

`angle(a, b, c)` = 向量 `ba` 与 `bc` 的夹角余弦，即
`dot(normalize(a-b), normalize(c-b))`，落在 `[-1, 1]`。

**DTW 序列结构（冻结）**：每帧 = `[33 × (x, y, z), 9 个关节角余弦] = 108 维`。
低置信度点（`visibility < 0.5`）在插值阶段由相邻帧线性补全，不参与代价计算。