BruteForceMatcher#

Functions#

NVCVStatus pvaBruteForceMatcherCreate(NVCVOperatorHandle *handle)

Constructs an instance of the Brute Force Matcher operator.

NVCVStatus pvaBruteForceMatcherSubmit(NVCVOperatorHandle handle, cudaStream_t stream, PVABriefDescriptor *query, int32_t queryCount, PVABriefDescriptor *reference, int32_t referenceCount, int32_t maxMatchesPerQuery, PVABFMatchesType *matches, uint8_t enableCrossCheck, uint8_t enableDistanceRatioTest, int32_t lowesTestThresholdNumerator, int32_t lowesTestThresholdDenominator)

Submits the BruteForceMatcher operator to a CUDA stream.

NVCVStatus pvaBruteForceMatcherSubmit(NVCVOperatorHandle handle, cupvaStream_t stream, PVABriefDescriptor *query, int32_t queryCount, PVABriefDescriptor *reference, int32_t referenceCount, int32_t maxMatchesPerQuery, PVABFMatchesType *matches, uint8_t enableCrossCheck, uint8_t enableDistanceRatioTest, int32_t lowesTestThresholdNumerator, int32_t lowesTestThresholdDenominator)

Submits the BruteForceMatcher operator to a cuPVA stream.

Functions#

NVCVStatus pvaBruteForceMatcherCreate(NVCVOperatorHandle *handle)#

Constructs an instance of the Brute Force Matcher operator.

The Brute Force Matcher finds optimal matches between two sets of BRIEF (Binary Robust Independent Elementary Features) descriptors. Each descriptor is 256 bits (32 bytes) in length.

The matching process computes the Hamming distance between each query descriptor and all reference descriptors. For each query descriptor, it can return up to PVA_MAX_BF_MATCHES_PER_DESCRIPTOR best matches, sorted by ascending Hamming distance.

Operating Modes:

  1. Standard Mode (Cross Check Disabled):

    • Returns up to PVA_MAX_BF_MATCHES_PER_DESCRIPTOR best matches per query descriptor

  2. Cross Check Mode (Cross Check Enabled):

    • Returns exactly one match per query descriptor

    • A match is valid only if the query descriptor is also the best match for the reference descriptor

    • Invalid matches are indicated by a reference index of -1

    • Requires maxMatchesPerQuery to be set to 1

Limitations: The number of either query or reference descriptors should not be larger than PVA_MAX_BF_DESCRIPTOR_COUNT.

Parameters:

handle – [out] Where the operator instance handle will be written to.

  • Must not be NULL.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Handle is null.

  • NVCV_ERROR_OUT_OF_MEMORY – Failed to allocate memory for the operator.

  • NVCV_SUCCESS – Operation executed successfully.

NVCVStatus pvaBruteForceMatcherSubmit(
NVCVOperatorHandle handle,
cudaStream_t stream,
PVABriefDescriptor *query,
int32_t queryCount,
PVABriefDescriptor *reference,
int32_t referenceCount,
int32_t maxMatchesPerQuery,
PVABFMatchesType *matches,
uint8_t enableCrossCheck,
uint8_t enableDistanceRatioTest,
int32_t lowesTestThresholdNumerator,
int32_t lowesTestThresholdDenominator,
)#

Submits the BruteForceMatcher operator to a CUDA stream.

Note

CUDA stream support requirements:

  • PVA SDK 2.7.0 or later

  • Jetpack 7 or later

  • DriveOS 7 or later

  • x86 Emulator is not supported

Parameters:

  • handle – [in] Handle to the operator.

  • stream – [in] Handle to a valid CUDA stream.

  • query – [in] Pointer to the query descriptors.

  • queryCount – [in] Number of query descriptors.

  • reference – [in] Pointer to the reference descriptors.

  • referenceCount – [in] Number of reference descriptors.

  • maxMatchesPerQuery – [in] Maximum number of matches per query.

  • matches – [out] Pointer to the matches.

  • enableCrossCheck – [in] Whether to enable cross check.

  • enableDistanceRatioTest – [in] Whether to enable distance ratio test.

  • lowesTestThresholdNumerator – [in] Numerator of the Lowe’s ratio test threshold.

  • lowesTestThresholdDenominator – [in] Denominator of the Lowe’s ratio test threshold.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – The possible cases might be invalid parameters.

  • NVCV_SUCCESS – Operation executed successfully.

