Image concepts (details)
========================

.. contents:: Table of Contents
    :local:


.. _concept-details-Image:

Image
-----

.. cpp:concept:: template <typename Ima> Image

    #. ``Ima::pixel_type`` models the :cpp:concept:`template <typename Pix> Pixel` concept.
    #. ``Ima::domain_type`` models the :cpp:concept:`template <typename Dom> Domain` concept.
    #. ``Ima::index_type`` models the :cpp:concept:`template <typename Idx> Index` concept.
    #. ``Ima::const_pixel_range`` models the :cpp:concept:`template <typename FwdRng> ForwardRange` concept.
    #. ``Ima::const_value_range`` models the :cpp:concept:`template <typename FwdRng> ForwardRange` concept.
    #. ``Ima::value_type`` models the :cpp:concept:`template <typename Val> Value` concept, is non-const and is not a reference.
    #. ``Ima::difference_type`` models the :cpp:concept:`template <typename T> SignedIntegral` concept.
    #. ``Ima`` is consistant with ``point_type``, ``value_type`` and ``reference`` from ``pixel_type``.
    #. ``Ima`` provide methods ``is_concrete``, ``to_concrete``, ``values``, ``pixels``, ``domain`` ``operator[]``, ``index_of_point``, ``point_at_index`` and ``delta_index``.

    **Notation**

    .. cpp:type::   domain_type = Ima::domain_type
    .. cpp:type::   pixel_type = Ima::pixel_type
    .. cpp:type::   const_pixel_type = const Ima::pixel_type
    .. cpp:type::   index_type = Ima::index_type
    .. cpp:type::   difference_type = decltype(index_type() - index_type())
    .. cpp:type::   point_type = pixel_type::point_type
    .. cpp:type::   value_type = pixel_type::value_type
    .. cpp:type::   const_reference = const_pixel_type::reference
    .. cpp:type::   const_pixel_range = Ima::const_pixel_range
    .. cpp:type::   const_value_range = Ima::const_value_range
    .. cpp:var::    Ima ima
    .. cpp:var::    const Ima cima
    .. cpp:var::    index_type k
    .. cpp:var::    point_type p

    **Valid Expressions**

    - :cpp:expr:`is_const_v<value_type>` returns ``false``
    - :cpp:expr:`is_reference<value_type>` returns ``false``
    - :cpp:expr:`cima.is_concrete(p)` returns-type models :cpp:concept:`template <typename B> Boolean`
    - :cpp:expr:`cima.to_concrete(p)` returns-type models :cpp:concept:`template <typename ConcIma> ConcreteImage`
    - :cpp:expr:`cima.pixels()` returns :cpp:expr:`const_pixel_range`
    - :cpp:expr:`cima.values()` returns :cpp:expr:`const_value_range`
    - :cpp:expr:`cima.domain()` returns :cpp:expr:`domain_type`
    - :cpp:expr:`cima[k]` returns :cpp:expr:`const_reference`
    - :cpp:expr:`cima.index_of_point(p)` returns :cpp:expr:`index_type`
    - :cpp:expr:`cima.point_of_index(k)` returns :cpp:expr:`point_type`
    - :cpp:expr:`cima.delta_index(p)` returns :cpp:expr:`difference_type`

    **Possible implementation**

    .. code:: cpp

        template <typename Im, Ima = remove_cvref<Im>>
        concept Image =
            requires {
                typename Ima::pixel_type;
                typename Ima::const_pixel_type
                typename Ima::point_type;
                typename Ima::value_type;
                typename Ima::domain_type;
                typename Ima::difference_type;
                typename Ima::index_type;
                typename Ima::const_reference;
                typename Ima::const_pixel_range;
                typename Ima::const_value_range;
            } &&

            Pixel<Ima::pixel_type> &&
            Point<Ima::point_type> &&
            Value<Ima::value_type> &&
            Domain<Ima::domain_type> &&
            Index<Ima::index_type> &&
            SignedIntegral<Ima::difference_type> &&
            ForwardRange<Ima::const_pixel_range> &&
            ForwardRange<Ima::const_value_range> &&

            Same<Ima::difference_type, decltype(Ima::index_type() - Ima::index_type())> &&
            Same<Ima::point_type, Ima::pixel_type::point_type> &&
            Same<Ima::value_type, Ima::pixel_type::value_type> &&
            Same<Ima::const_reference, const Ima::pixel_type::reference> &&
            Same<Ima::const_pixel_type, const Ima::pixel_type> &&
            Same<Ima::const_pixel_type, Ima::const_pixel_range::value_type> &&
            Same<Ima::const_reference, Ima::const_value_range::value_type> &&

            !is_const_v<Ima::value_type> &&
            !is_reference_v<Ima::value_type> &&

            requires(   Ima ima, const Ima cima, Ima::domain_type d,
                        Ima::index_type k, Ima::point_type p) {
                { cima[k] }                 -> Ima::const_reference,
                { cima.pixels() }           -> Ima::const_pixel_range;
                { cima.values() }           -> Ima::const_value_range;
                { cima.domain() }           -> Ima::domain_type;
                { cima.point_of_index(k) }  -> Ima::point_type
                { cima.index_at_point(p) }  -> Ima::index_type;
                { cima.delta_index(p) }     -> Ima::difference_Type;
                { cima.is_concrete() }      -> Boolean;
                { cima.to_toncrete() }      -> ConcreteImage;
            };


