VPI - Vision Programming Interface

2.2 Release

Minimum/Maximum Location


The Minimum/Maximum Location algorithm performs a 2D search operation on the input image. The algorithm looks for the minimum and maximum values of the pixels, which results in two sets of pixel locations for the minimum and maximum values. The locations are the \((x,y)\) coordinates of the pixels matching exactly the global minimum or maximum value. This operation is useful to locate peaks on an image, either highest or lowest or both.

This example shows an input image on the left with its corresponding minimum (blue) and maximum (red) locations on the right.

Input Output


The algorithm searches for the minimum and maximum values in the input image. Each pixel matching the minimum value has its location stored in an output array. The same is done for the maximum value in a second output array. Multiple locations of the same value, either minimum or maximum, may be found.

The location in the image is a keypoint with \((x, y)\) coordinates, corresponding to the \((j, i)\) matrix-based coordinates, respectively. The locations are stored in the user-provided output array up to the array capacity, which is defined upon array creation. This is done for both minimum and maximum output arrays. The maximum number of locations returned may be different for each array, as their corresponding capacity might differ. The user may choose not to provide an output array (by passing NULL in the argument) in which case the corresponding locations will not be searched for.

C API functions

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

Function Description
vpiCreateMinMaxLoc Creates payload for vpiSubmitMinMaxLoc.
vpiSubmitMinMaxLoc Finds minimum and maximum value locations in an image.


  1. Import VPI module
    import vpi
  2. Run MinMaxLoc search on the input image using the CPU backend. Input is a VPI image.
    with vpi.Backend.CPU:
    min_coords, max_coords = input.minmaxloc(min_capacity=10000, max_capacity=10000)
  3. Optionally, retrieve the minimum and maximum values.
    1. Lock the input image and the minimum/maximum output arrays to efficiently access their contents.
      with input.rlock_cpu() as in_data, min_coords.rlock_cpu() as min_data, max_coords.rlock_cpu() as max_data:
    2. Retrieve the coordinates of the first pixels with minimum and maximum values. The (x,y) coordinates are being swapped to (y,x) and converted into a tuple, suitable for 2D numpy array indexing.
      min_loc = tuple(min_data[0].astype(int)[::-1])
      max_loc = tuple(max_data[0].astype(int)[::-1])
    3. Use the first of these coordinates to retrieve the minimum/maximum pixel value.
      min_value = in_data[min_loc]
      max_value = in_data[max_loc]
  1. Initialization phase
    1. Include the header that defines the needed functions.
      Declares functions to perform minimum and maximum location finding in images.
    2. Define the input image object.
      VPIImage input = /*...*/;
      struct VPIImageImpl * VPIImage
      A handle to an image.
      Definition: Types.h:256
    3. Create the payload that will contain all temporary buffers needed for processing. Payload creation requires input's dimensions and format.
      vpiImageGetFormat(input, &format);
      int width, height;
      vpiImageGetSize(input, &width, &height);
      VPIPayload payload;
      vpiCreateMinMaxLoc(VPI_BACKEND_CPU, width, height, format, &payload);
      uint64_t VPIImageFormat
      Pre-defined image formats.
      Definition: ImageFormat.h:94
      VPIStatus vpiImageGetFormat(VPIImage img, VPIImageFormat *format)
      Get the image format.
      VPIStatus vpiImageGetSize(VPIImage img, int32_t *width, int32_t *height)
      Get the image dimensions in pixels.
      VPIStatus vpiCreateMinMaxLoc(uint64_t backends, int32_t imageWidth, int32_t imageHeight, VPIImageFormat imageFormat, VPIPayload *payload)
      Creates payload for vpiSubmitMinMaxLoc.
      struct VPIPayloadImpl * VPIPayload
      A handle to an algorithm payload.
      Definition: Types.h:268
      CPU backend.
      Definition: Types.h:92
    4. Create the output arrays for coordinates with minimum and maximum values. In this example, their capacity it set to 10,000, which limits the number of locations to be found.
      VPIArray minCoords;
      VPIArray maxCoords;
      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
      VPIKeypointF32 element.
      Definition: ArrayType.h:77
    5. 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 to the stream, passing the input image and output arrays. In this example, it will be executed by the CPU backend.
      vpiSubmitMinMaxLoc(stream, VPI_BACKEND_CPU, payload, input, minCoords, maxCoords);
      VPIStatus vpiSubmitMinMaxLoc(VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage input, VPIArray minCoords, VPIArray maxCoords)
      Finds minimum and maximum value locations in an image.
    2. Optionally, retrieve the minimum and maximum values.
      1. Synchronize the stream to make sure the operation is completed
        VPIStatus vpiStreamSync(VPIStream stream)
        Blocks the calling thread until all submitted commands in this stream queue are done (queue is empty)...
      2. Lock the input image and the minimum/maximum output arrays.
        VPIImageData inputImageData;
        VPIArrayData minCoordsData, maxCoordsData;
        VPIStatus vpiArrayLockData(VPIArray array, VPILockMode mode, VPIArrayBufferType bufType, VPIArrayData *data)
        Acquires the lock on an array object and returns the array contents.
        Host-accessible array-of-structures.
        Definition: Array.h:146
        Stores information about array characteristics and contents.
        Definition: Array.h:168
        VPIStatus vpiImageLockData(VPIImage img, VPILockMode mode, VPIImageBufferType bufType, VPIImageData *data)
        Acquires the lock on an image object and returns the image contents.
        Host-accessible with planes in pitch-linear memory layout.
        Definition: Image.h:172
        Stores information about image characteristics and content.
        Definition: Image.h:230
        @ VPI_LOCK_READ
        Lock memory only for reading.
        Definition: Types.h:498
      3. Retrieve the coordinates of the first minimum and maximum found.
        VPIKeypointF32 *min_coords = (VPIKeypointF32 *)minCoordsData.buffer.aos.data;
        VPIKeypointF32 *max_coords = (VPIKeypointF32 *)maxCoordsData.buffer.aos.data;
        int min_i = min_coords[0].y;
        int min_j = min_coords[0].x;
        int max_i = max_coords[0].y;
        int max_j = max_coords[0].x;
        void * data
        Points to the first element of the array.
        Definition: Array.h:135
        VPIArrayBuffer buffer
        Stores the array contents.
        Definition: Array.h:175
        VPIArrayBufferAOS aos
        Array stored in array-of-structures layout.
        Definition: Array.h:162
        float x
        Keypoint's x coordinate.
        Definition: Types.h:316
        float y
        Keypoint's y coordinate.
        Definition: Types.h:317
        Stores a float32 keypoint coordinate The coordinate is relative to the top-left corner of an image.
        Definition: Types.h:315
      4. Use these coordinates as a 2D index to the input image contents to retrieve the minimum/maximum pixel value. Here it's assumed that the input image format is VPI_IMAGE_FORMAT_U8. Different indexing must be employed for other formats.
        // Assuming that the input image is grayscale (only one plane).
        assert(inputImageData.buffer.pitch.numPlanes == 1);
        void *imgData = inputImageData.buffer.pitch.planes[0].data;
        int imgPitchBytes = inputImageData.buffer.pitch.planes[0].pitchBytes;
        // Assuming that the plane has 8-bit unsigned int type.
        assert(inputImageData.buffer.pitch.planes[0].pixelType == VPI_PIXEL_TYPE_U8);
        typedef unsigned char Pixel;
        typedef unsigned char Byte;
        const Pixel *min_row = (const Pixel *)((const Byte *)imgData + min_i * imgPitchBytes);
        const Pixel *max_row = (const Pixel *)((const Byte *)imgData + max_i * imgPitchBytes);
        unsigned char min_value = min_row[min_j];
        unsigned char max_value = max_row[max_j];
        #define VPI_PIXEL_TYPE_U8
        One channel of unsigned 8-bit value.
        Definition: PixelType.h:88
        VPIImageBuffer buffer
        Stores the image contents.
        Definition: Image.h:237
        VPIImagePlanePitchLinear planes[VPI_MAX_PLANE_COUNT]
        Data of all image planes in pitch-linear layout.
        Definition: Image.h:160
        VPIImageBufferPitchLinear pitch
        Image stored in pitch-linear layout.
        Definition: Image.h:206
        void * data
        Pointer to the first row of this plane.
        Definition: Image.h:141
        int32_t numPlanes
        Number of planes.
        Definition: Image.h:156
        VPIPixelType pixelType
        Type of each pixel within this plane.
        Definition: Image.h:115
        int32_t pitchBytes
        Difference in bytes of beginning of one row and the beginning of the previous.
        Definition: Image.h:134
      5. Since the image and array contents aren't needed anymore, they must be unlocked.
        VPIStatus vpiArrayUnlock(VPIArray array)
        Releases the lock on array object.
        VPIStatus vpiImageUnlock(VPIImage img)
        Releases the lock on an image object.
  3. Cleanup phase
    1. Free resources held by the stream, the payload and the input image and output arrays.
      void vpiArrayDestroy(VPIArray array)
      Destroy an array instance.
      void vpiImageDestroy(VPIImage img)
      Destroy an image instance.
      void vpiPayloadDestroy(VPIPayload payload)
      Deallocates the payload object and all associated resources.
      void vpiStreamDestroy(VPIStream stream)
      Destroy a stream instance and deallocate all HW resources.

For more information, see MinMaxLoc in the "C API Reference" section of VPI - Vision Programming Interface.


For information on how to use the performance table below, see Algorithm Performance Tables.
Before comparing measurements, consult Comparing Algorithm Elapsed Times.
For further information on how performance was benchmarked, see Performance Benchmark.