VPI - Vision Programming Interface

3.0 Release

Brute Force Matcher


The brute force matcher algorithm uses query and reference descriptors provided as inputs and finds the closest (by distance) reference descriptor for every query descriptor. There is an additional option of cross checking provided, which notifies the algorithm to output only those matches that are closest to each other both ways, i.e if A is a query descriptor and B is a reference descriptor, B is closest reference descriptor to A and A is the closest query descriptor to B.


The brute force matcher algorithm calculates the distance between query and reference descriptors provided as input. The norm for distance calculation is provided by the user. The user can also choose the number of matches they want per query descriptor, in which case the smallest N (N being the number of matches per query <= 3) distant matches are provided. The user can choose to enable or disable cross check as well.

C API functions

For list of limitations, constraints and backends that implements the algorithm, consult reference documentation of the following functions:

Function Description
vpiSubmitBruteForceMatcher Runs a brute force matcher algorithm on descriptors.


  1. Initialization phase
    1. Include the header that defines the needed functions and structures.
      Declares functions that implement brute force matcher algorithms.
    2. Define the input descriptor arrays. They have to be of type VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR.
      VPIArray queryDescriptors;
      vpiArrayCreate(numDescriptors, VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR, 0, &queryDescriptors);
      VPIArray referenceDescriptors;
      vpiArrayCreate(numDescriptors, VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR, 0, &referenceDescriptors);
      VPIStatus vpiArrayCreate(int32_t capacity, VPIArrayType type, uint64_t flags, VPIArray *array)
      Create an empty array instance.
      struct VPIArrayImpl * VPIArray
      A handle to an array.
      Definition: Types.h:232
      VPIBriefDescriptor element.
      Definition: ArrayType.h:84
    3. Create the output array. It has to be of type VPI_ARRAY_TYPE_MATCHES.
      VPIArray output;
      vpiArrayCreate(numDescriptors, VPI_ARRAY_TYPE_MATCHES, 0, &output);
      VPIMatches element.
      Definition: ArrayType.h:85
    4. Create the stream where the algorithm will be submitted for execution.
      VPIStream stream;
      vpiStreamCreate(0, &stream);
      struct VPIStreamImpl * VPIStream
      A handle to a stream.
      Definition: Types.h:250
      VPIStatus vpiStreamCreate(uint64_t flags, VPIStream *stream)
      Create a stream instance.
  2. Processing phase
    1. Submit the algorithm for the brute force matcher. It'll be executed by the CPU backend.
      VPI_CHECK_STATUS(vpiSubmitBruteForceMatcher(stream, VPI_BACKEND_CPU, queryDescriptors, referenceDescriptors,
      VPI_NORM_HAMMING, maxMatchesPerQuery, output, flags));
      Hamming norm.
      Definition: Types.h:713
      VPIStatus vpiSubmitBruteForceMatcher(VPIStream stream, uint64_t backend, VPIArray queryDescriptor, VPIArray referenceDescriptor, VPINormType normType, int32_t maxMatchesPerQuery, VPIArray matches, uint32_t algoFlag)
      Runs a brute force matcher algorithm on descriptors.
      CPU backend.
      Definition: Types.h:92
    2. Optionally, wait until the processing is done.
      VPIStatus vpiStreamSync(VPIStream stream)
      Blocks the calling thread until all submitted commands in this stream queue are done (queue is empty)...
  3. Cleanup phase
    1. Free resources held by the stream and the input and output arrays.
      void vpiArrayDestroy(VPIArray array)
      Destroy an array instance.
      void vpiStreamDestroy(VPIStream stream)
      Destroy a stream instance and deallocate all HW resources.

For more information, see Brute Force Matcher in the "API Reference" section of VPI - Vision Programming Interface.


Performance benchmarks will be added at a later time.