DCF 跟踪器

使用判别相关滤波器 (DCF) 算法跟踪帧序列中的对象边界框。更多...

数据结构
结构体	VPIDCFTrackerCreationParams
	DCF 跟踪器的创建参数。更多...
结构体	VPIDCFTrackerParams
	定义 vpiCreateDCFTracker 参数的结构体。更多...
结构体	VPIDCFTrackedBoundingBox
	存储关于由 DCF 跟踪器 跟踪的对象的信息。更多...

枚举
枚举	VPIDCFTrackerCreationFlag
	用于自定义 DCF 跟踪器算法的标志。更多...

函数
VPIStatus	vpiInitDCFTrackerCreationParams (VPIDCFTrackerCreationParams *params)
	使用默认值初始化 VPIDCFTrackerCreationParams。更多...
VPIStatus	vpiCreateDCFTracker (uint64_t backends, int32_t maxNumSequences, int32_t maxNumObjects, const VPIDCFTrackerCreationParams *params, VPIPayload *payload)
	为 DCF 跟踪器创建负载。更多...
VPIStatus	vpiInitDCFTrackerParams (VPIDCFTrackerParams *params)
	使用默认值初始化 VPIDCFTrackerParams。更多...
VPIStatus	vpiSubmitDCFTrackerLocalizeBatch (VPIStream stream, uint64_t backend, VPIPayload payload, const int32_t *enabledSequences, int32_t numSequences, VPIImage featureMaskingWindow, VPIImage inPatches, VPIArray inObjects, VPIArray outObjects, VPIImage outCorrelationResponses, VPIArray outMaxCorrelationResponses, const VPIDCFTrackerParams *params)
	使用判别相关滤波器方法在输入图像块中定位每个被跟踪对象。更多...
VPIStatus	vpiSubmitDCFTrackerUpdateBatch (VPIStream stream, uint64_t backend, VPIPayload payload, const int32_t *enabledSequences, int32_t numSequences, VPIImage featureMaskingWindow, VPIImage modelMaskingWindow, VPIImage inPatches, VPIArray trackedObjects, const VPIDCFTrackerParams *params)
	基于内部对象跟踪信息及其对应的输入图像块更新内部对象跟踪信息。更多...
VPIStatus	vpiDCFTrackerGetChannelWeights (VPIPayload payload, VPIArray *channelWeights, int32_t *numFeatureChannels)
	返回包含每个被跟踪对象的通道权重信息的数组。更多...

详细描述

使用判别相关滤波器 (DCF) 算法跟踪帧序列中的对象边界框。

处理流程允许外部自定义跟踪算法，包括跟踪终止条件和外部细化跟踪对象边界框的估计。

处理流程的高级伪代码如下

 VPIDCFTrackerCreationParams creatParams;
 vpiInitDCFTrackerCreationParams(&creatParams);
 // 根据需要自定义 creatParams
 
 VPIPayload dcfPayload;
 vpiCreateDCFTracker(..., NUM_SEQUENCES, MAX_OBJECTS, &creatParams, &dcfPayload);
 
 VPIPayload cropPayload;
 vpiCreateCropScaler(..., , NUM_SEQUENCES, MAX_OBJECTS, &cropPayload);
 
 // 可选地，用户可以检索存储通道权重的内部数组，以及
 // 每个被跟踪对象的最大相关性响应。这些可以与
 // 相关性图一起使用，以确定跟踪是否丢失。
 VPIArray channelWeights;
int32_t numFeatureChannels
 vpiDCFTrackerGetChannelWeights(dcfPayload, &channelWeights, &numFeatureChannels);
 
 // 存储每个对象的最大相关性响应的数组 (可选)
 VPIArray outMaxCorrelationResponses = // ...
 
 // 存储每个输入序列的当前（第一个）输入帧
 VPIImage frames[NUM_SEQUENCES] = // ...
 // 如果必须跟踪给定序列中的对象，则将元素设置为 1，否则
 // 0 表示忽略它们。
