Work on documentation.

doc/source/_static/code.css

@@ -18,6 +18,10 @@
     color: black;
 }
 
+.full {
+    width: 100%
+}
+
 /* .rst-content dl:not(.docutils) dt:last-child { */
 /*     margin-bottom: 6px; */
 /* } */

doc/source/core.rst

@@ -51,18 +51,24 @@ See :doc:`core/images` for a description of the image concepts and image basics.
 
 .. topic:: Fundamental image types
 
-  +--------------+-------------------------+
-  | `image2d<T>` | Buffer-encoded 2D image |
-  +--------------+-------------------------+
-  | `image3d<T>` | Buffer-encoded 3D image |
-  +--------------+-------------------------+
-  | `ndimage<T>` | Buffer-encoded nD image |
-  +--------------+-------------------------+
+  .. table::
+    :class: full
+    :widths: auto
+
+    +--------------+-------------------------+
+    | `image2d<T>` | Buffer-encoded 2D image |
+    +--------------+-------------------------+
+    | `image3d<T>` | Buffer-encoded 3D image |
+    +--------------+-------------------------+
+    | `ndimage<T>` | Buffer-encoded nD image |
+    +--------------+-------------------------+
 
 .. topic:: Functional image views
 
   .. table::
     :widths: auto
+    :class: full
+
 
     +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
     | :cpp:func:`view::transform(ima,f) <mln::view::transform>` | Views the image with values applied to a function.                                         |
@@ -80,6 +86,7 @@ See :doc:`core/images` for a description of the image concepts and image basics.
 
   .. table::
     :widths: auto
+    :class: full
 
     +--------------+-----------------------------------------------------------+
     | Arithmetical | `a + b`, `a - b`, `a * b`, `a / b`, `a % b`               |
@@ -102,6 +109,7 @@ See :doc:`core/images` for a description of the image concepts and image basics.
 
   .. table::
     :widths: auto
+    :class: full
     
     +---------------------------+---------------------------------------------------+
     | ``view::cast<V>(ima)``    | Views the image with the values casted into ``V`` |
@@ -197,18 +205,21 @@ Fundamental primitives for basic image manipulation. Those are grouped by:
 
 .. rubric:: Non-modifying image primitives that operates on values
 
+.. table::
+  :class: full
+  :widths: auto
 
-+-------------------------------------------+------------------------------------------------------------------------+
-| :doc:`core/algorithm/all_any_none_of`     | checks if a predicate is true for all, any or none of the image values |
-+-------------------------------------------+------------------------------------------------------------------------+
-| :doc:`core/algorithm/foreach`             | applies a function to the values of an image                           |
-+-------------------------------------------+------------------------------------------------------------------------+
-| `count` `count_if`                        | [TBI] returns the number of values satisfying specific criteria        |
-+-------------------------------------------+------------------------------------------------------------------------+
-| `equal`                                   | [TBI] checks if two images have the same values                        |
-+-------------------------------------------+------------------------------------------------------------------------+
-| :doc:`core/algorithm/accumulate` (reduce) | sums up values of an image                                             |
-+-------------------------------------------+------------------------------------------------------------------------+
+  +-------------------------------------------+------------------------------------------------------------------------+
+  | :doc:`core/algorithm/all_any_none_of`     | checks if a predicate is true for all, any or none of the image values |
+  +-------------------------------------------+------------------------------------------------------------------------+
+  | :doc:`core/algorithm/foreach`             | applies a function to the values of an image                           |
+  +-------------------------------------------+------------------------------------------------------------------------+
+  | `count` `count_if`                        | [TBI] returns the number of values satisfying specific criteria        |
+  +-------------------------------------------+------------------------------------------------------------------------+
+  | `equal`                                   | [TBI] checks if two images have the same values                        |
+  +-------------------------------------------+------------------------------------------------------------------------+
+  | :doc:`core/algorithm/accumulate` (reduce) | sums up values of an image                                             |
+  +-------------------------------------------+------------------------------------------------------------------------+
 
 
 .. rubric:: Non-modifying image primitives that operates on pixels
