ObjectTracker 关联跨帧检测,分配稳定的 ID 并报告每个跟踪的状态。它从 DetectionNetwork 或 SpatialDetectionNetwork 获取检测结果,并输出 Tracklets。 当上游节点是 SpatialDetectionNetwork 时,每个跟踪器还带有 spatialCoordinates(X/Y/Z,单位为毫米),并且跟踪器可以估计可选的 3D velocity 和 speed。ObjectTracker 的实现灵感来自 OC-SORT。当检测包含空间坐标时,空间数据会自动提供给跟踪器。空间感知关联是一个单独的跟踪器选项,默认禁用;仅当深度足够可靠以潜在地改善拥挤场景、交叉路口或部分遮挡中的 ID 时才启用它。在 DepthAI v3 中,跟踪器和帧还公开了转换元数据,允许在流之间重新映射 ROI(例如,RGB → 深度),如 Object Tracker Remap 示例所示。如何放置
Python
Python
1with dai.Pipeline() as pipeline:
2 objectTracker = pipeline.create(dai.node.ObjectTracker)输入和输出
零期跟踪
短期跟踪
空间数据和关联
- 跟踪器输出: 当
inputDetections来自SpatialDetectionNetwork时,每个Tracklet都会收到spatialCoordinates。如果跟踪器具有有效的空间状态,它还会输出可选的velocity和speed(单位为米/秒)。纯 RGB 管道会使这些可选字段为空,因此在 Python 中检查None,在 C++ 中检查std::nullopt。 - 跟踪关联: 调用
setSpatialAssociation(true)以在将检测与现有跟踪匹配时使用有效的 XYZ 坐标。空间门控与 2D IoU 门控一起应用,空间相似性与 2D 关联分数混合。
| Setter | 默认值 | 如何使用 |
|---|---|---|
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)支持的对象跟踪器类型
SHORT_TERM_IMAGELESS– 仅使用边界框位置和大小(无颜色数据)跨帧跟踪对象。轻量级且快速,适用于实时使用。
setTrackerType(...) 进行选择。 ID 策略使用 setTrackerIdAssignmentPolicy(...) 设置,可以是 SMALLEST_ID 或 UNIQUE_ID。限制: 最多可跟踪 1000 个对象(通过
setMaxObjectsToTrack(...) 设置上限)功能示例
参考
class
dai::node::ObjectTracker
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
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: true enables spatially-aware association, false uses 2D-only association. Default is false.
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)需要帮助?
请访问讨论论坛以获取技术支持或您可能有的任何其他问题。