ORB 特征

在输入图像上运行 ORB 算法以检测特征并提取描述符。 更多...

数据结构
struct	VPIORBParams
	定义 vpiSubmitORBFeatureDetector 参数的结构体。 更多...

宏
#define	VPI_DISABLE_RBRIEF   (0x01)
	在 ORB 中使用非旋转不变 BRIEF。

函数
VPIStatus	vpiInitORBParams (VPIORBParams *params)
	使用默认值初始化 VPIORBParams。 更多...
VPIStatus	vpiCreateORBFeatureDetector (uint64_t backends, int32_t capacity, VPIPayload *payload)
	创建一个 ORB 特征检测器 负载。 更多...
VPIStatus	vpiSubmitORBFeatureDetector (VPIStream stream, uint64_t backend, VPIPayload payload, VPIPyramid input, VPIArray outCorners, VPIArray outDescriptors, const VPIORBParams *params, VPIBorderExtension border)
	将 ORB 特征检测器 操作提交到流。 更多...
VPIStatus	vpiCreateORBDescriptorExtractor (uint64_t backends, VPIPayload *payload)
	创建一个 ORB 描述符提取器 负载。 更多...
VPIStatus	vpiSubmitORBDescriptorExtractor (VPIStream stream, uint64_t backend, VPIPayload payload, VPIPyramid input, VPIArray inCorners, VPIArray outDescriptors, uint32_t flags)
	将 ORB 描述符提取器 操作提交到流。 更多...

详细描述

在输入图像上运行 ORB 算法以检测特征并提取描述符。

有关更多详细信息和使用示例，请参阅 ORB 特征检测器。

---

数据结构文档

VPIORBParams

struct VPIORBParams

定义 vpiSubmitORBFeatureDetector 参数的结构体。

定义于文件 ORB.h 的第 88 行。

VPIORBParams 的协作图

数据字段
VPIFASTCornerDetectorParams	fastParams	FAST 角点检测器的参数，有关更多详细信息，请参阅 FAST 角点检测器。 ORB 使用 FAST 算法来检测输入金字塔每层的角点或特征。
int32_t	maxFeaturesPerLevel	ORB 每层输入金字塔要使用的最大特征数 N。 在过滤前 N 个最佳角点之前，FAST 算法可能会在每层找到大量 C 个角点。数字 C 是创建 ORB 负载函数的容量输入参数：vpiCreateORBFeatureDetector。所有级别的最大特征数由作为参数传递给 submit ORB 函数的输出数组的容量定义：vpiSubmitORBFeatureDetector。过滤取决于 VPIORBParams::scoreType 参数。 数字 N（即此参数）必须小于或等于容量 C（请参阅上面的定义）。
int32_t	maxPyramidLevels	要利用的输入金字塔中的最大层数。
VPICornerScore	scoreType	分数类型允许定义如何为角点分配分数。 角点性分数用于对 FAST 检测到的所有角点从最高分值到最低分值进行排序。在分数分配之后，ORB 会过滤前 N 个最佳角点，其中 N 由参数确定：VPIORBParams::maxFeaturesPerLevel。使用 VPI_CORNER_SCORE_HARRIS 以根据 Harris 响应分数分配角点性分数。使用 VPI_CORNER_SCORE_FAST 以跳过角点性分数分配和排序。通过使用 FAST 分数类型，ORB 的性能得到提高，但输出特征的质量会降低。
uint32_t	flags	控制标志。 有效值是以下一个或多个标志的组合 0：默认值，所有其他标志的否定。 VPI_DISABLE_RBRIEF：禁用旋转不变 BRIEF。

函数文档

vpiInitORBParams()

VPIStatus vpiInitORBParams

(

VPIORBParams *

params

)

#include <vpi/algo/ORB.h>

使用默认值初始化 VPIORBParams。

默认值为

• params.fastParams 请参阅 vpiInitFASTCornerDetectorParams
• params.maxFeaturesPerLevel: 100
• params.maxPyramidLevels: 4
• params.scoreType: VPI_CORNER_SCORE_HARRIS;
• params.flags: 0

返回值

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

vpiCreateORBFeatureDetector()

VPIStatus vpiCreateORBFeatureDetector	(	uint64_t	backends,
		int32_t	capacity,
		VPIPayload *	payload
	)

#include <vpi/algo/ORB.h>

创建一个 ORB 特征检测器 负载。

此函数分配算法所需的所有临时内存。

参数

[in]	backends	有资格执行该算法的 VPI 后端。 有效值 VPI_BACKEND_CPU VPI_BACKEND_CUDA 后端必须在当前上下文中启用。
[in]	capacity	用于存储每个输入金字塔级别的 FAST 角点和分数的内部缓冲区的容量。它决定了在 ORB 过滤之前 FAST 检测到的每层最大特征数。ORB 算法为这些特征分配分数，参见 VPIORBParams::scoreType，并对其进行排序以过滤前 N 个最佳特征，其中 N 是 VPIORBParams::maxFeaturesPerLevel 参数。
[out]	payload	指向接收创建句柄的负载变量的指针。

