README 17.3 KB
Newer Older
1
Copyright (C) 2008, 2009, 2010, 2011 EPITA Research and Development
2
Laboratory (LRDE)
3

4
This file is part of Olena.
5

6
7
8
9
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
10
11
12
13
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.
14

Roland Levillain's avatar
Roland Levillain committed
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.


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

Olena_, a platform dedicated to image processing.

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


31
--------
32
Overview
33
--------
34

Roland Levillain's avatar
Roland Levillain committed
35
36
37
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
38
characteristic is its genericity: it allows to write an algorithm once
Roland Levillain's avatar
Roland Levillain committed
39
and run it over many kinds of images (gray scale, color, 1D, 2D, 3D,
40
...).
41

42
43
44
45
46
47
48
49
50
51
52
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
53
54
Yet, Olena is an ongoing development project.  Few algorithms or
definitions may change in a near future.  A list of potential changes
55
is maintained here :
Roland Levillain's avatar
Roland Levillain committed
56
http://olena.lrde.epita.fr/FeaturesSubjectToChange.
57

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

   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
70
71
72
<http://olena.lrde.epita.fr>.


73
74
75
-----------------
Required Software
-----------------
76

77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
Here is a non-exhaustive list of required software required to build
Olena successfully.

   * to compile the user examples:

        - a POSIX shell, like Bash

        - a decent C++ compiler, like GNU C++

        - a `make' utility, like GNU `make'

Optional:

   * to use various image types:

        - Magick++

        - libtiff

        - GDCM

98
99
100
101
102
103
104
105
106
   * To use graphical user interfaces with Scribo:

	- Qt


   * To recognize text with Scribo:

	- Tesseract

107
108
109
110
111
112
113
114
115
116

==================
Quick Start Manual
==================

This section summarizes the installation procedure.  For more
information about building and installing Olena, see the next
sections.

To install Olena on your system, create a `_build' directory (even
117
118
though it is not mandatory) and type in the classical sequence at the
command prompt::
119

120
121
        mkdir _build
	cd _build
122
	../configure
123
124
125
	make
	make install (as root)

126
127
128
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
129
130
131
132
133
134
135
136
137
138
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.


139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
=====================
Detailed Instructions
=====================

-------------
Configuration
-------------

In order to prepare the build process, you need to configure the source
tree.

   Assuming your Olena distribution is uncompressed in directory
`olena-1.0', follow these steps:

     % cd olena-1.0
     % mkdir _build
     % cd _build
     % ../configure

   The build process can be altered by a number of options you can pass
Roland Levillain's avatar
Roland Levillain committed
159
to the `configure' script.  The following sections describe them.
160
161
162
163
164
165
166
167
168

   Additionally, if you are an Olena maintainer (a person who runs
`make distcheck'), _prefer setting `CXXFLAGS' as an environment
variable_: the flags given on the command line to `configure' are not
propagated to recursive runs by `make distcheck'.  Or better: use the
environment CONFIG_SITE to set up a configuration environment (see
Autoconf's manual).


Roland Levillain's avatar
Roland Levillain committed
169
170
171
172
173
174
175
176
177
178
179
180
Verbose Display
===============

A more verbose display can be turned on by passing the
`--enable-verbose' flag to configure:

     % ../configure --enable-verbose

Before configuring files, configure will display a summary of the
configuration step.


181
182
183
184
Installation Path
=================

By default, Olena is installed in the standard "local" directory of
Roland Levillain's avatar
Roland Levillain committed
185
your system.  This is usually `/usr/local' under Unix.
186
187
188
189
190
191
192
193
194
195

   You can change this path with the following flag:

      --prefix=<installation prefix>


Compiler Selection and Compilation Flags
========================================

By default, `configure' will try to use the first C++ compiler it
Roland Levillain's avatar
Roland Levillain committed
196
encounters on your system.  If `CXX' is not set, it will look, in order,
197
198
for:

Roland Levillain's avatar
Roland Levillain committed
199
   - the value of the `CXX' environment variable,
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

   - the GNU C++ compiler (`g++'),

   - the `c++' or `gpp' commands on your system,

   - `aCC', the HP-UX standard C++ compiler,

   - the `CC', `cxx', `cc++' or `cl' commands on your system,

   - KAI's C++ compiler (`KCC'),

   - `RCC', `xlC_r' or `xlC'.

   You can override the detection system by passing your favorite
compiler name to `configure', as follows:

     % ../configure CXX=<your-favorite-C++-compiler>

   As an alternative, you can also set the environment variable `CXX'.

220