.. _concept-details-ConcreteImage:

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

.. cpp:concept:: template <typename ConcIma> ConcreteImage

    #. Refines the :cpp:concept:`template <typename T> Semiregular` concept.
    #. Refines the :cpp:concept:`template <typename Ima> Image` concept.
    #. ``ConcIma`` provide methods ``resize`` and ``reindex``.

    **Notation**

    .. cpp:type::   domain_type = ConcIma::domain_type
    .. cpp:type::   index_type = ConcIma::index_type
    .. cpp:type::   pixel_type = ConcIma::pixel_type
    .. cpp:type::   value_type = pixel_type::value_type
    .. cpp:var::    ConcIma concima
    .. cpp:var::    ConcIma concima_cpy
    .. cpp:var::    const ConcIma cconcima
    .. cpp:var::    index_type k
    .. cpp:var::    domain_type d
    .. cpp:var::    value_type v

    **Valid Expressions**

    - :cpp:expr:`concima()` returns an instance of :cpp:expr:`ConcIma`.
    - :cpp:expr:`cconcima()` returns an instance of :cpp:expr:`const ConcIma`.

    - :cpp:expr:`concima_cpy(concima)` returns an instance of :cpp:expr:`ConcIma`.
    - :cpp:expr:`concima_cpy(cconcima)` returns an instance of :cpp:expr:`ConcIma`.
    - :cpp:expr:`concima_cpy(move(concima))` returns an instance of :cpp:expr:`ConcIma`.

    - :cpp:expr:`concima_cpy = concima` returns an instance of :cpp:expr:`ConcIma&`.
    - :cpp:expr:`concima_cpy = cconcima` returns an instance of :cpp:expr:`ConcIma&`.
    - :cpp:expr:`concima_cpy = move(concima)` returns an instance of :cpp:expr:`ConcIma&`.

    - :cpp:expr:`concima.resize(d)` is valid.
    - :cpp:expr:`concima.resize(d, v)` is valid.
    - :cpp:expr:`concima.reindex(k)` is valid.

    **Possible implementation**

    .. code:: cpp

        template <typename ConcIm, ConcIma = remove_cvref<ConcIm>>
        concept ConcreteImage = Semiregular<ConcIma> &&
                                Image<ConcIma> &&

                                requires(   ConcIma ima, ConcIma::domain_type d,
                                            ConcIma::index_type k, ConcIma::value_type v) {
                                    { ima.resize(d) };
                                    { ima.resize(d, v) };
                                    { ima.reindex(k) };
                                };


