# ObjectTracker

ObjectTracker 将跨帧的检测结果关联起来，分配稳定的 ID，并报告每个跟踪的状态。它从
[DetectionNetwork](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/detection_network.md) 或
[SpatialDetectionNetwork](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/spatial_detection_network.md)
获取检测结果，并输出 [Tracklets](https://docs.luxonis.com/software-v3/depthai/depthai-components/messages/tracklets.md)。 当上游节点是
SpatialDetectionNetwork 时，每个 tracklet 还会携带 spatialCoordinates（X/Y/Z，单位 mm），跟踪器可以估算可选的 3D velocity 和 speed。

当检测结果包含空间坐标时，tracklet 会自动获得空间数据。空间感知关联是一个独立的跟踪器选项，默认处于禁用状态；只有在深度足够可靠，能够潜在地改善拥挤场景、交叉或部分遮挡情况下的 ID 时，才启用该选项。

在 DepthAI v3 中，tracklet 和帧还会额外暴露变换元数据，允许跨流（例如 RGB → 深度）重新映射 ROI，如 [Object Tracker
Remap](https://docs.luxonis.com/software-v3/depthai/examples/object_tracker/object_tracker_remap.md) 示例所示。

## 如何放置

#### Python

```python
with dai.Pipeline() as pipeline:
    objectTracker = pipeline.create(dai.node.ObjectTracker)
```

#### C++

```cpp
dai::Pipeline pipeline;
auto objectTracker = pipeline.create<dai::node::ObjectTracker>();
```

## 输入与输出

## 零时跟踪

将当前帧的检测结果与已有跟踪轨迹关联（无时间预测）。

## 短时跟踪

通过外推运动在检测器帧之间传播跟踪轨迹，当检测器并非每帧都运行时，此功能有助于保持轨迹连续性。

## 空间数据与关联

空间数据有两个独立的用途：

 * **Tracklet 输出：**当 inputDetections 来自 SpatialDetectionNetwork 时，每个 Tracklet 会获得 spatialCoordinates。如果跟踪器有有效的空间状态，它还会输出可选的
   velocity 和 speed（单位 m/s）。仅 RGB 的流水线将保留这些可选字段为空，因此在 Python 中检查 None，在 C++ 中检查 std::nullopt。
 * **轨迹关联：**调用 setSpatialAssociation(true) 以在将检测结果与已有轨迹匹配时使用有效的 XYZ 坐标。空间门限与 2D IoU 门限共同应用，空间相似度会与 2D 关联得分混合。

当附近物体在图像空间中重叠但在深度上分离时，应使用空间关联。对于仅 RGB 的跟踪，或深度噪声过大而无法作为有用身份信号的场景，请保持禁用。

| 设置方法 | 默认值 | 使用方法 |
| --- | --- | --- |
| `setSpatialAssociation(bool)` | `false` | 当存在有效的空间坐标时启用空间感知匹配。 |
| `setSpatialAssociationWeight(float)` | `0.5` | 混合 2D 与空间得分。较低的值更倾向于图像空间跟踪，较高的值更倾向于空间一致性。这仅影响候选打分；最终接受仍需通过 2D IoU 门限。 |
| `setSpatialDistanceThreshold(float)` | `1.5` | 基础 3D 门限（单位米）。降低可进行更严格的匹配，提高可适应更快运动或噪声更大的深度。 |
| `setSpatialDepthAwareScale(float)` | `0.35` | 根据深度按比例放大 3D 门限：`threshold * (1 + scale * depthMeters)`。适用于远距离物体。 |

#### Python

```python
objectTracker.setSpatialAssociation(True)
objectTracker.setSpatialAssociationWeight(0.5)
objectTracker.setSpatialDistanceThreshold(1.5)
objectTracker.setSpatialDepthAwareScale(0.35)
```

#### C++

```cpp
objectTracker->setSpatialAssociation(true);
objectTracker->setSpatialAssociationWeight(0.5f);
objectTracker->setSpatialDistanceThreshold(1.5f);
objectTracker->setSpatialDepthAwareScale(0.35f);
```

## 支持的跟踪器类型

 * SHORT_TERM_IMAGELESS – 仅使用边界框位置和大小（无颜色数据）跨帧跟踪物体。轻量快速，适合实时使用。

使用 setTrackerType(...) 选择。 ID 策略通过 setTrackerIdAssignmentPolicy(...) 设置，可选值为 SMALLEST_ID 或 UNIQUE_ID。

> **限制：**
> 最多
> **1000**
> 个跟踪对象（通过
> `setMaxObjectsToTrack(...)`
> 设置上限）

## 功能示例

 * [对象跟踪器](https://docs.luxonis.com/software-v3/depthai/examples/object_tracker/object_tracker.md)
 * [对象跟踪器回放](https://docs.luxonis.com/software-v3/depthai/examples/object_tracker/object_tracker_replay.md)
 * [对象跟踪器重映射](https://docs.luxonis.com/software-v3/depthai/examples/object_tracker/object_tracker_remap.md)

## 参考

### dai::node::ObjectTracker

Kind: class

ObjectTracker node. Performs object tracking using Kalman filter and hungarian algorithm.

#### Input inputTrackerFrame

Kind: variable

Input ImgFrame message on which tracking will be performed. RGBp, BGRp, NV12, YUV420p types are supported. Default queue is
non-blocking with size 4.

#### Input inputDetectionFrame

Kind: variable

Input ImgFrame message on which object detection was performed. Default queue is non-blocking with size 4.

#### Input inputDetections

Kind: variable

Input message with image detection from neural network. Default queue is non-blocking with size 4.

#### Input inputConfig

Kind: variable

Input ObjectTrackerConfig message with ability to modify parameters at runtime. Default queue is non-blocking with size 4.

#### Output out

Kind: variable

Outputs Tracklets message that carries object tracking results.

#### Output passthroughTrackerFrame

Kind: variable

Passthrough ImgFrame message on which tracking was performed. Suitable for when input queue is set to non-blocking behavior.

#### Output passthroughDetectionFrame

Kind: variable

Passthrough ImgFrame message on which object detection was performed. Suitable for when input queue is set to non-blocking
behavior.

#### Output passthroughDetections

Kind: variable

Passthrough image detections message from neural network output. Suitable for when input queue is set to non-blocking behavior.

#### void setTrackerThreshold(float threshold)

Kind: function

Specify tracker threshold. parameters: threshold: Above this threshold the detected objects will be tracked. Default 0, all image
detections are tracked.

#### void setMaxObjectsToTrack(std::int32_t maxObjectsToTrack)

Kind: function

Specify maximum number of object to track. parameters: maxObjectsToTrack: Maximum number of object to track. Maximum 60 in case of
SHORT_TERM_KCF, otherwise 1000.

#### void setDetectionLabelsToTrack(const std::vector< std::uint32_t > & labels)

Kind: function

Specify detection labels to track. parameters: labels: Detection labels to track. Default every label is tracked from image
detection network output.

#### void setTrackerType(TrackerType type)

Kind: function

Specify tracker type algorithm. parameters: type: Tracker type.

#### void setTrackerIdAssignmentPolicy(TrackerIdAssignmentPolicy type)

Kind: function

Specify tracker ID assignment policy. parameters: type: Tracker ID assignment policy.

#### void setTrackingPerClass(bool trackingPerClass)

Kind: function

Whether tracker should take into consideration class label for tracking.

#### void setOcclusionRatioThreshold(float theshold)

Kind: function

Set the occlusion ratio threshold. Used to filter out overlapping tracklets. parameters: theshold: Occlusion ratio threshold.
Default 0.3.

#### void setTrackletMaxLifespan(uint32_t trackletMaxLifespan)

Kind: function

Set the tracklet lifespan in number of frames. Number of frames after which a LOST tracklet is removed. parameters:
trackletMaxLifespan: Tracklet lifespan in number of frames. Default 120.

#### void setTrackletBirthThreshold(uint32_t trackletBirthThreshold)

Kind: function

Set the tracklet birth threshold. Minimum consecutive tracked frames required to consider a tracklet as a new (TRACKED) instance.
parameters: trackletBirthThreshold: Tracklet birth threshold. Default 3.

#### void setSpatialAssociation(bool enabled)

Kind: function

Enable or disable spatially-aware association. If disabled, only 2D association is used. parameters: enabled:

#### void setSpatialAssociationWeight(float weight)

Kind: function

Set spatial association weight in [0,1]. parameters: weight: Spatial association weight in [0,1] used to blend 2D and spatial
association scores (0 = 2D-only scoring, 1 = spatial-only scoring). This weight affects candidate scoring only; final acceptance
still requires passing the 2D IoU threshold gate. Default is 0.5.

#### void setSpatialDistanceThreshold(float thresholdMeters)

Kind: function

Set base 3D gating threshold in meters for spatial association. parameters: thresholdMeters: Base spatial gating distance in
meters. Default is 1.5m.

#### void setSpatialDepthAwareScale(float scale)

Kind: function

Set depth-aware gating scale used for spatial association. Increases gating threshold with increased depth. parameters: scale:
Depth-aware gating scale factor. Default is 0.35

#### void setRunOnHost(bool runOnHost)

Kind: function

Specify whether to run on host or device By default, the node will run on device.

#### bool runOnHost()

Kind: function

Check if the node is set to run on host

#### void run()

Kind: function

#### DeviceNodeCRTP()

Kind: function

#### DeviceNodeCRTP(const std::shared_ptr< Device > & device)

Kind: function

#### DeviceNodeCRTP(std::unique_ptr< Properties > props)

Kind: function

#### DeviceNodeCRTP(std::unique_ptr< Properties > props, bool confMode)

Kind: function

#### DeviceNodeCRTP(const std::shared_ptr< Device > & device, std::unique_ptr< Properties > props, bool confMode)

Kind: function

### 需要帮助？

请前往 [OAKChina 官网](https://www.oakchina.cn/) 获取技术支持或解答您的任何疑问。