@@ -221,21 +232,25 @@ Fundamental primitives for basic image manipulation. Those are grouped by:
 .. rubric:: Modifying image primitives that operates on values
 
 
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/copy`      | copies image values to another image  (without localization) |
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/fill`      | assigns a value to image values                              |
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/clone`     | copies an image in a new image                               |
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/paste`     | copies image pixels to another image (with localization)     |
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/transform` | applies a function to the values of an image                 |
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/generate`  | generate the values of an image by a function                |
-+---------------------------------+--------------------------------------------------------------+
-| :doc:`core/algorithm/iota`      | generate the values of an image with increasing value        |
-+---------------------------------+--------------------------------------------------------------+
+.. table::
+  :class: full
+  :widths: auto
+
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/copy`      | copies image values to another image  (without localization) |
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/fill`      | assigns a value to image values                              |
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/clone`     | copies an image in a new image                               |
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/paste`     | copies image pixels to another image (with localization)     |
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/transform` | applies a function to the values of an image                 |
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/generate`  | generate the values of an image by a function                |
+  +---------------------------------+--------------------------------------------------------------+
+  | :doc:`core/algorithm/iota`      | generate the values of an image with increasing value        |
+  +---------------------------------+--------------------------------------------------------------+
 
 .. rubric:: Modifying image primitives that operates on pixels
 

doc/source/core/images.rst

-======
 Images
-======
+######
 
-operator== return a point-wise view where == comp is done on each pixel.
 
 Images defined by a vector of point -> value are not accessible (ima(p))
 
@@ -23,6 +21,227 @@ Forsee to add pdim (point) and vdim (value) for dimension constant in iamge conc
    :local:
 
 
