Image concepts
==============

.. contents:: Table of Contents
    :local:


.. _concept-Image:

Image
-----

Let `Ima` be a type that models :ref:`Image (details) <concept-details-Image>`.

.. _concept-Image-types:
.. rubric:: Types

Then we can define :

+--------------------------+--------------------------------------------------+--------------------------------------------+
|        Definition        |                   Description                    |                Requirement                 |
+==========================+==================================================+============================================+
| `Ima::pixel_type`        | type of a pixel                                  | models :ref:`concept-Pixel` concept        |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::const_pixel_type`  | type of a const pixel                            | models :ref:`concept-Pixel` concept        |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::domain_type`       | type of the domain                               | models :ref:`concept-Domain` concept       |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::index_type`        | type of the index to access a value              | models :ref:`concept-Index` concept        |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::difference_type`   | type of the difference between 2 indexes         |                                            |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::const_pixel_range` | type of the range to iterate over all the pixels | models :ref:`concept-ForwardRange` concept |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::const_value_range` | type of the range to iterate over all the values | models :ref:`concept-ForwardRange` concept |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::point_type`        | type of a point                                  | models :ref:`concept-Point` concept        |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::value_type`        | type of a value                                  | - models :ref:`concept-Value` concept      |
|                          |                                                  | - non-const                                |
|                          |                                                  | - not a reference                          |
+--------------------------+--------------------------------------------------+--------------------------------------------+
| `Ima::const_reference`   | type of a const reference on a value             |                                            |
+--------------------------+--------------------------------------------------+--------------------------------------------+

.. _concept-Image-expressions:
.. rubric:: Expressions

Let :
    - ``cima`` be an instance of `const Ima`.
    - ``ima`` be an instance of `Ima`
    - ``p`` be an instance of `Ima::point_type`
    - ``k`` be an instance of `Ima::index_type`

Then we have the following valid expressions :

+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
|         Expression         |          Return type           |         Pre-condition          |   Post-condition   |                           Description                           |
+============================+================================+================================+====================+=================================================================+
| ``cima[k]``                | `const_reference`              | none                           | none               | Return const reference of the value at index ``k``              |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.pixels()``          | `const_pixel_range`            | none                           | none               | Return a range of pixels to iterate over it                     |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.values()``          | `const_value_range`            | none                           | none               | Return a range of values to iterate over it                     |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.domain()``          | `domain_type`                  | none                           | none               | Return the current domain of the image                          |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.index_of_point(p)`` | `index_type`                   | none                           | none               | Return the index of the point ``p``                             |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.point_of_index(k)`` | `point_type`                   | none                           | none               | Return the point at the index ``k``                             |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.delta_index(p)``    | `difference_type`              | none                           | none               | Return a delta (?) from point ``p``                             |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.is_concrete()``     | `bool`                         | none                           | constexpr function | Check if the image is concrete                                  |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+
| ``cima.to_concrete()``     | `/* implementation defined */` | ``cima.is_concrete() == true`` | none               | Return type models :ref:`ConcreteImage <concept-ConcreteImage>` |
+----------------------------+--------------------------------+--------------------------------+--------------------+-----------------------------------------------------------------+


.. _concept-ConcreteImage:

ConcreteImage
-------------

Let `ConcIma` be a type that models :ref:`ConcreteImage (details) <concept-details-ConcreteImage>`.

Then `ConcIma` also models :ref:`Image <concept-Image>` and :ref:`Semiregular (fundamentals) <concept-fundamentals-object-Semiregular>`.

.. _concept-ConcreteImage-types:
.. rubric:: Types

Let `ConcIma` inherit all types defined for :ref:`Image <concept-Image-types>`.

.. _concept-ConcreteImage-expressions:
.. rubric:: Expressions

Let `ConcIma` inherit all valid expressions defined for :ref:`Image <concept-Image-expressions>`.

Let : 
    - ``concima`` be an instance of `ConcIma`.
    - ``concima_cpy`` be an instance of `ConcIma`.
    - ``cconcima`` be an instance of `const ConcIma`.
    - ``k`` be an instance of `ConcIma::index_type`
    - ``d`` be an instance of `ConcIma::domain_type`
    - ``v`` be an instance of `ConcIma::value_type`.

Then we have the following valid expressions :