.. _concept-details-WritableImage:

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

.. cpp:concept:: template <typename WIma> WritableImage

    #. Refines the concept :cpp:concept:`template <typename Ima> Image`.
    #. Defines the non-const version of ``reference``, ``value_range`` and ``pixel_range``.
    #. Access methods now return mutable references.

    **Notation**

    .. cpp:type::   pixel_type = WIma::pixel_type
    .. cpp:type::   index_type = WIma::index_type
    .. cpp:type::   reference = pixel_type::reference
    .. cpp:type::   pixel_range = WIma::pixel_range
    .. cpp:type::   value_range = WIma::value_range
    .. cpp:var::    WIma wima
    .. cpp:var::    index_type k
    .. cpp:var::    domain_type d

    **Valid Expressions**

    - :cpp:expr:`wima.pixels()` returns :cpp:expr:`pixel_range`
    - :cpp:expr:`wima.values()` returns :cpp:expr:`value_range`
    - :cpp:expr:`wima[k]` returns :cpp:expr:`reference`

    **Possible implementation**

    .. code:: cpp

        template <typename WIm, WIma = remove_cvref<WIm>>
        concept WritableImage =
            Image<WIma> &&

            requires {
                typename WIma::pixel_range;
                typename WIma::value_range;
            } &&

            ForwardRange<WIma::pixel_range> &&
            ForwardRange<WIma::value_range> &&
            OutputRange<WIma::pixel_range, WIma::pixel_type> &&
            OutputRange<WIma::value_range, WIma::value_type> &&

            Same<WIma::reference, WIma::pixel_type::reference> &&
            Same<WIma::pixel_type, WIma::pixel_range::value_type> &&
            Same<WIma::reference, WIma::value_range::value_type> &&

            requires(WIma wima, WIma::index_type k, WIma::domain_type d, WIma::value_type v) {
                { wima[k] }             -> WIma::reference;
                { wima.pixels() }       -> WIma::pixel_range;
                { wima.values() }       -> WIma::value_range;
            };


.. _concept-details-BidirectionalImage:

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

.. cpp:concept:: template <typename BidirIma> BidirectionalImage

    #. Refines the concept :cpp:concept:`template <typename Ima> Image`
    #. ``BidirIma::const_pixel_range`` models the :cpp:concept:`template <typename BidirRng> BidirectionalRange` concept.
    #. ``BidirIma::const_value_range`` models the :cpp:concept:`template <typename BidirRng> BidirectionalRange` concept.

    **Notation**

    .. cpp:type::   const_pixel_range = BidirIma::const_pixel_range
    .. cpp:type::   const_value_range = BidirIma::const_value_range

    **Possible implementation**

    .. code:: cpp

        template <typename BidirIm, BidirIma = remove_cvref<BidirIm>>
        concept BidirectionalImage =
            Image<BidirIma> &&

            BidirectionalRange<BidirIma::const_pixel_range> &&
            BidirectionalRange<BidirIma::const_value_range> &&

            Same<BidirIma::const_pixel_type, BidirIma::const_pixel_range::value_type> &&
            Same<BidirIma::const_reference, BidirIma::const_value_range::value_type>;


.. _concept-details-WritableBidirectionalImage:

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