返回值

VPI_ERROR_INVALID_ARGUMENT	payload 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	backends 引用了无效的后端。
VPI_ERROR_INVALID_OPERATION	后端硬件不可用。
VPI_ERROR_NOT_IMPLEMENTED	给定后端不支持 ORB 算法。
VPI_ERROR_INVALID_CONTEXT	当前上下文已销毁。
VPI_ERROR_OUT_OF_MEMORY	无法分配所需资源。
VPI_ERROR_INVALID_OPERATION	后端在当前上下文中未启用。
VPI_SUCCESS	操作执行成功。

vpiSubmitORBFeatureDetector()

VPIStatus vpiSubmitORBFeatureDetector	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		VPIPyramid	input,
		VPIArray	outCorners,
		VPIArray	outDescriptors,
		const VPIORBParams *	params,
		VPIBorderExtension	border
	)

#include <vpi/algo/ORB.h>

将 ORB 特征检测器 操作提交到流。

注意

此操作同时检测特征并提取描述符。如果只需要特征检测，请使用此操作并将 NULL 传递给描述符输出数组以使其被忽略。

参数

[in]	stream	操作将排队的流。 不得为 NULL。 流必须启用将执行该算法的后端。
[in]	backend	将执行该算法的后端。 有效值 VPI_BACKEND_CPU VPI_BACKEND_CUDA
[in]	payload	要与其他参数一起提交的负载。
[in]	input	输入 要在其上执行 ORB 的输入金字塔。 不得为 NULL。 金字塔必须启用将执行该算法的后端。 输入金字塔的比例必须为 0.5。 接受的图像格式为 VPI_IMAGE_FORMAT_Y8 VPI_IMAGE_FORMAT_Y16 VPI_IMAGE_FORMAT_Y8_ER VPI_IMAGE_FORMAT_Y16_ER VPI_IMAGE_FORMAT_U8 VPI_IMAGE_FORMAT_S8 VPI_IMAGE_FORMAT_U16 VPI_IMAGE_FORMAT_S16
[out]	outCorners	将接收检测到的角点的数组。数组大小根据找到的角点数量更新。数组容量定义了所有级别要找到的最大角点数。所有级别中可能的最大特征数 F 定义为 VPIORBParams.maxFeaturesPerLevel 乘以级别数。 不得为 NULL。 它必须具有 VPI_ARRAY_TYPE_PYRAMIDAL_KEYPOINT_F32 类型（请参阅注意）。 如果小于 F（见上文），则它必须与 outDescriptors 具有相同的容量。 数组必须启用将执行该算法的后端。
[out]	outDescriptors	将接收角点描述符的数组。数组大小根据找到的角点数量更新。数组容量定义了所有级别要找到的最大描述符数。所有级别中可能的最大特征数 F 定义为 VPIORBParams.maxFeaturesPerLevel 乘以级别数。 它可以为 NULL 以仅进行特征检测。 它必须具有 VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR 类型。 如果小于 F（见上文），则它必须与 outCorners 具有相同的容量。 数组必须启用将执行该算法的后端。
[in]	params	指向 VPIORBParams 的指针。它定义了此算法调用的参数。这些参数在每次调用中都可能不同，并将内部复制。因此，无需保留参数对象。 如果为 NULL，则使用 vpiInitORBParams 给出的默认值。
[in]	border	如何处理图像边界外的像素。它影响每个级别的 FAST 角点检测，参考 FAST 角点检测器。 接受的边界扩展为 VPI_BORDER_ZERO VPI_BORDER_CLAMP VPI_BORDER_REFLECT VPI_BORDER_MIRROR VPI_BORDER_LIMITED（忽略圆超出图像边界的像素）

注意

为了向后兼容 VPI 3.0，VPI_ARRAY_TYPE_KEYPOINT_F32 也作为 outCorners 参数的数组类型受支持。使用 VPI 3.0 传统 ORB 行为，关键点坐标缩放到第一金字塔级别的分辨率，描述符在金字塔的第一张图像中计算。

返回值

VPI_ERROR_INVALID_ARGUMENT	stream 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	input 或 outCorners 或 outDescriptors 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	backend 无效或未知。
VPI_ERROR_INVALID_ARGUMENT	params 中的参数超出有效范围。
VPI_ERROR_INVALID_ARRAY_TYPE	无效的 outCorners 或 outDescriptors 数组类型。
VPI_ERROR_INVALID_IMAGE_FORMAT	不支持的输入格式。
VPI_ERROR_INVALID_OPERATION	所需的后端在 stream 或 input 中未启用。
VPI_ERROR_INVALID_OPERATION	所需的后端在 outCorners 或 outDescriptors 中未启用。
VPI_SUCCESS	操作执行成功。

vpiCreateORBDescriptorExtractor()

VPIStatus vpiCreateORBDescriptorExtractor	(	uint64_t	backends,
		VPIPayload *	payload
	)

#include <vpi/algo/ORB.h>

创建一个 ORB 描述符提取器 负载。

此函数分配算法所需的所有临时内存。