+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
|           Expression            |   Return type   | Pre-condition | Post-condition |                        Description                         |
+=================================+=================+===============+================+============================================================+
| ``concima()``                   | `ConcIma`       | none          | none           | Constructs an image ``concima`` of type `ConcIma`          |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``cconcima()``                  | `const ConcIma` | none          | none           | Constructs an image ``cconcima`` of type `ConcIma`         |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima_cpy(concima)``        | `ConcIma`       | none          | none           | Copy-constructs an image ``concima_cpy`` from ``concima``  |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima_cpy(cconcima)``       | `ConcIma`       | none          | none           | Copy-constructs an image ``concima_cpy`` from ``cconcima`` |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima_cpy(move(pnt))``      | `ConcIma`       | none          | none           | Move-constructs an image ``concima_cpy`` from ``concima``  |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima_cpy = concima``       | `ConcIma&`      | none          | none           | Assign ``concima`` to ``concima_cpy``                      |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima_cpy = cconcima``      | `ConcIma&`      | none          | none           | Assign ``cconcima`` to ``concima_cpy``                     |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima_cpy = move(concima)`` | `ConcIma&`      | none          | none           | Move-assign ``concima`` to ``concima_cpy``                 |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima.resize(d)``           | `void`          | none          | none           | Resize ``concima`` to fit the domain ``d``                 |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima.resize(d, v)``        | `void`          | none          | none           | Resize ``concima`` to fit the domain ``d``                 |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+
| ``concima.reindex(k)``          | `void`          | none          | none           | Affects the index ``k`` to the first pixel                 |
+---------------------------------+-----------------+---------------+----------------+------------------------------------------------------------+


.. _concept-WritableImage:

WritableImage
-------------

Let `WIma` be a type that models :ref:`WritableImage (details) <concept-details-WritableImage>`.

Then `WIma` also models :ref:`Image <concept-Image>`.

.. _concept-WritableImage-types:
.. rubric:: Types

Let `WIma` inherit all types defined for :ref:`Image <concept-Image-types>`.

Then we can define :

+---------------------+--------------------------------------------------+---------------------------------------------------------------------------+
|     Definition      |                   Description                    |                                Requirement                                |
+=====================+==================================================+===========================================================================+
| `WIma::pixel_range` | type of the range to iterate over all the pixels | models :ref:`concept-ForwardRange` and :ref:`concept-OutputRange` concept |
+---------------------+--------------------------------------------------+---------------------------------------------------------------------------+
| `WIma::value_range` | type of the range to iterate over all the values | models :ref:`concept-ForwardRange` and :ref:`concept-OutputRange` concept |
+---------------------+--------------------------------------------------+---------------------------------------------------------------------------+
| `WIma::reference`   | type of a reference on a value                   |                                                                           |
+---------------------+--------------------------------------------------+---------------------------------------------------------------------------+

.. _concept-WritableImage-expressions:
.. rubric:: Expressions

Let `WIma` inherit all valid expressions defined for :ref:`Image <concept-Image-expressions>`.

Let :
    - ``wima`` be an instance of `WIma`
    - ``k`` be an instance of `WIma::index_type`.

Then we have the following valid expressions :

+-------------------+---------------+---------------+----------------+----------------------------------------------+
|    Expression     |  Return type  | Pre-condition | Post-condition |                 Description                  |
+===================+===============+===============+================+==============================================+
| ``wima[k]``       | `reference`   | none          | none           | Return reference of the value at index ``k`` |
+-------------------+---------------+---------------+----------------+----------------------------------------------+
| ``wima.pixels()`` | `pixel_range` | none          | none           | Return a range of pixels to iterate over it  |
+-------------------+---------------+---------------+----------------+----------------------------------------------+
| ``wima.values()`` | `value_range` | none          | none           | Return a range of values to iterate over it  |
+-------------------+---------------+---------------+----------------+----------------------------------------------+


.. _concept-BidirectionalImage:

BidirectionalImage
-------------------

Let `BidirIma` be a type that models :ref:`BidirectionalImage (details) <concept-details-BidirectionalImage>`.

Then `BidirIma` also models :ref:`Image <concept-Image>`.

.. _concept-BidirectionalImage-types:
.. rubric:: Types

Let `BidirIma` inherit all types defined for :ref:`Image <concept-Image-types>`.

Then we can define :

+-------------------------------+--------------------------------------------------+--------------------------------------------------+
|          Definition           |                   Description                    |                   Requirement                    |
+===============================+==================================================+==================================================+
| `BidirIma::const_pixel_range` | type of the range to iterate over all the pixels | models :ref:`concept-BidirectionalRange` concept |
+-------------------------------+--------------------------------------------------+--------------------------------------------------+
| `BidirIma::const_value_range` | type of the range to iterate over all the values | models :ref:`concept-BidirectionalRange` concept |
+-------------------------------+--------------------------------------------------+--------------------------------------------------+

.. _concept-BidirectionalImage-expressions:
.. rubric:: Expressions

