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 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)

Constructor.

Parameters

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

Parameters

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

std::size_t get_x_offset() const

Returns the x offset.

Returns

the x offset

std::size_t get_y_offset() const

Returns the y offset.

Returns

the y offset

std::size_t get_width() const

Returns the width of the ROI (for the whole image returns the width of the image).

Returns

the width of the ROI

std::size_t get_height() const

Returns the height of the ROI (for the whole image returns the height of the image).

Returns

the height of the 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:

using namespace oneapi;

sycl::queue                 queue;
ipl::shared_usm_allocator_t allocator{ queue };
const sycl::range<2>        image_size{ height, width };
const ipl::roi_rect         dst_roi_rect{ image_size / 6, image_size / 3 };

// Source 4-channel image data and destination images
ipl::image<ipl::layouts::channel4, std::uint8_t> src_image{ queue, p_image_data, image_size, allocator };
// Gray image data
ipl::image<ipl::layouts::plane, std::uint8_t> gray_image{ image_size, allocator };
// Gray image ROI
ipl::image<ipl::layouts::plane, std::uint8_t> gray_image_roi = gray_image.get_roi(dst_roi_rect);
// Sobel image ROI
ipl::image<ipl::layouts::plane, std::uint8_t> sobel_image_roi{ gray_image_roi.get_range(), allocator };

// Run pipeline: convert to grayscale -> Sobel filter on ROI
(void)ipl::rgb_to_gray(queue, src_image, gray_image);
auto event = ipl::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).