Image Regions of Interest

oneIPL 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. ROI of an image must be defined by the size and offset from the image origin as shown in figure. The origin of an image shall be in the top left corner, with x values increasing from left to right and y values increasing downwards.

Image, ROI, and Offsets


To fully describe a rectangular ROI, both its origin (coordinates of top left corner) and size must be referenced. The ROI shall be specified by roi_rect parameter of ipl::image constructor, meaning that all four values describing the rectangular ROI shall be given explicitly.

struct oneapi::ipl::roi_rect

Class that represents a rectangle bounding a region of interest (ROI) of an image.

Public Functions

inline explicit roi_rect(const sycl::id<2> &offset, const sycl::range<2> &size)


  • offset[in] the given 2D offset of ROI

  • size[in] the given 2D size of ROI

inline roi_rect(const sycl::range<2> &size)

Constructor of ROI rectangle that has a zero 2D offset.


size[in] the given 2D size of ROI.

Public Members

sycl::id<2> offset

2D offset of ROI

sycl::range<2> size

2D size of ROI

Both source and destination images can have a ROI. If function doesn’t change image size, 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 must be specified by image type constructed with roi parameter and can be obtained from image object:

template <formats Format>
using image_t = image<Format, std::uint8_t>;

const roi_rect dst_roi_rect{ dst_size / 6, dst_size / 3 };

// Create queue and allocator
sycl::queue queue{};
shared_usm_allocator_t allocator{ queue };

// Source rgba image data and destination images
image_t<formats::rgba>  src_image{ src_data_pointer, src_size };
image_t<formats::plane> gray_image{ src_size, allocator };                        // Gray image data
image                   gray_image_roi = gray_image.get_roi(dst_roi_rect);        // Gray image ROI
image_t<formats::plane> sobel_image_roi{ gray_image_roi.get_range(), allocator }; // Sobel image ROI

// Run pipeline: convert to grayscale -> sobel on ROI
(void)convert(queue, src_image, gray_image);
(void)sobel_3x3(queue, gray_image_roi, sobel_image_roi);

If ROI is present:

  • source and destination images can have different sizes;

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

Using ROI with Neighborhood


To ensure valid operation when image pixels are processed, the application should define the rules to handle border pixels (see Image Borders).