Minimum/Maximum Location

Overview

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

Implementation

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.

Usage

Language: C/C++ Python

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.lock(), min_coords.lock(), max_coords.lock():

   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_coords.cpu()[0].astype(int)[::-1])
          max_loc = tuple(max_coords.cpu()[0].astype(int)[::-1])

   3. Use the first of these coordinates to retrieve the minimum/maximum pixel value.

          min_value = input.cpu()[min_loc]
          max_value = input.cpu()[max_loc]

1. Initialization phase
   1. Include the header that defines the needed functions.

      #include <vpi/algo/MinMaxLoc.h>

   2. Define the input image object.

          VPIImage input = /*...*/;

   3. Create the payload that will contain all temporary buffers needed for processing. Payload creation requires input's dimensions and format.

          VPIImageFormat format;
          vpiImageGetFormat(input, &format);
       
          int width, height;
          vpiImageGetSize(input, &width, &height);
       
          VPIPayload payload;
          vpiCreateMinMaxLoc(VPI_BACKEND_CPU, width, height, format, &payload);

   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;
          vpiArrayCreate(10000, VPI_ARRAY_TYPE_KEYPOINT, 0, &minCoords);
       
          VPIArray maxCoords;
          vpiArrayCreate(10000, VPI_ARRAY_TYPE_KEYPOINT, 0, &maxCoords);

   5. Create the stream where the algorithm will be submitted for execution.

          VPIStream stream;
          vpiStreamCreate(0, &stream);

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);

   2. Optionally, retrieve the minimum and maximum values.
      1. Synchronize the stream to make sure the operation is completed

             vpiStreamSync(stream);

      2. Lock the input image and the minimum/maximum output arrays.

             VPIImageData inputImageData;
             vpiImageLock(input, VPI_LOCK_READ, &inputImageData);
          
             VPIArrayData minCoordsData, maxCoordsData;
             vpiArrayLock(minCoords, VPI_LOCK_READ, &minCoordsData);
             vpiArrayLock(maxCoords, VPI_LOCK_READ, &maxCoordsData);

      3. Retrieve the coordinates of the first minimum and maximum found.

             VPIKeypoint *min_coords = (VPIKeypoint *)minCoordsData.data;
             VPIKeypoint *max_coords = (VPIKeypoint *)maxCoordsData.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;

      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.numPlanes == 1);
          
             void *imgData     = inputImageData.planes[0].data;
             int imgPitchBytes = inputImageData.planes[0].pitchBytes;
          
             // Assuming that the plane has 8-bit unsigned int type.
             assert(inputImageData.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];

      5. Since the image and array contents aren't needed anymore, they must be unlocked.

             vpiArrayUnlock(maxCoords);
             vpiArrayUnlock(minCoords);
             vpiImageUnlock(input);

3. Cleanup phase
   1. Free resources held by the stream, the payload and the input image and output arrays.

          vpiStreamDestroy(stream);
          vpiPayloadDestroy(payload);
          vpiImageDestroy(input);
          vpiArrayDestroy(minCoords);
          vpiArrayDestroy(maxCoords);

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

Limitations and constraints

CPU and CUDA backends

• The following input image formats are accepted:
  • VPI_IMAGE_FORMAT_U8
  • VPI_IMAGE_FORMAT_S8
  • VPI_IMAGE_FORMAT_U16
  • VPI_IMAGE_FORMAT_S16
  • VPI_IMAGE_FORMAT_U32
  • VPI_IMAGE_FORMAT_S32
  • VPI_IMAGE_FORMAT_F32
  • VPI_IMAGE_FORMAT_F64

Other backends

• Not implemented.

Performance

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.