Let `BidirIma` inherit all valid expressions defined for :ref:`Image <concept-Image-expressions>`.


.. _concept-WritableBidirectionalImage:

WritableBidirectionalImage
--------------------------

Let `WBidirIma` be a type that models :ref:`WritableBidirectionalImage (details) <concept-details-WritableBidirectionalImage>`.

Then `WBidirIma` also models :ref:`WritableImage <concept-WritableImage>` and :ref:`BidirectionalImage <concept-BidirectionalImage>`.

.. _concept-WritableBidirectionalImage-types:
.. rubric:: Types

Let `WBidirIma` inherit all types defined for :ref:`WritableImage <concept-WritableImage-types>`.

Let `WBidirIma` inherit all types defined for :ref:`BidirectionalImage <concept-BidirectionalImage-types>`.

Then we can define :

+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------------+
|        Definition        |                   Description                    |                                   Requirement                                   |
+==========================+==================================================+=================================================================================+
| `WBidirIma::pixel_range` | type of the range to iterate over all the pixels | models :ref:`concept-BidirectionalRange` and :ref:`concept-OutputRange` concept |
+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------------+
| `WBidirIma::value_range` | type of the range to iterate over all the values | models :ref:`concept-BidirectionalRange` and :ref:`concept-OutputRange` concept |
+--------------------------+--------------------------------------------------+---------------------------------------------------------------------------------+

.. _concept-WritableBidirectionalImage-expressions:
.. rubric:: Expressions

Let `WBidirIma` inherit all valid expressions defined for :ref:`WritableImage <concept-WritableImage-expressions>`.

Let `WBidirIma` inherit all valid expressions defined for :ref:`BidirectionalImage <concept-BidirectionalImage-expressions>`.


.. _concept-AccessibleImage:

AccessibleImage
---------------

Let `AccIma` be a type that models :ref:`AccessibleImage (details) <concept-details-AccessibleImage>`.

Then `AccIma` also models :ref:`Image <concept-Image>`.

.. _concept-AccessibleImage-types:
.. rubric:: Types

Let `AccIma` inherit all types defined for :ref:`Image <concept-Image-types>`.

.. _concept-AccessibleImage-expressions:
.. rubric:: Expressions

Let `AccIma` inherit all valid expressions defined for :ref:`Image <concept-Image-expressions>`.

Let :
    - ``caccima`` be an instance of `const AccIma`
    - ``p`` be an instance of `Ima::point_type`

Then we have the following valid expressions :

+-------------------------+----------------------------+---------------+-------------------+---------------------------------+
|       Expression        |        Return type         | Pre-condition |  Post-condition   |           Description           |
+=========================+============================+===============+===================+=================================+
| ``caccima(p)``          | `AccIma::const_reference`  | none          | Bound checking    | Return the value at point ``p`` |
+-------------------------+----------------------------+---------------+-------------------+---------------------------------+
| ``caccima.pixel(p)``    | `AccIma::const_pixel_type` | none          | Bound checking    | Return the pixel at point ``p`` |
+-------------------------+----------------------------+---------------+-------------------+---------------------------------+
| ``caccima.at(p)``       | `AccIma::const_reference`  | none          | No bound checking | Return the value at point ``p`` |
+-------------------------+----------------------------+---------------+-------------------+---------------------------------+
| ``caccima.pixel_at(p)`` | `AccIma::const_pixel_type` | none          | No bound checking | Return the pixel at point ``p`` |
+-------------------------+----------------------------+---------------+-------------------+---------------------------------+


.. _concept-WritableAccessibleImage:

WritableAccessibleImage
-----------------------

Let `WAccIma` be a type that models :ref:`WritableAccessibleImage (details) <concept-details-WritableAccessibleImage>`.

Then `WAccIma` also models :ref:`WritableImage <concept-WritableImage>` and :ref:`AccessibleImage <concept-AccessibleImage>`.

.. _concept-WritableAccessibleImage-types:
.. rubric:: Types

Let `WAccIma` inherit all types defined for :ref:`WritableImage <concept-WritableImage-types>`.

Let `WAccIma` inherit all types defined for :ref:`AccessibleImage <concept-AccessibleImage-types>`.

.. _concept-WritableAccessibleImage-expressions:
.. rubric:: Expressions

Let `WAccIma` inherit all valid expressions defined for :ref:`WritableImage <concept-WritableImage-expressions>`.

Let `WAccIma` inherit all valid expressions defined for :ref:`AccessibleImage <concept-AccessibleImage-expressions>`.

Let :
    - ``wcaccima`` be an instance of `WAccIma`
    - ``p`` be an instance of `Ima::point_type`

Then we have the following valid expressions :

