[Olena-patches] olena: olena-2.0-608-g8c22dda Add documentation about neighborhood and window iterators.

* doc/examples-outputs.mk, * doc/examples.mk, * doc/outputs.mk, * doc/programs-examples.mk: Regen. * doc/outputs/neighborhood_iterator.txt, * doc/outputs/window_iterator.txt, * doc/examples/neighborhood_iterator.cc, * doc/examples/window_iterator.cc: New. * doc/examples.dox: Add links to examples. * doc/mln/core/neighb.dox, * doc/mln/win/win.dox: Write documentation. --- milena/ChangeLog | 19 +++++++++ milena/doc/examples-outputs.mk | 36 +++++++++++++++++ milena/doc/examples.dox | 20 ++++++---- milena/doc/examples.mk | 4 +- milena/doc/examples/neighborhood_iterator.cc | 40 +++++++++++++++++++ milena/doc/examples/window_iterator.cc | 40 +++++++++++++++++++ milena/doc/mln/core/neighb.dox | 41 +++++++++++++++++-- milena/doc/mln/win/win.dox | 39 ++++++++++++++++-- milena/doc/outputs.mk | 4 +- ...instantiation.txt => neighborhood_iterator.txt} | 0 ...right-instantiation.txt => window_iterator.txt} | 0 milena/doc/programs-examples.mk | 4 ++ 12 files changed, 227 insertions(+), 20 deletions(-) create mode 100644 milena/doc/examples/neighborhood_iterator.cc create mode 100644 milena/doc/examples/window_iterator.cc copy milena/doc/outputs/{accu-right-instantiation.txt => neighborhood_iterator.txt} (100%) copy milena/doc/outputs/{accu-right-instantiation.txt => window_iterator.txt} (100%) diff --git a/milena/ChangeLog b/milena/ChangeLog index 4d2da20..d65543d 100644 --- a/milena/ChangeLog +++ b/milena/ChangeLog @@ -1,5 +1,24 @@ 2013-05-14 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; + Add documentation about neighborhood and window iterators. + + * doc/examples-outputs.mk, + * doc/examples.mk, + * doc/outputs.mk, + * doc/programs-examples.mk: Regen. + + * doc/outputs/neighborhood_iterator.txt, + * doc/outputs/window_iterator.txt, + * doc/examples/neighborhood_iterator.cc, + * doc/examples/window_iterator.cc: New. + + * doc/examples.dox: Add links to examples. + + * doc/mln/core/neighb.dox, + * doc/mln/win/win.dox: Write documentation. + +2013-05-14 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; + * doc/DoxygenLayout.xml: Update demo URL. 2013-05-13 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; diff --git a/milena/doc/examples-outputs.mk b/milena/doc/examples-outputs.mk index 10645fb..4dd9d91 100644 --- a/milena/doc/examples-outputs.mk +++ b/milena/doc/examples-outputs.mk @@ -613,6 +613,24 @@ $(srcdir)/outputs/mln_var.txt: $(srcdir)/examples/mln_var.stamp fi +$(srcdir)/examples/neighborhood_iterator.stamp: examples/neighborhood_iterator.cc + @rm -f $@.tmp + @touch $@.tmp + $(MAKE) $(AM_MAKEFLAGS) neighborhood_iterator$(EXEEXT) + ./neighborhood_iterator$(EXEEXT) >$(srcdir)/outputs/neighborhood_iterator.txt.tmp + mv $(srcdir)/outputs/neighborhood_iterator.txt.tmp $(srcdir)/outputs/neighborhood_iterator.txt + @mv -f $@.tmp $@ +EXTRA_DIST += $(srcdir)/examples/neighborhood_iterator.stamp +MAINTAINERCLEANFILES += $(srcdir)/examples/neighborhood_iterator.stamp + +$(srcdir)/outputs/neighborhood_iterator.txt: $(srcdir)/examples/neighborhood_iterator.stamp +## Recover from the removal of $@ + @if test -f $@; then :; else \ + rm -f $<; \ + $(MAKE) $(AM_MAKEFLAGS) $<; \ + fi + + $(srcdir)/examples/parray-append.stamp: examples/parray-append.cc @rm -f $@.tmp @touch $@.tmp @@ -971,3 +989,21 @@ $(srcdir)/outputs/win-create-2.txt: $(srcdir)/examples/win-create-2.stamp rm -f $<; \ $(MAKE) $(AM_MAKEFLAGS) $<; \ fi + + +$(srcdir)/examples/window_iterator.stamp: examples/window_iterator.cc + @rm -f $@.tmp + @touch $@.tmp + $(MAKE) $(AM_MAKEFLAGS) window_iterator$(EXEEXT) + ./window_iterator$(EXEEXT) >$(srcdir)/outputs/window_iterator.txt.tmp + mv $(srcdir)/outputs/window_iterator.txt.tmp $(srcdir)/outputs/window_iterator.txt + @mv -f $@.tmp $@ +EXTRA_DIST += $(srcdir)/examples/window_iterator.stamp +MAINTAINERCLEANFILES += $(srcdir)/examples/window_iterator.stamp + +$(srcdir)/outputs/window_iterator.txt: $(srcdir)/examples/window_iterator.stamp +## Recover from the removal of $@ + @if test -f $@; then :; else \ + rm -f $<; \ + $(MAKE) $(AM_MAKEFLAGS) $<; \ + fi diff --git a/milena/doc/examples.dox b/milena/doc/examples.dox index 3a10c8a..e81f600 100644 --- a/milena/doc/examples.dox +++ b/milena/doc/examples.dox @@ -1,20 +1,24 @@ /*! \page examples Examples -\section examplesneighb Neighborhoods - -\li \link demos/genericity/neighborhood/neighborhood.cc Common neighborhoods \endlink -\li \link demos/genericity/neighborhood/duality.cc Dual neighborhoods \endlink -\li \link demos/genericity/neighborhood/permissive.cc Custom neighborhoods \endlink +\section examplesgraph Graphs +\li \link demos/graph/region_adjacency_graph.cc Region Adjacency Graph \endlink \section examplesmorpher Image Morphers \li \link doc/examples/transformed_image.cc Image domain translation. \endlink \li \link doc/examples/extended_image.cc Image domain extension/shrinking. \endlink \li \link doc/examples/sub_image.cc Image domain restriction. \endlink -\section examplesgraph Graphs -\li \link demos/graph/region_adjacency_graph.cc Region Adjacency Graph \endlink - \section examplesinterpixel Inter-pixel Processings \li \link demos/inter_pixel/inter_pixel.cc Watershed \endlink +\section examplesneighb Neighborhoods + +\li \link doc/examples/neighborhood_iterator.cc Iteration w.r.t. a neighborhood \endlink +\li \link demos/genericity/neighborhood/neighborhood.cc Common neighborhoods \endlink +\li \link demos/genericity/neighborhood/duality.cc Dual neighborhoods \endlink +\li \link demos/genericity/neighborhood/permissive.cc Custom neighborhoods \endlink + +\section exampleswin Windows +\li \link doc/examples/window_iterator.cc Iteration w.r.t. a window \endlink + */ diff --git a/milena/doc/examples.mk b/milena/doc/examples.mk index 180b32c..52c48dc 100644 --- a/milena/doc/examples.mk +++ b/milena/doc/examples.mk @@ -35,6 +35,7 @@ EXAMPLES = \ $(srcdir)/examples/labeling-compute.cc \ $(srcdir)/examples/logical-not.cc \ $(srcdir)/examples/mln_var.cc \ + $(srcdir)/examples/neighborhood_iterator.cc \ $(srcdir)/examples/parray-append.cc \ $(srcdir)/examples/parray-bbox.cc \ $(srcdir)/examples/paste-call-1.cc \ @@ -85,4 +86,5 @@ EXAMPLES = \ $(srcdir)/examples/tuto4/site_set_create.cc \ $(srcdir)/examples/tuto4_genericity_and_algorithms.cc \ $(srcdir)/examples/win-create-1.cc \ - $(srcdir)/examples/win-create-2.cc + $(srcdir)/examples/win-create-2.cc \ + $(srcdir)/examples/window_iterator.cc diff --git a/milena/doc/examples/neighborhood_iterator.cc b/milena/doc/examples/neighborhood_iterator.cc new file mode 100644 index 0000000..6c865fa --- /dev/null +++ b/milena/doc/examples/neighborhood_iterator.cc @@ -0,0 +1,40 @@ +#include <mln/core/image/image2d.hh> +#include <mln/core/alias/neighb2d.hh> +#include <mln/debug/iota.hh> + +// Example specific header. +#include <doc/tools/sample_utils.hh> + + +int main() +{ + using namespace mln; + + //! [Input image] + typedef image2d<bool> I; + I ima(5,5); + debug::iota(ima, 100); + //! [Input image] + + { + //! [Iteration over a site] + point2d p(2,2); + mln_niter_(neighb2d) q(c4(), p); + for_all(q) + ; // Do something here. + //! [Iteration over a site] + } + + { + //! [Iteration over a domain] + mln_piter_(I) p(ima.domain()); + mln_niter_(neighb2d) q(c4(), p); + + for_all(p) + for_all(q) + ; // Do something here. + //! [Iteration over a domain] + } +} + + diff --git a/milena/doc/examples/window_iterator.cc b/milena/doc/examples/window_iterator.cc new file mode 100644 index 0000000..a709cc6 --- /dev/null +++ b/milena/doc/examples/window_iterator.cc @@ -0,0 +1,40 @@ +#include <mln/core/image/image2d.hh> +#include <mln/core/alias/window2d.hh> +#include <mln/debug/iota.hh> + +// Example specific header. +#include <doc/tools/sample_utils.hh> + + +int main() +{ + using namespace mln; + + //! [Input image] + typedef image2d<bool> I; + I ima(5,5); + debug::iota(ima, 100); + //! [Input image] + + { + //! [Iteration over a site] + point2d p(2,2); + mln_qiter_(window2d) q(win_c4p(), p); + for_all(q) + ; // Do something here. + //! [Iteration over a site] + } + + { + //! [Iteration over a domain] + mln_piter_(I) p(ima.domain()); + mln_qiter_(window2d) q(win_c4p(), p); + + for_all(p) + for_all(q) + ; // Do something here. + //! [Iteration over a domain] + } +} + + diff --git a/milena/doc/mln/core/neighb.dox b/milena/doc/mln/core/neighb.dox index 1156e3f..1748928 100644 --- a/milena/doc/mln/core/neighb.dox +++ b/milena/doc/mln/core/neighb.dox @@ -1,9 +1,40 @@ /*! \defgroup modneighb Neighborhoods - * - * \brief All the predefined generic neighborhoods. - * - * \ingroup modtypes - */ + + \brief All the predefined generic neighborhoods. + + In the following sections, the common interface of Milena + neighborhood types is detailed. Methods and routines detailed + hereinafter are considered as generic and work for any + neighborhoods. + + \section docitereltneighb Iterate over elements in a neighborhood + + A neighborhood is always centered on a site. Sites parts of + neighborhoods are computed relatively from the neighborhood central + site. + + A generic way of iterating over neighborhood elements is to use + mln_niter() macro to declare an iterator. + + \snippet neighborhood_iterator.cc Iteration over a site + + A neighborhood iterator is defined upon a neighborhood and its + centeral site. The central site may also be a site iterator. + + \snippet neighborhood_iterator.cc Iteration over a domain + + \c p is a site iterator over all the sites of the image \c ima. \c + q, being a neighborhood iterator centered on that iterator, is + automatically updated and centered to the current site pointed by \p + p. + + A full example is available in \link neighborhood_iterator.cc + neighborhood_iterator.cc \endlink + + \note In Milena, neighborhoods never include the central site. + + \ingroup modtypes +*/ /*! \defgroup modneighb1d 1D neighborhoods * diff --git a/milena/doc/mln/win/win.dox b/milena/doc/mln/win/win.dox index a7e9431..2ce3cb1 100644 --- a/milena/doc/mln/win/win.dox +++ b/milena/doc/mln/win/win.dox @@ -1,9 +1,38 @@ /*! \defgroup modwin Windows - * - * \brief All the predefined generic windows. - * - * \ingroup modtypes - */ + + \brief All the predefined generic windows. + + In the following sections, the common interface of Milena window + types is detailed. Methods and routines detailed hereinafter are + considered as generic and work for any window. + + \section docitereltwin Iterate over elements in a window + + A window is always centered on a site. Sites parts of windows are + computed relatively from the window central site. + + A generic way of iterating over window elements is to use + mln_qiter() macro to declare an iterator. + + \snippet window_iterator.cc Iteration over a site + + A window iterator is defined upon a window and its centeral + site. The central site may also be a site iterator. + + \snippet window_iterator.cc Iteration over a domain + + \c p is a site iterator over all the sites of the image \c ima. \c + q, being a window iterator centered on that iterator, is + automatically updated and centered to the current site pointed by \p + p. + + A full example is available in \link window_iterator.cc + window_iterator.cc \endlink + + \note In Milena, windows may include the central site. + + \ingroup modtypes +*/ /*! \defgroup modwin1d 1D windows * diff --git a/milena/doc/outputs.mk b/milena/doc/outputs.mk index 0ff7b94..346db79 100644 --- a/milena/doc/outputs.mk +++ b/milena/doc/outputs.mk @@ -35,6 +35,7 @@ OUTPUTS = \ $(srcdir)/outputs/labeling-compute.txt \ $(srcdir)/outputs/logical-not.txt \ $(srcdir)/outputs/mln_var.txt \ + $(srcdir)/outputs/neighborhood_iterator.txt \ $(srcdir)/outputs/parray-append.txt \ $(srcdir)/outputs/parray-bbox.txt \ $(srcdir)/outputs/paste-call-1.txt \ @@ -54,4 +55,5 @@ OUTPUTS = \ $(srcdir)/outputs/tuto4_point2d.txt \ $(srcdir)/outputs/tuto4_site_set_create.txt \ $(srcdir)/outputs/win-create-1.txt \ - $(srcdir)/outputs/win-create-2.txt + $(srcdir)/outputs/win-create-2.txt \ + $(srcdir)/outputs/window_iterator.txt diff --git a/milena/doc/outputs/accu-right-instantiation.txt b/milena/doc/outputs/neighborhood_iterator.txt similarity index 100% copy from milena/doc/outputs/accu-right-instantiation.txt copy to milena/doc/outputs/neighborhood_iterator.txt diff --git a/milena/doc/outputs/accu-right-instantiation.txt b/milena/doc/outputs/window_iterator.txt similarity index 100% copy from milena/doc/outputs/accu-right-instantiation.txt copy to milena/doc/outputs/window_iterator.txt diff --git a/milena/doc/programs-examples.mk b/milena/doc/programs-examples.mk index 5cc70df..9fe1c47 100644 --- a/milena/doc/programs-examples.mk +++ b/milena/doc/programs-examples.mk @@ -60,6 +60,7 @@ PROGRAMS_examples = \ labeling-compute \ logical-not \ mln_var \ + neighborhood_iterator \ parray-append \ parray-bbox \ paste \ @@ -68,6 +69,7 @@ PROGRAMS_examples = \ predicate-1 \ sub_image \ transformed_image \ + window_iterator \ win-create-1 \ win-create-2 @@ -127,6 +129,7 @@ ima_size_SOURCES = examples/ima-size.cc labeling_compute_SOURCES = examples/labeling-compute.cc logical_not_SOURCES = examples/logical-not.cc mln_var_SOURCES = examples/mln_var.cc +neighborhood_iterator_SOURCES = examples/neighborhood_iterator.cc parray_append_SOURCES = examples/parray-append.cc parray_bbox_SOURCES = examples/parray-bbox.cc paste_SOURCES = examples/paste.cc @@ -135,6 +138,7 @@ point_1_SOURCES = examples/point-1.cc predicate_1_SOURCES = examples/predicate-1.cc sub_image_SOURCES = examples/sub_image.cc transformed_image_SOURCES = examples/transformed_image.cc +window_iterator_SOURCES = examples/window_iterator.cc win_create_1_SOURCES = examples/win-create-1.cc win_create_2_SOURCES = examples/win-create-2.cc -- 1.7.2.5