int32_t enabledSequences[NUM_SEQUENCES] = // ...
 
 // 输入帧中检测到的对象数组。它必须填充
 // 在所有输入帧序列中检测到的对象
 // 对象的状态必须为 \ref VPI_TRACKING_STATE_NEW。
 VPIArray inObjects = // ...
 
 // 具有估计边界框的对象数组。
 // 最初它是一个空数组，具有与 inObjects 相同的容量和格式。
 VPIArray outObjects = // ...
 
 // 存储所有对象的图像块的图像。
 // 尺寸必须为
 // 宽度：createParams.featurePatchSize*createParams.hogCellSize
 // 高度：宽度 * (inObjects 的容量)
 VPIImage objPatches = // ...
 
 VPIDCFTrackerParams params;
 vpiInitDCFTrackerParams(&params);
 // 根据需要自定义 params
 
 // 从第一帧中提取每个对象的图像块，给定其当前边界框。
 vpiSubmitCropScalerBatch(stream, cropPayload, frames, NUM_SEQUENCES,
inObjects, objPatches);
 
 // 使用在第一帧中检测到的新对象更新内部状态。
 vpiSubmitDCFTrackerUpdateBatch(stream, dcfPayload, enabledSequences, NUM_SEQUENCES,
NULL, objPatches, inObjects, &params);
 while(HasMoreFrames())
 {
     // 从输入序列加载下一组帧。
LoadNextFramesFromSequence(frames, NUM_SEQUENCES);
 
     for(int i=0; i<NUM_SEQUENCES; ++i) enabledSequences[i] = frames[i] != NULL;
 
     // 从当前帧中提取每个对象的图像块，给定
     // 其当前边界框。
     vpiSubmitCropScalerBatch(stream, cropPayload, frames, NUM_SEQUENCES,
NULL, inObjects, objPatches);
 
     // 在新的图像块中定位被跟踪的对象。
     vpiSubmitDCFTrackerLocalizeBatch(stream, dcfPayload, enabledSequences, NUM_SEQUENCES,
NULL, objPatches, inObjects, outObjects, outCorrelationResponses,
outMaxCorrelationResponses, &params);
     // 对象边界框将反映其在输入帧中的位置
 
     // 通过使用 'outMaxCorrelationResponses'、'outCorrelationResponses' 和 'channelWeights'，
     // 可以在此时完成以下处理
     // 1. 可以通过某些外部方法细化对象的边界框。
     // 2. 可以更新对象的状态，例如，跟踪是否丢失。如果跟踪
     // 丢失，则对象的状态必须设置为 \ref VPI_TRACKING_STATE_LOST。
     // 3. 可以将新对象添加到 outObjects，它们的状态必须为 \ref VPI_TRACKING_STATE_NEW。
     // 状态为 \ref VPI_TRACKING_STATE_LOST 的数组中的对象可以重用于新对象。
 
     // 从当前帧中提取每个对象的图像块，给定其细化的边界框。
     vpiSubmitCropScalerBatch(stream, cropPayload, frames, NUM_SEQUENCES, inObjects, objPatches);
 
     // 更新跟踪信息
     vpiSubmitDCFTrackerUpdateBatch(stream, dcfPayload, enabledSequences, NUM_SEQUENCES,
NULL, objPatches, outObjects, &params);
 
     // 使用 in 和 out 对象进行乒乓操作。
     // 输出对象数组将是下一次迭代的输入，而当前输入将是输出。
std::swap(inObjects, outObjects);
}

---

数据结构文档

VPIDCFTrackerCreationParams

struct VPIDCFTrackerCreationParams

DCF 跟踪器的创建参数。

定义在 191 行 DCFTracker.h 文件中。

VPIDCFTrackerCreationParams 的协作图

数据字段
uint32_t	flags	用于自定义 DCF 跟踪器算法的标志。 必须是 VPIDCFTrackerCreationFlag 枚举中的一个或多个，并进行或运算。 必须选择 colorname 或 HOG 或两者特征。 对于 PVA 后端，必须同时使用 colorname 和 hog。
int32_t	featurePatchSize	对象特征块的大小。 块图像始终是正方形，因此传递的值对应于一个维度。 对于 VPI_BACKEND_CUDA，有效大小为：12、18、24、30、32、36。 对于 VPI_BACKEND_PVA，有效大小为：24。
int32_t	hogCellSize	定向梯度直方图的特征的单元格大小。 必须介于 2 和 32 之间，包括 2 和 32。 必须是 2 的幂。
float	featureFocusVertOffsetFactor	汉宁窗口中心相对于块高度的偏移量。 必须介于 -0.5 到 0.5 之间，包括 -0.5 和 0.5
float	gaussianSigma	期望响应的高斯函数的标准差。 必须 > 0.0。

