物体检测 — 高尔夫球杆与球体追踪
什么是物体检测？
启用物体检测后，Swing Catalyst 会在每一帧视频中检测高尔夫球杆和球，并在骨架可视化之上绘制 3D 叠加图层。您将看到：
- 球杆叠加图层 — 沿杆身分布的五个关键点（杆头顶部、杆头底部、杆身底部、中部和握把末端），通过彩色编码的线条连接。颜色从杆头处的黄色渐变到握把处的青色，使方向一目了然。
- 球体叠加图层 — 在检测到的球所在位置显示一个白色球体。
无论是在实时摄像头画面中，还是在已录制片段的播放过程中，叠加图层都会显示。未启用物体检测录制的片段将正常播放，仅显示身体可视化效果。
为什么物体检测仅支持高尔夫
物体检测目前仅支持高尔夫。其底层模型（用于物体检测的 RTMDet-M 和用于球杆姿态估计的 RTMPose-M）是专门针对高尔夫器材训练的。要扩展到其他运动（棒球、网球），需要额外的训练模型，而这些模型目前尚未提供。该架构在设计时已考虑到未来支持更多运动；新模型发布后，无需对处理流程进行任何代码改动。
如何启用或禁用物体检测
检测模式（全局设置）
- 打开 设置 → 视频与捕捉。
- 滚动到 高级设置 部分。
- 找到 检测模式 下拉菜单。
- MultiClass — 同时运行人体检测和物体检测。这是默认选项。
- HumanOnly — 仅运行人体检测。如果您不需要球杆和球的追踪，或遇到性能问题，请使用此选项。
- 更改模式会自动重启检测服务，无需重启应用程序。
启用物体检测开关（按会话）
当检测模式设置为 MultiClass 时，会出现一个单独的 启用物体检测 开关。关闭它可以在不更改全局检测模式的情况下，为当前会话临时跳过物体检测。当检测模式为 HumanOnly 时，此开关显示为灰色不可用。
在视口中显示/隐藏叠加图层
使用视口上方的工具栏，可以分别控制球杆和球的叠加图层的显示与隐藏：
- Show Club — 切换球杆关键点和骨骼叠加图层。
- Show Ball — 切换球体叠加图层。
这些开关会立即生效，无需重启检测，并且设置会在各会话间保留。
硬件要求
物体检测比仅捕捉身体的动作捕捉需要更多 GPU 显存。
| 模式 | 最低显存 | 推荐显存 |
|---|---|---|
| HumanOnly（仅身体） | 6 GB | 8 GB |
| MultiClass（身体 + 高尔夫器材） | 8 GB | 10 GB 以上 |
有关完整详情及兼容显卡的完整列表，请参阅 推荐的计算机配置 。
在显存低于 8 GB 的系统上，应用程序可能会自动回退到仅人体检测。如果发生这种情况，设置 → 视频与捕捉 中会出现通知横幅。
Intel 集成显卡（UHD 620/770）： 在 Intel 集成显卡配置下，物体检测会自动禁用，因为操作系统分配的显存预算（通常为 400–800 MB）不足。仅身体的动作捕捉仍可正常工作。
播放时您会看到什么
当您打开一个启用了物体检测录制的片段时：
- 球杆和球的叠加图层会与身体骨架一起显示在时间轴上。
- 当您拖动时间轴时，叠加图层会与视频帧保持同步。
- 置信度较低的检测结果会淡出，而不是跳到错误的位置。
- 您可以使用上文所述的工具栏控件，分别切换球杆和球的可见性。
在物体检测功能推出之前录制的片段，或检测模式设置为 HumanOnly 时录制的片段，只会显示身体骨架。查看这些片段无需重新处理，它们可以正常打开。
要为现有片段添加物体检测数据，请在分析模式下打开该录制内容，点击工具栏中的 动作捕捉 按钮，然后选择 Reprocess MoCap。这将对录制的帧重新运行身体检测和物体检测。
故障排查
球杆和球的叠加图层未显示
- 检查 设置 → 视频与捕捉 → 检测模式 是否设置为 MultiClass。
- 检查 启用物体检测 开关是否已打开。
- 检查设置中是否显示通知横幅“球杆和球追踪模型尚不可用”。如果显示，说明组件目录中缺少所需的模型文件。请按照 组件安装指南 重新安装动作捕捉组件。
显存警告 / 自动回退到仅人体检测
在以下情况下，应用程序会记录警告并回退到仅人体检测：
- 服务启动时 DirectML 报告的可用显存低于 600 MB；或
- 系统使用 Intel 集成显卡。
要解决此问题：请确保没有其他占用大量 GPU 资源的应用程序在运行，并检查您的显卡是否满足 MultiClass 检测所需的 推荐配置 （最低 8 GB 显存）。
叠加图层显示的运动类型不正确
物体检测仅在 高尔夫 活动中生效。如果您正在录制非高尔夫运动且未看到球杆或球的叠加图层，这是正常现象。对于非高尔夫活动，设置中不会显示检测模式选项。
检测精度低或叠加图层闪烁
- 确保球杆和球在挥杆的大部分过程中光线充足且未被遮挡。
- 尝试降低摄像头帧率以减轻系统负载（参见 动作捕捉设置 ）。
- 如果背景物体导致误检，请在 设置 → 视频与捕捉 → 高级设置 中提高检测置信度阈值。
- 如果检测效果持续不佳，请尝试将 Execution Provider 切换为 DirectML，因为它具有最广泛的硬件兼容性。
更新后模型文件缺失
如果应用程序更新更改了所需的模型版本，通知横幅会在设置中再次出现。请按照 组件安装指南 重新安装组件。