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)¶
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.
-
inline explicit roi_rect(const sycl::id<2> &offset, const sycl::range<2> &size)¶
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).