[Olena-patches] cleanup-2008 b62ba4d: First draft of the tutorial

URL: https://svn.lrde.epita.fr/svn/oln Git branch: cleanup (HEAD: 557f721) ChangeLog: 2008-09-08 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; First draft of the tutorial. * milena/doc/tutorial/tutorial.tex: New. --- ChangeLog | 5 + milena/doc/tutorial/tutorial.tex | 578 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 583 insertions(+), 0 deletions(-) diff --git a/ChangeLog b/ChangeLog index fb00fa6..c2d0668 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-09-08 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; + + First draft of the tutorial. + * milena/doc/tutorial/tutorial.tex: New. + 2008-05-05 Roland Levillain &lt;roland(a)lrde.epita.fr&gt; Update the list of Makefiles to be configured. diff --git a/milena/doc/tutorial/tutorial.tex b/milena/doc/tutorial/tutorial.tex new file mode 100644 index 0000000..1df6993 --- /dev/null +++ b/milena/doc/tutorial/tutorial.tex @@ -0,0 +1,578 @@ +\documentclass{report} +\usepackage{graphicx} +\usepackage{listings} +\usepackage{makeidx} +\usepackage{xcolor} + +\newcommand{\img}[4]{ +\begin{figure}[ht!] + \begin{center} + \includegraphics[width=#2]{figures/#1} + \caption{#4\label{fig:#1}} + \end{center} + \end{figure} +} + +\title{Olena - Tutorial +} +\author{LRDE} +\date{} + +%%%LISTINGS SETTINGS +\lstset{frameround=fttt} +\lstloadlanguages{[ISO]C++} +\lstset{backgroundcolor=\color{yellow}} + + +\begin{document} + +\tableofcontents + +ajouter dans => milena/doc/tutorial | +------------------------------------------------- + +\chapter{Foreword} + +The following tutorial talks about 2D images. We chose that kind of images +because it is easier to understand and this is the +most used. \\ + +FIXME +[dessin de grille 2d, colonnes/lignes numerotees + repere x/y] +Intersection <=> point 2d <=> milieu d'un pixel \\ + +Since examples are based on 2D images pixels are actually "points" however we +will call them "sites" which is the most generic name.\\ + +Here is also a list of common variable name conventions: +\begin{figure}[ht!] + \begin{tabular}{|l|l|} + \hline + \textbf{Object} & \textbf{Variable name} \\ \hline + Site & p \\ \hline + Value & v \\ \hline + Neighboor & n \\ \hline + A site close to another site p & q \\ \hline + \end{tabular} +\end{figure} + +Methods provided by the objects in the library are in constant time. If you need +a specific method but you cannot find it, you may find an algorithm which can +compute the information you need. + +\chapter{Concepts} +//FIXME lister \underline{TOUS} les concepts (core/concepts) + +\section{Site set} + +Site sets are used: +\begin{enumerate} + \item To define an image definition domain. + \item As Site container. +\end{enumerate} + +Here is a list of all the site set concepts which can be found in +core/site\_set: + +\begin{tabular}{|l|p{8cm}|} +\hline +Site set & Description \\ \hline + +p\_complex\_piter & \\ \hline +p\_graph\_piter & \\ \hline +p\_key & \\ \hline +p\_priority & \\ \hline +p\_run\_piter & \\ \hline +box & \\ \hline +p\_bgraph & \\ \hline +p\_double & \\ \hline +p\_if & \\ \hline +p\_line\_graph & \\ \hline +p\_queue\_fast & \\ \hline +p\_set & \\ \hline +box\_piter & \\ \hline +p\_bgraph\_piter & \\ \hline +p\_faces & \\ \hline +p\_if\_piter & \\ \hline +p\_line\_graph\_piter & \\ \hline +p\_queue & \\ \hline +p\_set\_of & \\ \hline +line2d & \\ \hline +p\_complex & \\ \hline +p\_graph & \\ \hline +p\_image & \\ \hline +p\_mutable\_array\_of & \\ \hline +p\_run & \\ \hline +p\_vaccess & \\ \hline +\end{tabular} + +\subsection{Basic interface} +Common basic interface:\\ + +\begin{tabular}{|l|l|l|l|p{4cm}|} +\hline +Return Type & Name & Arguments & Const & Commor type automatically from the +given container type +passed as parameter. These macros can be used with any container like images or +site sets.ents \\ \hline + +bool & is\_valid & - & X & Returns true if it has been initialized. The +default constructor does not do it. \\ \hline + +bool & has & const P\& p & X & See \ref{fig:box_has} \\ \hline +\end{tabular} \\ + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + box2d<int> b(2,3); + + std::cout << b.has(point2d(4, 5)) << std::endl; // false + std::cout << b.has(point2d(1, 0)) << std::endl; // true + \end{lstlisting} + \caption{How to use has()\label{fig:box_has}} +\end{figure} + + +\subsection{Optional interface} +Site sets may have other methods depending on their type: \\ + +\begin{tabular}{|l|l|l|l|p{4cm}|} +\hline +Return Type & Name & Arguments & Const & Comments \\ \hline + +size\_t & nsites & - & - & \\ \hline +const Box\& & bbox & - & X & Bounding box. Available only on grid site sets. +\\ \hline +\end{tabular} \\ + +The previous methods are available depending on the site set. A box +will have the bbox() method since it can be retrived in constant time: a box +is it's own bounding box (see \ref{fig:box_bbox}). A p\_array does not have this +method since sites do not have to be adjacent. Maintaining such information, in +order to keep getting the bbox in constant time, would be time and memory +consuming. Instead of providing a method directly in p\_array, an algorithm is +available if this information needed (see \ref{fig:parray_bbox}). +P\_array and box both have a nsites method since the internal structure allow a +constant time retrieval. + +\subsubsection*{Sample code} + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + p_array<point2d> arr; + + // The bbox is computed thanks to bbox() algorithm. + box2d<int> box = geom::bbox(arr); + std::cout << box << std::endl; + + // p_array provides nsites(), + // it can be retrieved in constant time. + std::cout << "nsites = " << arr.nsites() << std::endl; + \end{lstlisting} + \caption{How to retrieve information from a p\_array.\label{fig:parray_bbox}} +\end{figure} + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + box2d<int> b(2,3); + + // The bbox can be retrived in constant time. + std::cout << b.bbox() << std::endl; + + // nsites can be retrieved in constant time. + std::cout << "nsites = " << b.nsites() << std::endl; + \end{lstlisting} + \caption{How to retrieve information from a box.\label{fig:box_bbox}} +\end{figure} + +\clearpage +\newpage +\section{Image} + +An image is composed both of: +\begin{itemize} +\item A function $$ +f : \left\{ + \begin{array}{lll} + Site &\rightarrow & Value \\ + p & \mapsto & v + \end{array} +\right. +$$ +\item A site set, also called the "domain". +\end{itemize} + +Every image type is defined on a specific site type. An image2d will always +have a domain defined by a box2d. +The Value set, which includes all the possible values a site can have, is also +called "destination" set. + +//FIXME: remove this line +ici, site <=> Point2d + +//FIXME : un tuto existe deja +[sample code] +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + box2d b(2,3); + image2d<int> ima(b); // Define the domain of the image. + + cout << b << std::endl; // Display b + + cout << ima.domain() << std::endl; // Display b too + \end{lstlisting} + \caption{Equivalence between domain and bounding box.\label{fig:img_bbox}} +\end{figure} + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + box2d b(2,3); + image2d<int> ima(b); + point2d p(1, 2); + + ima.at(1,2) = 9; // The value is returned by reference + // and can be changed. + cout << ima(p) << std::endl; // prints 9 + + ima(p) = 2; // The value is returned by reference + // and can be changed. + cout << ima(p) << std::endl; // prints 2 + \end{lstlisting} + \caption{How to update a site value.\label{fig:img_sitevalue}} +\end{figure} + + +\subsection{Interface} + +\begin{tabular}{|l|l|l|l|p{4cm}|} +\hline +Return Type & Name & Arguments & Const & Comments \\ \hline + +site\_set & domain & - & X - & \\ \hline +const Value\& & operator() & const point\& p & X & Used for reading. \\ \hline +Value\& & operator() & const point\& p & - & Used for writing. \\ \hline +const P\& & at & unsigned x, + unsigned y & X & Used for reading. \\ \hline +P\& & at & unsigned x, + unsigned y & - & Used for writing. \\ \hline +bool & has & const Point\& p & X & \\ \hline +bool & has\_data & - & X & Returns true if the domain is defined. \\ \hline +site\_id & id & - & X & Return the Id of the underlying shared data. \\ \hline +FIXME & destination & - & X & Value set of all the possible site values in this +Image. \\ \hline + +\end{tabular} + +Images do not actually store the data in the class. This is a pointer +to an allocated space which can be shared with other objects. Once an image is +assigned to another one, the two images share the same data so they have the +same ID and point to the same memory space. +If a deep copy of the image is needed, a method clone() is available. +Example in figure \ref{fig:img_sitevalue} illustrates this behavior. + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + image2d<int> ima1(box2d(2, 3)); + image2d<int> ima2; + image2d<int> ima3; + point2d p(1,2); + + ima2 = ima1; // ima1.id() == ima2.id() + // and both point to the same memory area. + + ima2(p) = 2; // ima1 is modified as well. + + // prints "2 - 2" + std::cout << ima2(p) << " - " << ima1(p) << std::endl; + // prints "true" + std::cout << (ima2.id() == ima1.id()) << std::endl; + + ima3 = ima1.clone(); // Makes a deep copy. + + ima3(p) = 3; + + // prints "3 - 2" + std::cout << ima3(p) << " - " << ima1(p) << std::endl; + // prints "false" + std::cout << (ima3.id() == ima1.id()) << std::endl; + \end{lstlisting} + \caption{Data sharing with Images.\label{fig:img_sitevalue}} +\end{figure} + +[Illustration : grille + intersection + pmin() + pmax() + distance entre 2 +points en x et en y = 1]\\ + +\newpage +\section{Neighborhood} + + + +\newpage +\section{Window} + + + +\newpage +\section{Accumulator} +\section{Box} +\section{Browsing} +\section{Delta point site} +\section{Dpoint} +\section{Function} +\section{Gdpoint} +\section{Generalized pixel} +\section{Gpoint} + +\section{Iterator} +\section{Literal} +\section{Mesh} +\section{Meta accumulator} +\section{Object} +\section{Pixel iterator} +\section{Point} +\section{Point site} +\section{Proxy} +\section{Pseudo site} +\section{Regular grid} +\section{Site} +\section{Site iterator} +\section{Site proxy} +\section{Value} +\section{Value iterator} +\section{Value set} +\section{Weighted window} + +\chapter{Iterators} + +Every objects +Each container object in Olena like site sets or images have iterators. +There are usually three kinds: +\begin{itemize} +\item \textbf{fwd\_iter}, depends on the container, +\item \textbf{bkd\_iter}, iterates like forward but to the opposite way, +\item \textbf{iter}, usually the same as fwd\_iter. It is guaranteed to +iterate all over the elements. +\end{itemize} + +The iterator type name depends on the data pointed by it: \\ + +\begin{tabular}{|l|l|l|l|p{4cm}|} +\hline +Data type & Iterator Names \\ \hline +Site & fwd\_piter, bkd\_piter, piter \\ \hline +Value & fwd\_viter, bkd\_viter, viter \\ \hline +\end{tabular} \\ + +As you may have noticed, according to the data type, the word "iter" is prefixed +by the usual name variable used for that data type. Sites variables are usually +called 'p' so the proper iterator is "piter".\\ + + +An iterator has the following interface: \\ + +\begin{tabular}{|l|l|l|l|p{4cm}|} +\hline +Return Type & Name & Arguments & Const & Comments \\ \hline + +void & start & - & - & \\ \hline +void & next & - & - & \\ \hline +bool & is\_valid & - & - & Return false if created with the default +constructor and not associated to a proper container.\\ \hline +\end{tabular} \\ + + +Example of different forward iterations: +\begin{itemize} + \item box2d: from top to bottom then from left to right. + \item p\_array<point2d>: from left to right. +\end{itemize} + +A for\_all() macro is available to iterate over all the sites +(Fig. \ref{fig:for_all}). \\ + + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + box2d b(3, 2); + mln_piter(box2d) p(b); + + for_all(p) + std::cout << p; //prints every site coordinates. + \end{lstlisting} + \caption{Use of the for\_all() macro.\label{fig:for_all}} +\end{figure} + +Note that when you declare an iterator, prefer using the "mln\_*iter" macros. +They resolve the iterator type automatically from the given container type +passed as parameter. These macros can be used with any container like images or +site sets. +(\ref{fig:iter_allcontainers}). + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] + image2d<int> ima(box2d<int>(2, 3)); + + mln_piter(box2d<int>) p(ima.domain()); + for_all(p) + std::cout << p << std::endl; + + mln_viter(image2d<int>) v(ima.destination()); + for_all(v) + std::cout << v << std::endl; + \end{lstlisting} + \caption{mln\_*iter macros can be used with any +containers.\label{fig:iter_allcontainers}} +\end{figure} + + +\chapter{Basic operations} +//FIXME : illustrer +\begin{itemize} + \item level::clone(), creates a deep copy of an object. Any shared data is +duplicated. + \item level::fill(), fill an object with a value (fig. \ref{fig:fill_impl}). + \item level::paste(), paste object data to another object (fig. +\ref{fig:paste_impl}) + + \item labeling::blobs(), find and label the different components of an image. +\end{itemize} + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] +template <typename I> +void fill(I& ima, mln_value(I) v) +{ + mln_piter(I) p(ima.domain()); + for_all(p) + ima(p) = v; +} + \end{lstlisting} + \caption{Implementation of the fill routine.\label{fig:fill_impl}} +\end{figure} + + +\begin{figure}[ht!] + \begin{lstlisting}[frame=single] +template <typename I, typename J> +void paste(const I& data, J& dest) +{ + mln_piter(I) p(data.domain()); + for_all(p) + dest(p) = data(p); +} + \end{lstlisting} + \caption{Implementation of the paste routine.\label{fig:paste_impl}} +\end{figure} + + +\section{Work with parts of an image} + +Sometime it may be interesting to work only on some part of the image or to +extract only a sub set of that image. Olena enables that thoughout out the +operator '|'. + +Three kinds of that operator exist:\\ + +\begin{tabular}{|l|l|l|l|p{4cm}|} +\hline +Prototype & Comments \\ \hline + +Image $|$ Sub Domain & Create a new image.\\ \hline +Image $|$ Function\_p2b & Do not create a new image but create a morpher.\\ +\hline +Function\_p2v $|$ Sub Domain & Do not create a new image but create a morpher.\\ +\hline +\end{tabular} \\ + +A Sub Domain can be a site set, an image or any value returned by this +operator. +Function\_p2v is a function which returns a Value from a given +Site and Function\_p2b returns a boolean from a given point. These functions. + are actually a sort of predicate. You can easily get of function of +function\_p2v kind thanks to pw::value(Image). It returns the point to value +function used in the given image. C functions can also be used as predicate by +passing the function pointer. + +You can easily get a function\_p2b by comparing the value returned +by a function\_p2v to another Value. +The following sample code illustrates this feature. + +All along the examples, the image "ima" will refer to the following declaration: +\begin{lstlisting}[frame=single] + bool vals[6][5] = { + {0, 1, 1, 0, 0}, + {0, 1, 1, 0, 0}, + {0, 0, 0, 0, 0}, + {1, 1, 0, 1, 0}, + {1, 0, 1, 1, 1}, + {1, 0, 0, 0, 0} + }; + image2d<bool> ima = make::image2d(vals); +\end{lstlisting} + +A simple example is to fill only a part of an image with a specific value: +\begin{lstlisting}[frame=single] +p_array2d<bool> arr; + +// We add two points in the array. +arr.append(point2d(0, 1)); +arr.append(point2d(4, 0)); + +// We restrict the image to the sites +// contained in arr and fill these ones +// with 0. +// We must call "inplace" here. +fill(inplace(ima | arr), 0); + + +mln_VAR(ima2, ima | arr); +// We do not need to call "inplace" here. +fill(ima2, 0); +\end{lstlisting} + +NOTE: due to C++ issues, "in place" routines, such as fill and paste, which +modify the image passed as argument, cannot be called directly with temporary +objects. This means that either the routines are called with an image which is a +local variable or the image is passed to "inplace()". That routine is a work +around that \textbf{MUST} be used otherwise the code will not compile. The last +example show two most common use cases.\\ + +The two next examples extract a specific component from an image and fill a new +image with red only in the extracted component's domain. +\begin{lstlisting}[frame=single] + using namespace mln; + using value::int_u8; + using value::rgb8; + + // Find and label the different components. + int_u8 nlabels; + image2d<int_u8> lab = labeling::blobs(ima, c4(), nlabels); + + // Store a boolean image. True if the site is part of + // component 2, false otherwise. + mln_VAR(lab_2b, lab | (pw::value(lab) == 2)); + + // Get the sub site set containing only the sites + // part of component 2. + mln_VAR(lab_2, lab_2b.domain(1)); + + // Fill the sites of component 2 with red. + fill(lab_2, color::red); +\end{lstlisting} + +This last example can be written more quickly: +\begin{lstlisting}[frame=single] + using namespace mln; + using value::int_u8; + using value::rgb8; + + // Find and label the different components. + int_u8 nlabels; + image2d<int_u8> lab = labeling::blobs(ima, c4(), nlabels); + + // Fill the sites of component 2 with red. + fill(inplace(lab.domain(2)), color::red); +\end{lstlisting} + + +\end{document} \ No newline at end of file