.. cpp:concept:: template <typename WBidirIma> WritableBidirectionalImage

    #. Refines the concept :cpp:concept:`template <typename WIma> WritableImage`.
    #. Refines the concept :cpp:concept:`template <typename BidirIma> BidirectionnalImage`.
    #. ``WBidirIma::pixel_range`` models the :cpp:concept:`template <typename BidirRng> BidirectionalRange` concept.
    #. ``WBidirIma::value_range`` models the :cpp:concept:`template <typename BidirRng> BidirectionalRange` concept.

    **Notation**

    .. cpp:type::   pixel_range = WBidirIma::pixel_range
    .. cpp:type::   value_range = WBidirIma::value_range

    **Possible implementation**

    .. code:: cpp

        template <typename WBidirIm, WBidirIma = remove_cvref<WBidirIm>>
        concept WritableBidirectionalImage =
            WritableImage<WBidirIma> &&
            BidirectionnalImage<WBidirIma> &&

            BidirectionalRange<WBidirIma::pixel_range> &&
            BidirectionalRange<WBidirIma::value_range> &&

            Same<WBidirIma::pixel_type, WBidirIma::pixel_range::value_type> &&
            Same<WBidirIma::reference, WBidirIma::value_range::value_type>;


.. _concept-details-AccessibleImage:

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

.. cpp:concept:: template <typename AccIma> AccessibleImage

    #. Refines the concept :cpp:concept:`template <typename Ima> Image`.
    #. Add new access methods based on ``point_type`` : ``operator()``, ``pixel``, ``at`` and ``pixel_at``

    **Notation**

    .. cpp:type::   const_pixel_type = const AccIma::pixel_type
    .. cpp:type::   point_type = pixel_type::point_type
    .. cpp:type::   value_type = pixel_type::value_type
    .. cpp:type::   const_reference = const pixel_type::reference
    .. cpp:var::    const AccIma caccima
    .. cpp:var::    point_type p

    **Valid Expressions**

    - :cpp:expr:`caccima(p)` returns :cpp:expr:`const_reference` with bound checking.
    - :cpp:expr:`caccima.pixel(p)` returns :cpp:expr:`const_pixel_type` with bound checking.
    - :cpp:expr:`caccima.at(p)` returns :cpp:expr:`const_reference` without bound checking.
    - :cpp:expr:`caccima.pixel_at(p)` returns :cpp:expr:`const_pixel_type` without bound checking.

    **Possible implementation**

    .. code:: cpp

        template <typename AccIm, AccIma = remove_cvref<AccIm>>
        concept AccessibleImage =
            Image<AccIma> &&

            requires(const AccIma caccima, AccIma::point_type p)
                { accima(p) }           -> AccIma::const_reference;
                { accima.pixel(p) }     -> AccIma::const_pixel_type;
                { accima.at(p) }        -> AccIma::const_reference;
                { accima.pixel_at(p) }  -> AccIma::const_pixel_type;
            };


.. _concept-details-WritableAccessibleImage:

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

.. cpp:concept:: template <typename WAccIma> WritableAccessibleImage

    #. Refines the concept :cpp:concept:`template <typename WIma> WritableImage`.
    #. Refines the concept :cpp:concept:`template <typename AccIma> AccessibleImage`.
    #. Add new access methods based on ``point_type`` : ``operator()``, ``pixel``, ``at`` and ``pixel_at``

    **Notation**

    .. cpp:type::   pixel_type = WAccIma::pixel_type
    .. cpp:type::   point_type = pixel_type::point_type
    .. cpp:type::   value_type = pixel_type::value_type
    .. cpp:type::   reference = pixel_type::reference
    .. cpp:var::    WAccIma waccima
    .. cpp:var::    point_type p

    **Valid Expressions**

    - :cpp:expr:`waccima(p)` returns :cpp:expr:`reference` with bound checking.
    - :cpp:expr:`waccima.pixel(p)` returns :cpp:expr:`pixel_type` with bound checking.
    - :cpp:expr:`waccima.at(p)` returns :cpp:expr:`reference` without bound checking.
    - :cpp:expr:`waccima.pixel_at(p)` returns :cpp:expr:`pixel_type` without bound checking.

    **Possible implementation**

    .. code:: cpp

        template <typename WAccIm, WAccIma = remove_cvref<WAccIm>>
        concept WritableAccessibleImage =
            WritableImage<WAccIma> &&
            AccessibleImage<WAccIma> &&

            requires(WAccIma waccima, WAccIma::point_type p)
                { waccima(p) }          -> WAccIma::reference;
                { waccima.pixel(p) }    -> WAccIma::pixel_type;
                { waccima.at(p) }       -> WAccIma::reference;
                { waccima.pixel_at(p) } -> WAccIma::pixel_type;
            };