VPIDCFTrackerParams

struct VPIDCFTrackerParams

定义 vpiCreateDCFTracker 的参数的结构体。

定义在 277 行 DCFTracker.h 文件中。

VPIDCFTrackerParams 的协作图

数据字段
float	dcfRegFactor	DCF 滤波器创建中使用的正则化因子。

VPIDCFTrackedBoundingBox

struct VPIDCFTrackedBoundingBox

存储关于由 DCF 跟踪器 跟踪的对象的信息。

定义在 515 行 Types.h 文件中。

VPIDCFTrackedBoundingBox 的协作图

数据字段
VPIAxisAlignedBoundingBoxF32	bbox	被跟踪对象周围的边界框。
VPITrackingState	state	此边界框的跟踪状态。
int32_t	seqIndex	跟踪对象所在的输入序列的索引。 如果 seqIndex < 0，则假定序列被禁用，即，对象将不会被处理。
float	filterLR	指数移动平均中 DCF 滤波器的学习率。 必须介于 0.0 和 1.0 之间，包括 0.0 和 1.0。
float	filterChannelWeightsLR	DCF 中不同特征通道权重的学习率。 必须介于 0.0 和 1.0 之间，包括 0.0 和 1.0。
void *	userData	指向某些未指定用户数据的指针。 这用于将某些外部数据与跟踪对象关联。DCFTracker 不会以任何方式解释它，它只会复制它。

枚举类型文档

VPIDCFTrackerCreationFlag

enum VPIDCFTrackerCreationFlag

#include <vpi/algo/DCFTracker.h>

用于自定义 DCF 跟踪器算法的标志。

枚举器
VPI_DCFTRACKER_USE_COLORNAMES	使用 ColorNames 特征。
VPI_DCFTRACKER_USE_HOG	使用定向梯度直方图特征。
VPI_DCFTRACKER_USE_HIGH_PRECISION_FEATURES	使用 16 位高精度特征。 如果未设置，则使用 8 位精度特征。
VPI_DCFTRACKER_DETERMINISTIC	使用确定性模式。 确定性只能在每个架构上保证。

定义在 178 行 DCFTracker.h 文件中。

函数文档

vpiInitDCFTrackerCreationParams()

VPIStatus vpiInitDCFTrackerCreationParams

(

VPIDCFTrackerCreationParams *

params

)

#include <vpi/algo/DCFTracker.h>

使用默认值初始化 VPIDCFTrackerCreationParams。

默认值

• flags: VPI_DCFTRACKER_USE_COLORNAMES | VPI_DCFTRACKER_USE_HOG
• featurePatchSize: 24
• hogCellSize: 4
• featureFocusVertOffsetFactor: 0.0
• gaussianSigma: 0.75

参数

[out]

params

要填充默认值的结构体。

返回值

VPI_ERROR_INVALID_ARGUMENT	params 为 NULL。
VPI_SUCCESS	操作成功执行。

vpiCreateDCFTracker()

VPIStatus vpiCreateDCFTracker	(	uint64_t	backends,
		int32_t	maxNumSequences,
		int32_t	maxNumObjects,
		const VPIDCFTrackerCreationParams *	params,
		VPIPayload *	payload
	)

#include <vpi/algo/DCFTracker.h>

为 DCF 跟踪器创建负载。

参数

[in]	backends	有资格执行该算法的 VPI 后端。 有效值 VPI_BACKEND_PVA VPI_BACKEND_CUDA 后端必须在当前上下文中启用。
[in]	maxNumSequences	包含对象的序列的最大数量。 必须 >= 1。 对于 VPI_BACKEND_PVA，必须 <= 33 对于 VPI_BACKEND_CUDA，必须 <= 1024
[in]	maxNumObjects	要跟踪的最大对象数。 必须 >= 1。 对于 VPI_BACKEND_PVA，必须 <= 512
[in]	params	配置参数。传递 NULL 以使用 vpiInitDCFTrackerCreationParams 指定的默认值。
[out]	payload	指向接收创建句柄的负载变量的指针。

