VPI - Vision Programming Interface

3.0 Release

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/vpi3/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_ARGUMENTparams is NULL.
VPI_SUCCESSOperation executed successfully.

◆ vpiCreateORBFeatureDetector()

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

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

Creates an ORB feature detector payload.

This function allocates all temporary memory needed by the algorithm.

Parameters
[in]backendsVPI backends that are eligible to execute the algorithm.
[in]capacityCapacity 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]payloadPointer to the payload variable that receives the created handle.
Return values
VPI_ERROR_INVALID_ARGUMENTpayload is NULL.
VPI_ERROR_INVALID_ARGUMENTbackends refers to an invalid backend.
VPI_ERROR_INVALID_OPERATIONBackend hardware not available.
VPI_ERROR_NOT_IMPLEMENTEDORB algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_ERROR_OUT_OF_MEMORYCannot allocate required resources.
VPI_ERROR_INVALID_OPERATIONBackend isn't enabled in current context.
VPI_SUCCESSOperation 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/vpi3/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]streamThe stream where the operation will be queued in.
  • Must not be NULL.
  • Stream must have enabled the backends that will execute the algorithm.
[in]backendBackend that will execute the algorithm.
[in]payloadPayload to be submitted along the other parameters.
[in]inputInput Input pyramid on which ORB will be executed.
[out]outCornersArray 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]outDescriptorsArray 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]paramsPointer 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.
[in]borderHow to handle pixels outside image boundaries. It affects FAST corner detection per level, rf. FAST Corners Detector.
Return values
VPI_ERROR_INVALID_ARGUMENTstream is NULL.
VPI_ERROR_INVALID_ARGUMENTinput or outCorners or outDescriptors are NULL.
VPI_ERROR_INVALID_ARGUMENTbackend is invalid or unknown.
VPI_ERROR_INVALID_ARGUMENTA parameter in params is outside valid range.
VPI_ERROR_INVALID_ARRAY_TYPEInvalid outCorners or outDescriptors array type.
VPI_ERROR_INVALID_IMAGE_FORMATUnsupported input format.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in stream or input.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in outCorners or outDescriptors.
VPI_SUCCESSOperation executed successfully.

◆ vpiCreateORBDescriptorExtractor()

VPIStatus vpiCreateORBDescriptorExtractor ( uint64_t  backends,
VPIPayload payload 
)

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

Creates an ORB descriptor extractor payload.

This function allocates all temporary memory needed by the algorithm.

Parameters
[in]backendsVPI backends that are eligible to execute the algorithm.
[out]payloadPointer to the payload variable that receives the created handle.
Return values
VPI_ERROR_INVALID_ARGUMENTpayload is NULL.
VPI_ERROR_INVALID_ARGUMENTbackends refers to an invalid backend.
VPI_ERROR_INVALID_OPERATIONBackend hardware not available.
VPI_ERROR_NOT_IMPLEMENTEDORB algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_ERROR_OUT_OF_MEMORYCannot allocate required resources.
VPI_ERROR_INVALID_OPERATIONBackend isn't enabled in current context.
VPI_SUCCESSOperation executed successfully.

◆ vpiSubmitORBDescriptorExtractor()

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

#include </opt/nvidia/vpi3/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]streamThe stream where the operation will be queued in.
  • Must not be NULL.
  • Stream must have enabled the backends that will execute the algorithm.
[in]backendBackend that will execute the algorithm.
[in]payloadPayload reserved for future use. It may be NULL.
[in]inputInput image on which ORB descriptor extractor will be executed.
[in]inCornersArray 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]outDescriptorsArray 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.
[in]flagsControl 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_ARGUMENTEither stream or input or inCorners or outDescriptors is NULL.
VPI_ERROR_INVALID_ARGUMENTThe backend is invalid or unknown.
VPI_ERROR_INVALID_ARRAY_TYPEInvalid inCorners or outDescriptors array type.
VPI_ERROR_INVALID_IMAGE_FORMATUnsupported input format.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in stream or input.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in inCorners or outDescriptors.
VPI_SUCCESSOperation executed successfully.