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

.. _Normalize:

Normalization
=============


Normalization of an image.


.. rubric:: Description
  :class: sectiontitle

This function applies a normalization operation to the source image with the
specified subtrahend and divisor with vector size corresponding to the number of image channels.
Algorithm to compute kernel is described by formula below:


.. figure:: ./normalize.png
  :scale: 30%
  :align: center

where


-  `d` is divisor
-  `s` is subtrahend
-  `I`\ :sub:`i,j` is image pixel
-  `I`\ :sup:`N`\ :sub:`i,j` is normalized image pixel


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/misc/normalize.hpp``


.. rubric:: Syntax
  :class: sectiontitle


.. doxygenfunction:: oneapi::ipl::normalize
  :project: oneIPL


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

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

  v,v,x


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

.. csv-table::
  :align: center
  :header: **SrcDataT/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 SrcDataT = ``std::uint8_t``):
  :class: sectiontitle

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

  x,x


.. rubric:: Parameters
   :class: sectiontitle


.. doxygenclass:: oneapi::ipl::normalize_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`` 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.


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


.. code-block:: cpp


  template <typename DataT>
  using rgba_image_t = image<formats::rgba, DataT>;
  
  // Create queue
  sycl::queue queue{};
  
  rgba_image_t<std::uint8_t> src_image{ src_data_pointer, src_size };
  rgba_image_t<std::uint8_t> dst_image{ src_size };
  rgba_image_t<float>        norm_image{ src_size };
  rgba_image_t<float>        denorm_image{ src_size };
  
  sycl::float4 sub{ 127.5f };
  sycl::float4 div{ 127.5f };
  
  // Create a normalize arguments (buffer of 2 elements: 1st is sub, 2nd is div)
  normalize_spec norm_spec{ sub, div };
  
  // Create a de-normalize arguments (buffer of 2 elements: 1st is sub, 2nd is div)
  normalize_spec denorm_spec{ -sub / div, sycl::float4{ 1.f } / div };
  
  // Normalize image
  (void)normalize(queue, src_image, norm_image, norm_spec);
  
  // Denormalize image
  (void)normalize(queue, norm_image, denorm_image, denorm_spec);
  
  // Convert image
  (void)copy(queue, denorm_image, dst_image);