返回值

VPI_ERROR_INVALID_ARGUMENT	payload 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	backends 指的是无效的后端。
VPI_ERROR_INVALID_ARGUMENT	maxTrackedObjects 超出有效范围。
VPI_ERROR_INVALID_ARGUMENT	一个或多个配置参数无效。
VPI_ERROR_INVALID_OPERATION	PVA 硬件不可用。
VPI_ERROR_INVALID_OPERATION	后端在当前上下文中未启用。
VPI_ERROR_NOT_IMPLEMENTED	给定后端不支持 DCF 跟踪器算法。
VPI_ERROR_INVALID_CONTEXT	当前上下文已销毁。
VPI_ERROR_OUT_OF_MEMORY	无法分配所需资源。
VPI_SUCCESS	操作成功执行。

vpiInitDCFTrackerParams()

VPIStatus vpiInitDCFTrackerParams

(

VPIDCFTrackerParams *

params

)

#include <vpi/algo/DCFTracker.h>

使用默认值初始化 VPIDCFTrackerParams。

默认值

• dcfRegFactor: 5.f/100

参数

[out]

params

要填充默认值的结构体。

返回值

失败时返回错误代码，否则返回 VPI_SUCCESS。

vpiSubmitDCFTrackerLocalizeBatch()

VPIStatus vpiSubmitDCFTrackerLocalizeBatch	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		const int32_t *	enabledSequences,
		int32_t	numSequences,
		VPIImage	featureMaskingWindow,
		VPIImage	inPatches,
		VPIArray	inObjects,
		VPIArray	outObjects,
		VPIImage	outCorrelationResponses,
		VPIArray	outMaxCorrelationResponses,
		const VPIDCFTrackerParams *	params
	)

#include <vpi/algo/DCFTracker.h>

使用判别相关滤波器方法在输入图像块中定位每个被跟踪对象。

每个被跟踪对象的边界框将使用对象在其对应的输入块中的估计位置进行更新。

参数

[in]	stream	操作将要排队进入的流。 不得为 NULL。 流必须已启用将执行该算法的后端。
[in]	backend	将执行该算法的后端。 必须是在负载创建期间指定的后端，或者为 0 以简写形式使用此后端。
[in]	payload	由 vpiCreateDCFTracker 创建的负载。 不得为 NULL。
[in]	enabledSequences	定义要处理其对象的序列，而与其状态无关。 如果数组中的元素为 0，则引用给定索引的序列的对象将不会被处理，否则算法将使用对象的状态来判断是否要处理对象。 如果为 NULL，则所有序列都将启用。
[in]	numSequences	enabledSequences 中的元素数。 如果对象引用索引 >= numSequences 的序列，则假定此序列已启用。 或者，如果引用的序列索引 < 0，则假定此序列已禁用。 必须 >= 0 且 <= 负载创建中指定的最大序列数。
[in]	featureMaskingWindow	用作应用于每个对象特征通道的窗口的图像，通常用于减少边界效应。 如果为 NULL，则将在所有被跟踪的对象中使用标准汉宁窗口。 图像格式必须为 VPI_IMAGE_FORMAT_F32。 图像大小必须等于 featurePatchSize 配置中指定的特征大小。
[in]	inPatches	包含可能包含被跟踪对象的图像块的图像。 块通常由 CropScaler 算法生成。 不得为 NULL。 图像宽度必须等于 featurePatchSize * hogCellSize（参见 VPIDCFTrackerCreationParams）。 如果未使用 HOG，请考虑 hogCellSize==1。 图像高度必须是 featurePatchSize * hogCellSize 的倍数，并且至少为 featurePatchSize * hogCellSize * (inObjects 中对象的数量)。 如果未使用 HOG，请考虑 hogCellSize==1。 有效的图像格式 格式 CUDA PVA VPI_IMAGE_FORMAT_RGBA8 * VPI_IMAGE_FORMAT_RGB8p *
[in]	inObjects	包含被跟踪对象的输入数组。 不得为 NULL。 必须具有类型 VPI_ARRAY_TYPE_DCF_TRACKED_BOUNDING_BOX。 数组必须已启用将执行该算法的后端。
[out]	outObjects	输出对象的数组，其边界框已使用输入序列上的估计位置进行更新。 仅更新状态为 VPI_TRACKING_STATE_TRACKED 的对象。 其余对象只是被复制。 不得为 NULL。 必须具有类型 VPI_ARRAY_TYPE_DCF_TRACKED_BOUNDING_BOX。 其容量必须等于或大于 inObjects 中元素的数量。 数组必须已启用将执行该算法的后端。
[out]	outCorrelationResponses	可选输出，包含每个被跟踪对象的关联响应图。 如果为 NULL，则不会生成关联响应。 对象 'o' 的关联图将从行 o * featurePatchSize 开始，高度为 'featurePatchSize'。 必须是格式为 VPI_IMAGE_FORMAT_F32 的图像。 图像宽度必须等于块宽度（参见 VPIDCFTrackerCreationParams::featurePatchSize） 图像高度必须等于块高度乘以 inObjects 中对象的数量。
[out]	outMaxCorrelationResponses	可选输出，包含每个被跟踪对象的最大关联响应。 最大关联响应仅对状态为 VPI_TRACKING_STATE_TRACKED 和 VPI_TRACKING_STATE_SHADOW_TRACKED 的对象有效。 必须是类型为 VPI_ARRAY_TYPE_F32 的数组。 数组容量必须 >= inObjets 数组中对象的数量。
[in]	params	DCF 跟踪器算法的控制参数。 如果为 NULL，则使用 vpiInitDCFTrackerParams 指定的默认值。

