ORB features

Runs the ORB algorithm over the input image to detect features and extract descriptors. More...

Data Structures
struct	VPIORBParams
	Structure that defines the parameters for vpiSubmitORBFeatureDetector. More...

Macros
#define	VPI_DISABLE_RBRIEF   (0x01)
	Use non-rotationally-invariant BRIEF in ORB.

Functions
VPIStatus	vpiInitORBParams (VPIORBParams *params)
	Initializes VPIORBParams with default values. More...
VPIStatus	vpiCreateORBFeatureDetector (uint64_t backends, int32_t capacity, VPIPayload *payload)
	Creates an ORB feature detector payload. More...
VPIStatus	vpiSubmitORBFeatureDetector (VPIStream stream, uint64_t backend, VPIPayload payload, VPIPyramid input, VPIArray outCorners, VPIArray outDescriptors, const VPIORBParams *params, VPIBorderExtension border)
	Submits an ORB feature detector operation to the stream. More...
VPIStatus	vpiCreateORBDescriptorExtractor (uint64_t backends, VPIPayload *payload)
	Creates an ORB descriptor extractor payload. More...
VPIStatus	vpiSubmitORBDescriptorExtractor (VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage input, VPIArray inCorners, VPIArray outDescriptors, uint32_t flags)
	Submits an ORB descriptor extractor operation to the stream. More...

Detailed Description

Runs the ORB algorithm over the input image to detect features and extract descriptors.

Refer to ORB feature detector for more details and usage examples.

---

Data Structure Documentation

VPIORBParams

struct VPIORBParams

Structure that defines the parameters for vpiSubmitORBFeatureDetector.

Definition at line 88 of file ORB.h.

Collaboration diagram for VPIORBParams:

Data Fields
VPIFASTCornerDetectorParams	fastParams	Parameters for the FAST corner detector, see FAST Corners Detector for more details. The FAST algorithm is used by ORB to detect corners or features per level of the input pyramid.
int32_t	maxFeaturesPerLevel	The maximum number N of features per level of the input pyramid to be used by ORB. The FAST algorithm may find a large number C of corners per level prior to filtering the N top corners. The number C is the capacity input argument for the create ORB payload function: vpiCreateORBFeatureDetector. The maximum number of features for all levels is defined by the capacity of the output arrays passed as arguments to the submit ORB function: vpiSubmitORBFeatureDetector. The filtering is done depending on the VPIORBParams::scoreType parameter. The number N (i.e. this parameter) must be lower or equal to the capacity C (see above definitions).
int32_t	maxPyramidLevels	Maximum number of levels in the input pyramid to utilize.
VPICornerScore	scoreType	The score type allows to define how scores are assigned to corners. The cornerness score is used to sort all corners detected by FAST from highest to lowest score value. After score assignment, ORB filters the top N corners, where N is determined by the parameter: VPIORBParams::maxFeaturesPerLevel. Use VPI_CORNER_SCORE_HARRIS to assign cornerness scores based on Harris response score. Use VPI_CORNER_SCORE_FAST to skip cornerness score assignment and sorting. By using FAST score type the performance of ORB is improved but the quality of output features is reduced.
uint32_t	flags	Control flags. Valid values are a combination of one or more of the following flags: 0: default, negation of all other flags. VPI_DISABLE_RBRIEF : Disable rotationally-invariant BRIEF.

Function Documentation

vpiInitORBParams()

VPIStatus vpiInitORBParams

(

VPIORBParams *

params

)

#include </opt/nvidia/vpi2/include/vpi/algo/ORB.h>

Initializes VPIORBParams with default values.

Default values are:

• params.fastParams See vpiInitFASTCornerDetectorParams
• params.maxFeaturesPerLevel: 100
• params.maxPyramidLevels: 4
• params.scoreType: VPI_CORNER_SCORE_HARRIS;
• params.flags: 0

Return values

VPI_ERROR_INVALID_ARGUMENT	params is NULL.
VPI_SUCCESS	Operation executed successfully.

vpiCreateORBFeatureDetector()

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

#include </opt/nvidia/vpi2/include/vpi/algo/ORB.h>

Creates an ORB feature detector payload.

This function allocates all temporary memory needed by the algorithm.

Parameters

[in]	backends	VPI backends that are eligible to execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA Backend must be enabled in current context.
[in]	capacity	Capacity of internal buffers used to store FAST corners and scores per input pyramid level. It determines the maximum number of features per level detected by FAST prior to ORB filtering. The ORB algorithm assigns scores to these features, cf. VPIORBParams::scoreType, and sort them to filter the top N best features in accordance to these scores, where N is the VPIORBParams::maxFeaturesPerLevel parameter.
[out]	payload	Pointer to the payload variable that receives the created handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	payload is NULL.
VPI_ERROR_INVALID_ARGUMENT	backends refers to an invalid backend.
VPI_ERROR_INVALID_OPERATION	Backend hardware not available.
VPI_ERROR_NOT_IMPLEMENTED	ORB algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_ERROR_OUT_OF_MEMORY	Cannot allocate required resources.
VPI_ERROR_INVALID_OPERATION	Backend isn't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitORBFeatureDetector()

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

#include </opt/nvidia/vpi2/include/vpi/algo/ORB.h>

Submits an ORB feature detector operation to the stream.

Note

This operation detects features and extracts descriptors at the same time. In case only the feature detection is necessary, use this operation passing NULL to the descriptor output array for it to be ignored.

