README 10.6 KB
Newer Older
1
Copyright (C) 2009 EPITA Research and Development Laboratory (LRDE)
2

3
This file is part of Olena.
4

5
6
7
8
Olena is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, version 2 of the License.

Roland Levillain's avatar
Roland Levillain committed
9
10
11
12
Olena is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
13

Roland Levillain's avatar
Roland Levillain committed
14
15
16
17
18
19
20
21
You should have received a copy of the GNU General Public License
along with Olena.  If not, see <http://www.gnu.org/licenses/>.

The complete GNU General Public License Notice can also be found in
the 'COPYING' file in the root directory.


======================
22
 Introduction to Olena
Roland Levillain's avatar
Roland Levillain committed
23
======================
24
25
26

Olena_, a platform dedicated to image processing.

Roland Levillain's avatar
Roland Levillain committed
27
.. _Olena: http://olena.lrde.epita.fr
28
29
30
31


Overview
========
32

Roland Levillain's avatar
Roland Levillain committed
33
34
35
Olena is a platform dedicated to image processing.  At the moment it is
mainly composed of a C++ library: Milena.  This library features many
tools to easily perform image processing tasks.  Its main
36
characteristic is its genericity: it allows to write an algorithm once
Roland Levillain's avatar
Roland Levillain committed
37
and run it over many kinds of images (gray scale, color, 1D, 2D, 3D,
38
...).
39

40
41
42
43
44
45
46
47
48
49
50
Olena is a project developed by the `EPITA Research and Development
Laboratory (LRDE)`__ since 1997.  We did numerous prototypes and
throwaway experiments before settling into the kind of programming
paradigm which is finally here.

__ http://www.lrde.epita.fr

We do our image processing research using this library, but most
importantly we have gathered (and still do) generic programming
expertise from the library development.

Roland Levillain's avatar
Roland Levillain committed
51
52
Yet, Olena is an ongoing development project.  Few algorithms or
definitions may change in a near future.  A list of potential changes
53
54
55
is maintained here :
https://olena.lrde.epita.fr/FeaturesSubjectToChange.

Roland Levillain's avatar
Roland Levillain committed
56
Likewise, the documentation does not cover the whole project yet.  In the
57
`doc/' directory you will find the first draft of a reference
Roland Levillain's avatar
Roland Levillain committed
58
manual.  It includes a quick reference guide and a tutorial.  This is a
59
good start.  In `milena/tools' and `milena/doc/examples' few sample
Roland Levillain's avatar
Roland Levillain committed
60
61
programs are available.  Most of them are already used to illustrate
the tutorial.   For the rest, we're afraid you will have to dig the
62
code or e-mail us.
63
64
65
66
67

   Please direct any question or comments to <olena@lrde.epita.fr>, or
<olena-bugs@lrde.epita.fr>.

   Olena also has a web page, located at
68
69
70
71
72
73
<http://olena.lrde.epita.fr>.


Installation
============

