$extrastylesheet
Olena  User documentation 2.1
An Image Processing Platform
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Foreword




Generality

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.




Directory hierarchy

Olena’s tarball is structured as follow:

  • milena
    • doc
      • benchmark: set of benchmark.
      • examples: more examples.
      • technical: technical doc.
      • tutorial: code sample and tutorial.
    • img: a set of sample images.
    • mesh: a full example which uses Olena.
    • mln: the library. Contains only headers.
    • tests: test suite.
  • swilena: Python bindings for Olena.




Writing and compiling a program with Olena

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

  • By default, Olena enables a lot of internal pre and post conditions. Usually, this is a useful feature and it should be enabled. However, it can heavily slow down a program though so these tests can be disabled by compiling using -DNDEBUG.
    $ g++ -O2 -DNDEBUG -Ipath/to/mln my_program.cc
      
  • If you decide to use optimization flags to compile for debugging, prefer using -O1. It is much faster to compile and it gives good performance results.




Compiling a multiple files program with Olena

In case of a large project, Olena may be used in several source files. Even if compilation is fine, you may encounter the following linking error:

fidji\% g++ main.cc f1.cc f2.cc -I$OLN/milena
/tmp/ccZLOEyG.o:(.data+0x0): multiple definition of `mln::debug::trace::quiet'
/tmp/ccqHhSP3.o:(.data+0x0): first defined here
/tmp/ccZLOEyG.o:(.bss+0x0): multiple definition of `mln::debug::trace::tab'
/tmp/ccqHhSP3.o:(.bss+0x0): first defined here
/tmp/ccZLOEyG.o:(.bss+0x4): multiple definition of `mln::debug::trace::full_trace'
/tmp/ccqHhSP3.o:(.bss+0x4): first defined here
/tmp/ccZLOEyG.o:(.bss+0x20): multiple definition of `mln::debug::trace::start_times_'
/tmp/ccqHhSP3.o:(.bss+0x20): first defined here

These multiple symbol definitions are due to some global variables used in Olena. They are built in each source file which includes Olena headers and are therefore duplicated, causing linking errors.

An easy way to override this issue is to compile all the source files of your project passing -DMLN_WO_GLOBAL_VARS. Then, at the top of one of the files which includes Olena headers, add:

#undef MLN_WO_GLOBAL_VARS

Here is a small example.

  • main.cc
    #undef MLN_WO_GLOBAL_VARS
    // This include is needed here to compile the global variables with
    // this file. We include that file because it is used in other parts
    // of the project.
    #include <mln/core/image/image2d.hh>
    // Forward declarations
    void f1();
    void f2();
    int main()
    {
    f1();
    f2();
    }
  • f1.cc
    #include <mln/core/image/image2d.hh>
    void f1()
    {
    }
  • f2.cc
    #include <mln/core/image/image2d.hh>
    void f2()
    {
    }

This example can be compiled with the following command:

$ g++ -DNDEBUG -O2 -DMLN_WO_GLOBAL_VARS -Ipath/to/mln main.cc f1.cc f2.cc
  

Note that the file where MLN_WO_GLOBAL_VARS is undefined must include olena headers to declare and compile the global variables.