VPI - Vision Programming Interface

3.0 Release
Data Structures | Functions
WarpMap
Core Components

Defines the VPIWarpMap object and related functions. More...

Data Structures

struct  VPIWarpGrid
 Holds VPI's warp grid definition. More...
 
struct  VPIWarpMap
 Defines the mapping between input and output images' pixels. More...
 

Functions

VPIStatus vpiWarpMapAllocData (VPIWarpMap *warpMap)
 Allocates the warp map's control point array for a given warp grid. More...
 
void vpiWarpMapFreeData (VPIWarpMap *warpMap)
 Deallocates the warp map control points allocated by vpiWarpMapAllocData. More...
 
VPIStatus vpiWarpMapGenerateIdentity (VPIWarpMap *warpMap)
 Fills the given warp map with an identity mapping. More...
 
#define VPI_WARPGRID_MAX_HORIZ_REGIONS_COUNT   4
 Maximum number of regions horizontally in a warp grid.
 
#define VPI_WARPGRID_MAX_VERT_REGIONS_COUNT   4
 Maximum number of regions vertically in a warp grid.
 
#define VPI_WARPGRID_MIN_REGION_WIDTH   64
 Minimum warp grid region width.
 
#define VPI_WARPGRID_MIN_REGION_HEIGHT   16
 Minimum warp grid region height.
 

Detailed Description

Defines the VPIWarpMap object and related functions.

Warp map holds the mapping from output to input images, used in Remap algorithm. It allows both dense and sparse mapping.

Data Structure Documentation

◆ VPIWarpGrid

struct VPIWarpGrid

Holds VPI's warp grid definition.

This structure defines the layout of the control points in the destination image of a remap operation.

The control points are used as the basis for geometric transformation from source image to destination image. The remaining points are transformed based on the interpolation. Thus the density of the control points controls the quality of the geometric transformation.

This is an example of defining regions in the image:

warp grid width
/ \
/ \
/ \
regionWidth[0] regionWidth[numHorizRegions-1]
/ \ / \
|------| |------|
-------------------------------- \
|******* ******* *******|-- \
|* . . * * * * *| \ \
|* . . * * * ... * *| regionHeight[0] \
|* . . * * * * *| / \
|******* ******* *******|-- \
| | \
| . . . |
| . . . | warp grid height
| . . . |
| | /
|******* ******* *******|-- /
|* * * * * *| \ /
|* * * * ... * *| regionHeight[numVertRegions-1] /
|* * * * * *| / /
|******* ******* *******|-- /
-------------------------------- /
VPIWarpGrid::numHorizRegions
int8_t numHorizRegions
Number of regions horizontally.
Definition: WarpGrid.h:159
VPIWarpGrid::numVertRegions
int8_t numVertRegions
Number of regions vertically.
Definition: WarpGrid.h:162
VPIWarpGrid::regionWidth
int16_t regionWidth[VPI_WARPGRID_MAX_HORIZ_REGIONS_COUNT]
Width of each region.
Definition: WarpGrid.h:165
VPIWarpGrid::regionHeight
int16_t regionHeight[VPI_WARPGRID_MAX_VERT_REGIONS_COUNT]
Height of each region.
Definition: WarpGrid.h:168

This is an example of defining control points in one region:

*********
* + + *-- \
* * vertInterval
* + + *-- /
* *
*********
|--|
horizInterval
VPIWarpGrid::horizInterval
int16_t horizInterval[VPI_WARPGRID_MAX_HORIZ_REGIONS_COUNT]
Horizontal spacing between control points within a given region.
Definition: WarpGrid.h:174
VPIWarpGrid::vertInterval
int16_t vertInterval[VPI_WARPGRID_MAX_VERT_REGIONS_COUNT]
Vertical spacing between control points within a given region.
Definition: WarpGrid.h:180

Here's an example of a WxH dense grid definition:

VPIWarpGrid grid;
grid.numHorizRegions = 1;
grid.numVertRegions = 1;
grid.horizInterval[0] = 1;
grid.vertInterval[0] = 1;
grid.regionWidth[0] = W;
grid.regionHeight[0] = H;
VPIWarpGrid
Holds VPI's warp grid definition.
Definition: WarpGrid.h:157

Restrictions

Definition at line 156 of file WarpGrid.h.

+ Collaboration diagram for VPIWarpGrid:
Data Fields
int8_t numHorizRegions Number of regions horizontally.
int8_t numVertRegions Number of regions vertically.
int16_t regionWidth[VPI_WARPGRID_MAX_HORIZ_REGIONS_COUNT] Width of each region.
int16_t regionHeight[VPI_WARPGRID_MAX_VERT_REGIONS_COUNT] Height of each region.
int16_t horizInterval[VPI_WARPGRID_MAX_HORIZ_REGIONS_COUNT] Horizontal spacing between control points within a given region.
  • Must be power-of-two.
  • Must be >= 1.
  • On PVA, maximum is 128.
int16_t vertInterval[VPI_WARPGRID_MAX_VERT_REGIONS_COUNT] Vertical spacing between control points within a given region.
  • Must be power-of-two.
  • Must be >= 1.
  • On PVA, maximum is 128.

◆ VPIWarpMap

struct VPIWarpMap

Defines the mapping between input and output images' pixels.

This structure is used as input to Remap. It defines the control point positions in the input image. The corresponding positions in the output image is implicitly defined by the warp grid definition.

Definition at line 87 of file WarpMap.h.

+ Collaboration diagram for VPIWarpMap:
Data Fields
VPIWarpGrid grid Warp grid control point structure definition.

It implicitly defines the control point positions in the output image.

int16_t numHorizPoints Number of points horizontally.
  • Must match the number of points defined by the grid. This is calculated by vpiWarpMapAllocData.
int16_t numVertPoints Number of points vertically.
  • Must match the number of points defined by the grid. This is calculated by vpiWarpMapAllocData.
int32_t pitchBytes Number of bytes between one control point and the one immediately below.
  • Must be at least sizeof(VPIKeypointF32)*numHorizPoints.
VPIKeypointF32 * keypoints Pointer to an array with control point positions in the input image corresponding to those in the output image.

Coordinates are absolute, (0,0) is the top/left corner of output image.

Function Documentation

◆ vpiWarpMapAllocData()

VPIStatus vpiWarpMapAllocData ( VPIWarpMap *  warpMap)

#include </opt/nvidia/vpi3/include/vpi/WarpMap.h>

Allocates the warp map's control point array for a given warp grid.

This function will read the warp grid structure and allocated an appropriately sized control point array, filling the numHorizPoints, numVertPoints, strideBytes and keypoints attributes of VPIWarpMap. The warp map must be deallocated by vpiWarpMapFreeData when no longer needed.

Parameters
[in,out]warpMapThe warp map whose keypoint array will be allocated.
  • The warp grid attribute must be already filled out with the grid structure.
  • Keypoints must be NULL.
  • All attributes other then grid and keypoints will be overwriten.
Return values
VPI_ERROR_INVALID_ARGUMENTwarpMap is NULL.
VPI_ERROR_INVALID_ARGUMENTParameters to generate warpMap are invalid.
VPI_SUCCESSOperation executed successfully.

◆ vpiWarpMapFreeData()

void vpiWarpMapFreeData ( VPIWarpMap *  warpMap)

#include </opt/nvidia/vpi3/include/vpi/WarpMap.h>

Deallocates the warp map control points allocated by vpiWarpMapAllocData.

This function does nothing if control points array is NULL. It sets numHorizPoints, numVertPoints and strideBytes to zero, and keypoints to NULL.

Parameters
[in,out]warpMapWarp map whose control points array needs to be deallocated.
Return values
VPI_ERROR_INVALID_ARGUMENTwarpMap is NULL.

◆ vpiWarpMapGenerateIdentity()

VPIStatus vpiWarpMapGenerateIdentity ( VPIWarpMap *  warpMap)

#include </opt/nvidia/vpi3/include/vpi/WarpMap.h>

Fills the given warp map with an identity mapping.

This function is useful if the user wants to specify their own mapping. It sets the control points coordinates to the destination coordinates as defined implicitly by the warp grid. The user then can iterate through these points and apply a custom mapping function to each one.

Parameters
[in,out]warpMapWarp map with allocated control point array to be filled with identity mapping.
  • WarpMap must be allocated before generating identity.
Return values
VPI_ERROR_INVALID_ARGUMENTwarpMap is NULL.
VPI_ERROR_INVALID_ARGUMENTwarpMap is not allocated.
VPI_SUCCESSOperation executed successfully.