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

.. _image-borders:

Image Borders
=============


Some of the oneIPL image processing functions operate on
user-defined border types. It means that the values of border pixels must be
assigned in accordance with the ``border_type`` (or border) and ``border_val`` (optional)
parameters, specified in the algorithmic ``spec``.


oneIPL supports the following border types:


-  `Replicated border <#replicated-border>`__
-  `Wrapped border <#wrapped-border>`__
-  `Mirrored border <#mirrored-border>`__
-  `Mirrored border with replication <#mirrored-with-replication-border>`__
-  `Default border <#default-border>`__
-  `Constant border <#constant-border>`__
-  `Transparent border <#transparent-border>`__
-  `Border in memory <#in-memory-border>`__

The borders must be controlled via enum.


.. doxygenenum:: oneapi::ipl::border_types
  :project: oneIPL


.. _replicated-border:
.. rubric:: Replicated Border
   :class: sectiontitle

This type of border shall correspond to the ``repl`` value in the
``border_types`` enumerator. When using a replicated border, values for
border pixels shall be obtained from the source image boundary pixels, as
shown in the figure below. Squares marked in red shall correspond to pixels
copied from the source image ROI. Squares with green values
shall correspond to border pixels, which must be replicated from the boundary
pixels of the source image.


.. figure:: ./GUID-2DF7FF10-8052-4800-9E45-039AC05EB14A-low.jpg
   :scale: 100%
   :align: center


.. _wrapped-border:
.. rubric:: Wrapped Border
   :class: sectiontitle

This type of border shall correspond to the ``wrap`` value in the
``border_types`` enumerator. When using a wrapped border, values for
border pixels shall be obtained from the source image boundary pixels, as
shown in the figure below. Squares marked in red shall correspond to pixels
copied from the source image ROI. Squares with green values
shall correspond to border pixels that must be taken from the source image.


.. figure:: ./GUID-B39EBA55-F5B8-47C3-AD4A-094DED9C065-low.jpg
   :scale: 100%
   :align: center


.. _mirrored-border:
.. rubric:: Mirrored Border
   :class: sectiontitle

This type of border shall correspond to the ``mirror`` value in the
``border_types`` enumerator. When using a mirrored border, values for
border pixels shall be obtained from the source image boundary pixels, as
shown in the figure below. Squares marked in red shall correspond to pixels
copied from the source image ROI. Squares with green values
shall correspond to border pixels, which must be mirrored from the source image
pixels.


.. figure:: ./GUID-B39EBA55-F5B8-47C3-AD4A-094DED9C065E-low.jpg
   :scale: 100%
   :align: center


.. _mirrored-with-replication-border:
.. rubric:: Mirrored Border with Replication
   :class: sectiontitle

This type of border shall correspond to the ``mirror_repl`` value in the
``border_types`` enumerator. When using a mirrored border with
replication, values for border pixels shall be obtained from the source
image boundary pixels, as shown in the figure below. Squares marked
in red shall correspond to pixels copied from the source image ROI. Squares
with green values shall correspond to border pixels, which must be mirrored
from the source image pixels. The difference of this border type from
the mirrored border is that the anchor cell value shall be replicated to
the border pixels.


.. figure:: ./GUID-94FDEDFD-410C-4F45-93EB-73E03462BDFE-low.jpg
   :scale: 100%
   :align: center


.. _default-border:
.. rubric:: Default Border
      :class: sectiontitle

This type of border shall correspond to the ``default_val`` value in the
``border_types`` enumerator. When using a default border, values for
all border pixels shall be set to the constant value equal to corresponding
data type default value. In the figure below, this default value
is marked as V. Squares marked in red correspond to pixels copied
from the source image ROI.


.. figure:: ./GUID-E1D4DC2D-67AA-4B09-A374-4ABC9D3CD1EF-low.jpg
   :scale: 100%
   :align: center


.. _constant-border:
.. rubric:: Constant Border
      :class: sectiontitle

This type of border shall correspond to the ``const_val`` value in the
``border_types`` enumerator. When using a constant border, values for
all border pixels shall be set to the constant value specified in
the ``spec`` parameter of the corresponding function. In the figure below, this constant value
is marked as V. Squares marked in red correspond to pixels copied
from the source image ROI.


.. figure:: ./GUID-E1D4DC2D-67AA-4B09-A374-4ABC9D3CD1EF-low.jpg
   :scale: 100%
   :align: center


.. _transparent-border:
.. rubric:: Transparent Border
      :class: sectiontitle

This type of border shall correspond to the ``transp`` value in the
``border_types`` enumerator. When using a transparent border, border
pixels are not processed.


.. _in-memory-border:
.. rubric:: Border in Memory
   :class: sectiontitle


If ROI is inside image across any boundary and external pixels from source image are available,
the values shall be taken from external pixels if crop flag is ``crop == crop_types::off``. 
If ``crop == crop_types::on``, the border in memory is not used and pixels must be generated 
according to the ``border_types`` enumerator value. In the figure below, squares marked in
red correspond to pixels copied from the source image ROI. Squares
with black values correspond to source image pixels in memory.


.. figure:: ./GUID-F564FF7B-2990-4368-BF7D-047D7F44ED49-low.jpg
   :scale: 100%
   :align: center


Borders in Neighborhood Operations
++++++++++++++++++++++++++++++++++

Filtering functions described in this section shall perform neighborhood
operations. They shall operate on the assumption that for each pixel to be
processed, all neighborhood pixels required for the operation are also
available.


The neighborhood for each given pixel must be defined by the filter kernel
(or mask) size and anchor cell position. For more information about
anchors and how to define the anchor cell position refer to
:ref:`neighborhood-operations`.


As the following figure illustrates, if the input pixel is near the
horizontal or vertical edge of the image, the overlaid kernel may refer
to neighborhood pixels that do not exist within the source image and are
located outside the image area.


.. figure:: ./GUID-32FE13D1-0580-4CC6-9037-BB8A6771B43E-low.jpg
   :scale: 100%
   :align: center


The set of all boundary source image pixels that require such
non-existent pixels to complete the neighborhood operation for the given
kernel and anchor is shaded yellow, while the collection of all scanned
external pixels (called border pixels) is shaded gray.


If the neighborhood operation is needed to be applied to the part of the
source image, or ROI, then the necessity of extending the image area
with border pixels shall depend on the ROI size and position within the
image. There are two options to handle borders in case of ROI, which
can be switched by ``crop_types`` enumeration in algorithm specification:


.. doxygenenum:: oneapi::ipl::crop_types
  :project: oneIPL

If boundary pixels are part of ROI, some area
of the source image must be extended.

.. csv-table::
  :align: center
  :header: **Crop type**, **Description**

  on, All ROI borders must be treated according to the specified border type
  off, Pixels outside ROI must be used for calculations when available. Otherwise specified border type is applied


The figure below illustrates behavior when ``crop == crop_types::off``.
If ROI does not cover yellow (internal boundary) pixels, then
internal image pixels outside ROI shall be used.


.. figure:: ./GUID-F308A1FD-80D0-4C31-9E58-BE8780962D15-low.jpg
   :scale: 100%
   :align: center