.. SPDX-FileCopyrightText: 2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _image-regions-of-interest:

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

.. _image-roi-and-offsets:
.. figure:: ./GUID-D0340CB0-7050-4627-BB90-21E6433E7B8F-low.jpg
   :scale: 100%
   :align: center


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.


.. doxygenstruct:: oneapi::ipl::roi_rect
  :project: oneIPL
  :members:


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:

.. code-block:: cpp


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

.. figure:: ./GUID-941E5B41-80A3-4D84-A86C-222A6491CA06-low.jpg
   :scale: 100%
   :align: center

To ensure valid operation when image pixels are processed, the
application should define the rules to handle border pixels (see
:ref:`image-borders`).