返回值

VPI_ERROR_INVALID_ARGUMENT	stream 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	inPatches、inObjects 或 outObjects 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	payload 不是由 vpiCreateDCFTracker 创建的。
VPI_ERROR_INVALID_ARGUMENT	inObjects 或 outObjects 中不支持的数组类型。
VPI_ERROR_INVALID_ARGUMENT	outObjects 容量太小。
VPI_ERROR_INVALID_ARGUMENT	params 中的参数超出有效范围。
VPI_ERROR_INVALID_PAYLOAD_TYPE	payload 无效。
VPI_ERROR_INVALID_OPERATION	所需的后端在 stream、inPatches、inObjects 或 outObjects 中未启用。
VPI_SUCCESS	操作成功执行。

vpiSubmitDCFTrackerUpdateBatch()

VPIStatus vpiSubmitDCFTrackerUpdateBatch	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		const int32_t *	enabledSequences,
		int32_t	numSequences,
		VPIImage	featureMaskingWindow,
		VPIImage	modelMaskingWindow,
		VPIImage	inPatches,
		VPIArray	trackedObjects,
		const VPIDCFTrackerParams *	params
	)

#include <vpi/algo/DCFTracker.h>

基于内部对象跟踪信息及其对应的输入图像块更新内部对象跟踪信息。

对每个对象执行的操作取决于对象的状态

• VPI_TRACKING_STATE_NEW : 对象将设置为从给定的输入图像块开始跟踪。 在给定流中执行函数后，如果可以跟踪对象，则其状态将转换为 VPI_TRACKING_STATE_TRACKED，否则转换为 VPI_TRACKING_STATE_LOST。
• VPI_TRACKING_STATE_TRACKED : 使用输入图像块更新关于对象的内部信息，输入图像块必须对应于其在当前序列帧中的边界框，该边界框可能在 localize 和 update 调用之间被修改。

参数