74
75
76
To install Olena on your system, create a `build' directory (even
though it is not mandatory) and type in the classical sequence at the
command prompt::
77

78
79
80
        mkdir build
	cd build
	../configure
81
82
83
	make
	make install (as root)

84
85
86
Note that an installation is specific to the compiler used to install
it.  Indeed, the call to ``../configure`` enables some workarounds
and, consequently, users must compile with the same compiler to avoid
87
88
89
90
91
92
93
94
95
96
97
98
99
100
compatibility problems.

Between ``make`` and ``make install``, you may also want to run::

	make check

 ``make check`` will run the test suite to check the whole library.
Running the test suite may require up several hours.


Please read the INSTALL file for more information about building and
installing Olena.


Roland Levillain's avatar
Roland Levillain committed
101
Additional Features
102
103
-------------------

Roland Levillain's avatar
Roland Levillain committed
104
105
106
Swilena is an optional component of Olena exposing Milena to other
languages thanks to the Simplified Wrapper and Interface Generator
(SWIG_).
107

Roland Levillain's avatar
Roland Levillain committed
108
109
110
111
112
113
114
115
116
.. _SWIG: http://www.swig.org

For the moment, only some Python_ bindings are provided.  They are
disabled by default because they require extra dependencies (SWIG and
Python).

.. _Python: http://www.python.org

To enable the installation of this module use::
117

Roland Levillain's avatar
Roland Levillain committed
118
       ./configure --enable-swilena
119

Roland Levillain's avatar
Roland Levillain committed
120
121
Sample tools are shipped with the tarball. To enable the installation of
these tools use::
122

Roland Levillain's avatar
Roland Levillain committed
123
       ./configure --enable-tools
124

Roland Levillain's avatar
Roland Levillain committed
125
126
Sample applications are shipped with the tarball.  To enable the
installation of these applications use::
127
128
129

       ./configure --enable-apps

130
131
132
133
134
135
Olena ships with Trimesh, a third-party library that we have been
using to manipulate 3D meshes.  Eventually, we will drop Trimesh from
the distribution.  To enable it, use::

       ./configure --enable-trimesh

136

Roland Levillain's avatar
Roland Levillain committed
137
138
139
140
141
To read/write TIFF images with Olena, libtiff is required.  If
``configure`` is unable to find libtiff on your system, you can help
it by specifying the base directory of libtiff, e.g.::

       ./configure --with-tiff=/usr/local
142
143


Roland Levillain's avatar
Roland Levillain committed
144
145
146
To read/write DICOM images with Olena, GDCM is required.  Likewise,
you can tell ``configure`` where to find it by giving its install
prefix, e.g.::
147

Roland Levillain's avatar
Roland Levillain committed
148
       ./configure --with-gdcm=/usr/local
149

Roland Levillain's avatar
Roland Levillain committed
150
151
152
Olena use Magick++ to read and write images in common formats.  As for
other optional dependencies, you can specify where it is located (if
needed) at configuration time::
153

Roland Levillain's avatar
Roland Levillain committed
154
       ./configure --with-magickxx=/usr/local/
155
156


Roland Levillain's avatar
Roland Levillain committed
157
Layout of the Tarball
158
159
160
161
162
---------------------

The Olena project directory layout is as follows:

build-aux
Roland Levillain's avatar
Roland Levillain committed
163
   Auxiliary tools used by the GNU Build System during ``configure``
164
165
166
167
168
169
170
   and ``make`` stages.

external
   Sources of Shipped dependencies.


m4
Roland Levillain's avatar
Roland Levillain committed
171
   Extra Autoconf macros.
172
173
174
175
176
177
178

milena

  apps
     Application examples.

  mln
Roland Levillain's avatar
Roland Levillain committed
179
     Headers of the Milena library.
180
181
182
183
184
185
186
187
188
189
190

  tests
     The test suite.

  doc
     The documentation.

  tools
     Example tools.

  mesh
Roland Levillain's avatar
Roland Levillain committed
191
     Some 3D meshes, mostly used for test purpose.
192
193

  img
Roland Levillain's avatar
Roland Levillain committed
194
     Some (2D) images, mostly used for test purpose.
195
196
197
198
199
200

  demos
     Demos of Milena.


swilena
201

Roland Levillain's avatar
Roland Levillain committed
202
203
204

  python
     Some Python bindings for Milena.
205
206
207
208
209
210
211


Requirements
============

Olena has been tested on the following configurations:

Roland Levillain's avatar
Roland Levillain committed
212
213
214
215
216
217
218
219
===========================  =============================================
System                       Compiler
===========================  =============================================
GNU/Linux on IA-32           g++ (GNU GCC) 3.3, 3.4, 4.0, 4.1, 4.2 and 4.3
GNU/Linux on IA-32           icpc (Intel C/C++ Compiler) 10.1 and 11.0
GNU/Linux on AMD64/Intel 64  g++ (GNU GCC) 4.1
Mac OS X (10.5) on IA-32     g++ (GNU GCC) 4.0.1
===========================  =============================================
220
221
222
223
224
225
226
227
228


According to the wanted features, some dependencies may be required:


To enable I/O with TIFF images, `libtiff`_ must be installed.

.. _libtiff: http://www.libtiff.org/

Roland Levillain's avatar
Roland Levillain committed
229
To enable I/O with GDCM images, `GDCM`_ must be installed.
230

Roland Levillain's avatar
Roland Levillain committed
231
.. _GDCM: http://sourceforge.net/apps/mediawiki/gdcm/
232

Roland Levillain's avatar
Roland Levillain committed
233
To support many image formats in Olena's I/O system, `Magick++`_ must
234
235
be installed.

Roland Levillain's avatar
Roland Levillain committed
236
.. _Magick++: http://www.imagemagick.org/Magick++/
237

Roland Levillain's avatar
Roland Levillain committed
238
239
The Boost Tuple Library from the `Boost`_ Project is needed if you
want to support tuple accumulators.
240
241
242

.. _Boost: http://www.boost.org/

Roland Levillain's avatar
Roland Levillain committed
243
244
245
246
247
Apart from GDCM, these dependencies are commonly provided by the
package management systems (e.g., Debian's APT, Mac OS X's Mac Ports,
etc.).  We recommend using package managers instead of installing
dependencies by hand.

248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265

See Also
========

There are other sources of interest in the distribution.

- Headline news about the project can be found in the file ``NEWS`` at
  the root of the source tree.

- The library reference HTML documentation, generated by Doxygen_, is
  located in ``doc/user/html/``.

.. _Doxygen: http://www.doxygen.org


License
=======

Roland Levillain's avatar
Roland Levillain committed
266
Olena is released under the GNU General Public Licence.  See the file
267
268
269
270
271
272
``COPYING`` (at the root of the source tree) for details.


Contacts
========

Roland Levillain's avatar
Roland Levillain committed
273
274
The team can be reached by mail at olena@lrde.epita.fr.  The snail
mail address follows.
275
276
277

* Olena - LRDE

278
  | Laboratoire de Recherche et Développement de l'EPITA (LRDE)
279
  | 14-16 rue Voltaire
Roland Levillain's avatar
Roland Levillain committed
280
  | FR-94276 Le Kremlin-Bicêtre CEDEX
281
282
283
  | France


284
285
286
287
Bibliography
============

Further information about Olena can be found into the following related
288
papers.
289

290
About Image Processing Programming:
291

292
   * `Milena: Write Generic Morphological Algorithms Once, Run on Many