Parameters

[in]	stream	The stream where the operation will be queued in. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA
[in]	payload	Payload to be submitted along the other parameters.
[in]	input	Input Input pyramid on which ORB will be executed. Must not be NULL. Pyramid must have enabled the backends that will execute the algorithm. The accepted image formats are: 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	Array that will receive the detected corners. Array size is updated with the number of corners found. Array capacity defines the maximum number of corners to be found for all levels. The maximum possible number of features in all levels F is defined as the VPIORBParams.maxFeaturesPerLevel times the number of levels. Must not be NULL. It must have type VPI_ARRAY_TYPE_KEYPOINT_F32. It must have the same capacity as outDescriptors if less than F (see above). Array must have enabled the backends that will execute the algorithm.
[out]	outDescriptors	Array that will receive the descriptors for the corners Array size is updated with the number of corners found. Array capacity defines the maximum number of descriptors to be found for all levels. The maximum possible number of features in all levels F is defined as the VPIORBParams.maxFeaturesPerLevel times the number of levels. It may be NULL to do feature detection only. It must have type VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR. It must have the same capacity as outCorners if less than F (see above). Array must have enabled the backends that will execute the algorithm.
[in]	params	Pointer to a VPIORBParams. It defines the parameters for this algorithm invocation. These parameters can vary in every call and will be copied internally. Thus there is no need to keep the parameters object around. If NULL, use the defaults given by vpiInitORBParams.
[in]	border	How to handle pixels outside image boundaries. It affects FAST corner detection per level, rf. FAST Corners Detector. The accepted border extensions are: VPI_BORDER_ZERO VPI_BORDER_CLAMP VPI_BORDER_REFLECT VPI_BORDER_MIRROR VPI_BORDER_LIMITED (ignore pixels with circle going outside image boundaries)

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	input or outCorners or outDescriptors are NULL.
VPI_ERROR_INVALID_ARGUMENT	backend is invalid or unknown.
VPI_ERROR_INVALID_ARGUMENT	A parameter in params is outside valid range.
VPI_ERROR_INVALID_ARRAY_TYPE	Invalid outCorners or outDescriptors array type.
VPI_ERROR_INVALID_IMAGE_FORMAT	Unsupported input format.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream or input.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in outCorners or outDescriptors.
VPI_SUCCESS	Operation executed successfully.

vpiCreateORBDescriptorExtractor()

VPIStatus vpiCreateORBDescriptorExtractor	(	uint64_t	backends,
		VPIPayload *	payload
	)

#include </opt/nvidia/vpi2/include/vpi/algo/ORB.h>

Creates an ORB descriptor extractor payload.

This function allocates all temporary memory needed by the algorithm.

Parameters

[in]	backends	VPI backends that are eligible to execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA Backend must be enabled in current context.
[out]	payload	Pointer to the payload variable that receives the created handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	payload is NULL.
VPI_ERROR_INVALID_ARGUMENT	backends refers to an invalid backend.
VPI_ERROR_INVALID_OPERATION	Backend hardware not available.
VPI_ERROR_NOT_IMPLEMENTED	ORB algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_ERROR_OUT_OF_MEMORY	Cannot allocate required resources.
VPI_ERROR_INVALID_OPERATION	Backend isn't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitORBDescriptorExtractor()

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

#include </opt/nvidia/vpi2/include/vpi/algo/ORB.h>

Submits an ORB descriptor extractor operation to the stream.

Note

This operation is only useful in a scenario where decoupled ORB feature detection and extraction is necessary. For cases where both detection and extraction is executed at the same time, use vpiSubmitORBFeatureDetector instead.

Parameters

[in]	stream	The stream where the operation will be queued in. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA
[in]	payload	Payload reserved for future use. It may be NULL.
[in]	input	Input image on which ORB descriptor extractor will be executed. Must not be NULL. Image must have enabled the backends that will execute the algorithm. The accepted image formats are: 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
[in]	inCorners	Array with corners to compute descriptors from. Each item in this array, i.e. a corner, is used to compute one item in the output array, i.e. a descriptor for the corresponding corner. The size of this input array determines the number of corners to extract descriptors from. Must not be NULL. It must have type VPI_ARRAY_TYPE_KEYPOINT_F32. Array must have enabled the backends that will execute the algorithm.
[out]	outDescriptors	Array that will receive the descriptors for the corners. Each position in this output array corresponds to the corner descriptor for the same position in the input array. The output array capacity defines the maximum number of descriptors to be extracted. The output array capacity must be bigger than the size of the input array to extract descriptors for all corners. Must not be NULL. It must have type VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR. Array must have enabled the backends that will execute the algorithm.
[in]	flags	Control flags. Valid values are a combination of one or more of the following flags: 0: default, negation of all other flags. VPI_DISABLE_RBRIEF : Enable rotationally-invariant BRIEF.

Return values

VPI_ERROR_INVALID_ARGUMENT	Either stream or input or inCorners or outDescriptors is NULL.
VPI_ERROR_INVALID_ARGUMENT	The backend is invalid or unknown.
VPI_ERROR_INVALID_ARRAY_TYPE	Invalid inCorners or outDescriptors array type.
VPI_ERROR_INVALID_IMAGE_FORMAT	Unsupported input format.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream or input.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in inCorners or outDescriptors.
VPI_SUCCESS	Operation executed successfully.