参数

[in]	backends	有资格执行该算法的 VPI 后端。 有效值 VPI_BACKEND_CPU VPI_BACKEND_CUDA VPI_BACKEND_PVA 后端必须在当前上下文中启用。
[out]	payload	指向接收创建句柄的负载变量的指针。

返回值

VPI_ERROR_INVALID_ARGUMENT	payload 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	backends 引用了无效的后端。
VPI_ERROR_INVALID_OPERATION	后端硬件不可用。
VPI_ERROR_NOT_IMPLEMENTED	给定后端不支持 ORB 算法。
VPI_ERROR_INVALID_CONTEXT	当前上下文已销毁。
VPI_ERROR_OUT_OF_MEMORY	无法分配所需资源。
VPI_ERROR_INVALID_OPERATION	后端在当前上下文中未启用。
VPI_SUCCESS	操作执行成功。

vpiSubmitORBDescriptorExtractor()

VPIStatus vpiSubmitORBDescriptorExtractor	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		VPIPyramid	input,
		VPIArray	inCorners,
		VPIArray	outDescriptors,
		uint32_t	flags
	)

#include <vpi/algo/ORB.h>

将 ORB 描述符提取器 操作提交到流。

注意

仅在需要解耦 ORB 特征检测和提取的情况下，此操作才有用。对于同时执行检测和提取的情况，请改用 vpiSubmitORBFeatureDetector。

参数

[in]	stream	操作将排队的流。 不得为 NULL。 流必须启用将执行该算法的后端。
[in]	backend	将执行该算法的后端。 有效值 VPI_BACKEND_CPU VPI_BACKEND_CUDA VPI_BACKEND_PVA
[in]	payload	为将来使用保留的负载。它可以为 NULL。
[in]	input	输入 要在其上执行 ORB 描述符提取器的输入。 不得为 NULL。 输入必须启用将执行该算法的后端。 输入必须是 VPIPyramid（请参阅注意）。 输入金字塔的比例必须为 0.5。 接受的图像格式为 VPI_IMAGE_FORMAT_Y8 VPI_IMAGE_FORMAT_Y16 VPI_IMAGE_FORMAT_Y8_ER VPI_IMAGE_FORMAT_Y16_ER VPI_IMAGE_FORMAT_U8 VPI_IMAGE_FORMAT_S8 VPI_IMAGE_FORMAT_U16 VPI_IMAGE_FORMAT_S16 使用 VPI_BACKEND_PVA 不支持有符号的图像格式。 每个金字塔级别的分辨率必须大于 45x45
[in]	inCorners	包含要从中计算描述符的角点的数组。此数组中的每个项目（即一个角点）用于计算输出数组中的一个项目（即相应角点的描述符）。此输入数组的大小决定了要从中提取描述符的角点数。 不得为 NULL。 它必须具有 VPI_ARRAY_TYPE_PYRAMIDAL_KEYPOINT_F32 类型（请参阅注意）。 数组必须启用将执行该算法的后端。 使用 VPI_BACKEND_PVA VPIPyramidalKeypointF32::layer 被忽略，并且描述符的计算方式始终好像 layer == 0。
[out]	outDescriptors	将接收角点描述符的数组。此输出数组中的每个位置都对应于输入数组中相同位置的角点描述符。输出数组容量定义了要提取的最大描述符数。输出数组容量必须大于输入数组的大小，才能为所有角点提取描述符。 不得为 NULL。 它必须具有 VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR 类型。 数组必须启用将执行该算法的后端。 使用 VPI_BACKEND_PVA 由 PVA 生成的描述符通常与由其他后端生成的描述符不兼容。
[in]	flags	控制标志。 有效值是以下一个或多个标志的组合 0：默认值，所有其他标志的否定。 VPI_DISABLE_RBRIEF：禁用旋转不变 BRIEF

注意

为了向后兼容 VPI 3.0，提供了一种替代 API 签名，其中 input 必须是 VPIImage，并且 inCorners 必须具有 VPI_ARRAY_TYPE_KEYPOINT_F32 类型。要选择 VPI 3.0 接口，请在包含 ORB.h 头文件之前，将 NV_VPI_VERSION_API 定义为 NV_VPI_MAKE_VERSION(3,0)。PVA 后端仅支持 API 级别 3.1 及更高版本，同时使用 VPI 库版本 3.2 及更高版本。

返回值

VPI_ERROR_INVALID_ARGUMENT	stream 或 input 或 inCorners 或 outDescriptors 为 NULL。
VPI_ERROR_INVALID_ARGUMENT	backend 无效或未知。
VPI_ERROR_INVALID_ARRAY_TYPE	无效的 inCorners 或 outDescriptors 数组类型。
VPI_ERROR_INVALID_IMAGE_FORMAT	不支持的输入格式。
VPI_ERROR_INVALID_OPERATION	所需的后端在 stream 或 input 中未启用。
VPI_ERROR_INVALID_OPERATION	所需的后端在 inCorners 或 outDescriptors 中未启用。
VPI_SUCCESS	操作执行成功。