人员 3D 轨迹

在浏览器中用 Three.js 搭建地面坐标系场景，把后台 YOLO + ByteTrack 检测出的人员，按标定后的地面直角坐标 (ground_x, ground_y)（单位：米）映射到 3D 世界中，用骨骼模型实时表现位置、朝向、步态，并绘制行走轨迹线。

1. 使用前准备

1. 完成地面标定
   在 / 标定页完成标定点并保存。3D 落点依赖 Homography 变换；未标定则无法得到正确的地面坐标。

2. 配置视频源
   config/config.yaml 中配置 RTSP / 本地视频 / 摄像头，与监控页相同。

3. 启动 Web 服务
   按 README 启动后，浏览器打开 /trajectory。

4. 网络与模型

   • 页面通过 importmap 从 unpkg 加载 Three.js 0.160.0（需能访问外网，或自行改为本地静态资源）。
   • 人物模型路径：/static/models/Human.glb（含 Idle / Walk / Run 等动画）。

2. 快速上手

1. 打开 http://127.0.0.1:8080/trajectory
2. 确认已完成标定
3. 点击 开始检测
   • 初始化 3D 场景（地面、网格、坐标轴、刻度）
   • 加载 Human.glb
   • 调用 POST /api/detect/start 启动后台检测
   • 连接 ws://…/ws/detect 接收人员列表
   • 右下角显示监控画面画中画（MJPEG）
4. 观察 3D 模型出场、移动、轨迹线与右侧人员列表
5. 点击 停止 结束检测并清理场景中的人员模型

3. 界面布局

┌─────────────────────────────────────────────────────────────┐
│  标题：3D 人员轨迹          [标定] [实时监控] [3D 轨迹]      │
├──────────────────────────────────────────────┬──────────────┤
│  工具栏：开始/停止/重置视角/清空轨迹/开关…    │  当前人员    │
│                                              │  （列表）    │
│  ┌────────────────────────────────────────┐  │              │
│  │           3D 视口 (viewport)           │  │  坐标说明    │
│  │                                        │  │              │
│  │                    ┌──────────┐        │  │              │
│  │                    │ 画中画   │        │  │              │
│  │                    └──────────┘        │  │              │
│  └────────────────────────────────────────┘  │              │
└──────────────────────────────────────────────┴──────────────┘

3.1 工具栏按钮与开关

3.2 画中画（PiP）

• 源：GET /api/detect/stream（与监控页相同的 MJPEG）
• 点击画中画或右上角按钮可放大/缩小；Esc 退出放大
• 用于对照「真实视频」与「3D 地面映射」是否一致

3.3 侧栏「当前人员」

每条展示：

• #person_id
• 相对原点的 ground_x、ground_y（米）
• 速度（m/s）与方向文案（靠近 / 远离 / 静止 / 未知）
• 若开启「衣物贴图」且该 ID 有外观缓存，显示缩略图

3.4 侧栏「坐标说明」

页面内嵌简要说明：原点 O、x/y 含义，以及到 Three.js 世界坐标的映射（详见下一节）。

4. 坐标系（务必理解）

4.1 标定地面坐标（业务坐标）

检测与运动分析使用的是相对标定原点 O 的地面直角坐标，不是极径距离 D：

脚点：检测框底部中心 → Homography → (ground_x, ground_y)，再经卡尔曼平滑。

4.2 Three.js 世界坐标

映射约定（代码中 toWorldPos）：

worldX = -ground_x
worldY = 0          （人站在地面上，竖直向上为 +Y）
worldZ =  ground_y

对 ground_x 取反，是为了从场景深处（世界 +Z）往回看时，左右与监控画面一致。

场景辅助元素：

• 80m × 80m 地面 + 网格
• 橙色原点环与 O 标签
• 标定轴示意：X+ / X-、Y →（纵深）
• 纵深刻度：y = 5/10/15/20/30 m
• 横向刻度：x = ±5 / ±10 m（标签为标定 x，位置已按 -ground_x 放置）

5. 数据流与架构

视频源 → LiveDetection（后台线程）
            │
            ├─ MJPEG ──► /api/detect/stream ──► 页面画中画
            │
            └─ 每帧 persons[] ──► WebSocket /ws/detect
                                      │
                                      ▼
                               trajectory.js
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
              侧栏人员列表      PersonAgent 同步     头顶 CSS2D 标签
                                      │
                                      ▼
                         位置平滑 / 朝向 / Idle·Walk·Run
                         轨迹线 / 进出场淡入淡出

5.1 启动与停止时序

开始检测：

1. initScene()：WebGLRenderer、CSS2DRenderer、OrbitControls、灯光、地面
2. loadHumanModel()：加载 GLB 模板（之后每人 SkeletonUtils.clone）
3. POST /api/detect/start
4. 设置画中画 img.src = /api/detect/stream?…
5. connectWebSocket() → /ws/detect
6. resetCamera()

停止：

1. 断开 WebSocket（不再自动重连）
2. POST /api/detect/stop
3. 清空画中画、销毁全部 PersonAgent、重置列表与徽章

5.2 WebSocket 行为

• URL：ws://<host>/ws/detect（HTTPS 页面则为 wss:）
• 服务端有新检测帧（seq 变化）时推送一条 JSON
• 前端关心的类型：
  • type: "status"（或历史兼容的 "ping"）：更新 FPS、人员、错误
  • type: "error"：显示错误条