[in]	stream	操作将要排队进入的流。 不得为 NULL。 流必须已启用将执行该算法的后端。
[in]	backend	将执行该算法的后端。 必须是在负载创建期间指定的后端，或者为 0 以简写形式使用此后端。
[in]	payload	由 vpiCreateDCFTracker 创建的负载。 不得为 NULL。
[in]	enabledSequences	定义要处理其对象的序列，而与其状态无关。 如果数组中的元素为 0，则引用给定索引的序列的对象将不会被处理，否则算法将使用对象的状态来判断是否要处理对象。 如果为 NULL，则所有序列都将启用。
[in]	numSequences	enabledSequences 中的元素数。 如果对象引用索引 >= numSequences 的序列，则假定此序列已启用。 或者，如果引用的序列索引 < 0，则假定此序列已禁用。 必须 >= 0 且 <= 负载创建中指定的最大序列数。
[in]	featureMaskingWindow	用作应用于每个对象特征通道的窗口的图像，通常用于减少边界效应。 如果为 NULL，则将对所有被跟踪的块使用标准汉宁窗口。 图像格式必须为 VPI_IMAGE_FORMAT_F32。 图像大小必须等于 featurePatchSize 配置中指定的块大小。
[in]	modelMaskingWindow	用作应用于内部对象模型的窗口的图像。 如果为 NULL，则将使用特征掩蔽窗口。 图像格式必须为 VPI_IMAGE_FORMAT_F32。 图像大小必须等于 featurePatchSize 配置中指定的块大小。
[in]	inPatches	包含 trackedObjects 中每个对象的块的图像，这些块对应于其边界框。 块通常由 CropScaler 算法生成。 不得为 NULL。 图像宽度必须等于 featurePatchSize * hogCellSize（参见 VPIDCFTrackerCreationParams）。 如果未使用 HOG，请考虑 hogCellSize==1。 图像高度必须是 featurePatchSize * hogCellSize 的倍数，并且至少为 featurePatchSize * hogCellSize * (trackedObjects 中对象的数量)。 如果未使用 HOG，请考虑 hogCellSize==1。 有效的图像格式 格式 CUDA PVA VPI_IMAGE_FORMAT_RGBA8 * VPI_IMAGE_FORMAT_RGB8p *
[in,out]	trackedObjects	包含被跟踪对象的数组。 不得为 NULL。 必须具有类型 VPI_ARRAY_TYPE_DCF_TRACKED_BOUNDING_BOX。 数组必须已启用将执行该算法的后端。
[in]	params	DCF 跟踪器算法的控制参数。 如果为 NULL，则使用 vpiInitDCFTrackerParams 指定的默认值。

返回值

VPI_ERROR_INVALID_ARGUMENT	stream 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	inPatches 或 trackedObjects 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	payload 不是由 vpiCreateDCFTracker 创建的。
VPI_ERROR_INVALID_ARGUMENT	inPatches 维度超出有效范围。
VPI_ERROR_INVALID_ARGUMENT	trackedObjects 中不支持的数组类型。
VPI_ERROR_INVALID_ARGUMENT	params 中的参数超出有效范围。
VPI_ERROR_INVALID_PAYLOAD_TYPE	payload 无效。
VPI_ERROR_INVALID_OPERATION	所需的后端在 stream、inPatches 或 trackedObjects 中未启用。
VPI_SUCCESS	操作成功执行。

vpiDCFTrackerGetChannelWeights()

VPIStatus vpiDCFTrackerGetChannelWeights	(	VPIPayload	payload,
		VPIArray *	channelWeights,
		int32_t *	numFeatureChannels
	)

#include <vpi/algo/DCFTracker.h>

返回包含每个被跟踪对象的通道权重信息的数组。

参数

[in]	payload	由 vpiCreateDCFTracker 创建的负载。 不得为 NULL。
[out]	channelWeights	每个被跟踪对象的通道权重数组。 返回的 VPIArray 具有类型 VPI_ARRAY_TYPE_F32，大小等于 numFeatureChannels 乘以被跟踪对象的数量。 数组缓冲区 'd' 中索引为 'o' 的对象权重 'c' 由下式给出 \[ w_d(c,o) = (float)d + c * numFeatureChannels \] 权重信息仅对状态为 VPI_TRACKING_STATE_TRACKED 的对象有效。 不得为 NULL。

注意

此数组不得通过 vpiArrayDestroy 销毁。

参数

[out]

numFeatureChannels

每个对象的特征通道数量。

返回值

VPI_ERROR_INVALID_ARGUMENT	channelWeights 或 numFeatureChannels 为 NULL。
VPI_SUCCESS	操作成功执行。