\endhtmlonly

\page quickref Quick Reference Guide - \subpage installation - \subpage foreword - \subpage site - \subpage siteset - \subpage image - \subpage winneigh - \subpage sitesandco - \subpage iterators - \subpage imamemmgmt - \subpage basicops - \subpage inputoutput - \subpage graphandima - \subpage globalvars - \subpage macros - \subpage compilerrors \htmlonly

\endhtmlonly*/ /*! \page installation Installation\htmlonly




\endhtmlonly\section requirements Requirements\htmlonly

\endhtmlonly\subsection compexample To compile the user examples\htmlonly

\endhtmlonly\subsection compdoc To compile the documentation (Optional)\htmlonly

\endhtmlonly\subsection devolena To develop in Olena\htmlonly




\endhtmlonly\section getolena Getting Olena\htmlonly

The latest version of Olena is available at the following addresses:




\endhtmlonly\section buildingolena Building Olena\htmlonly

First uncompress the archive. According to the downloaded archive, the options are different.

$ tar zxvf olena.tar.gz

Or

$ tar jxvf olena.tar.bz2

Then follow these steps:

$ mkdir olena-build
$ cd olena-build
$ ../olena-1.0/configure && make
$ sudo make install

\endhtmlonly*/ /*! \page foreword Foreword\htmlonly




\endhtmlonly\section generality Generality\htmlonly The following tutorial explains the basic concepts behind Olena and how to use the most common objects and routines. This tutorial includes many code examples and figures. In order to make this tutorial easier to understand, we will mainly talk about 2D images. This is not so restrictive since 1D, 3D, nD images behave the same way.

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:


ObjectVariable name
Sitep
Valuev
Neighboorn
A site close to another site pq

Olena is organized in a namespace hierarchy. Everything is declared by Olena within the ’mln::’ namespace, and possibly a sub-namespace such as ’mln::arith::’ (arithmetic operations on images), ’mln::morpho::’ (morphological operations), etc. Usually, the namespace hierarchy is mapped to the mln directory tree. For the sake of simplicity, we will neglect the ’mln::’ prefix in all the code examples.

Methods provided by 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.




\endhtmlonly\section dirtree Directory hierarchy\htmlonly Olena’s tarball is structured as follow:




\endhtmlonly\section compilehint Writing and compiling a program with Olena\htmlonly

Before writing your first program, please be aware of these hints:

\endhtmlonly*/ /*! \page site Site\htmlonly

Usually, when talking about images, we think about common images composed of a set of pixels. Since Olena is generic, we want to support many kind of images, even images which are not composed of a set of points, such as images having images as sites.

In order to express this genericity, we have the “site” concept. This concept allows us to divide a pixel into two information:

Let’s say we have a 2D grid like this:

On such a regular grid, in 2D, we usually use a 2D point as a site which means we have the following equivalence:

Intersection ≡ point2d (2D site) ≡ center of a pixel

The site does not store any value but refers to an area where we will be able to read its value.

Sites may have a different types, depending on the image type:

NameDescription
point2d2D point on a regular grid
pointGeneric point (nD) on a regular grid
algebra::vecAlgebraic vector
util::vertexGraph vertex
util::edgeGraph edge

\endhtmlonly*/ /*! \page siteset Site set\htmlonly

Site sets are used:

  1. To define an image definition domain.
  2. As Site container.

They do not actually store any image value. They only store site information.

Here is a list of all the site set concepts which can be found in core/site_set:

Site setDescription
p_arraysite array.
p_box compact domain defined on a regular grid (in 2D, a rectangle).
p_if site set verifying a predicate.
p_queuesite queue.
p_run site range.
p_runs site range set.
p_set mathematical site set.
p_vaccesssite set ordered by value.
p_edgesset of graph edges associated to sites.
p_verticesset of graph vertices associated to sites.

All site sets are iterable. More detailed explanations are available in section \endhtmlonly\ref iterators\htmlonly .




\endhtmlonly\section sitesetinterface Basic interface\htmlonly Common basic interface:

Return TypeNameArgumentsConstComments
boolis_valid-XReturns true if it has been initialized. The default constructor does not initialize it.
boolhasconst P& pX 





\endhtmlonly\section sitesetopinterface Optional interface\htmlonly Site sets may have other methods depending on their type:

Return TypeNameArgumentsConstComments
size_tnsites--Return the number of sites.
const Box&bbox-XBounding box. Available only on grid site sets.


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.

\endhtmlonly\include box2d-bbox-1.cc.raw\htmlonly Output: \endhtmlonly\include box2d-bbox.txt\htmlonly

A p_array does not have the bbox method since its 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 is needed. p_array and box both have a nsites method since the internal structure allows a constant time retrieval.

\endhtmlonly\include parray-bbox-1.cc.raw\htmlonly Output: \endhtmlonly\include parray-bbox.txt\htmlonly

\endhtmlonly*/ /*! \page image Image\htmlonly




\endhtmlonly\section definition Definition\htmlonly An image is composed both of:




\endhtmlonly\section imatypes Possible image types\htmlonly

Here is a short list of the main/usual image types you may want to use with Olena:


NameDescription
image1d1D image
image2d2D image
image3d3D image
flat_imageConstant value image
image_ifImage defined by a function




\endhtmlonly\section imapossvalues Possible value types\htmlonly

Every image type must take its type of value as parameter. The value type can be one of the builtins one:

Other data types are also available:

Value typeunderlying data type
float01_8unsigned long
float01_16unsigned long
float01_ffloat
gl8unsigned char
gl16unsigned short
glffloat
hsi_ddouble
hsi_ffloat
int_s8char
int_s16short
int_s32int
int_u8unsigned char
int_u16unsigned short
int_u32unsigned int
rgb16mln::algebra::vec<unsigned short>
rgb8mln::algebra::vec<unsigned char>


All these types are available in mln/value and accessible in the mln::value namespace. Most of the time, the name of the header which must be included to use one of these data types is actually “type_name.hh". For instance, for rgb8 the header will be rgb8.hh.




\endhtmlonly\section imadomain Domain\htmlonly The site set contains the sites which compose the image. Sites are based on a grid so the image depends on that grid as well. It means that a 2D images can only be defined by sites based on a 2D grid. Likewise, an image2d will always have its bouding box defined by a box2d.

Being defined on a grid means that the image can be defined anywhere. For instance, defining a 2D image with a box2d starting from point (-20, -20) to (-3, 5) is completely valid.

The following example shows that the definition domain and the site set are exactly equivalent.

\endhtmlonly\include ima2d-1-1.cc.raw\htmlonly Output: \endhtmlonly\include ima2d-1.txt\htmlonly

To know if a site belongs to an image domain or not, a method “has()” is available. \endhtmlonly\include point-1-1.cc.raw\htmlonly Output: \endhtmlonly\include point-1.txt\htmlonly

Since the notion of site is independent from the image it applies on, we can form expressions where a site passed to several images: \endhtmlonly\include ima2d-4-1.cc.raw\htmlonly Output: \endhtmlonly\include ima2d-4.txt\htmlonly




\endhtmlonly\section imaborder Border and extension\htmlonly Olena provides extension mechanisms for the image domain. In the library, both the concept of border and of extension can be encountered. These concepts are useful in many algorithms and can avoid costly tests while working with sites located on image edges.

\endhtmlonly\subsection imabordersection Image border\htmlonly

A border is a finite extension provided to a basic image type, such as image2d. By default, every image is created with a border. The default width is defined through the global variable border::thickness defined in mln/border/thickness.hh. Since this is a variable, it can be changed as shown in the following example.

\endhtmlonly\include borderthickness-1.cc.raw\htmlonly

Output:

\endhtmlonly\include borderthickness.txt\htmlonly

It is important to note that to display the border in the ouput, we use a special debug function, debug::println_with_border. Indeed, the border and the extension are considered as part of an image only in the algorithms. They are ignored while saving or printing an image.

Some operations can be performed on the border. The functions are located in mln/border.


RoutineDescription
adjustIncrease the border thickness if it is inferior to a minimum.
duplicateAssign the border with the duplicate of the edges of this image.
equalizeEqualize the border of two images so that their size is equal and is at least a minimum size.
fillFill the border with a given value.
findFind the border thickness of an image.
getGet the border thickness of an image.
mirrorFills border using nearer pixels with a mirroring effect.
resizeSet image border to a specific size.


\endhtmlonly\subsection imextgeneral Generality on image extension\htmlonly

On morphed images, described in section \endhtmlonly\ref imamorphed\htmlonly , the border concept does not exist and is generalized to the extension concept. A simple example of a morphed image is a sub-image. A sub image does not have border nor extension by default. Thanks to mln/core/routine/extend.hh, an extension can be defined through a function. This means that the extension can be infinite. Another point is that an image can be used as extension. For instance, in the case of a sub-image, you may be interested in extending the sub-image with the image itself.

The extension supports the following operations. These functions are located in mln/extension.


RoutineDescription
adjustAdjust the extension given a structural element.
adjust_duplicateAdjust the size of the extension given a structural element and duplicate the image inner boundary.
adjust_fillAdjust the size of the extension given a structural element and fill it with a value.
duplicateDuplicate the values of the image inner boundary in the extension.
fillFill the extension with a given value.


In order to extend an image, a routine extend is available in mln/core/routine/extend.hh. The routine extended_to may also help during debug. It allows to extend the image domain to a larger one. The values associated to the new sites comes from the extension.

\endhtmlonly\subsection extexample Different extensions\htmlonly

Let’s say we have want to extract a sub domain from an image. In the following example, ima_roi holds several small rectangles from the original image. \endhtmlonly\include extend-2.cc.raw\htmlonly

\endhtmlonly\image html small-enlarged.png\htmlonly  →  \endhtmlonly\image html extend-1.png\htmlonly
lena ima_roi (black color means the sites are not included in the domain)

Then, we may extend this sub image with one of the three following extension type.

\endhtmlonly\subsubsection extval Extension with a value\htmlonly

Let’s extend with the value literal::blue. \endhtmlonly\include extend-3.cc.raw\htmlonly \endhtmlonly\image html extend-2.png\htmlonly

Note the use of the extended_to() routine. We used a larger bbox to extend the image domain. That is the reason why the image is surrounded by the extension value, blue.

\endhtmlonly\subsubsection extfun Extension with a function\htmlonly

Let’s use the following function: \endhtmlonly\include extend-1.cc.raw\htmlonly \endhtmlonly\include extend-4.cc.raw\htmlonly \endhtmlonly\image html extend-3.png\htmlonly

\endhtmlonly\subsubsection extima Extension with an image\htmlonly

Let’s extend with the original image, lena. \endhtmlonly\include extend-5.cc.raw\htmlonly

\endhtmlonly\image html extend-4.png\htmlonly \endhtmlonly\image html extend-5.png\htmlonly
ext_with_ima, the extended image.The actual data in the domain (light) with its extension (dark)

IMPORTANT NOTE

Many times, you may want to check if a site is part of the image before applying a treatment. All images provide a method “has(Site)” which can return this information. Be careful though, calling has() on the image returns “true” if the given site is part of the domain OR the the extension/border. All algorithms in Olena call that method which means that all the algorithms take in consideration the extension/border if it exists. The default border thickness is set to 3 as shown by the following example.

\endhtmlonly\include ima-has-1.cc.raw\htmlonly

Output:

\endhtmlonly\include ima-has.txt\htmlonly

Most of the time, this is the good behavior. For instance, if a rotation is applied to an image, sites which were not previously in the domain will be part of it. Thanks to the extension/border, these sites will be associated to the value of the extension/border.

In the following example, the extension is set to a constant color yellow. It means that whatever the new sites computed through the rotation, it will be part of the image and a value will be available. Site which were previously in the extension/border, will be associated to yellow in the output image.

\endhtmlonly\include ima2d-rot-1.cc.raw\htmlonly

Output:



\endhtmlonly\image html ima2d-rot-1.png\htmlonly \endhtmlonly\image html ima2d-rot-2.png\htmlonly
ima1 and its border before rotation (left) and ima2 and its border after rotation (right).



Sometimes taking the domain in consideration may not be the expected behavior. If you do not want to use the extension/border for a specific routine, simply restrict the image to its domain.

\endhtmlonly\include extension-ignore-1.cc.raw\htmlonly

Note that:

ima.domain().has()(ima | ima.domain()).has()




\endhtmlonly\section imainterface Interface\htmlonly

Return TypeNameArgumentsConstComments
I::pvsetdomain-X 
const Value&operator()const point& pXUsed for reading.
Value&operator()const point& p-Used for writing.
boolhasconst Point& pX 
boolhas_data-XReturns true if the domain is defined.
site_idid-XReturn the Id of the underlying shared data.
I::vsetdestination-XValue set of all the possible site values in this Image.
site_setbbox--Returns the bounding box of the domain.
site_setbbox_large--Returns the bouding box of the domain and the extended domain.




\endhtmlonly\section imaio Load and save images\htmlonly

Currently, Olena supports the following input image formats:

This support is provided through two headers for each type, save.hh and load.hh. They are located in mln/io/<image-format>/.

Once the right header is included, the image can be loaded:

\endhtmlonly\include ima-load-1.cc.raw\htmlonly

Note that each format is associated to specific image value types:

 
hline FormatValue type
PBMbool
PFMfloat, double, float01_*
PGMunsigned, long, int, int_u*, gl*
PNMSee PGM, PBM and PPM
PPMrgb*

\endhtmlonly\include ima-save-1.cc.raw\htmlonly




\endhtmlonly\section imacreate Create an image\htmlonly

Loading an image is not mandatory, an image can be created from scratch. There are two possibilites to do so:

\endhtmlonly\include ima2d-2-1.cc.raw\htmlonly

img1a has no data and its definition domain is still unset. We do not know yet the number of sites it contains. However, it is really useful to have such an "empty image" because it is a placeholder for the result of some processing, or another image. Trying to access the site value from an empty image leads to an error at run-time. img1b is defined on a domain but does not have data yet.
An image can also be created and initialized at the same time: \endhtmlonly\include labeling-compute-1.cc.raw\htmlonly It constructs the following image:

\endhtmlonly\image html labeling-compute-1.png\htmlonly

Sometimes, you may want to initialize an image from another one: \endhtmlonly\include ima2d-7-1.cc.raw\htmlonly img2b is declared without specifying a domain. Its border size is set to the default one, e.g 0. By using initialize(), img2b is initialized with the same domain and border/extension as img2a. The data is not copied though. Other routines like data::fill() can be called in order to do so (See also \endhtmlonly\ref fillop\htmlonly ).




\endhtmlonly\section imaaccessmodval Access and modify values\htmlonly

There are several ways to access/modify an image “ima”:

Most of the time, images can be modified and these two methods can be used both to read a value and modify it. Both methods are equivalent. \endhtmlonly\include ima2d-3-1.cc.raw\htmlonly Output: \endhtmlonly\include ima2d-3.txt\htmlonly

Usually, you will want to use the functional way, “ima(Site)”, more particularly while iterating over all the sites through an iterator. This use case will be detailed further in section \endhtmlonly\ref iterators\htmlonly .




\endhtmlonly\section imasize Image size\htmlonly Most typical image types owns special methods to retrieve the image size.

Image typeMethods
image1dlength()
image2dncols(), nrows()
image3dncols(), nrows(), nslis()

If you need a more generic way to get the size, you can use the routines provided in mln/geom in the following files:

\endhtmlonly\include ima-size-1.cc.raw\htmlonly Output: \endhtmlonly\include ima-size.txt\htmlonly

\endhtmlonly*/ /*! \page winneigh Structural elements: Window and neighborhood\htmlonly

In Olena, there are both the window and neighborhood concept. A window can be defined on any site around a central site which may also be included. A neighborhood is more restrictive and must not include the central site. Therefore these two concepts are really similar and are detailed together in this section.

By default, structural elements are centered. The central site is located at the origin of the grid: “literal::origin”. With image2d, the central site is (0,0). Centered structural elements must have an odd size.




\endhtmlonly\section sedef Define an element\htmlonly

\endhtmlonly\subsection winwin Window\htmlonly

Generic Predefined windows

NameDescriptionRepresentation
win_c4p4-connectivity 
win_c8p8-connectivity 



1D Predefined windows

NameDescriptionRepresentation
segment1d1D segment-



2D Predefined windows

NameDescriptionRepresentation
backdiag2dBack diagonal-
diag2d2D diagonal-
disk2d2D disk-
hline2d2D horizontal line-
octagon2d2D octogon-
rectangle2d2D rectangle-
vline2d2D vertical line-



3D Predefined windows

NameDescriptionRepresentation
cube3d3D Cube-
cuboid3dCuboid-

These predefined windows can be passed directly to a function. The headers are located in mln/core/alias/window*.hh.

\endhtmlonly\subsection neighborhood Neighborhood\htmlonly

Predefined neighborhood:

NameDescriptionRepresentation
c44-connectivity 
c88-connectivity 

These predefined neighborhood can be passed directly to a function. The headers are located in mln/core/alias/neigh*.hh.

Use case example: \endhtmlonly\include labeling-compute-2.cc.raw\htmlonly

\endhtmlonly\subsection customse Custom structural elements\htmlonly

Windows

There are several ways to define a new window. The first and the most common way is to declare a window variable and insert dpoints: \endhtmlonly\include win-create-1-1.cc.raw\htmlonly This code creates the following window where “X” is the central point from which the window is computed: \endhtmlonly\include win-create-1-display.txt\htmlonly

Another way to define the same window is to provide a bool array: \endhtmlonly\include win-create-2-1.cc.raw\htmlonly

Note that despite the different ways of defining these windows, “varwin” == “win2. The boolean array must always have an odd size. While creating a windows thanks to a bool array/matrix, the window’s center is the central site of the array/matrix.

\endhtmlonly\subsection convneighwin Conversion between Neighborhoods and Windows\htmlonly

Windows are not convertible to a Neighborhood. Neighborhood are convertible to a window though.

A neighborhood has a method “win()” which returns the definition window. Be ware that this window is not centered, thus does not include the central point.

\endhtmlonly*/ /*! \page sitesandco Sites, psites and dpoints\htmlonly




\endhtmlonly\section sitessite Need for site\htmlonly

As we have seen before, an image is usually defined on a grid. It has associated data and a site set which defines the domain of the image on that grid. Usually, we need to access a value by its coordinates. With default images it can be done easily, at no cost.

Example with an image2d: \endhtmlonly\include ima2d-display-1.txt\htmlonly

The site x is the point (0, 1). The image values are stored in a multi-dimensional array. The point coordinates can be used directly. The site (0, 1) is the point (0, 1) and the data is stored at row 0 and column 1.

Here we have:

I::site == I::psite == point2d

where, roughly, point2d = { row, column }.




\endhtmlonly\section sitespsite Need for psite\htmlonly

Sometimes, accessing a value in constant-time complexity, O(1), is not possible with a site object.

Let’s have a small example. Define a function returning a value for a given point: \endhtmlonly\include fun-p2v-1-1.cc.raw\htmlonly

So, for each point having (0, x) as coordinate, this function will return 8, otherwise it will be 9.

Then, define a p_array with few point2d: \endhtmlonly\include parray-append-1.cc.raw\htmlonly

Now, create a point-wise image from this function and this p_array: \endhtmlonly\include mln_var-1.cc.raw\htmlonly

ima is actually that image: \endhtmlonly\include ima2d-display-2.txt\htmlonly

However, in memory, since it is based on a p_array, sites are stored in a vector.

The site x is the point (3, 7) which corresponds to the cell 1 in the p_array. \endhtmlonly\include parray-display-1.txt\htmlonly

Obviously, we cannot check in constant time whether the site x, point2d here, is part of that image or not: knowing the point coordinates is not enough. That’s why we need a different mechanism in order to access this information: the psites.

Here we have:

I::site == point2d but I::psite == pseudo_site<point2d>

where, roughly, pseudo_site<point2d> = { i_in_p_array, p_array_ptr }.

Psites contains all the needed information to access the values in constant-time.




\endhtmlonly\section sitespsitensite From psite to site\htmlonly

In the last example there was an image of type I such as I::site != I::psite. In that case, an object of type I::psite is actually convertible towards an object of type I::site. Furthermore, a psite shall behave as if it was a site.

Design note: it seems impossible to offer through the interface of some psite what is expected from its corresponding site. For instance, when a site has a given feature, say a method "m", then this method has to appear in the psite interface. However, thanks to inheritance, we fetch an interface and an implementation that delegates to the site.

For instance, in the last example, I::psite has a method row() because I::site, point2d, provides such a method.

How it works: a psite inherits from internal::site_impl<site> which is specialized for every site type; for instance, internal::site_impl<point2d> owns the method “coord row() const” which is defined as “return exact(this)->to_site().row()”.




\endhtmlonly\section sitesdpoint Dpoint\htmlonly Dpoints are relative sites. They are usually used in window and neighborhood definitions. Since the central site is not constant, windows and neighborhoods must be recomputed and dpoints help in doing that.

\endhtmlonly\include dpoint-1-1.cc.raw\htmlonly Output: \endhtmlonly\include dpoint-1.txt\htmlonly

\endhtmlonly*/ /*! \page iterators Iterators\htmlonly

Each container object in Olena like site sets or images have iterators. The iteration mechanism for images is directly derived from the mechanism for site sets.

There are usually three kinds:

Every iterable object have these three kinds of iterator. There are all bidirectional containers. Whatever the iterator used, the basic iterator has the only property of browsing every site once.

The iterator type name depends on the data pointed by it:

Data typeIterator Names
Sitefwd_piter, bkd_piter, piter
Valuefwd_viter, bkd_viter, viter
Neighboorsfwd_niter, bkd_niter, niter


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 “typepiter”. (See the foreword)

An iterator has the following interface:

Return TypeNameArgumentsConstComments
voidstart-- 
voidnext-- 
boolis_valid--Return false if created with the default constructor and not associated to a proper container.


Example of different forward iterations:

A for_all() macro is available to iterate over all the sites:
\endhtmlonly\include forall-piter-1.cc.raw\htmlonly Output: \endhtmlonly\include forall-piter.txt\htmlonly

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.

Here follow an example with the implemantions of the most basic routines which use the for_all() loop: data::fill() and data::paste().

\endhtmlonly\include fill-1.cc.raw\htmlonly

\endhtmlonly\include paste-1.cc.raw\htmlonly

Important note: macros for iterators exist in two versions: “mln_*iter” and “mln_*iter_”. The difference is that the first version must be used in templated function whereas the second one must be used in non templated functions.

If you want a list of all the macros available in Olena, please refert to section \endhtmlonly\ref macros\htmlonly .

\endhtmlonly*/ /*! \page imamemmgmt Memory management\htmlonly

In the Olena library, all image types behave like image2d:

Exemple with image2d

Images do not actually store the data in the class. Images store 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. Therefore, assigning an image to another one is NOT a costly operation. The new variable behaves like some mathematical variable. Put differently it is just a name to designate an image: \endhtmlonly\include ima2d-5-1.cc.raw\htmlonly

If a deep copy of the image is needed, a duplicate() routine is available: \endhtmlonly\include ima2d-6-clone-1.cc.raw\htmlonly Output: \endhtmlonly\include ima2d-6-clone.txt\htmlonly

\endhtmlonly*/ /*! \page basicops Basic routines\htmlonly

Routine nameDescription
duplicate()creates a deep copy of an object. Any shared data is duplicated.
data::fill()fill an object with a value.
data::paste()paste object data to another object.
labeling::blobs()find and label the different components of an image.
logical::not_() logical::not_inplace()Point-wise "logical not"
*::compute()compute an accumulator on specific elements.





\endhtmlonly\section fillop Fill\htmlonly First, create an image: \endhtmlonly\include fill-call-1-1.cc.raw\htmlonly

Memory has been allocated so data can be stored but site values have not been initialized yet. So we fill imga with the value ’a’:

\endhtmlonly\include fill-call-1-2.cc.raw\htmlonly

The fill() algorithm is located in the sub-namespace "mln::data" since this algorithm deals with the site values.

The full name of this routine is mln::data::fill(). To access to a particular algorithm, the proper file shall be included. The file names of algorithms strictly map their C++ name; so mln::data::fill is defined in the file mln/data/fill.hh.

Note

Most algorithms in Olena are constructed following the classical scheme: "output algo(input)", where the input image is only read. However some few algorithms take an input image in order to modify it. To enforce this particular feature, the user shall explicitly state that the image is provided so that its data is modified "read/write". The algorithm call shall be data::fill(ima.rw(), val). When forgetting the rw() call, it does not compile.

\endhtmlonly\include fill-call-1-3.cc.raw\htmlonly




\endhtmlonly\section pasteop Paste\htmlonly We then define below a second image to play with. As you can see this image has data for the sites (5, 5) to (14, 14) (so it has 100 sites).

\endhtmlonly\include paste-call-1-1.cc.raw\htmlonly Output: \endhtmlonly\include paste-call-1.txt\htmlonly

Note

With this simple example we can see that images defined on different domains (or set of sites) can interoperate. The set of sites of an image is defined and can be accessed and printed. The following code:

\endhtmlonly\include domain-display-1.cc.raw\htmlonly

Gives: \endhtmlonly\include domain-display-1.cc.raw\htmlonly

The notion of site sets plays an important role in Olena. Many tests are performed at run-time to ensure that the program is correct.

For instance, the algorithm data::paste() tests that the set of sites of imgb (whose values are to be pasted) is a subset of the destination image.




\endhtmlonly\section blobs Blobs\htmlonly

labeling::blobs() is used to label an image. It returns a new image with the component id as value for each site. The background has 0 as id therefore the component ids start from 1.

Consider the following image: \endhtmlonly\include labeling-compute-1.cc.raw\htmlonly

Output:

\endhtmlonly\image html labeling-compute-1.png\htmlonly

Then label this image thanks to labeling::blobs(): \endhtmlonly\include labeling-compute-2.cc.raw\htmlonly

Output:

\endhtmlonly\image html labeling-compute-2.png\htmlonly

Note that this routine returns the number of components in its third parameter. This parameter must be of the same type as the returned image value.




\endhtmlonly\section logicalnot Logical not\htmlonly

Headermln/logical/not.hh
Full namespacemln::logical
Routine(s)not_(), not_inplace()



This small routine only works on binary images. It performs a point-wise "logical not" and therefore "negates" the image. There are two versions of that algorithm: a version which returns a new image and another which works in place. Example:

Make a binary image: \endhtmlonly\include logical-not-1.cc.raw\htmlonly

\endhtmlonly\image html logical-not-1.png\htmlonly

Return the result in a new image: \endhtmlonly\include logical-not-2.cc.raw\htmlonly

\endhtmlonly\image html logical-not-1.png\htmlonly \endhtmlonly\image html logical-not-2.png\htmlonly
ima (left) and imaneg (right) after having called logical::not_().

Or, work in place: \endhtmlonly\include logical-not-3.cc.raw\htmlonly Then, ima looks like:

\endhtmlonly\image html logical-not-3.png\htmlonly




\endhtmlonly\section compute Compute\htmlonly

There are several flavour of the compute routine, depending on what the kind of elements it computes.

labeling::compute()compute an accumulator for each component in a labeled image.
data::compute()compute an accumulator on the values of an image.

\endhtmlonly\subsection accu Accumulators\htmlonly An accumulator is a special object accumulating data while iterating all over the image values or sites. Hereby follows a list of accumulators available in Olena.

Accumulators on sites

NameDescription
bboxBounding boxes
count_adjacent_verticesCount adjacent vertices
countCount the number of sites
height 
volume 

Accumulators on values

NameDescription
histoHistogram
maxMax value
max_hMax value (Hexa)
meanMean value
median_altMedian
median_hMedian (Hexa)
minMin value
min_hMin value (Hexa)
min_maxMin and Max value
rank_bool 
rank 
rank_high_quant 
sumSum the values

Special accumulators

NameDescription
pairPair of accumulators
tuplen-uplets of accumulators

Each accumulator can be used in *::compute(). It exists two versions of each accumulator.

Note that when an accumulator is passed to *::compute(), it must be instanciated.You cannot write: \endhtmlonly\include accu-wrong-instantiation.cc.raw\htmlonly Instead, you must write: \endhtmlonly\include accu-right-instantiation-1.cc.raw\htmlonly

\endhtmlonly\subsection exlblcompute Example with labeling::compute()\htmlonly

In this example we will try to retrieve the bounding box of each component in an image.

Consider the following image: \endhtmlonly\include labeling-compute-1.cc.raw\htmlonly

Then label this image thanks to labeling::blobs(): \endhtmlonly\include labeling-compute-2.cc.raw\htmlonly Output: \endhtmlonly\image html labeling-compute-2.png\htmlonly

Then, use labeling::compute() with the bbox accumulator: \endhtmlonly\include labeling-compute-3.cc.raw\htmlonly

labeling::compute() holds an accumulator for each component, which means it returns an array of accumulator results. In this case, it returns an array of box2d.

Important note: since labeling::blobs() labels the component from 1 and set the background to 0, we will want to iterate from 1 to nlabels included. \endhtmlonly\include labeling-compute-4.cc.raw\htmlonly Output: \endhtmlonly\include labeling-compute.txt\htmlonly

0.0.1  Routines based on accumulators and *::compute()

In order to make the code cleaner, small routines are available for the most used accumulators.

Currently there are the following routines:

NameDescription
nsitesReturn the number of sites of an image or a site set.
meanReturn the mean of the values of an image.
min_maxReturn the min and max values of the values of an image.
sumReturn the sum of the values of an image.

These routines can be found in mln/geom and in mln/estim. For example, with geom::nsites() simply write: \endhtmlonly\include estim-sites-1.cc.raw\htmlonly




\endhtmlonly\section partima Working with parts of an image\htmlonly

Sometimes it may be interesting to work only on some parts of the image or to extract only a sub set of that image. Olena enables that through the operator ’|’.

Three kinds of that operator exist:

PrototypeComments
Image | Sub DomainCreate a new image.
Image | Function_p2bDo not create a new image but create a morpher.
Function_p2v | Sub DomainDo not create a new image but create a morpher.


A Sub Domain can be a site set, an image or any value returned by this operator. For a given site, Function_p2v returns a value and Function_p2b returns a boolean. These functions are actually a sort of predicate. A common Function_p2v is 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 codes illustrate this feature.

In order to use C functions as predicate, they must have one of the following prototype if you work on 2D images: \endhtmlonly\include predicate-1-1.cc.raw\htmlonly Of course, you just need to change the point type if you use another image type. For instance, you would use point3d with 3D images. The returned value type V for Function_p2v depends on the image value type. With image2d<int>, V would be int.

In this section, all along the examples, the image ima will refer to the following declaration: \endhtmlonly\include fill-part-image-1.cc.raw\htmlonly Output:

\endhtmlonly\image html fill-subdomain-1.png\htmlonly

\endhtmlonly\subsection restrictsiteset Restrict an image with a site set\htmlonly A simple example is to fill only a part of an image with a specific value: \endhtmlonly\include fill-part-image-2.cc.raw\htmlonly

Output: \endhtmlonly\include fill-part-image.txt\htmlonly

\endhtmlonly\subsection restrictpred Restrict an image with a predicate\htmlonly In the following example, we aim at extracting a component from an image and create a new image with it.

First, find and label the components. \endhtmlonly\include fill-subdomain-2.cc.raw\htmlonly Output:

\endhtmlonly\image html fill-subdomain-2.png\htmlonly

Then, restrict the image to the sites being part of component 2. \endhtmlonly\include fill-subdomain-3.cc.raw\htmlonly

lbl_2 is a new image. lbl_2 looks like:

\endhtmlonly\image html fill-subdomain-3.png\htmlonly

Finally, create a new color image, fill it with black and fill the sites part of component 2 with red. \endhtmlonly\include fill-subdomain-4.cc.raw\htmlonly Output:

\endhtmlonly\image html fill-subdomain-4.png\htmlonly

The previous example can be written more quickly: \endhtmlonly\include fill-subdomain-shorter-2.cc.raw\htmlonly

\endhtmlonly\subsection restrictcfun Restrict an image with a C function\htmlonly In this example, the image is restricted to its odd lines. A new image is created in which odd lines are in red and others in black.

Here is the simple C function used as predicate: \endhtmlonly\include fill-imageif-cfun-1.cc.raw\htmlonly

Restrict the image with it: \endhtmlonly\include fill-imageif-cfun-3.cc.raw\htmlonly

Output:

\endhtmlonly\image html fill-imageif-cfun-1.png\htmlonly


Important note

When writing:

\endhtmlonly\include ima2d-restricted-1.cc.raw\htmlonly

sub_D must be included in ima.domain().

Let’s have an image, imab, like this: \endhtmlonly\include ima2d-display-output-1.txt\htmlonly

Extract a sub image from imab with sites having their value set to 1. \endhtmlonly\include mln_var-2.cc.raw\htmlonly Then, imab1 looks like: \endhtmlonly\include ima2d-display-output-2.txt\htmlonly

Now, if we want to extract a sub image it may fail, depending on the site set used: \endhtmlonly\include ima2d-restricted-2.cc.raw\htmlonly

If you do not want this constraint, you may want to use an alternative operator: \endhtmlonly\include ima2d-restricted-3.cc.raw\htmlonly

\endhtmlonly*/ /*! \page inputoutput Input / Output\htmlonly

Olena offers a builtin support for PNM (PBM, PGM & PPM), PFM and dump file formats.

You can extend the range of supported files by installing third-parties libraries such as:




\endhtmlonly\section ioim ImageMagick\htmlonly http://www.imagemagick.org
You have to install ImageMagick with Magick++ support. You will be able to load every file recognized as an image by ImageMagick.
Olena only support binary and 8 bits images through ImageMagick.
During the compilation, you will have to specify the ImageMagick flags and libraries.
To do so, just add the following line to your compilation:

  `Magick++-config --cppflags --cxxflags --ldflags --libs`
  

Magick++-config will automatically fill the dependencies depending of your installation.




\endhtmlonly\section iodcm GDCM\htmlonly http://apps.sourceforge.net/mediawiki/gdcm
GDCM is a library for manipulating DICOM files. DICOM files are used in medical imaging.

\endhtmlonly*/ /*! \page graphandima Graphs and images\htmlonly




\endhtmlonly\section graphdesc Description\htmlonly Olena enables the possibility of using graphs with images. Graphs can help you to handle directly parts of an image and represent their relationship. Specific data can be associated to each vertex and/or edges.




\endhtmlonly\section graphexample Example\htmlonly

First, create a graph which looks like the following:

\endhtmlonly\include graph-output-1.txt\htmlonly

First we need to add vertices:

\endhtmlonly\include graph-data-2.cc.raw\htmlonly

Finally, populate the graph with edges: \endhtmlonly\include graph-data-3.cc.raw\htmlonly

Now there is a graph topology and we want to associate elements of this graph to a site in the image. The idea is to use specific site sets such as p_vertices and p_edges. Let’s associate the vertices with sites. To do so we need a function which maps a vertex id to a site, e.g. a point2d here. \endhtmlonly\include graph-data-4.cc.raw\htmlonly

Then declare a p_vertices: \endhtmlonly\include graph-data-5.cc.raw\htmlonly

Thanks to the p_vertices there is now a mapping between vertices and sites. We may want to map data to it. The idea is to provide a function which returns the associated data according to the site given as parameter. Combining this function and the p_vertices, we get an image which can be used with algorithms and for_all loops.

\endhtmlonly\include graph-data-1.cc.raw\htmlonly \endhtmlonly\include graph-data-6.cc.raw\htmlonly

Output: \endhtmlonly\include graph-data.txt\htmlonly

Note that like any image in Olena, graph images share their data. Therefore, while constructing a graph image from a graph and a function, the graph is not copied and this is NOT a costly operation.

Of course, creating a graph image is not necessary and you can work directly with the graph and container/function mapping sites and data.

\endhtmlonly\include graph-iter-1.cc.raw\htmlonly Output: \endhtmlonly\include graph-iter-1.txt\htmlonly

Graphs have iterators like any other site sets and also provide specific iterators in order to iterate over graphs in a more intuitive way.

Iteration over the adjacent edges of all the vertices: \endhtmlonly\include graph-iter-2.cc.raw\htmlonly Output: \endhtmlonly\include graph-iter-2.txt\htmlonly

Iteration over the adjacent edges of all the edges: \endhtmlonly\include graph-iter-3.cc.raw\htmlonly Output: \endhtmlonly\include graph-iter-3.txt\htmlonly

Iteration over the adjacent vertices of all the vertices: \endhtmlonly\include graph-iter-4.cc.raw\htmlonly Output: \endhtmlonly\include graph-iter-4.txt\htmlonly

\endhtmlonly*/ /*! \page globalvars Useful global variables\htmlonly

NameDescriptionPossible values
literal::zeroGeneric zero value. Can be used with various types such as algebra::vec, dpoint…n.a.
   
literal::oneGeneric one value. Can be used with various types such as algebra::vec, dpoint…n.a.
   
literal::originGeneric value for the origin point on a grid.n.a.
   
border::thicknessSet the default border thickness of images[0−UINT_MAX]
   
trace::quietEnable trace printingtrue/false

\endhtmlonly*/ /*! \page macros Useful macros\htmlonly




\endhtmlonly\section vardeclmacros Variable declaration macros\htmlonly

NameArgumentsDescription
mln_VAR(N, V) N : name of the variable. 
V : value to assign to N.Declare a variable N of type N_t and assign the value V.
mln_const_VAR(N, V)N : name of the variable. 
V : value to assign to N.Declare a const variable N of type N_t and assign the value V.




\endhtmlonly\section macrositerators Iterator type macros\htmlonly

\endhtmlonly\subsection macrosdefit Default iterator types\htmlonly

NameArgumentsDescription
mln_eiter(T) T : iterable container type Type of the element iterator of T
mln_niter(T) T : iterable container/Image typeType of the neighborhood iterator of T
mln_piter(T) T : iterable container/image typeType of the site iterator
mln_qiter(T) T : iterable container/image typeType of the window neighbors iterator of T
mln_viter(T) T : iterable value container typeType of the value iterator of T
mln_pixter(I) I : image Type of the pixel iterator of I
mln_qixter(I, W)I : image type,  
W : window Type Type of the pixel iterator of a window on an image of type I.
mln_nixter(I, N)I : image type,  
N : neighborhood type Type of the pixel iterator of a neighborhood on an image of type I.

\endhtmlonly\subsection macrosfwdit Forward iterator types\htmlonly

NameArgumentsDescription
mln_fwd_eiter(T) T : iterable container type Type of the element forward iterator of T
mln_fwd_niter(T) T : iterable container/Image typeType of the neighborhood forward iterator of T
mln_fwd_piter(T) T : iterable container/image typeType of the site forward iterator
mln_fwd_qiter(T) T : iterable container/image typeType of the window neighbors forward iterator of T
mln_fwd_viter(T) T : iterable value container typeType of the value forward iterator of T
mln_fwd_pixter(I) I : image Type of the pixel forward iterator of I
mln_fwd_qixter(I, W) I : image type,  
W : window Type Type of the pixel forward iterator of a window on an image of type I.
mln_fwd_nixter(I, N) I : image type,  
N : neighborhood type Type of the pixel forward iterator of a neighborhood on an image of type I.

\endhtmlonly\subsection macrosbkdit Backward iterators\htmlonly

NameArgumentsDescription
mln_bkd_eiter(T) T : iterable container type Type of the element backward iterator of T
mln_bkd_niter(T) T : iterable container/Image typeType of the neighborhood backward iterator of T
mln_bkd_piter(T) T : iterable container/image typeType of the site backward iterator
mln_bkd_qiter(T) T : iterable container/image typeType of the window neighbors backward iterator of T
mln_bkd_viter(T) T : iterable value container typeType of the value backward iterator of T
mln_bkd_pixter(I) I : image Type of the pixel backward iterator of I
mln_bkd_qixter(I, W) I : image type,  
W : window Type Type of the pixel backward iterator of a window on an image of type I.
mln_bkd_nixter(I, N) I : image type,  
N : neighborhood type Type of the pixel backward iterator of a neighborhood on an image of type I.

\endhtmlonly\subsection macrosgraphit Graph iterators\htmlonly

NameArgumentsDescription
mln_vertex_iter(G) G : graph typeIterator on vertices.
mln_edge_iter(G) G : graph typeIterator on edges.
mln_vertex_nbh_edge_iter(G) G : graph typeIterator on the edges adjacent to a vertex.
mln_vertex_nbh_vertex_iter(G)G : graph typeIterator on the vertices adjacent to a vertex.
mln_edge_nbh_edge_iter(G) G : graph typeIterator on the edges adjacent to an edge.

\endhtmlonly*/ /*! \page compilerrors Common Compilation Errors\htmlonly

In this section, the most common compilation errors are gathered and explained.


This document was translated from LATEX by HEVEA.