概览硬件软件云平台
此页面由 AI 自动翻译。查看英文原版
OAK 应用
DepthAI
AI
软件栈
故障排除

本页目录

  • 如何放置它
  • 输入和输出
  • Zero term tracking
  • Short term tracking
  • 空间数据和关联
  • 支持的对象跟踪器类型
  • 功能示例
  • 参考

ObjectTracker

Supported on:RVC2RVC4
ObjectTracker 会跨帧关联检测结果，分配稳定的 ID 并报告每个跟踪的状态。它接收来自 DetectionNetwork 或 SpatialDetectionNetwork 的检测结果，并输出 Tracklets。 当上游节点是 SpatialDetectionNetwork 时，每个 tracklet 还会携带 spatialCoordinates（以毫米为单位的 X/Y/Z），并且跟踪器可以估算可选的 3D velocity 和 speed。当检测结果包含空间坐标时，tracklet 会自动获得空间数据。空间感知的关联是跟踪器的另一个选项，默认禁用；仅当深度信息足够可靠以可能提高拥挤场景、交叉或部分遮挡下的 ID 时才启用。在 DepthAI v3 中，tracklets 和 frames 额外暴露了转换元数据，允许跨流（例如，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>();

输入和输出

Zero term tracking

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

Short term tracking

通过外推运动在检测器帧之间传播跟踪，这在检测器未运行每一帧时很有帮助。

空间数据和关联

空间数据有两种不同的用途：
  • Tracklet 输出： 当 inputDetections 来自 SpatialDetectionNetwork 时，每个 Tracklet 会接收 spatialCoordinates。如果跟踪器具有有效的空间状态，它还会输出可选的 velocity 和 speed（单位为 m/s）。仅 RGB 的管道会留空这些可选字段，因此在 Python 中检查 None 或在 C++ 中检查 std::nullopt。
  • Track 关联： 调用 setSpatialAssociation(true) 以在匹配检测结果与现有跟踪时使用有效的 XYZ 坐标。空间门与 2D IoU 门一起应用，空间相似度与 2D 关联分数混合。
当相邻物体在图像空间中重叠但在深度上分离时，请使用空间关联。对于仅 RGB 的跟踪，或深度太嘈杂而无法作为有用身份信号的场景，请保持禁用状态。
SetterDefaultHow to use it
setSpatialAssociation(bool)false在存在有效空间坐标时启用空间感知的匹配。
setSpatialAssociationWeight(float)0.5混合 2D 和空间分数。较低的值偏向图像空间跟踪，较高的值偏向空间一致性。这仅影响候选评分；最终接受仍需要通过 2D IoU 门。
setSpatialDistanceThreshold(float)1.5以米为单位的基础 3D 门。降低它以进行更严格的匹配，或提高它以适应更快的运动或更嘈杂的深度。
setSpatialDepthAwareScale(float)0.35随着深度按 threshold * (1 + scale * depthMeters) 的方式增大 3D 门。适用于远距离物体。

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(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)

需要帮助？

请前往 Discussion Forum 获取技术支持或提出您可能有的任何其他问题。