+--------------------------+-----------------------+---------------+-------------------+---------------------------------+
|        Expression        |      Return type      | Pre-condition |  Post-condition   |           Description           |
+==========================+=======================+===============+===================+=================================+
| ``wcaccima(p)``          | `WAccIma::reference`  | none          | Bound checking    | Return the value at point ``p`` |
+--------------------------+-----------------------+---------------+-------------------+---------------------------------+
| ``wcaccima.pixel(p)``    | `WAccIma::pixel_type` | none          | Bound checking    | Return the pixel at point ``p`` |
+--------------------------+-----------------------+---------------+-------------------+---------------------------------+
| ``wcaccima.at(p)``       | `WAccIma::reference`  | none          | No bound checking | Return the value at point ``p`` |
+--------------------------+-----------------------+---------------+-------------------+---------------------------------+
| ``wcaccima.pixel_at(p)`` | `WAccIma::pixel_type` | none          | No bound checking | Return the pixel at point ``p`` |
+--------------------------+-----------------------+---------------+-------------------+---------------------------------+


.. _concept-RandomAccessImage:

RandomAccessImage
-----------------

Let `RndAccIma` be a type that models :ref:`RandomAccessImage (details) <concept-details-RandomAccessImage>`.

Then `RndAccIma` also models :ref:`BidirectionalImage <concept-BidirectionalImage>` and :ref:`AccessibleImage <concept-AccessibleImage>`.

.. _concept-RandomAccessImage-types:
.. rubric:: Types

Let `RndAccIma` inherit all types defined for :ref:`BidirectionalImage <concept-BidirectionalImage-types>`.

Let `RndAccIma` inherit all types defined for :ref:`AccessibleImage <concept-AccessibleImage-types>`.

Then we can define :

+--------------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------+
|           Definition           |                   Description                    |                                     Requirement                                     |
+================================+==================================================+=====================================================================================+
| `RndAccIma::const_pixel_range` | type of the range to iterate over all the pixels | models both :ref:`concept-RandomAccessRange` and :ref:`concept-SizedRange` concepts |
+--------------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------+
| `RndAccIma::const_value_range` | type of the range to iterate over all the values | models both :ref:`concept-RandomAccessRange` and :ref:`concept-SizedRange` concepts |
+--------------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------+

.. _concept-RandomAccessImage-expressions:
.. rubric:: Expressions

Let `RndAccIma` inherit all valid expressions defined for :ref:`BidirectionalImage <concept-BidirectionalImage-expressions>`.

Let `RndAccIma` inherit all valid expressions defined for :ref:`AccessibleImage <concept-AccessibleImage-expressions>`.


.. _concept-WritableRandomAccessImage:

WritableRandomAccessImage
-------------------------

Let `WRndAccIma` be a type that models :ref:`WritableRandomAccessImage (details) <concept-details-WritableRandomAccessImage>`.

Then `WRndAccIma` also models :ref:`RandomAccessImage <concept-RandomAccessImage>`, :ref:`WritableBidirectionalImage <concept-WritableBidirectionalImage>` and :ref:`WritableAccessibleImage <concept-WritableAccessibleImage>`.

.. _concept-WritableRandomAccessImage-types:
.. rubric:: Types

Let `WRndAccIma` inherit all types defined for :ref:`RandomAccessImage <concept-RandomAccessImage-types>`.

Let `WRndAccIma` inherit all types defined for :ref:`WritableBidirectionalImage <concept-WritableBidirectionalImage-types>`.

Let `WRndAccIma` inherit all types defined for :ref:`WritableAccessibleImage <concept-WritableAccessibleImage-types>`.

Then we can define :

+---------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------+
|        Definition         |                   Description                    |                                     Requirement                                     |
+===========================+==================================================+=====================================================================================+
| `WRndAccIma::pixel_range` | type of the range to iterate over all the pixels | models both :ref:`concept-RandomAccessRange` and :ref:`concept-SizedRange` concepts |
+---------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------+
| `WRndAccIma::value_range` | type of the range to iterate over all the values | models both :ref:`concept-RandomAccessRange` and :ref:`concept-SizedRange` concepts |
+---------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------+

.. _concept-WritableRandomAccessImage-expressions:
.. rubric:: Expressions

Let `WRndAccIma` inherit all valid expressions defined for :ref:`RandomAccessImage <concept-RandomAccessImage-expressions>`.

Let `WRndAccIma` inherit all valid expressions defined for :ref:`WritableBidirectionalImage <concept-WritableBidirectionalImage-expressions>`.

Let `WRndAccIma` inherit all valid expressions defined for :ref:`WritableAccessibleImage <concept-WritableAccessibleImage-expressions>`.