.. _concept-details-RandomAccessImage:

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

.. cpp:concept:: template <typename RndAccIma> RandomAccessImage

    #. Refines the concept :cpp:concept:`template <typename BidirIma> BidirectionalImage`.
    #. Refines the concept :cpp:concept:`template <typename AccIma> AccessibleImage`.
    #. ``RndAccIm::const_pixel_range`` models both the :cpp:concept:`template <typename RndAccRng> RandomAccessRange` and the :cpp:concept:`template <typename SRng> SizedRange` concept.
    #. ``RndAccIm::const_value_range`` models both the :cpp:concept:`template <typename RndAccRng> RandomAccessRange` and the :cpp:concept:`template <typename SRng> SizedRange` concept.

    **Notation**

    .. cpp:type::   RndAccIm
    .. cpp:type::   const_pixel_range = RndAccIm::const_pixel_range
    .. cpp:type::   const_value_range = RndAccIm::const_value_range

    **Possible implementation**

    .. code:: cpp

        template <typename RndAccIm, RndAccIma = remove_cvref<RndAccIm>>
        concept RandomAccessImage =
            BidirectionalImage<RndAccIma> &&
            AccessibleImage<RndAccIma> && 
            
            RandomAccessRange<RndAccIma::const_pixel_range> &&
            RandomAccessRange<RndAccIma::const_value_range> &&
            SizedRange<WRndAccIma::const_pixel_range> &&
            SizedRange<WRndAccIma::const_value_range> &&

            Same<RndAccIma::const_pixel_type, RndAccIma::const_pixel_range::value_type> &&
            Same<RndAccIma::const_reference, RndAccIma::const_value_range::value_type>;


.. _concept-details-WritableRandomAccessImage:

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

.. cpp:concept:: template <typename WRndAccIma> WritableRandomAccessImage

    #. Refines the concept :cpp:concept:`template <typename WBidirIma> WritableBidirectionalImage`.
    #. Refines the concept :cpp:concept:`template <typename WAccIma> WritableAccessibleImage`.
    #. ``WRndAccIm::pixel_range`` models both the :cpp:concept:`template <typename RndAccRng> RandomAccessRange` and the :cpp:concept:`template <typename SRng> SizedRange` concept.
    #. ``WRndAccIm::value_range`` models both the :cpp:concept:`template <typename RndAccRng> RandomAccessRange` and the :cpp:concept:`template <typename SRng> SizedRange` concept.
    
    **Notation**

    ..cpp:type::    WRndAccIm
    .. cpp:type::   pixel_range = WRndAccIm::pixel_range
    .. cpp:type::   value_range = WRndAccIm::value_range

    **Possible implementation**

    .. code:: cpp

        template <typename WRndAccIm, WRndAccIma = remove_cvref<WRndAccIm>>
        concept WritableRandomAccessImage =
            WritableBidirectionalImage<WRndAccIma> &&
            WritableAccessibleImage<WRndAccIma> &&
            RandomAccessImage<WRndAccIma> &&

            RandomAccessRange<WRndAccIma::pixel_range> &&
            RandomAccessRange<WRndAccIma::value_range> &&
            SizedRange<WRndAccIma::pixel_range> &&
             SizedRange<WRndAccIma::value_range> &&

            Same<WRndAccIma::pixel_type, WRndAccIma::pixel_range::value_type> &&
            Same<WRndAccIma::reference, WRndAccIma::value_range::value_type>;