摄像机自动跟踪

支持视场角（FOV）内相对转动的具有 ONVIF 功能的 PTZ（平移-俯仰-变焦）摄像机可配置为自动跟踪移动目标并将其保持在画面中心。

自动跟踪行为

一旦 Frigate 确定目标不是误报，并进入了指定防区之一，自动跟踪器就会转动 PTZ 摄像机，使目标保持在画面中心，直到目标移出画面、PTZ 无法继续转动或 Frigate 失去跟踪为止。

一旦失去追踪，Frigate 将扫描丢失目标所在区域 timeout 秒。如果在该区域发现相同类型的目标，Frigate 将自动追踪该新目标。

跟踪结束后，Frigate 将返回到由 return_preset 配置项指定的摄像机固件 PTZ 预设值位置。

检查 ONVIF 摄像机支持

Frigate 自动跟踪功能可与可在视场角内进行相对移动的 PTZ 摄像机配合使用（按照ONVIF 规范中的规定，RelativePanTiltTranslationSpace 有一个 TranslationSpaceFov 条目）。

许多较便宜或较旧的 PTZ 可能不支持此标准。如果您的 PTZ 不受支持，Frigate 会在日志中报告错误信息，并禁用自动跟踪功能。

或者，您也可以下载并运行 这个简单的 Python 脚本，用摄像机的 IP 地址、ONVIF 端口、用户名和密码替换第 4 行的详细信息，以检查您的摄像机。

用户报告的可与 Frigate 自动跟踪系统配合使用的摄像机和品牌列表不断增加，请点击此处查看用户报告的可与 Frigate 自动跟踪系统配合使用的相机和品牌列表不断增加，请点击此处查看。

配置

首先，在摄像机固件中设置 PTZ 预置并为其命名。如果您不确定如何操作，请查阅摄像机制造商的固件文档。一些常见品牌的教程：Amcrest、Reolink、Dahua。

编辑 Frigate 配置文件并输入摄像机的 ONVIF 参数。指定要跟踪的目标类型、目标必须进入的区域以开始自动跟踪，以及在摄像机固件中配置的摄像机预设名称，以便在跟踪结束后返回。还可以指定 Frigate 将摄像机返回预设值之前的延迟时间（以秒为单位）。

自动跟踪功能需要 ONVIF 连接。此外，建议在摄像机的时间戳和任何叠加文本上添加动态遮罩，以确保在摄像机转动时将它们完全排除在场景变化计算之外。

请注意 autotracking 默认为禁用，但可在配置中或通过 MQTT 启用。

cameras:
  ptzcamera:
    ...
    onvif:
      # 必填：所连接的摄像机。
      host: 0.0.0.0
      # 可选：设备的ONVIF端口（默认值：如下所示）。
      port: 8000
      # 可选：用于登录的用户名。
      # 注意：某些设备需要admin才能访问ONVIF。
      user: admin
      # 可选：登录密码。
      password: admin
      # 可选：PTZ摄像机目标自动跟踪。通过自动转动PTZ摄像机，将移动目标保持在画面中心。
      autotracking:
        # 可选：启用/禁用目标自动跟踪。(默认：如下所示）
        enabled: False
        # 可选：启动时校准摄像机（默认值：如下所示）
        # 校准将以增量方式移动云台，并测量移动所需的时间。
        # 这些结果用于帮助估算摄像机移动后被跟踪目标的位置。
        # 在校准之后，Frigate 会自动更新配置文件，为摄像机添加 "movement_weights "条目。此时，您应将校准启动设置为False.
        calibrate_on_startup: False
        # 可选：在自动跟踪过程中放大/缩小目标时使用的模式。(默认：如下所示）
        # 可用的选项有：disabled, absolute, and relative
        #   disabled - 不要放大/缩小自动跟踪的目标，只使用平移/倾斜功能
        #   absolute - 使用绝对变焦（大多数具有PTZ功能的摄像机都支持该功能）
        #   relative - 使用相对变焦（并非所有PTZ都支持，但可同时进行摇摄/俯仰/缩放运动）
        zooming: disabled
        # 可选：用于更改自动跟踪目标缩放行为的值。(默认值：如下所示）
        # 数值越小，被跟踪目标周围的场景就越多。
        # 数值越大，越能放大被跟踪的目标，但 Frigate 可能会更快地失去跟踪目标。
        # 数值应介于 0.1 和 0.75 之间
        zoom_factor: 0.3
        # 可选：要从labelmap.txt跟踪的目标列表（默认值：如下所示）
        track:
          - person
        # 必填：当目标进入列出的任何区域时，开始自动跟踪。
        required_zones:
          - zone_name
        # 必填：摄像机固件中ONVIF预置的名称，用于在跟踪结束后返回。(默认：如下所示）
        return_preset: home
        # 可选：返回预设值前的延迟秒数。(默认：如下所示）
        timeout: 10
        # 可选：由摄像机校准自动生成的值。请勿手动修改。(默认：如下所示）
        movement_weights: []

