Commit 18cb167c authored by Edwin Carlinet's avatar Edwin Carlinet
Browse files

Start documentation of views.

parent dc9af6aa
Pipeline #12808 failed with stages
in 9 minutes and 12 seconds
......@@ -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:
......
=====
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
--------
......
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);
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment