Pairwise Matcher

group NVCV_C_ALGORITHM_PAIRWISE_MATCHER

Functions

NVCVStatus cvcudaPairwiseMatcherCreate(NVCVOperatorHandle *handle, NVCVPairwiseMatcherType algoChoice)

Constructs and an instance of the PairwiseMatcher operator.

Parameters:

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

    • Must not be NULL.

  • algoChoice – [in] Choice of algorithm to find pair-wise matches.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Handle is null.

  • NVCV_ERROR_OUT_OF_MEMORY – Not enough memory to create the operator.

  • NVCV_SUCCESS – Operation executed successfully.

NVCVStatus cvcudaPairwiseMatcherSubmit(NVCVOperatorHandle handle, cudaStream_t stream, NVCVTensorHandle set1, NVCVTensorHandle set2, NVCVTensorHandle numSet1, NVCVTensorHandle numSet2, NVCVTensorHandle matches, NVCVTensorHandle numMatches, NVCVTensorHandle distances, bool crossCheck, int matchesPerPoint, NVCVNormType normType)

Executes the PairwiseMatcher operation on the given CUDA stream. This operation does not wait for completion.

This operation computes the pair-wise matcher between two sets of n-dimensional points. For instance 128-dimensional descriptors as points. For each point $p1_i$, in the 1st set defined by set1 with size numSet1, the operator finds the best match (minimum distance) from $p1_i$ to a point in the 2nd set $p2_j$, defined by set2 with size numSet2. If crossCheck is true, $p1_i$ must also be the best match from $p2_j$ considering all possible matches from the 2nd set to the 1st set, to return them as a match.

Note

This operation does not guarantee deterministic output. Each output tensor limits the number of matches found by the operator, that is the total number may be greater than this limitation and the order of matches returned might differ in different runs.

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

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

    • Must be a valid CUDA stream.

  • set1 – [in] Input 1st set of points tensor. The first set of points to calculate pair-wise matcher between this 1st set and the 2nd set. The expected layout is [NMD] meaning a rank-3 tensor with first dimension as number of samples N, second dimension M as maximum number of points, and a third dimension D as depth dimension of each point, e.g. the output of SIFT has 128-Byte descriptor or D=128 and U8 data type that can be used as a set of points.

    • It must have consistent number of samples N across input and output tensors.

    • The size of the depth dimension D and data type must be consistent across input set of points tensors.

    • It must have U8 or U32 or F32 data type.

  • set2 – [in] Input 2nd set of points tensor. The second set of points to calculate pair-wise matcher between this 2nd set and the 1st set. The expected layout is [NMD] meaning a rank-3 tensor with first dimension as number of samples N, second dimension M as maximum number of points, and a third dimension D as depth dimension of each point, e.g. the output of SIFT has 128-Byte descriptor or D=128 and U8 data type that can be used as a set of points.

    • It must have consistent number of samples N across input and output tensors.

    • The size of the depth dimension D and data type must be consistent across input set of points tensors.

    • It must have U8 or U32 or F32 data type.

  • numSet1 – [in] Input tensor storing the actual number of points in set1 tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as number of samples N, and a potential last dimension C with number of channels. It expresses the total number of valid points in set1 if less than its maximum capacity M, else uses all M points.

    • It must have consistent number of samples N across input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have S32 data type.

    • It may be NULL to use entire set1 maximum capacity M as valid points.

  • numSet2 – [in] Input tensor storing the actual number of points in set2 tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as number of samples N, and a potential last dimension C with number of channels. It expresses the total number of valid points in set2 if less than its maximum capacity M, else uses all M points.

    • It must have consistent number of samples N across input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have S32 data type.

    • It may be NULL to use entire set2 maximum capacity M as valid points.

  • matches – [out] Output tensor to store the matches of points between 1st set set1 and 2nd set set2. The expected layout is [NMA], meaning rank-3 tensor with first dimension as the number of samples N, same as other tensors, second dimension M as maximum number of matches, not necessarily the same as other tensors, and third dimension A as the attributes of each match, fixed to 2 attributes: set1 index and set2 index.

    • It must have consistent number of samples N across input and output tensors.

    • It must have a number of matches M per sample N equal to the maximum allowed number of matches to be found between set1 and set2. The actual number of matches found is stored in numMatches.

    • It must have size of attributes dimension A equal 2.

    • It must have S32 data type.

  • numMatches – [out] Output tensor to store the number of matches found by the operator. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as number of samples N, and a potential last dimension C with number of channels. It expresses the toal number of matches found, regardless of the maximum allowed number of matches M in output tensor matches. Since matches are found randomly, they are discarded in a non-deterministic way when the number of matches found is bigger than M.

    • It must have consistent number of samples N across input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have S32 data type.

    • It may be NULL if crossCheck is false to disregard storing number of matches.

  • distances – [out] Output tensor to store distances of matches found by the operator. The expected layout is [NM] or [NMC], meaning rank-2 or rank-3 tensor with first dimension as number of samples N, same as other tensors, second dimension M as maximum number of distances, same as matches output tensors, and a potential last dimension C with number of channels. For each match found in matches, the distance between matched points is stored.

    • It must have consistent number of samples N across input and output tensors.

    • It must have the same dimension M of the matches tensor, meaning the maximum allowed number of distances must be equal to the maximum allowed number of matches.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NMC] tensor.

    • It must have F32 data type.

    • It may be NULL to disregard storing distances.

  • crossCheck – [in] Choice to do cross check. Use false to search only for matches from 1st set of points in set1 to 2nd set of points in set2. Use true to cross check best matches, a best match is only returned if it is the best match (minimum distance) from 1st set to 2nd set and vice versa.

  • matchesPerPoint – [in] Number of best matches $k$ per point. The operator returns the top-$k$ best matches from 1st set to 2nd set.

    • It must be between 1 and 64.

    • It has to be 1 if crossCheck is true.

  • normType – [in] Choice of norm type to normalize distances, used in points difference $|p1 - p2|$.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Some parameter is outside valid range.

  • NVCV_ERROR_INTERNAL – Internal error in the operator, invalid types passed in.

  • NVCV_SUCCESS – Operation executed successfully.