## VPI - Vision Programming Interface

#### 3.1 Release

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.

# C API functions

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

Function Description
vpiSubmitMinMaxLoc Finds minimum and maximum value locations in an image.

# Usage

Language:
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);
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.
A handle to an algorithm payload.
Definition: Types.h:268
@ VPI_BACKEND_CPU
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
@ VPI_ARRAY_TYPE_KEYPOINT_F32
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
vpiStreamSync(stream);
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.
@ VPI_ARRAY_BUFFER_HOST_AOS
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.
@ VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR
Host-accessible with planes in pitch-linear memory layout.
Definition: Image.h:172
Stores information about image characteristics and content.
Definition: Image.h:234
Definition: Types.h:617
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:335
float y
Keypoint's y coordinate.
Definition: Types.h:336
Stores a float32 keypoint coordinate The coordinate is relative to the top-left corner of an image.
Definition: Types.h:334
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:241
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:210
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.
vpiArrayUnlock(maxCoords);
vpiArrayUnlock(minCoords);
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.
vpiArrayDestroy(minCoords);
vpiArrayDestroy(maxCoords);
void vpiArrayDestroy(VPIArray array)
Destroy an array instance.
void vpiImageDestroy(VPIImage img)
Destroy an image instance.
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.

# 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.

-