Start documentation of views.

18cb167c · Edwin Carlinet · dc9af6aa · 18cb167c · 18cb167c · 18cb167c
Commit 18cb167c authored Jan 29, 2019 by Edwin Carlinet
--- a/doc/source/core.rst
+++ b/doc/source/core.rst
@@ -7,104 +7,16 @@ Core Module
 .. toctree::
   :hidden:

-   core/values
-   core/points
-   core/pixels
-   core/domains
-   core/indexes
-   core/ranges
+
   core/images
+   core/ranges
   core/neighborhood
   core/stl




-.. raw:: html
-
-         <h2>Values</h2>
-
-
-:doc:`core/values` are the fundamentals tools to model values held by images.
-
-
-.. topic:: Concepts
-
-   * :ref:`Value <concept-values-Value>`
-   * :ref:`ComparableValue <concept-values-ComparableValue>`
-   * :ref:`OrderedValue <concept-values-OrderedValue>`
-
-.. topic:: Predefined values
-
-   * :doc:`core/values/rgba`
-
-.. topic:: Utilities
-
-   TODO channel utilities
-..   * :cpp:func:`is_multichannel`
-..   * :cpp:func:`dynamic_channel_get`
-..   * :cpp:func:`dynamic_channel_size`
-..   * :cpp:func:`static_channel_get`
-..   * :cpp:func:`static_channel_size`
-
-
-
-.. raw:: html
-
-         <h2>Points</h2>
-
-
-:doc:`core/points` are the fundamentals tools to locate a value inside an images.
-
-
-.. topic:: Concepts
-
-   * :ref:`Point <concept-points-Point>`
-
-
-
-
-.. raw:: html
-
-         <h2>Pixels</h2>
-
-
-:doc:`core/pixels` are the fundamentals tools when browsing an images to access both the point and the value.
-
-
-.. topic:: Concepts

-   * :ref:`Pixel <concept-pixels-Pixel>`
-
-
-
-
-.. raw:: html
-
-         <h2>Domains</h2>
-
-
-:doc:`core/domains` are the fundamental tools when expressing the valid set of points for an image.
-
-
-.. topic:: Concepts
-
-   * :ref:`Domain <concept-domains-Domain>`
-
-
-
-
-.. raw:: html
-
-         <h2>Indexes</h2>
-
-
-:doc:`core/indexes` are the lowest level tools to locate a value inside an images.
-
-
-.. topic:: Concepts
-
-   * :ref:`Index <concept-indexes-Index>`



@@ -114,7 +26,8 @@ Core Module
         <h2>Images</h2>


-:doc:`core/images` represent an image and all its properties.
+See :doc:`core/images` for a description of the image concepts and image basics.
+


 .. topic:: Concepts
@@ -136,11 +49,69 @@ Core Module

   TODO

