cimg_documentation.h

this a image processing program

/*------------------------------------------------------------------------
#
#  File        : CImg_documentation.h
#
#  Description : Extra documentation file for the CImg Library.
#                Used by doxygen to generate the reference documentation.
#                ( http://cimg.sourceforge.net )
#
#  Copyright   : David Tschumperle
#                ( http://www.greyc.ensicaen.fr/~dtschump/ )
#
#
-------------------------------------------------------------------------*/

/*-----------------------------------

  Main reference documentation page

  -------------------------------------*/

/**
   \mainpage

   This is the reference documentation of <a href="http://cimg.sourceforge.net">the CImg Library</a>,
   the C++ template image processing library.
   This documentation have been generated using the tool <a href="http://www.doxygen.org">doxygen</a>.
   It contains a detailed description of all classes and functions of the %CImg Library.
   If you have downloaded the CImg package, you actually have a local copy of these pages in the
   \c CImg/documentation/reference/ directory.

   Use the menu above to navigate through the documentation pages.
   As a first step, you may look at the list of <a href="modules.html">available modules</a>.

   A complete PDF version of this reference documentation is
   <a href="../CImg_reference.pdf">available here</a> for off-line reading.

   You may be interested also in the
   <a href="../CImg_slides.pdf">presentation slides</a> presenting an overview
   of the %CImg Library capabilities.

**/

/*-----------------------------------

  CImg Library overview

  -------------------------------------*/