+Description & Design Overview
+=============================
+
+
+
+An image `f` is basically a function associating a *point* `p` to a *value* `f(p)`. The pair *(point,value)* is called a
+*pixel*. An image is defined over a :cpp:concept:`domain` which is an *ordered range* of points. Depending on the image
+properties, an image type enables a set of operations.
+
+Images have pointer semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+FIXME
+Explain that:
+
+* Images have shallow copy (pointers semantics)
+* Owner vs non-owner images
+
+Images (generally) do not have *const-semantics*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+FIXME:
+Explain how to pass images to function.
+
+
+Images are iterables
+^^^^^^^^^^^^^^^^^^^^
+
+Most images provide 3 ways of traversing.
+
+* Iterating on *points* through the *domain*
+* Iterating on *values*
+* Iterating on *pixels*
+
+As a consequence, such an image ``f`` provide:
+
+* ``f.domain()`` The range of the image *points*
+* ``f.values()`` The range of the image *values*
+* ``f.pixels()`` The range of the image *pixels*
+
+An image can be a :cpp:concept:`BidirectionalImage` and
+allows to be traversed in the reverse order. In that case, the
+*ranges* are :cpp:concept:`ReversibleRange`.
+
+Below is an example of image traversal::
+
+    mln::image2d<uint8_t> f = {{1,2,3}, {4,5,6}}; 
+
+    mln_foreach(auto p, f.domain())
+        std::cout << p << ":" << f(p) << "\n";
+
+    
+    mln_foreach(auto v, f.values())
+        std::cout << v << "\n";
+
+
+    mln_foreach(auto px, f.pixels())
+        std::cout << px.point() << ":" << px.val() << "\n"; 
+
+
+    mln_foreach(auto p, mln::ranges::view::reverse(f.domain()))
+        std::cout << p << ":" << f(p) << "\n";
+
+    
+    mln_foreach(auto v, mln::ranges::view::reverse(f.values()))
+        std::cout << v << "\n";
+
+
+    mln_foreach(auto px, mln::ranges::view::reverse(f.pixels()))
+        std::cout << px.point() << ":" << px.val() << "\n"; 
+
+It produces the following output.
+
+.. code-block:: none
+
+   == Traversing forward ==
+   Traversing through points.
+   [0,0]:1
+   [0,1]:2
+   [0,2]:3
+   [1,0]:4
+   [1,1]:5
+   [1,2]:6
+   Traversing on values.
+   1
+   2
+   3
+   4
+   5
+   6
+   Traversing with pixels.
+   [0,0]:1
+   [0,1]:2
+   [0,2]:3
+   [1,0]:4
+   [1,1]:5
+   [1,2]:6
+
+   == Traversing backward ==
+   Traversing through points.
+   [1,2]:6
+   [1,1]:5
+   [1,0]:4
+   [0,2]:3
+   [0,1]:2
+   [0,0]:1
+   Traversing on values.
+   6
+   5
+   4
+   3
+   2
+   1
+   Traversing with pixels.
+   [1,2]:6
+   [1,1]:5
+   [1,0]:4
+   [0,2]:3
+   [0,1]:2
+   [0,0]:1
+
+
+.. note:: Not all image provide the access of the value associated to a point (the `f(p)` syntax). This is available for :cpp:concept:`AccessibleImage` images. 
+
+.. note::  The macro :c:macro:`mln_foreach` is just a shortcut to iterate over rows in an efficient way.
+
+
+To iterate over several images in the same time, use :cpp:func:`mln::ranges::view::zip` to pack the value or pixel ranges of each image::
+
+
+    auto&& v_rng = mln::ranges::view::zip(f1.values(), f2.values())
+    mln_foreach((auto [v1, v2]), v_rng)
+        std::cout << v1 << " " << v2 << "\n";
+
+
+Images can be initialized from other images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is quite common to use temporary images for computation or to return new images whose type depend on the image input
+type. As a consequence, we may need to initialize images from other images, this is called *concretization*.
+
+The effects of the *concretization* are:
+
+    Given a image `f`, the concretization of `f` gives an image `g`, with a domain equal to `f`'s, which can store
+    values and such that any write to `f` or `g` does not have any side-affect on the other.
+
+
+Two methods enable to create a new image `g` from a prototype `f`. The second allows to use another value type::
+
+    I f = ...;
+    mln::concrete_t<I>  g1 = f.concretize();
+    mln::ch_value_t<I, OtherType> g2 = f.template ch_value<OtherType>()
+
+Because the syntax of a call to a template method is quite cumbersome, free functions can be used::
+
+    I f = ...;
+    mln::concrete_t<I>            g1 = mln::concretize(f);
+    mln::ch_value_t<I, OtherType> g2 = mln::ch_value<OtherType>(f);
+
+.. warning:: The type returned by `concretize` et al. are not images but *image initializers* that support advanced
+    parameterization of the initialization.  So you should not use ``auto`` type deduction for variables.
+
+
+.. topic:: Advanced initialization
+
+*image initializers* follow the `Named parameter Idiom
+<https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Named_Parameter>`_ and provides additional init parameters. Note that it may fail to fulfill the requirements, so a status code may be queried to check if everything succeeded.
+
+
+
++------------------------+---------------------------------------------------------------------------------------------+
+| ``init(v)``            | Requires the image to be set to `v`                                                         |
++------------------------+---------------------------------------------------------------------------------------------+
+| ``adjust(nbh)``        | Requires the extension of the image to be wide enough to hold the :ref:`neighborhood` `nbh` |
++------------------------+---------------------------------------------------------------------------------------------+
+| ``get_status(status)`` | Get the status code                                                                         |
++------------------------+---------------------------------------------------------------------------------------------+
+
+Example::
+
+    I f = ...;
+    int st_code = 0;
+    mln::concrete_t<I> g1 = mln::concretize(f).adjust(mln::c4).get_status(st_code);
+    if (st_code == 0)
+        // run with g1
+    else
+        // g1 may not have the adequate extension
+
+
+.. topic:: Initialization constructor
+
+Advanced initialization require an initialization constructor that enables an image to be initialized from another image
+and deduces the initialization configuration from it.
+
+It has the form:
+
+``I(const I& other, mln::image_initializer_params_t params)``
+    Initialize from `other` but overrides init-parameters with those from `params`.
+
+
+
+
+
+
+
+
+
+
+Image Concepts
+==============
+
+Image-related Concepts
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Values
+
+* Point
+
+* Domain
+
+* Pixel
 
 
 
@@ -112,7 +331,52 @@ Forsee to add pdim (point) and vdim (value) for dimension constant in iamge conc
 
    * :ref:`Index <concept-indexes-Index>`
 
