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

.. _sobel:

Sobel Filter
============


Filters an image using a Sobel filter.


.. rubric:: Description
  :class: sectiontitle

This function applies a Sobel filter to the source image with the 3x3 kernel size.
Algorithm parameters must be set through the ``sobel_spec`` class.
The values of border pixels may be assigned in accordance with the border type.
The formulae below describe the algorithm for the 3x3 and 5x5 Sobel operators.


.. figure:: ./GUID-3491E1C0-BF2D-43A9-8AF4-9E61DD3CD418-low.jpg
  :scale: 100%
  :align: center

  3x3 Sobel operator


.. figure:: ./GUID-11D6D318-97A3-4C81-B918-C6A2A929AD4D-low.jpg
  :scale: 100%
  :align: center

  5x5 Sobel operator

where


-  `A` is the source image
-  `*` is the 2D convolution operator
-  `G`\ :sub:`x` and `G`\ :sub:`y` are horizontal and vertical magnitude of the source image, respectively


Sobel filter output `G`, as overall gradient magnitude, shall be generated
through L1 and L2 normalization of `G`\ :sub:`x` and `G`\ :sub:`y`.


L1 normalization:

.. figure:: ./GUID-FC335369-33F6-4355-9010-204E3C0B4BFA-low.jpg
  :scale: 100%
  :align: center

L2 normalization:

.. figure:: ./GUID-F857AF83-9416-4A6C-A37F-BD8218838A35-low.jpg
  :scale: 100%
  :align: center


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/filter/sobel.hpp``


.. rubric:: Syntax
   :class: sectiontitle


.. doxygenfunction:: oneapi::ipl::sobel_3x3
  :project: oneIPL


.. rubric:: Supported values for ComputeT:
  :class: sectiontitle

.. csv-table::
  :align: center
  :header: **float**,**double**,**half**

  v,v,x


.. rubric:: Supported combinations for SrcDataT/DstDataT/Formats:
  :class: sectiontitle

.. csv-table::
  :align: center
  :header: **SrcDataT/DstDataT/Formats**,**plane**,**rgb/bgr**,**rgba/bgra**,**rgbp**

  **std::uint8_t** ,v,x,x,x
  **std::int8_t**  ,v,x,x,x
  **std::uint16_t**,v,x,x,x
  **std::int16_t** ,v,x,x,x
  **std::uint32_t**,v,x,x,x
  **std::int32_t** ,v,x,x,x
  **float**        ,v,x,x,x
  **double**       ,v,x,x,x


.. rubric:: Supported values for subsampled Format (only for SrcDataT/DstDataT = ``std::uint8_t``):
  :class: sectiontitle

.. csv-table::
  :align: center
  :header: **nv12**,**i420**

  x,x


.. rubric:: Parameters
   :class: sectiontitle


.. list-table::
   :header-rows: 0

   * -     border type support
     -  Type of border. Possible values are:

        ``const_val`` - Values of all border pixels are set to constant.

        ``repl`` - Border is replicated from the edge pixels.


.. doxygenclass:: oneapi::ipl::sobel_spec
  :project: oneIPL
  :members:

.. rubric:: Errors
   :class: sectiontitle

.. list-table::
   :header-rows: 0

   * -     compile-time format check
     -  Indicates an error when image format is not supported (only grayscale format is supported).
   * -     compile-time data type check
     -  Indicates an error when image data type is not supported.
   * -     compile-time compute data type check
     -  Indicates an error when compute data type is not supported.
   * -     ``invalid_argument`` exception
     -  Indicates an error when ROI sizes of the source image and the destination image are not equal.
   * -     ``invalid_argument`` exception
     -  Indicates an error when one of the pitch values is not divisible by size of component data type in bytes.
   * -     ``unimplemented`` exception
     -  Indicates an error when border type is not supported.


The code example below demonstrates how to use the
``oneapi::ipl::sobel_3x3``:


.. code-block:: cpp


  using image_t = image<formats::plane, std::uint8_t>;
  
  // Create queue
  sycl::queue queue{};
  // Create allocator
  shared_usm_allocator_t allocator{ queue };
  
  // Image representing source grayscale image
  image_t src_image{ queue, src_data_pointer, src_size, allocator };
  // Destination image with result of Sobel filtering
  image_t sobel_image{ src_size, allocator };
  
  // Apply Sobel filter to whole image
  // Sobel filter will use replicated border handling by default since explicit border specialization wasn't provided
  (void)sobel_3x3(queue, src_image, sobel_image);