校准

PTZ 电机的运行速度各不相同。进行校准后，Frigate 将通过各种运动来测量这一速度，并利用这些测量结果更好地预测保持自动跟踪目标在画面中心所需的运动量。

校准是可选的，但将极大地帮助 Frigate 自动跟踪那些在摄像机视野内快速移动的物体。

要开始校准，请将摄像机的calibrate_on_startup 设置为 True ，并重启 Frigate。然后，Frigate 会对摄像机进行一系列大大小小的转动。校准过程中不要手动转动 PTZ。校准完成后，摄像机转动将停止，配置文件将自动更新，并加入用于转动计算的 movement_weights 参数。请勿手动修改此参数。

校准结束后，PTZ 将回到 return_preset 指定的预置位。

备注

在校准过程中，Frigate 的网络用户界面和所有其他摄像机都将处于无响应状态。这是预料之中的正常现象，以避免在校准过程中出现过多的网络流量或 CPU 占用。大多数 PTZ 的校准大约需要两分钟。Frigate 日志将显示校准进度和任何错误。

此时，Frigate 将开始运行，并会随着 PTZ 在自动跟踪过程中的转动和更多测量结果的获得，继续自动完善和更新配置中的 movement_weights 参数。

在重新启动 Frigate 之前，应将配置文件中的 calibrate_on_startup 设置为 False，否则已完善的movement_weights 将被覆盖，并在再次启动时进行校准。

你可以随时移除 movement_weights 参数，将 calibrate_on_startup 设为 True，然后重启 Frigate，重新校准。如果自动跟踪不稳定，可能需要重新校准或从配置中完全删除 movement_weights。如果以任何方式更改了 return_preset 或更改了摄像机的检测 fps 值，也建议重新校准。

如果最初校准时禁用了变焦功能，后来又启用了变焦功能，则还应重新校准。

最佳做法和注意事项

每台 PTZ 摄像机都不尽相同，因此自动跟踪功能不一定在任何情况下都能发挥理想的作用。此实验功能最初是使用 EmpireTech/Dahua SD1A404XB-GNR 开发的。

Frigate 中的目标跟踪器会估算 PTZ 的转动，因此当摄像机转动时，被跟踪的物体也会保留下来。在大多数情况下，5 帧/秒就足够了，但如果您计划跟踪移动速度较快的目标，可能需要稍微提高帧频。更高的帧率（> 10fps）只会减慢 Frigate 和运动估算器的速度，并可能导致丢帧，尤其是在使用试验性变焦的情况下。

建议使用快速目标检测器。CPU 检测器性能不佳或根本无法工作。您可以在 Frigate 的调试视图中查看您的摄像机，在当前正在自动跟踪的目标周围会出现一个较厚的彩色方框。

不建议在 required_zones 中设置全画幅防区，尤其是在校准了摄像机并且在配置文件中定义了 movement_weights 的情况下。Frigate 会继续自动跟踪已进入其中一个 required_zones 的目标，即使该目标移动到了该防区之外。

一些用户发现调整防区的 inertia 值很有帮助。请参阅配置参考。

变焦

变焦是一项非常试验性的功能，在跟踪目标时可能会比平移/倾斜使用更多的 CPU。

绝对变焦使变焦动作与平移/俯仰动作分开。大多数 PTZ 摄像机都支持绝对变焦。绝对变焦的开发非常保守，以便与各种摄像机和场景配合使用。绝对变焦通常在目标停止移动或移动速度非常缓慢时才会发生。

相对变焦尝试在进行任何平移/俯仰动作的同时进行变焦动作。经测试，它可与某些 Dahua 和 Amcrest PTZ 配合使用。但 ONVIF 规范指出，在使用相对缩放时，不能假设通用缩放范围如何映射到放大率、视场或其他物理缩放维度。因此，如果相对缩放行为不稳定或不起作用，请尝试绝对缩放。