/** \addtogroup cimg_structure CImg Library Overview */
/*@{*/
/**
  \page foo2

  The <b>CImg Library</b> is an image processing library, designed for C++ programmers.
  It provides useful classes and functions to load/save, display and process various types of images.

  \section s1 Library structure

  The %CImg Library consists in a <b>single header file</b> CImg.h providing a set of C++ template classes that
  can be used in your own sources, to load/save, process and display images or list of images.
  Very portable (Unix/X11,Windows, MacOS X, FreeBSD,..), efficient, simple to use, it's a pleasant toolkit
  for coding image processing stuffs in C++.

  The header file CImg.h contains all the classes and functions that compose the library itself.
  This is one originality of the %CImg Library. This particularly means that :
  - No pre-compilation of the library is needed, since the compilation of the CImg functions is done at the same time as
  the compilation of your own C++ code.
  - No complex dependencies have to be handled : Just include the CImg.h file, and you get a working C++ image processing toolkit.
  - The compilation is done on the fly : only CImg functionalities really used by your program are compiled and appear in the
  compiled executable program. This leads to very compact code, without any unused stuffs.
  - Class members and functions are inlined, leading to better performance during the program execution.

  The %CImg Library is structured as follows :

  - All library classes and functions are defined in the namespace \ref cimg_library. This namespace
  encapsulates the library functionalities and avoid any class name collision that could happen with
  other includes. Generally, one uses this namespace as a default namespace :
  \code
  #include "CImg.h"
  using namespace cimg_library;
  ...
  \endcode

  - The namespace \ref cimg_library::cimg defines a set of \e low-level functions and variables used by the library.
  Documented functions in this namespace can be safely used in your own program. But, \b never use the
  \ref cimg_library::cimg namespace as a default namespace, since it contains functions whose names are already
  defined in the standard C/C++ library.

  - The class \ref cimg_library::CImg<T> represents images up to 4-dimensions wide, containing pixels of type \c T
  (template parameter). This is actually the main class of the library.

  - The class \ref cimg_library::CImgList<T> represents lists of cimg_library::CImg<T> images. It can be used for instance
  to store different frames of an image sequence.

  - The class \ref cimg_library::CImgDisplay is able to display images or image lists into graphical display windows.
  As you may guess, the code of this class is highly system-dependent but this is transparent for the programmer,
  as environment variables are automatically set by the CImg library (see also \ref cimg_environment).

  - The class \ref cimg_library::CImgStats represents image statistics. Use it to compute the
  minimum, maximum, mean and variance of pixel values of images, as well as the corresponding min/max pixel location.

  - The class \ref cimg_library::CImgException (and its subclasses) are used by the library to throw exceptions
  when errors occur. Those exceptions can be catched with a bloc <tt>try { ..} catch (CImgException) { .. }</tt>.
  Subclasses define precisely the type of encountered errors.

  Knowing these five classes is \b enough to get benefit of the %CImg Library functionalities.


  \section s2 CImg version of "Hello world".

  Below is a very simple code that creates a "Hello World" image. This shows you basically how a CImg program looks like.

  \code
  #include "CImg.h"
  using namespace cimg_library;

  int main() {
    CImg<unsigned char> img(640,400,1,3);        // Define a 640x400 color image with 8 bits per color component.
    img.fill(0);                                 // Set pixel values to 0 (color : black)
    unsigned char purple[3]={255,0,255};         // Define a purple color
    img.draw_text("Hello World",100,100,purple); // Draw a purple "Hello world" at coordinates (100,100).
    img.display("My first CImg code");           // Display the image in a display window.
    return 0;
  }
  \endcode

  Which can be also written in a more compact way as :

  \code
  #include "CImg.h"
  using namespace cimg_library;

  int main() {
    const unsigned char purple[3]={255,0,255};
    CImg<unsigned char>(640,400,1,3,0).draw_text("Hello World",100,100,purple).display("My first CImg code");
    return 0;
  }
  \endcode

  Generally, you can write very small code that performs complex image processing tasks. The %CImg Library is very simple
  to use and provide a lot of interesting algorithms for image manipulation.

  \section s3 How to compile ?

  The CImg library is a very light and user-friendly library : only standard system libraries are used.
  It avoid to handle complex dependancies and problems with library compatibility.
  The only thing you need is a (quite modern) C++ compiler :

  - <b>Microsoft Visual C++ 6.0, Visual Studio.NET and Visual Express Edition</b> : Use project files and solution files provided in the
  %CImg Library package (directory 'compilation/') to see how it works.
  - <b>Intel ICL compiler</b> : Use the following command to compile a CImg-based program with ICL :
  \code
  icl /Ox hello_world.cpp user32.lib gdi32.lib
  \endcode
  - <b>g++ (MingW windows version)</b> : Use the following command to compile a CImg-based program with g++, on Windows :
  \code
  g++ -o hello_word.exe hello_word.cpp -O2 -lgdi32
  \endcode
  - <b>g++ (Linux version)</b> : Use the following command to compile a CImg-based program with g++, on Linux :
  \code
  g++ -o hello_word.exe hello_world.cpp -O2 -L/usr/X11R6/lib -lm -lpthread -lX11
  \endcode
  - <b>g++ (Solaris version)</b> : Use the following command to compile a CImg-based program with g++, on Solaris :
  \code
  g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -R/usr/X11R6/lib -lrt -lnsl -lsocket
  \endcode
  - <b>g++ (Mac OS X version)</b> : Use the following command to compile a CImg-based program with g++, on Mac OS X :
  \code
  g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -L/usr/X11R6/lib -lm -lpthread -lX11
  \endcode
  - <b>Dev-Cpp</b> : Use the project file provided in the CImg library package to see how it works.

  If you are using another compilers and encounter problems, please
  <a href="http://www.greyc.ensicaen.fr/~dtschump">write me</a> since maintaining compatibility is one
  of the priority of the %CImg Library. Nevertheless, old compilers that does not respect the C++ norm will not
  support the %CImg Library.

  \section s4 What's next ?

  If you are ready to get more, and to start writing more serious programs
  with CImg, you are invited to go to the \ref cimg_tutorial section.

**/
/*@}*/

/*-----------------------------------

   FAQ : Frequently Asked Questions

  -------------------------------------*/