Roland Levillain's avatar
Roland Levillain committed
293
     Kinds of Images`.  Roland Levillain, Thierry Géraud, Laurent
294
295
296
     Najman.  In the proceedings of the 9th International Symposium on
     Mathematical Morphology (ISMM) http://www.cs.rug.nl/~ISMM09/
     Groningen, The Netherlands August 24 - 27, 2009.
297

298
   * `Generic Algorithmic Blocks Dedicated to Image Processing`,
Roland Levillain's avatar
Roland Levillain committed
299
     Jérôme Darbon, Thierry Géraud, Patrick Bellot.  In the proceedings
300
     of ECOOP PHD Oslo, Norway, June 2004.
301

302
303
304
305
   * `Generic Implementation of Morphological Image Operators`, Jérôme
     Darbon, Thierry Géraud, and Alexandre Duret-Lutz, submitted to
     International Symposium On Mathematical Morphology VI (ISMM
     2002), April 3-5, 2002, Sydney, Australia.
306

307
308
309
310
311
312
   * `Applying Generic Programming to Image Processing`, Thierry
     Géraud, Yoann Fabre, and Alexandre Duret-Lutz.  In the
     Proceedings of the IASTED International Conference on Applied
     Informatics (AI'2001) - Symposium Advances in Computer
     Applications, ACTA Press, pages 577-581, Innsbruck, Austria,
     February 2001.
313

314
315
316
317
318
319
   * `Obtaining Genericity for Image Processing and Pattern
     Recognition Algorithms`.  Thierry Géraud, Yoann Fabre, Alexandre
     Duret-Lutz, Dimitri Papadopoulos-Orfanos, and Jean-François
     Mangin.  In the Proceedings of the 15th International Conference
     on Pattern Recognition (ICPR'2000), IEEE Computer Society,
     vol. 4, pages 816-819, Barcelona, Spain, September 2000.
320

321
About Generic Programming Paradigm:
322
323
324
325
326
327
328
329
330

   * `Semantics-Driven Genericity: A Sequel to the Static C++
     Object-Oriented Programming Paradigm (SCOOP 2)`.  Thierry Géraud,
     Roland Levillain.  In the proceedings of the 6th International
     Workshop on Multiparadigm Programming with Object-Oriented
     Languages
     http://homepages.fh-regensburg.de/~mpool/mpool08/welcome.html
     Paphos, Cyprus July 7, 2008.

331
332
   * `Static C++ Object-Oriented Programming (SCOOP)`, Nicolas Burrus,
     Alexandre Duret-Lutz, Thierry Géraud, David Lesage, and Raphaël
Roland Levillain's avatar
Roland Levillain committed
333
     Poss.  In the Proceedings of the Workshop on Multiple Paradigm
334
335
     with OO Languages (MPOOL'03) Anaheim, CA, October 2003.

Roland Levillain's avatar
Roland Levillain committed
336
   * `Generic Design Patterns in C++`.  Alexandre Duret-Lutz, Thierry
337
338
339
340
341
342
     Géraud, and Akim Demaille.  In the Proceedings of the 6th USENIX
     Conference on Object-Oriented Technologies and Systems
     (COOTS'2001), pages 189-202, San Antonio, Texas, USA,
     January-February 2001.

   * `Olena: a Component-Based Platform for Image Processing, mixing
Roland Levillain's avatar
Roland Levillain committed
343
     Generic, Generative and OO Programming`.  Alexandre Duret-Lutz.
344
345
346
347
348
     In the Proceedings of the 2nd International Symposium on
     Generative and Component-Based Software Engineering (GCSE 2000),
     Young Researchers Workshop (published in "Net.ObjectDays2000";
     ISBN 3-89683-932-2), pages 653-659, Erfurt, Germany, October
     2000.
349
350
351
352
353
354


   You can download these papers and related materials from
<http://www.lrde.epita.fr/cgi-bin/twiki/view/Publications>


355
356
357
358

.. Local Variables:
.. mode: rst
.. End: