概览硬件软件云平台
OAK 应用
DepthAI
AI
软件栈
故障排除

本页目录

  • 如何放置
  • 输入与输出
  • 零时跟踪
  • 短时跟踪
  • 空间数据与关联
  • 支持的跟踪器类型
  • 功能示例
  • 参考

ObjectTracker

Supported on:RVC2RVC4
ObjectTracker 将跨帧的检测结果关联起来，分配稳定的 ID，并报告每个跟踪的状态。它从 DetectionNetwork 或 SpatialDetectionNetwork 获取检测结果，并输出 Tracklets。 当上游节点是 SpatialDetectionNetwork 时，每个 tracklet 还会携带 spatialCoordinates（X/Y/Z，单位 mm），跟踪器可以估算可选的 3D velocity 和 speed。当检测结果包含空间坐标时，tracklet 会自动获得空间数据。空间感知关联是一个独立的跟踪器选项，默认处于禁用状态；只有在深度足够可靠，能够潜在地改善拥挤场景、交叉或部分遮挡情况下的 ID 时，才启用该选项。在 DepthAI v3 中，tracklet 和帧还会额外暴露变换元数据，允许跨流（例如 RGB → 深度）重新映射 ROI，如 Object Tracker Remap 示例所示。

如何放置

Python

Python
1with dai.Pipeline() as pipeline:
2    objectTracker = pipeline.create(dai.node.ObjectTracker)

C++

C++
1dai::Pipeline pipeline;
2auto 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
1objectTracker.setSpatialAssociation(True)
2objectTracker.setSpatialAssociationWeight(0.5)
3objectTracker.setSpatialDistanceThreshold(1.5)
4objectTracker.setSpatialDepthAwareScale(0.35)

C++

C++
1objectTracker->setSpatialAssociation(true);
2objectTracker->setSpatialAssociationWeight(0.5f);
3objectTracker->setSpatialDistanceThreshold(1.5f);
4objectTracker->setSpatialDepthAwareScale(0.35f);

支持的跟踪器类型

  • SHORT_TERM_IMAGELESS – 仅使用边界框位置和大小（无颜色数据）跨帧跟踪物体。轻量快速，适合实时使用。
使用 setTrackerType(...) 选择。 ID 策略通过 setTrackerIdAssignmentPolicy(...) 设置，可选值为 SMALLEST_ID 或 UNIQUE_ID。

功能示例

参考

class

dai::node::ObjectTracker

#include ObjectTracker.hpp
variable
Input inputTrackerFrame
Input ImgFrame message on which tracking will be performed. RGBp, BGRp, NV12, YUV420p types are supported. Default queue is non-blocking with size 4.
variable
Input inputDetectionFrame
Input ImgFrame message on which object detection was performed. Default queue is non-blocking with size 4.
variable
Input inputDetections
Input message with image detection from neural network. Default queue is non-blocking with size 4.
variable
Input inputConfig
Input ObjectTrackerConfig message with ability to modify parameters at runtime. Default queue is non-blocking with size 4.
variable
Output out
Outputs Tracklets message that carries object tracking results.
variable
Output passthroughTrackerFrame
Passthrough ImgFrame message on which tracking was performed. Suitable for when input queue is set to non-blocking behavior.
variable
Output passthroughDetectionFrame
Passthrough ImgFrame message on which object detection was performed. Suitable for when input queue is set to non-blocking behavior.
variable
Output passthroughDetections
Passthrough image detections message from neural network output. Suitable for when input queue is set to non-blocking behavior.
function
void setTrackerThreshold(float threshold)
Specify tracker threshold.
Parameters
  • threshold: Above this threshold the detected objects will be tracked. Default 0, all image detections are tracked.
function
void setMaxObjectsToTrack(std::int32_t maxObjectsToTrack)
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.
function
void setDetectionLabelsToTrack(const std::vector< std::uint32_t > & labels)
Specify detection labels to track.
Parameters
  • labels: Detection labels to track. Default every label is tracked from image detection network output.
function
void setTrackerType(TrackerType type)
Specify tracker type algorithm.
Parameters
  • type: Tracker type.
function
void setTrackerIdAssignmentPolicy(TrackerIdAssignmentPolicy type)
Specify tracker ID assignment policy.
Parameters
  • type: Tracker ID assignment policy.
function
void setTrackingPerClass(bool trackingPerClass)
Whether tracker should take into consideration class label for tracking.
function
void setOcclusionRatioThreshold(float theshold)
Set the occlusion ratio threshold. Used to filter out overlapping tracklets.
Parameters
  • theshold: Occlusion ratio threshold. Default 0.3.
function
void setTrackletMaxLifespan(uint32_t trackletMaxLifespan)
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.
function
void setTrackletBirthThreshold(uint32_t trackletBirthThreshold)
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.
function
void setSpatialAssociation(bool enabled)
Enable or disable spatially-aware association. If disabled, only 2D association is used.
Parameters
  • enabled:
function
void setSpatialAssociationWeight(float weight)
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.
function
void setSpatialDistanceThreshold(float thresholdMeters)
Set base 3D gating threshold in meters for spatial association.
Parameters
  • thresholdMeters: Base spatial gating distance in meters. Default is 1.5m.
function
void setSpatialDepthAwareScale(float scale)
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
function
void setRunOnHost(bool runOnHost)
Specify whether to run on host or device By default, the node will run on device.
function
bool runOnHost()
Check if the node is set to run on host
function
void run()
inline function
DeviceNodeCRTP()
inline function
DeviceNodeCRTP(const std::shared_ptr< Device > & device)
inline function
DeviceNodeCRTP(std::unique_ptr< Properties > props)
inline function
DeviceNodeCRTP(std::unique_ptr< Properties > props, bool confMode)
inline function
DeviceNodeCRTP(const std::shared_ptr< Device > & device, std::unique_ptr< Properties > props, bool confMode)

需要帮助？

请前往 OAKChina 官网 获取技术支持或解答您的任何疑问。