-.. topic:: Images
-
-   * :doc:`core/images/ndimage`
-
-
+.. topic:: Fundamental image types
+
+  +--------------+-------------------------+
+  | `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
+
+    +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
+    | :cpp:func:`view::transform(ima,f) <mln::view::transform>` | Views the image with values applied to a function.                                         |
+    +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
+    | ``view::filter(ima, pred)``                               | Views the image restricted to pixels with values passing a predicate.                      |
+    +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
+    | ``view::mask(ima, mask)``                                 | Views the image restricted to pixels in a binary mask.                                     |
+    +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
+    | ``view::clip(ima, roi)``                                  | Views the image restricted to a sub-region.                                                |
+    +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
+    | ``view::zip(ima1, ima2, ..., imaN)``                      | Views a list of images as a single image where values are tuples of the each image values. |
+    +-----------------------------------------------------------+--------------------------------------------------------------------------------------------+
+
+.. topic:: Common image operators (views)
+
+  .. table::
+    :widths: auto
+
+    +--------------+-----------------------------------------------------------+
+    | Arithmetical | `a + b`, `a - b`, `a * b`, `a / b`, `a % b`               |
+    +--------------+-----------------------------------------------------------+
+    | Logical      | ``land(a,b)``, ``lor(a,b)``, ``lnot(a)``                  |
+    +--------------+-----------------------------------------------------------+
+    | Comparison   | `a < b`, `a <= b`, `a == b`, `a != b`, `a >= b`, `a > b`  |
+    +--------------+-----------------------------------------------------------+
+    | Conditional  | ``view::ifelse(a,b,c)``                                   |
+    +--------------+-----------------------------------------------------------+
+
+
+.. topic:: Mathematical image operator (views)
+
+  +-------+-------+
+  | FIXME | FIXME |
+  +-------+-------+
+
+.. topic:: Other image operators (views)
+
+  .. table::
+    :widths: auto
+    
+    +---------------------------+---------------------------------------------------+
+    | ``view::cast<V>(ima)``    | Views the image with the values casted into ``V`` |
+    +---------------------------+---------------------------------------------------+
+    | ``view::channel(ima, k)`` | Views the k-th channel of the image               |
+    +---------------------------+---------------------------------------------------+
+    | ``view::red(ima)``        |                                                   |
+    | ``view::green(ima)``      |                                                   |
+    | ``view::blue(ima)``       | Views the red, green or blue channel of the image |
+    +---------------------------+---------------------------------------------------+


 .. raw:: html
@@ -205,13 +176,17 @@ Image primitives
 .. toctree::
    :hidden:

-    core/algorithm/fill
+    core/algorithm/accumulate    
+    core/algorithm/all_any_none_of
+    core/algorithm/clone
    core/algorithm/copy
+    core/algorithm/fill
+    core/algorithm/foreach
+    core/algorithm/generate  
+    core/algorithm/iota
    core/algorithm/paste
+    core/algorithm/sort
    core/algorithm/transform
-    core/algorithm/iota
-    core/algorithm/accumulate    
-    core/algorithm/generate  

 Fundamental primitives for basic image manipulation. Those are grouped by:


--- a/doc/source/core/images.rst
+++ b/doc/source/core/images.rst
-=====
-Image
-=====
+======
+Images
+======

 operator== return a point-wise view where == comp is done on each pixel.

@@ -8,13 +8,110 @@ Images defined by a vector of point -> value are not accessible (ima(p))

 Forsee to add pdim (point) and vdim (value) for dimension constant in iamge concept

+.. toctree::
+   :hidden:

+   values
+   points
+   pixels
+   domains
+   indexes
+   view/transform


 .. contents::
   :local:


+
+
+
+.. raw:: html
+
+         <h2>Values</h2>
+
+
+:doc:`core/values` are the fundamentals tools to model values held by images.
+
+
+.. topic:: Concepts
+
+   * :ref:`Value <concept-values-Value>`
+   * :ref:`ComparableValue <concept-values-ComparableValue>`
+   * :ref:`OrderedValue <concept-values-OrderedValue>`
+
+.. topic:: Predefined values
+
+   * :doc:`core/values/rgba`
+
+.. topic:: Utilities
+
+   TODO channel utilities
+..   * :cpp:func:`is_multichannel`
+..   * :cpp:func:`dynamic_channel_get`
+..   * :cpp:func:`dynamic_channel_size`
+..   * :cpp:func:`static_channel_get`
+..   * :cpp:func:`static_channel_size`
+
+
+
+.. raw:: html
+
+         <h2>Points</h2>
+
+
+:doc:`core/points` are the fundamentals tools to locate a value inside an images.
+
+
+.. topic:: Concepts
+
+   * :ref:`Point <concept-points-Point>`
+
+
+
+
+.. raw:: html
+
+         <h2>Pixels</h2>
+
+
+:doc:`core/pixels` are the fundamentals tools when browsing an images to access both the point and the value.
+
+
+.. topic:: Concepts
+
+   * :ref:`Pixel <concept-pixels-Pixel>`
+
+
+
+
+.. raw:: html
+
+         <h2>Domains</h2>
+
+
+:doc:`core/domains` are the fundamental tools when expressing the valid set of points for an image.
+
+
+.. topic:: Concepts
+
+   * :ref:`Domain <concept-domains-Domain>`
+
+
+
+
+.. raw:: html
+
+         <h2>Indexes</h2>
+
+
+:doc:`core/indexes` are the lowest level tools to locate a value inside an images.
+
+
+.. topic:: Concepts
+
+   * :ref:`Index <concept-indexes-Index>`
+
 Concepts
 --------


--- a/doc/source/core/view/transform.rst
+++ b/doc/source/core/view/transform.rst
+Transform (View)
+################
+
+Include :file:`<mln/core/image/view/transform.hpp>`
+
+.. cpp:namespace:: mln::view
+
+#. .. cpp:function:: auto transform(Image ima, UnaryFunction f)
+#. .. cpp:function:: auto transform(Image ima, Image ima2, BinaryFunction f)
+
+    1. Makes a view from `ima` where for each pixel value evals to `out(p) = f(ima(p))`
+    2. Makes a view from `ima` where for each pixel value evals to `out(p) = f(ima(p),ima2(p))`. For this overload, the domain of both image must be equal.
+    
+
+    :param ima: Input range
+    :param ima2: Input range
+    :param f: Function to apply on pixel values
+
+
+
+.. warning:: The function f must not create dangling references on the input.
+
+    .. code::
+    
+        mln::image2d<mln::rgb8> ima = ...;
+        auto g1 = mln::view::transform(ima, [](rgb8 v) { return v; }); // OK: identity but creates a non-mutable image 
+        auto g2 = mln::view::transform(g1, [](const rgb8& v) -> const uint8& { return v[0]; }); // KO: create a dangling reference to g1(p)
+
+
+
+----------------+---------------+------------+---------------------+---------------------------+
+|                |               | *ima,ima2* | *transform(ima, f)* | *transform(ima, ima2, f)* |
+================+===============+============+=====================+===========================+
+|                | Forward       | X          | X                   | X                         |
+                +---------------+------------+---------------------+---------------------------+
+| **Category**   | Bidirectional | X          | X                   | X                         |
+                +---------------+------------+---------------------+---------------------------+
+|                | Raw           | X          |                     |                           |
+----------------+---------------+------------+---------------------+---------------------------+
+|                | Writable      | X          | X*                  | X*                        |
+                +---------------+------------+---------------------+---------------------------+
+| **Properties** | Accessible    | X          | X                   | X                         |
+                +---------------+------------+---------------------+---------------------------+
+|                | Indexable     | X          | X                   | X                         |
+----------------+---------------+------------+---------------------+---------------------------+
+
+
+(*): only if `f` is a projection.
+
+
+Examples
+--------
+   
+* Multiply all values by 2:
+
+.. code::
+
+    mln::image2d<uint8_t> input = { {0,1,2}, {3,4,5} }; 
+    auto g = mln::view::transform(input, [](mln::uint8 v) { return v * 2; });
+    mln::io::imprint(g);
+
+Outputs:
+
+.. code-block:: text
+
+    0 2 4
+    6 8 10
+
+* Write on the red projected member:
+
+.. code::
+
+    mln::image2d<mln::rgb8> input = {{{0,0,0}, {1,1,1}, {2,2,2}}, {{3,3,3}, {4,4,4}, {5,5,5}}}; 
+    auto g = mln::view::transform(input, [](mln::rgb8& x) -> uint8_t& { return x[0]; });
+    mln::fill(g, 42);
+
+Outputs:
+
+.. code-block:: text
+
+    [42,0,0] [42,1,1] [42,2,2]
+    [42,3,3] [42,4,4] [42,5,5]
+
+
+* Transform two images with a binary function (alpha blending):
+
+.. code-block:: cpp
+
+    mln::image2d<uint8_t> input1 = ...; 
+    mln::image2d<uint8_t> input2 = ...; 
+    auto f = [](uint8_t x, uint8_t y) { return alpha * x + (1 - alpha) * y; };
+    auto g = mln::view::transform(input1, input2, f);