-Concepts
+
+Image properties
+^^^^^^^^^^^^^^^^
+
+Image concepts are *property*-based. An image concept is group of images types sharing some properties.
+
+Image (traversal) category
+    The image category describes how an image can be traversed. It can be **forward**, **bidirectional** (can be
+    traversed **backward** and **forward**), or **raw** (buffer encoded image with *contiguous* line buffer)
+Image Accessibility
+    An image is said **accessible** whenever it allows to access the value associated to a point, i.e. it allows to
+    write `f(p)`. While it may seem trivial, not all image are accessible (for example image defined by a vector of pair
+    *(p, f(p))*.
+Image Indexability
+    An image is **indexable** whenever it enables to access values with an index localisator. Usually, accessing through
+    an index is faster than accessing by a point.
+Image Writability
+    An image **writable** can be used as an output image to store the result of a processing. Some image are *read-only* as images that compute values on-the-fly and are not buffer-encoded.  
+
+
+
+The figure below illustrates image properties and some of the image concept.
+
+.. figure:: /figures/core/image-concepts.svg
+    :width: 100%
+
+    Image concepts and properties.
+
+
+
+    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 --------
 
 

doc/source/core/neighborhood.rst

+.. _neighborhood 
+
 Neighborhood, Sliding Windows and Structuring Elements
 ######################################################
 

doc/source/figures/core/image-concepts.tex

+\documentclass[svgnames,tikz]{standalone}
+\usepackage{tikz-uml,verbatimbox}
+\usetikzlibrary{positioning,calc}
+
+\tikzumlset{
+  font=\small\tt
+}
+
+\newcommand{\rref}{\&\&}
+
+\begin{document}
+
+\small
+  \begin{myverbbox}{\bONE}
+using point_type       = ...;
+using value_type       = ...;
+using reference        = ...;
+using pixel_type       = ...;
+
+using concrete_type    = ...;
+using ch_value_type<V> = ...;
+
+using category    = forward_image_tag;
+using accessible  = ...;
+using indexable   = ...;
+\end{myverbbox}
+
+
+\begin{tikzpicture}
+  \tikzset{prop/.style={font=\itshape}}
+
+
+  \umlclass{Image}{\bONE
+  }{
+    concretize() -> auto \\
+    ch\_value<V>() -> auto \\
+
+    domain() -> ForwardRange\rref \\
+    values() -> ForwardRange\rref \\
+    pixels() -> ForwardRange\rref
+  }
+
+
+  \umlclass[below=1cm of Image,fill=magenta!30]{Bidirectional Image}{
+    using category = bidirectional\_image\_tag
+  }{
+    domain() -> ReversibleRange\rref \\
+    values() -> ReversibleRange\rref \\
+    pixels() -> ReversibleRange\rref
+  }
+
+  \umlclass[right=1cm of Image.east, anchor=north west, fill=orange!30]{Accessible Image}{
+    using accessible = std::true\_type;
+  }{
+    operator() (point\_type p) -> reference \\
+    at(point\_type p) -> reference\\
+    pixel(point\_type p) -> pixel\_type\\
+    pixel\_at(point\_type p) -> pixel\_type\\
+  }
+
+
+  \umlclass[right=1cm of Accessible Image.north east, anchor=north west, fill=green!30]{Indexable Image}{
+    using indexable = std::true\_type;\\
+    using index\_type = \ldots
+  }{
+    operator[] (index\_type k) -> reference \\
+  }
+
+  \umlclass[below=4cm of $(Accessible Image.north)!0.5!(Indexable Image.north)$ ,fill=none]{Indexable And Accessible Image}{
+  }{
+    index\_of\_point(point\_type) const -> index\_type\\
+    point\_at\_index(index\_type) const -> point\_type\\
+    delta\_index(point\_type) const -> index\_type
+  }
+
+  \node[prop,magenta] [above=of Image] {Traversability};
+  \node[prop,orange] [above=of Accessible Image] {Accessibility};
+  \node[prop,DarkGreen] [above=of Indexable Image] {Indexability};
+
+  \umlVHVinherit{Bidirectional Image}{Image}
+  \umlVHVinherit{Indexable And Accessible Image}{Accessible Image}
+  \umlVHVinherit{Indexable And Accessible Image}{Indexable Image}
+\end{tikzpicture}
+\end{document}
\ No newline at end of file