Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference

ID 790148
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Regions of Interest in Intel IPP

Most Intel IPP image processing functions operate not only on entire images but also on image areas. Image region of interest (ROI) is a rectangular area that may be either some part of the image or the whole image.

The Intel IPP functions with ROI support have an R descriptor in their names. ROI of an image is defined by the size and offset from the image origin as shown in figure Image, ROI, and Offsets. The origin of an image is in the top left corner, with x values increasing from left to right and y values increasing downwards.

Image, ROI, and Offsets



Both the source and destination images can have a ROI. In such cases the sizes of ROIs are assumed to be the same while offsets may differ. Image processing is performed on data of the source ROI, and the results are written to the destination ROI. In function call sequences, ROI is specified by:

  • roiSize parameter of the IppiSize type

  • pSrc and pDst pointers to the starts of source and destination ROI buffers

  • srcStep and dstStep parameters that are equal to distances in bytes between the starting points of consecutive lines in source and destination images, respectively.

Thus, the srcStep and dstStep parameters set steps in bytes through image buffers to start processing a new line in the ROI of an image.

The following code example illustrates the use of the dstStep parameter in function calls:

Example

IppStatus roi( void ) {
   Ipp8u x[8*3] = {0};
   IppiSize roiSize = {3,2};
   IppiPoint roiPoint = {2,1};
   /// place the pointer to the ROI start position
   return ippiSet_8u_C1R( 7, x+8*roiPoint.y+roiPoint.x, 8, roiSize );
}

The resulting image x contains the following data:

00 00 00 00 00 00 00 00
00 00 07 07 07 00 00 00
00 00 07 07 07 00 00 00

If ROI is present:

  • source and destination images can have different sizes;

  • lines may have padding at the end for aligning the line sizes;

  • application must correctly define the pSrc, pDst, and roiSize parameters.

The pSrc and pDst parameters are the shifted pointers to the image data. For example, in case of ROI operations on 3-bytes-per-pixel image data (8u_C3R), pSrc points to the start of the source ROI buffer and can be interpreted as follows:

pSrc = pSrcImg + 3*(srcImgSize.width * srcRoiOffset.y + srcRoiOffset.x),

where

pSrcImg

points to the start of the source image buffer

srcImgSize

is the image size in pixels (of the IppiSize type)

srcRoiOffset

determines an offset of ROI relative to the start of the image as shown in Figure Image, ROI, and Offsets.

Another example for operations on four-channel image of 32-bit floating point data type 32f_AC4:

pSrc = (Ipp32f*)((Ipp8u*)pSrcImg + srcImgStep * srcRoiOffset.y + 4*SizeOf(Ipp32f)*srcRoiOffset.x.

In this example the multiplier 4 is used because the AC4 pixel consists of 4 values - R, G, B, A. Pointer type conversion is required as in Intel IPP all image steps are always in bytes, and it is not recommended to use step/SizeOf(Ipp32f) as in a general case step value may be not a multiple of 4.

For functions using ROI with a neighborhood, you should correctly use values of the pSrc and roiSize parameters. These functions assume that the points in the neighborhood exist and that therefore pSrc is almost never equal to pSrcImg. Figure Using ROI with Neighborhood illustrates the case when neighborhood pixels can fall outside the source image.

Using ROI with Neighborhood



To ensure valid operation when image pixels are processed, the application should correctly define additional border pixels (see Borders in Neighborhood Operations).

Warning:

If the required border pixels are not defined prior to calling neighborhood functions that attempt to process such pixels, you may get memory violation errors.

The following code example shows how to process an image with ROI:

Example

IppStatus alignedLine( void
) {
   Ipp8u x[8*3] = {0};
   IppiSize imgSize = {5,3};
   /// The image is of size 5x3. Width 8 has been
   /// chosen by the user to align every line of the image
   return ippiSet_8u_C1R( 7, x, 8, imgSize);
}

The resulting image x contains the following data:

07 07 07 07 07 00 00 00
07 07 07 07 07 00 00 00
07 07 07 07 07 00 00 00