Commit d6b7aa89 authored by Edwin Carlinet's avatar Edwin Carlinet
Browse files

Work on documentation.

parent 9f0ed7ed
Pipeline #12920 failed with stages
in 7 minutes and 10 seconds
......@@ -18,6 +18,10 @@
color: black;
}
.full {
width: 100%
}
/* .rst-content dl:not(.docutils) dt:last-child { */
/* margin-bottom: 6px; */
/* } */
......
......@@ -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
......
======
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.
--------
......
.. _neighborhood
Neighborhood, Sliding Windows and Structuring Elements
######################################################
......
This diff is collapsed.
\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
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