Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014 EPITA Research and Development Laboratory (LRDE). This file is part of Olena. 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. 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. 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. ===================== Introduction to Olena ===================== Olena_, a platform dedicated to image processing. .. _Olena: http://olena.lrde.epita.fr -------- Overview -------- 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 characteristic is its genericity: it allows to write an algorithm once and run it over many kinds of images (gray scale, color, 1D, 2D, 3D, ...). 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. Yet, Olena is an ongoing development project. Few algorithms or definitions may change in a near future. A list of potential changes is maintained here : http://olena.lrde.epita.fr/FeaturesSubjectToChange. Likewise, the documentation does not cover the whole project yet. In the `doc/' directory you will find the first draft of a reference manual. It includes a quick reference guide and a tutorial. This is a good start. In `milena/tools' and `milena/doc/examples' few sample 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 code or e-mail us. 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 <http://olena.lrde.epita.fr>. ----------------- Required Software ----------------- 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++ (either provided by ImageMagick or GraphicsMagick) - libtiff - GDCM * To use graphical user interfaces with Scribo: - Qt * To recognize text with Scribo: - Tesseract ================== 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 though it is not mandatory) and type in the classical sequence at the command prompt:: mkdir _build cd _build ../configure make make install (as root) 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 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. ===================== 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-2.1', follow these steps: % cd olena-2.1 % mkdir _build % cd _build % ../configure The build process can be altered by a number of options you can pass to the `configure' script. The following sections describe them. 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). 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. Installation Path ================= By default, Olena is installed in the standard "local" directory of your system. This is usually `/usr/local' under Unix. 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 encounters on your system. If `CXX' is not set, it will look, in order, for: - the value of the `CXX' environment variable, - 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'. For some compilers (GNU g++ and Intel's icpc to some extent) , `configure' will use default CXXFLAGS. You can override the default C++ flags by giving `configure' your selection of flags: % ../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 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 Swilena ------- Swilena is an optional component of Olena exposing Milena to other languages thanks to the Simplified Wrapper and Interface Generator (SWIG_). .. _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:: ./configure --enable-swilena Tools ----- Sample tools are shipped with the tarball. To enable the installation of these tools use:: ./configure --enable-tools Applications ------------ Sample applications are shipped with the tarball. To enable the installation of these applications use:: ./configure --enable-apps Input/output libraries ---------------------- 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 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.:: ./configure --with-gdcm=/usr/local 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:: ./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 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/ -------- 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/', 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. ===================== Layout of the Tarball ===================== The Olena project directory layout is as follows: build-aux Auxiliary tools used by the GNU Build System during ``configure`` and ``make`` stages. external Sources of Shipped dependencies. m4 Extra Autoconf macros. milena apps Application examples. mln Headers of the Milena library. tests The test suite. doc The documentation. tools Example tools. mesh Some 3D meshes, mostly used for test purpose. img Some (2D) images, mostly used for test purpose. demos Demos of Milena. scribo demo Full applications using Scribo DIA capabilities. scribo Headers of the Scribo framework. src Example tools. swilena python Some Python bindings for Milena. =================== Supported Platforms =================== Olena has been tested on the following configurations: =========================== ============================================= System Compiler =========================== ============================================= GNU/Linux on x86-64 g++ (GNU GCC) 4.7, 4.8 GNU/Linux on x86-64 clang++ (LLVM) 3.5 OS X (10.8) on Intel 64 g++ (GNU GCC) 4.8 OS X (10.8) on Intel 64 clang++ (Apple LLVM) 5.0 =========================== ============================================= 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/ To enable I/O with GDCM images, `GDCM`_ must be installed. .. _GDCM: http://sourceforge.net/apps/mediawiki/gdcm/ To support many image formats in Olena's I/O system, `Magick++`_ must be installed. .. _Magick++: http://www.imagemagick.org/Magick++/ The Boost Tuple Library from the `Boost`_ Project is needed if you want to support tuple accumulators. .. _Boost: http://www.boost.org/ 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. 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 ======= Olena is released under the GNU General Public Licence. See the file ``COPYING`` (at the root of the source tree) for details. Contacts ======== The team can be reached by mail at olena@lrde.epita.fr. The snail mail address follows. * Olena - LRDE | Laboratoire de Recherche et Développement de l'EPITA (LRDE) | 14-16 rue Voltaire | FR-94276 Le Kremlin-Bicêtre CEDEX | France Bibliography ============ Further information about Olena and image processing can be found in the following papers. About Image Processing Programming: * `Writing Reusable Digital Topology Algorithms in a Generic Image Processing Framework`. Roland Levillain, Thierry Géraud, Laurent Najman. In Ullrich Köthe, Annick Montanvert, Pierre Soille (editors), WADGMM 2010 -- Proceedings of the Workshop on Applications of Digital Geometry and Mathematical Morphology), pages 140-153, Lecture Notes in Computer Science, volume 7346, Springer-Verlag Berlin Heidelberg, 2012. * `Une approche générique du logiciel pour le traitement d'images préservant les performances`. Roland Levillain, Thierry Géraud, Laurent Najman. In the proceedings of the 23rd Symposium on Signal and Image Processing (GRETSI) http://www.gretsi2011.org/ Bordeaux, France, September 5 - 8, 2011. * `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. * `Milena: Write Generic Morphological Algorithms Once, Run on Many Kinds of Images`. Roland Levillain, Thierry Géraud, Laurent 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. * `Generic Algorithmic Blocks Dedicated to Image Processing`, Jérôme Darbon, Thierry Géraud, Patrick Bellot. In the proceedings of ECOOP PHD Oslo, Norway, June 2004. * `Generic Implementation of Morphological Image Operators`, Jérôme Darbon, Thierry Géraud, and Alexandre Duret-Lutz. In the proceedings of the International Symposium On Mathematical Morphology VI (ISMM 2002), April 3-5, 2002, Sydney, Australia. * `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. * `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. About Generic Programming Paradigm: * `Towards a Software Architecture for Generic Image Processing`. Roland Levillain. Ph.D. thesis, Universit\'e Paris-Est, Marne-la-Vallée, France, 2011. * `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. * `Static C++ Object-Oriented Programming (SCOOP)`, Nicolas Burrus, Alexandre Duret-Lutz, Thierry Géraud, David Lesage, and Raphaël Poss. In the proceedings of the Workshop on Multiple Paradigm with OO Languages (MPOOL'03), Anaheim, CA, October 2003. * `Generic Design Patterns in C++`. Alexandre Duret-Lutz, Thierry 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 Generic, Generative and OO Programming`. Alexandre Duret-Lutz. 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. You can download these papers and related material from <http://publications.lrde.epita.fr>. .. Local Variables: .. mode: rst .. End: