opendance-windows/tasks/004-keypoint-deserialize.md

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 x 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 调试帧。