Regions of Interest in Intel IPP

Intel® Integrated Performance Primitives Developer Guide and Reference

Download PDF

ID 790148

Date 11/07/2023

Version

Public

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

Visible to Intel only — GUID: GUID-F80D62EF-782C-401E-BD08-8578427BE8ED

View Details

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

Parent topic: Major Operation Models

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Integrated Performance Primitives Developer Guide and Reference

Regions of Interest in Intel IPP

Example

Example

See Also