/** \addtogroup cimg_faq FAQ : Frequently Asked Questions. */
/*@{*/
/**
  \page foofaq

  \section ssf0 FAQ Summary

  - <a href="#sf1">General information and availability</a>
    - <a href="#ssf11">What is the CImg Library ?</a>
    - <a href="#ssf12">What platforms are supported ?</a>
    - <a href="#ssf13">How is CImg distributed ?</a>
    - <a href="#ssf14">What kind of people are concerned by CImg ?</a>
    - <a href="#ssf15">What are the specificities of the CeCILL license ?</a>
    - <a href="#ssf16">Who is behind CImg ?</a>

  - <a href="#sf2">C++ related questions</a>
    - <a href="#ssf21">What is the level of C++ knowledge needed to use CImg ?</a>
    - <a href="#ssf22">How to use CImg in my own C++ program ?</a>

  \section sf1 1. General information and availability

  \subsection ssf11 1.1. What is the CImg Library ?

  The CImg Library is an <i>open-source C++ toolkit for image processing</i>.\n

  It mainly consists in a (big) single header file
  <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>
  providing a set of C++ classes and functions that can be used in your own sources,
  to load/save, process and display images.
  It's actually a very simple and pleasant toolkit for coding image processing stuffs in C++ :
  Just include the header file <i>CImg.h</i>, and you are ready to handle images in your C++ programs.

  \subsection ssf12 1.2. What platforms are supported ?

  CImg is designed with <i>portability</i> in mind. It is regularly tested on different architectures and compilers,
  and should also work on any decent OS having a recent C++ compiler.
  Before each release, the CImg Library is compiled under these different configurations :
  \li PC Linux 32 bits, with g++.
  \li PC Windows 32 bits, with Visual C++ 6.0.
  \li PC Windows 32 bits, with Visual C++ Express Edition.
  \li Sun SPARC Solaris 32 bits, with g++.
  \li Mac PPC with OS X and g++.

  CImg has a minimal number of dependencies. In its minimal version, it can be compiled only with standard C++ headers.
  Anyway, it has interesting extension capabilities and can use external libraries to perform specific tasks more
  efficiently (Fourier Transform computation using FFTW for instance).

  \subsection ssf13 1.3. How is CImg distributed ?

  The CImg Library is freely distributed as a complete .zip compressed package, hosted at the
  <a href="http://sourceforge.net/project/showfiles.php?group_id=96492">Sourceforge servers</a>.\n
  The package is distributed under the <a href="http://www.cecill.info">CeCILL license</a>.

  This package contains :
  - The main library file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> (C++ header file).
  - Several C++ source code showing <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/examples/">examples of using CImg</a>.
  - A complete library documentation, in <a href="index.html">HTML</a> and <a href="../CImg_reference.pdf">PDF</a> formats.
  - Additional <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/plugins/">library plug-ins</a> that can be used to extend
  library capabilities for specific uses.

  The CImg Library is a quite lightweight library which is easy to maintain (due to its particular structure), and thus
  has a fast rythm of release. A new version of the CImg package is released approximately every three months.

  \subsection ssf14 1.4. What kind of people are concerned by CImg ?

  The CImg library is an <i>image processing</i> library, primarily intended for computer scientists or students working in the fields
  of image processing or computer vision, and knowing bases of C++.
  As the library is handy and really easy to use, it can be also used by any programmer
  needing occasional tools for dealing with images in C++, since there are no standard library yet
  for this purpose.

  \subsection ssf15 1.5. What are the specificities of the CeCILL license ?

  The <a href="http://www.cecill.info">CeCILL license</a> governs the use of the CImg Library.
  This is an <i>open-source</i> license which gives you rights to access, use, modify and redistribute the source code,
  under certains conditions.
  There are two different variants of the CeCILL license used in CImg
  (namely
  <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> and
  <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a>, all open-source),
  corresponding to different constraints on the source files :
  - The <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a> license is the most permissive one, close to
  the <i>GNU LGPL license</i>, and <i>applies <b>only</b> on the main library file
  <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a></i>.
  Basically, this license allows to use <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>
  in a closed-source product without forcing you to redistribute the entire software source code. Anyway,
  if one modifies the <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> source file, one has to redistribute
  the modified version of the file that must be governed by the same <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a> license.

  - The <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> license applies to all other files
  (source examples, plug-ins and documentation) of the CImg Library package, and is close (even <i>compatible</i>)
  with the <i>GNU GPL license</i>. It <i>does not allow</i> the use of these files in closed-source products.

  You are invited to read the complete descriptions of the
  the <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a>
  and <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> licenses before releasing a
  software based on the CImg Library.

  \subsection ssf16 1.6. Who is behind CImg ?

  CImg has been started by
  <a href="http://www.greyc.ensicaen.fr/~dtschump/">David Tschumperl