221
   For some compilers (GNU g++ and Intel's icpc to some extent) ,
Roland Levillain's avatar
Roland Levillain committed
222
`configure' will use default CXXFLAGS.  You can override the default
223
C++ flags by giving `configure' your selection of flags:
224

225
226
227
228
229
230
231
232
233
234
235
236
     % ../configure CXXFLAGS="<your-favorite-flags>"


Additional Components
=====================

In additional to Milena, several build targets can be enabled.  These
parts are called "components", and you can obtain a list of them by
running:

     % ../configure --help

237
238
239
240
241
242
243
244
245
246
Scribo
------

Scribo is an optional component of Olena providing Document Image
Analysis tools and routines. It is based on Milena.

To enable the installation of this module use::

       ./configure --enable-scribo

247
248
Swilena
-------
249

Roland Levillain's avatar
Roland Levillain committed
250
251
252
Swilena is an optional component of Olena exposing Milena to other
languages thanks to the Simplified Wrapper and Interface Generator
(SWIG_).
253

Roland Levillain's avatar
Roland Levillain committed
254
255
256
257
258
259
260
261
262
.. _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::
263

Roland Levillain's avatar
Roland Levillain committed
264
       ./configure --enable-swilena
265

266
267
268
Tools
-----

Roland Levillain's avatar
Roland Levillain committed
269
Sample tools are shipped with the tarball.  To enable the installation of
Roland Levillain's avatar
Roland Levillain committed
270
these tools use::
271

Roland Levillain's avatar
Roland Levillain committed
272
       ./configure --enable-tools
273

274
275
Applications
------------
Roland Levillain's avatar
Roland Levillain committed
276
277
Sample applications are shipped with the tarball.  To enable the
installation of these applications use::
278
279
280

       ./configure --enable-apps

281
282
283
284
285
286
Trimesh
-------

Trimesh, a third-party library that we have been using to manipulate
3D meshes, is shipped with Olena.  (We will probably drop Trimesh from
the distribution someday.)  To enable it, use::
287
288
289

       ./configure --enable-trimesh

290
291
Input/output libraries
----------------------
292

Roland Levillain's avatar
Roland Levillain committed
293
294
295
296
297
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
298

Roland Levillain's avatar
Roland Levillain committed
299
300
301
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.::
302

Roland Levillain's avatar
Roland Levillain committed
303
       ./configure --with-gdcm=/usr/local
304

305
306
307
308
Olena uses the Magick++ API provided by ImageMagick or GraphicsMagick
to read and write images in common formats.  As for other optional
dependencies, you can specify where such a package is located (if
needed) at configuration time, using either::
309

310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
       ./configure --with-imagemagickxx=/usr/local/

or

       ./configure --with-graphicsmagickxx=/usr/local/

respectively.

If ``configure`` finds both ImageMagick and GraphicsMagick in your
system (either automatically or because you used one of the above
flags), the former is chosen by default.  If you want to select
GraphicsMagick instead, tell configure explicitly that you do not want
to use ImageMagick.  For instance, in the case where configure is able
to discover GraphicsMagick by itself, the following command line is
enough::

       ./configure --with-imagemagickxx=no

Otherwise, it suffices to combine it with the option telling where
GraphicsMagick is located::

       ./configure --with-imagemagickxx=no --with-graphicsmagickxx=/usr/local
332

Roland Levillain's avatar
Roland Levillain committed
333
334
335
336
337
338
339
340
341
Other libraries
---------------

The Boost Tuple library is used to implement a tuple accumulator
class.  This project is a part of the Boost libraries; you can help
configure find these libraries using the `--with-boost flag':

       ./configure --with-boost=/usr/local/

342

343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
--------
Building
--------

Once your build directory is `configure'd, you can run

     % make

to recursively build all the selected components.


   Additionally, you can build and run the test suite with:

     % make check

However, this process is time- and memory- consuming, and you probably
do not need it except if you are developing/debugging Olena.


----------
Installing
----------

To install the Olena headers and additional files on your system, run:

      % make install

from the build directory.

   If not overridden with `--prefix', this will install:

   * the headers in `/usr/local/include/mln/',

   * some applications and tools in `/usr/local/bin/',

   * sample images and meshes in `/usr/local/share/olena/images/',

   * the documentation in `/usr/local/share/doc/olena/`

And optionally:

   * Swilena's Python bindings in `/usr/local/lib/python2.x/site-packages/',

   * Trimesh programs in `/usr/local/bin/',

   * Trimesh libraries in `/usr/local/lib/',

   * Trimesh headers in `/usr/local/share/trimesh/',


   You can later remove Olena from your system by running

      % make uninstall

from the build directory (if you have kept it).  We recommend the use
of GNU Stow (or any similar program) during the installation of Olena,
to make the uninstallation of Olena easier.

Roland Levillain's avatar
Roland Levillain committed
401

402
=====================
Roland Levillain's avatar
Roland Levillain committed
403
Layout of the Tarball
404
=====================
405
406
407
408

The Olena project directory layout is as follows:

build-aux
Roland Levillain's avatar
Roland Levillain committed
409
   Auxiliary tools used by the GNU Build System during ``configure``
410
411
412
413
414
415
   and ``make`` stages.

external
   Sources of Shipped dependencies.

m4
Roland Levillain's avatar
Roland Levillain committed
416
   Extra Autoconf macros.
417
418
419
420
421
422
423

milena

  apps
     Application examples.

  mln
Roland Levillain's avatar
Roland Levillain committed
424
     Headers of the Milena library.
425
426
427
428
429
430
431
432
433
434
435

  tests
     The test suite.

  doc
     The documentation.

  tools
     Example tools.

  mesh
Roland Levillain's avatar
Roland Levillain committed
436
     Some 3D meshes, mostly used for test purpose.
437
438

  img
Roland Levillain's avatar
Roland Levillain committed
439
     Some (2D) images, mostly used for test purpose.
440
441
442
443

  demos
     Demos of Milena.

444
445
446
447
448
449
450
451
452
453
454
scribo

  demo
     Full applications using Scribo DIA capabilities.

  scribo
     Headers of the Scribo framework.

  src
     Example tools.

455
swilena
456

Roland Levillain's avatar
Roland Levillain committed
457
458
  python
     Some Python bindings for Milena.
459
460


461
462
463
===================
Supported Platforms
===================
464
465
466

Olena has been tested on the following configurations:

Roland Levillain's avatar
Roland Levillain committed
467
468
469
470
471
472
473
474
===========================  =============================================
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
===========================  =============================================
475
476
477
478
479
480
481
482
483


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
484
To enable I/O with GDCM images, `GDCM`_ must be installed.
485

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

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

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

Roland Levillain's avatar
Roland Levillain committed
493
494
The Boost Tuple Library from the `Boost`_ Project is needed if you
want to support tuple accumulators.
495
496
497

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

Roland Levillain's avatar
Roland Levillain committed
498
499
500
501
502
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.

503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520

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
521
Olena is released under the GNU General Public Licence.  See the file
522
523
524
525
526
527
``COPYING`` (at the root of the source tree) for details.


Contacts
========

Roland Levillain's avatar
Roland Levillain committed
528
529
The team can be reached by mail at olena@lrde.epita.fr.  The snail
mail address follows.
530
531
532

* Olena - LRDE

533
  | Laboratoire de Recherche et Développement de l'EPITA (LRDE)
534
  | 14-16 rue Voltaire
Roland Levillain's avatar
Roland Levillain committed
535
  | FR-94276 Le Kremlin-Bicêtre CEDEX
536
537
538
  | France


539
540
541
542
Bibliography
============

Further information about Olena can be found into the following related
543
papers.
544

545
About Image Processing Programming:
546

Roland Levillain's avatar
Roland Levillain committed
547
548
549
550
551
552
553
554
555
556
557
558
559
560
   * `Why and How to Design a Generic and Efficient Image Processing
     Framework: The Case of the Milena Library`.  Roland Levillain,
     Thierry Géraud, Laurent Najman.  In the proceedings of the 2010
     International Conference on Image Processing (ICIP)
     http://www.icip2010.org/
     Hong Kong, September 26 - 29, 2010.

   * `Writing Reusable Digital Geometry Algorithms in a Generic Image
     Processing Framework`.  Roland Levillain, Thierry Géraud, Laurent
     Najman.  In the proceedings of the Workshop on Applications of
     Digital Geometry and Mathematical Morphology (WADGMM)
     http://mdigest.jrc.ec.europa.eu/wadgmm2010/
     Istanbul, Turkey, August 22, 2010.

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

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

572
573
574
575
   * `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.
576

577
578
579
580
581
582
   * `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.
583

584
585
586
587
588
589
   * `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.
590

591
About Generic Programming Paradigm:
592
593
594
595
596
597
598
599
600

   * `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.

601
602
   * `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
603
     Poss.  In the Proceedings of the Workshop on Multiple Paradigm
604
605
     with OO Languages (MPOOL'03) Anaheim, CA, October 2003.

Roland Levillain's avatar
Roland Levillain committed
606
   * `Generic Design Patterns in C++`.  Alexandre Duret-Lutz, Thierry
607
608
609
610
611
612
     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
613
     Generic, Generative and OO Programming`.  Alexandre Duret-Lutz.
614
615
616
617
618
     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.
619
620
621
622
623
624


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


625
626
627
628

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