NVCVStatus pvaBruteForceMatcherSubmit(
NVCVOperatorHandle handle,
cupvaStream_t stream,
PVABriefDescriptor *query,
int32_t queryCount,
PVABriefDescriptor *reference,
int32_t referenceCount,
int32_t maxMatchesPerQuery,
PVABFMatchesType *matches,
uint8_t enableCrossCheck,
uint8_t enableDistanceRatioTest,
int32_t lowesTestThresholdNumerator,
int32_t lowesTestThresholdDenominator,
)#

Submits the BruteForceMatcher operator to a cuPVA stream.

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

  • stream – [in] Handle to a valid cuPVA stream.

    • Must not be NULL.

  • query – [in] Pointer to the query descriptors. PVABriefDescriptor.

    • Should point to a buffer that is accessible by PVA engine.

    • The size of the buffer should be at least queryCount * sizeof(PVABriefDescriptor).

  • queryCount – [in] Number of query descriptors.

    • Must be larger than 0 and less than or equal to PVA_MAX_BF_DESCRIPTOR_COUNT.

  • reference – [in] Pointer to the reference descriptors. PVABriefDescriptor.

    • Should point to a buffer that is accessible by PVA engine.

    • The size of the buffer should be at least referenceCount * sizeof(PVABriefDescriptor).

  • referenceCount – [in] Number of reference descriptors.

    • Must be larger than 0 and less than or equal to PVA_MAX_BF_DESCRIPTOR_COUNT.

  • maxMatchesPerQuery – [in] Maximum number of matches per query.

    • Must be larger than 0 and less than or equal to PVA_MAX_BF_MATCHES_PER_DESCRIPTOR.

    • When enableCrossCheck is 1 or enableDistanceRatioTest is 1, maxMatchesPerQuery must be 1

  • matches – [out] Pointer to the matches. PVABFMatchesType.

    • Should point to a buffer that is accessible by PVA engine.

    • The size of the buffer should be at least queryCount * sizeof(PVABFMatchesType).

  • enableCrossCheck – [in] Whether to enable cross check.

    • Must be 0 or 1.

  • enableDistanceRatioTest – [in] Whether to enable distance ratio test (Lowe’s ratio test).

    • Must be 0 or 1.

    • Only used when queryCount and referenceCount are larger than 1.

  • lowesTestThresholdNumerator – [in] Numerator of the Lowe’s ratio test threshold.

    • Must be larger than 0.

    • Only used when enableDistanceRatioTest is 1.

  • lowesTestThresholdDenominator – [in] Denominator of the Lowe’s ratio test threshold.

    • Must be larger than 0.

    • Only used when enableDistanceRatioTest is 1.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – The possible cases might be the following: 1) The handle or stream or query or reference is either NULL or points to an invalid address. 2) The queryCount or referenceCount is not larger than 0 or larger than PVA_MAX_BF_DESCRIPTOR_COUNT. 3) The maxMatchesPerQuery is not larger than 0 or less than or equal to PVA_MAX_BF_MATCHES_PER_DESCRIPTOR. 4) The enableCrossCheck is not 0 or 1. 5) The enableCrossCheck is 1 and maxMatchesPerQuery is not 1. 6) The enableDistanceRatioTest is not 0 or 1. 7) The enableDistanceRatioTest is 1 and maxMatchesPerQuery is not 1. 8) The enableDistanceRatioTest is 1 and queryCount and referenceCount are not larger than 1. 9) The enableDistanceRatioTest is 1 and lowesTestThresholdNumerator and lowesTestThresholdDenominator are not larger than 0. 10) The enableCrossCheck is 0 and enableDistanceRatioTest is 0 and maxMatchesPerQuery is greater than referenceCount.

  • NVCV_SUCCESS – Operation executed successfully.