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

.. _gaussian:

Gaussian Filter
===============


Filters an image using a Gaussian filter.


.. rubric:: Description
  :class: sectiontitle

This function applies a Gaussian filter to the source image with the
specified kernel radius. Algorithm parameters shall be set through the
``gaussian_spec`` class. The values of border pixels are assigned in
accordance with the border type. The formulae below describe the
algorithm to compute kernel.


.. figure:: ./cq5dam.web.1280.1280.jpeg
  :scale: 100%
  :align: center

where


-  `K` is kernel size, `K`/2 is kernel radius
-  `sigma` - standard deviation of gaussian distribution
-  `G`\ :sub:`i,j` are gaussian kernel values


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/filter/gaussian.hpp``

.. rubric:: Syntax
   :class: sectiontitle


.. doxygenfunction:: oneapi::ipl::gaussian
  :project: oneIPL

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

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

  v,v,x


.. rubric:: Supported combinations for DataT/Formats:
  :class: sectiontitle

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

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


.. rubric:: Supported values for subsampled Format (only for DataT = ``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.

        ``mirror`` - Border is mirrored from the edge pixels.


.. doxygenclass:: oneapi::ipl::gaussian_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.
   * -     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``
     -  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::gaussian``:


.. code-block:: cpp


  // Create queue
  sycl::queue queue{};
  
  image<formats::rgba, std::uint8_t> src_image{ src_data_pointer, size };
  image<formats::rgba, std::uint8_t> dst_image{ size };
  
  // Create a gaussian arguments (kernel radius = 2, sigma is caluculated)
  const gaussian_spec spec{ 2 };
  
  (void)gaussian(queue, src_image, dst_image, spec);