您可以选择在配置文件中调整摄像机的 zoom_factor 。数值越小，跟踪目标周围的场景空间就越大，而数值越大，摄像机就会更多放大对象。不过，请记住，Frigate 需要在被跟踪目标的边界框外留出相当多的像素和场景细节，以估算摄像机的运动。如果目标占据了太多的画面，Frigate 将无法跟踪摄像机的动作，目标也将丢失。

该选项的范围为 0.1 至 0.75。默认值 0.3 比较保守，对大多数用户来说应该足够。由于每个 PTZ 和场景都不尽相同，您应该尝试确定最适合您的值。

自动跟踪应用

在安防和监控领域，将 "观测器 "摄像机与 PTZ 结合使用是很常见的。当固定监视摄像机检测到目标时，您可以使用 Home Assistant 等自动化平台将 PTZ 转到特定的预设位置，这样 Frigate 就可以开始自动跟踪该目标。例如：一栋住宅的东西两侧可能装有固定摄像机，可以捕捉街道的上下方向。当西侧的摄像机检测到有人时， Home Assistant 自动化系统就会将 PTZ 转到到西侧的摄像机预设位置。当目标进入指定防区时，Frigate 的自动跟踪器会继续跟踪该目标，直至其离开任何固定摄像机的视野。

故障排除和常见问题

自动跟踪器无法追踪目标。为什么？

出现这种情况的原因有很多。如果您使用的是实验性变焦，您的 zoom_factor 值可能过高，目标可能移动得太快，场景可能太暗，场景中没有足够的细节（例如，PTZ俯视车道或其他没有足够硬边或硬角的单色背景），或者场景不适合 Frigate 保持跟踪。

您的摄像机快门速度也可能设置得过低，以至于运动时会出现模糊。检查摄像机固件，看看是否可以提高快门速度。

观察 Frigate 的调试视图有助于确定可能的原因。自动跟踪目标周围会有一个较厚的彩色方框。

我在日志中看到一个错误，说我的摄像机 "仍处于 ONVIF 'MOVING' 状态"。这是什么意思？

造成这种情况的原因可能有两个（也许还有其他未知原因）：PTZ 电机速度慢或摄像机固件有问题。Frigate 使用摄像机提供的 ONVIF 参数 MoveStatus 来确定 PTZ 电机是不是在空转。据一些用户称，海康威视 PTZ（即使使用最新固件）在 PTZ 转动后不会更新该值。遗憾的是，海康威视固件中没有解决这一错误的方法，因此自动跟踪功能将无法正常运行，并应在配置中禁用。使用海康威视固件的其他非海康威视摄像机也可能出现这种情况。

我试着校准摄像机，但日志显示摄像机卡在 0%，Frigate 也无法启动。

造成这种情况的原因通常与上述原因相同--由于摄像机固件中的错误，MoveStatus ONVIF 参数没有变化。另请参阅上面的说明：在校准过程中，Frigate 的 Web UI 和所有其它摄像机都将无响应。这是预料之中的正常现象。但如果您没有看到每隔几秒就有一次的校准进度记录，则说明您的摄像机与自动跟踪不兼容。

我在日志中看到了这个错误："Autotracker: motion estimator couldn't get transformations". 这是什么意思？

为了在 PTZ 移动过程中保持目标跟踪，Frigate 会根据帧的细节来跟踪摄像机的转动。如果您看到此信息，可能意味着您的 zoom_factor 设置过高，检测到的目标周围的场景没有足够的细节（如硬边缘或色彩变化），或者您的摄像机快门速度太慢，导致运动模糊。请尝试降低 zoom_factor ，想办法改变目标周围的场景，或改变摄像机的快门速度。

校准似乎已经完成，但摄像头实际上并没有移动来跟踪我的物体。为什么？

有些摄像机的固件报告支持 FOV RelativeMove（Frigate 用于自动跟踪的 ONVIF 命令）。但是，如果当物体进入指定的防区时，摄像机没有平移或倾斜，那么摄像机的固件实际上并不支持 FOV RelativeMove。Uniview IPC672LR-AX4DUPK 就是这样一台摄像机。它实际上是在转动变焦马达，而不是平移和倾斜，而且完全不遵循 ONVIF 标准。