• 连接意外断开且用户仍希望运行时：约 1.5s 后自动重连，状态显示「重连中…」

推送载荷核心字段（在 type 之外展开自检测状态）：

{
  "type": "status",
  "running": true,
  "fps": 18.5,
  "seq": 1234,
  "error": null,
  "persons": [
    {
      "person_id": 12,
      "ground_x": 1.25,
      "ground_y": 8.40,
      "distance": 8.49,
      "speed": 1.32,
      "speed_kmh": 4.75,
      "direction": "approaching",
      "timestamp": "2026-10-12 11:20:00",
      "has_appearance": true
    }
  ]
}

direction 取值：approaching | retreating | stationary | unknown（侧栏显示为中文）。

6. 人物代理（PersonAgent）

每个 person_id 对应一个 PersonAgent：克隆骨骼模型、动画混合器、轨迹线、头顶标签、材质淡入淡出，以及可选衣物贴图。

6.1 生命周期

出场方向：

• 默认沿「原点 → 检测点」的径向再往外偏移 SPAWN_OFFSET_M = 2.4
• 若检测点离原点很近（< 0.4m），则默认从相机一侧（世界 -Z）走进，避免穿模感

跟踪恢复：

• 离场过程中若该 ID 再次出现在 persons 中，会 cancelExit()：淡回可见，并回到 active 或继续 spawning（取决于当前透明度）

6.2 位置平滑与死区

• 原始目标：toWorldPos(ground_x, ground_y)
• 位移死区约 0.1m：跳变更小时不猛追目标，抑制检测抖动
• 目标点再用 TARGET_FOLLOW 做指数平滑；模型位置 smooth 以追赶速度向目标移动
• 追赶速度：优先用检测 speed，过低则用标称步速约 1.2 m/s，并限制在约 0.85～4.5 m/s；落后过远时适当加速追上

6.3 朝向

• 优先用检测点真实位移估计行进方向（EMA 平滑；疑似掉头时混入更慢，减少噪声瞬间反向）
• 尚无有效行进样本且离目标较远时，用「当前位置 → 目标」方向兜底
• 大幅转向需确认时间（约 180ms～450ms），小幅则快速对齐，视觉上更稳

6.4 动画状态机

出场阶段强制保持行走，直到走进检测落点附近。

6.5 轨迹线

• 统一蓝色（#3b82f6），不随靠近/远离变色
• 行走时按位移间隔约 0.35m 追加点；最多保留约 200 点（FIFO）
• 透明度随人物淡入淡出同步（峰值约 0.85）
• 「清空轨迹」只清点列，不删人

6.6 头顶标签（CSS2D）

• 默认：#ID + 速度（m/s）
• 勾选「显示坐标」后追加：x / y（标定地面米制坐标）
• 透明度随生命周期淡入淡出

7. 衣物贴图（可选）

开启「衣物贴图」后：

1. 若人员事件带 has_appearance: true，请求
   GET /api/detect/appearance/{person_id}
2. 用纹理加载器取 JPEG，通过自定义着色器按绑定姿势正面投影映射到躯干 / 头 / 腿，手臂改到画面两侧袖子区域
3. 每个 ID 最多尝试加载约 3 次；关闭开关时恢复默认材质
4. 侧栏同步显示缩略图

说明：贴图来自检测画面裁剪/缓存，效果受角度、遮挡与分辨率影响，主要用于增强辨识度，而非精确换装。

8. 相机与交互

基于 OrbitControls：

极角上限约 89°，避免翻到地面以下。

9. 相关 HTTP / WebSocket 接口

本页直接使用的接口：

静态资源：

10. 源码入口（便于二次开发）

关键常量（均在 trajectory.js 顶部，可按现场调参）：

11. 常见问题

3D 里左右和视频反了？
检查标定原点与横向点是否按「左负右正」录入；世界坐标已对 ground_x 取反，标定错误会直接表现为镜像或偏移。

人凭空出现/消失？
正常流程应有 spawning / exiting。若跟踪 ID 抖动（同一人频繁换 ID），会表现为多人反复进出场——需从检测/跟踪侧改善，而非仅改前端。

点击开始后一直「加载模型…」？
确认 web/static/models/Human.glb 存在且可访问；浏览器控制台查看 GLB 加载错误。

场景是黑的 / Three 报错？
当前依赖 CDN 加载 Three.js，检查网络或改用本地 three 静态文件。

画中画有画面但 3D 没人？
确认已标定且 WebSocket 的 persons 非空；未标定时脚点变换可能失败或坐标异常。也可在侧栏核对是否有人员条目。

与监控页抢「开始/停止」？
共用同一检测服务：一处停止，全局停止；一处启动，全局运行。轨迹页断开 WebSocket 不会自动停检测，只有点「停止」才会 POST /api/detect/stop。

12. 设计要点小结

1. 业务坐标用直角 (x, y)，距离 D 只作列表/方向辅助，不直接驱动 3D 落点。
2. 视觉连续性：外侧走进 + 淡入；丢失宽限期 + 沿行进方向走离 + 淡出。
3. 检测与表现解耦：后端给稀疏、带噪声的地面点；前端用死区、平滑、朝向确认和动画掩盖抖动。
4. 与监控页同源：同一检测线程、同一 WebSocket、同一标定与视频源，便于对照验证标定是否正确。