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

.. _image-data-types-and-ranges:

Image Data Types and Ranges
===========================


The oneIPL image processing functions support only absolute color
images in which each pixel is represented by its channel intensities.
The data storage for an image can be either pixel-oriented or
plane-oriented (planar). For images in pixel order, all channel values
for each pixel are clustered and stored consecutively, for example,
RGBRGBRGB in case of an RGB image. The number of channels in a
pixel-order image can be 1, 3, or 4.


For images in planar order, all image data for each channel is stored
contiguously followed by the next channel, for example, RRR...GGG...BBB.

If the source and destination images are in the 4:2:0 two-plane image
format (NV12): all Y samples are found first in memory as an
array of unsigned chars with an even number of lines memory
alignment, followed by an array of unsigned chars containing
interleaved U and V samples: YYYY... UVUV...

If the source and destination images are in the 4:2:0 three-plane image
format (I420): all Y samples are found first in memory as an
array of unsigned chars with an even number of lines memory
alignment, followed by a half-sized array of unsigned chars containing
U samples and then, followed by a half-sized array of unsigned chars
containing V samples: YYYY... UU... VV...


The image data type is specified as template parameter during ``ipl::image`` construction.
The data may be signed, unsigned, or floating-point real. All channels in
an image must have the same data type.


For example, in RGB image with ``std::uint8_t`` data type, three consecutive
bytes (24 bits) per pixel represent the three channel intensities in the
pixel mode (see :ref:`RGB Image Formats <rgb-image-formats>` for more details).


If an alpha (opacity) channel is present in image data, the image must
have four channels, with alpha channel being the last one.
The presence of the alpha channel can modify the function's behavior.
For such functions, oneIPL provides versions with and without alpha.
If an alpha channel is specified, the operation usually is not performed
on that channel. It is specified per function.


The range of values that can be represented by each data type lies
between the lower and upper bounds. The following table lists data
ranges and constant identifiers used in oneIPL to denote the
respective range bounds:


.. list-table::
  :header-rows: 1

  * -     \ **Data Type**\
    -     \ **Lower Bound Identifier**\
    -     \ **Lower Bound Value**\
    -     \ **Upper Bound Identifier**\
    -     \ **Upper Bound Value**\
  * -     ``int8_t``
    -     ``numerical_limits<int8_t>::min()``
    -     -128
    -     ``numerical_limits<int8_t>::max()``
    -     127
  * -     ``uint8_t``
    -     ``numerical_limits<uint8_t>::min()``
    -     0
    -     ``numerical_limits<uint8_t>::max()``
    -     255
  * -     ``int16_t``
    -     ``numerical_limits<int16_t>::min()``
    -     -32768
    -     ``numerical_limits<int16_t>::max()``
    -     32767
  * -     ``uint16_t``
    -     ``numerical_limits<uint16_t>::min()``
    -     0
    -     ``numerical_limits<uint16_t>::max()``
    -     65535
  * -     ``int32_t``
    -     ``numerical_limits<int32_t>::min()``
    -     -2\ :sup:`31`\
    -     ``numerical_limits<int32_t>::max()``
    -     2\ :sup:`31`-1
  * -     ``uint32_t``
    -     ``numerical_limits<uint32_t>::min()``    -
    -     0
    -     ``numerical_limits<uint32_t>::max()``
    -     2\ :sup:`32`-1
  * -     ``float``\ :sup:`†`\
    -     ``numerical_limits<float>::min()``
    -     1.175494351e\ :sup:`-38`\
    -     ``numerical_limits<float>::max()``
    -     3.402823466e\ :sup:`38`\
  * -     ``double``\ :sup:`†`\
    -     ``numerical_limits<double>::min()``
    -     2.22507e\ :sup:`-308`\
    -     ``numerical_limits<double>::max()``
    -     1.79769e\ :sup:`308`\

:sup:`†` The floating point range is for absolute values