| /*------------------------------------------------------------------------ |
| # |
| # File : CImg_documentation.h |
| # |
| # Description : Extra documentation file for the CImg Library. |
| # Used by doxygen to generate the reference documentation. |
| # ( http://cimg.eu ) |
| # |
| # Copyright : David Tschumperle |
| # ( http://tschumperle.users.greyc.fr/ ) |
| # |
| # |
| -------------------------------------------------------------------------*/ |
| |
| /*----------------------------------- |
| |
| Main reference documentation page |
| |
| -------------------------------------*/ |
| |
| /** |
| \mainpage |
| |
| This is the reference documentation of <a href="http://cimg.eu">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. |
| |
| 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>. |
| |
| 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_overview 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 single header file <tt>CImg.h</tt> 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 stuff in C++. |
| |
| The header file <tt>CImg.h</tt> 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 <tt>CImg.h</tt> 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 stuff. |
| - 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 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 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::CImgException (and its subclasses) are used by the library to throw exceptions |
| when errors occur. Those exceptions can be caught with a <tt>try { ..} catch (CImgException) { .. }</tt> block. |
| Subclasses define precisely the type of encountered errors. |
| |
| Knowing these four classes is \b enough to get benefit of the %CImg Library functionalities. |
| |
| |
| \section s2 CImg version of "Hello world". |
| |
| Below is some 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[] = { 255,0,255 }; // Define a purple color |
| img.draw_text(100,100,"Hello World",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[] = { 255,0,255 }; |
| CImg<unsigned char>(640,400,1,3,0).draw_text(100,100,"Hello World",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 provides 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 avoids handling complex dependencies and problems with library compatibility. |
| The only thing you need is a (quite modern) C++ compiler : |
| |
| - <b>Microsoft Visual Studio.NET and Visual Express Edition</b> : Use the 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 -I/usr/X11R6/include -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 other compilers and encounter problems, please |
| <a href="http://www.greyc.ensicaen.fr/~dtschump">write me</a> since maintaining compatibility is one |
| of the priorities of the %CImg Library. Nevertheless, old compilers that do not respect the C++ standard 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> |
| - <a href="#ssf23">Why is CImg entirely contained in a single header file ?</a> |
| |
| - <a href="#sf3">Other resources</a> |
| - <a href="#ssf31">Translations</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="https://framagit.org/dtschump/CImg/raw/master/CImg.h">CImg.h</a> |
| providing a set of C++ classes and functions that can be used in your own sources, |
| to load/save, manage/process and display generic images. |
| It's actually a very simple and pleasant toolkit for coding image processing stuff in C++ : |
| Just include the header file <tt>CImg.h</tt>, and you are ready to handle images in your C++ programs. |
| |
| \subsection ssf12 1.2. What platforms are supported ? |
| |
| CImg has been 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 decent C++ compiler. |
| Before each release, the CImg Library is compiled under these different configurations : |
| \li PC Linux 32/64 bits, with g++. |
| \li PC Windows 32/64 bits, with Visual C++ Express Edition. |
| |
| 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://cimg.eu/files">CImg server</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="https://framagit.org/dtschump/CImg/raw/master/CImg.h">CImg.h</a> (C++ header file). |
| - Several C++ source code showing <a href="https://framagit.org/dtschump/CImg/tree/master/examples">examples of using CImg</a>. |
| - A complete library documentation, in <a href="../CImg_reference.pdf">PDF</a> format. |
| - Additional <a href="https://framagit.org/dtschump/CImg/tree/master/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="https://framagit.org/dtschump/CImg/raw/master/CImg.h">CImg.h</a></i>. |
| Basically, this license allows to use <a href="https://framagit.org/dtschump/CImg/raw/master/CImg.h">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="https://framagit.org/dtschump/CImg/raw/master/CImg.h">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://tschumperle.users.greyc.fr/">David Tschumperle</a> at the beginning of his PhD thesis, in October 1999. |
| He is still the main coordinator of the project. |
| Since the first release, a growing number of contributors has appeared. |
| Due to the very simple and compact form of the library, submitting a contribution is quite easy and can be |
| fastly integrated into the supported releases. |
| List of contributors can be found on the front page. |
| |
| \section sf2 2. C++ related questions |
| |
| \subsection ssf21 2.1 What is the level of C++ knowledge needed to use CImg ? |
| |
| The CImg Library has been designed using C++ templates and object-oriented programming techniques, |
| but in a very accessible level. |
| There are only public classes without any derivation (just like C structures) and |
| there is at most one template parameter for each CImg class (defining the pixel type of the images). |
| The design is simple but clean, making the library accessible even for non professional C++ programmers, while proposing |
| strong extension capabilities for C++ experts. |
| |
| \subsection ssf22 2.2 How to use CImg in my own C++ program ? |
| |
| Basically, you need to add these two lines in your C++ source code, in order |
| to be able to work with CImg images : |
| \code |
| #include "CImg.h" |
| using namespace cimg_library; |
| \endcode |
| |
| \subsection ssf23 2.3 Why is CImg entirely contained in a single header file ? |
| |
| People are often surprised to see that the complete code of the library is contained in a single (big) C++ header file |
| <a href="https://framagit.org/dtschump/CImg/raw/master/CImg.h">CImg.h</a>. |
| There are good practical and technical reasons to do that. Some arguments are listed below to justify this approach, |
| so (I hope) you won't think this is a awkwardly C++ design of the CImg library :\n |
| |
| - First, the library is based on <i>template datatypes</i> (images with generic pixel type), |
| meaning that the programmer is free to decide what type of image he instanciates in his code. |
| Even if there are roughly a limited number of fully supported types (basically, the "atomic" types of C++ : <i>unsigned char, int, float, ...</i>), |
| this is <i>not imaginable</i> to pre-compile the library classes and functions for <i>all possible atomic datatypes</i>, |
| since many functions and methods can have two or three arguments having different template parameters. |
| This really means <i>a huge number</i> of possible combinations. The size of the object binary file generated to cover all possible cases |
| would be just <i>colossal</i>. Is the STL library a pre-compiled one ? No, CImg neither. |
| CImg is not using a classical <i>.cpp</i> and <i>.h</i> mechanism, just like the STL. |
| Architectures of C++ <i>template-based</i> libraries are somewhat special in this sense. This is a proven technical fact. |
| |
| - Second, why CImg does not have several header files, just like the STL does (one for each class for instance) ? |
| This would be possible of course. |
| There are only 4 classes in CImg, the two most important being <i>CImg<T></i> and <i>CImgList<T></i> representing respectively |
| an image and a collection of images. |
| But contrary to the STL library, these two CImg classes are strongly <i>inter-dependent</i>. All CImg algorithms |
| are actually not defined as separate functions acting on containers (as the STL does with his header \<algorithm\>), |
| but are directly methods of the image and image collection classes. This inter-dependence practically means that you |
| will undoubtly need these two main classes at the same time if you are using CImg. |
| If they were defined in separate header files, you would be forced to include both of them. What is the gain then ? No gain.\n |
| Concerning the two other classes : You can disable the third most important class <i>CImgDisplay</i> of the CImg library, by setting the compilation |
| macro <i>cimg_display</i> to 0, avoiding thus to compile this class if you don't use display capabilities of CImg in your code. |
| But to be honest, this is a quite small class and doing this doesn't save much compilation time. |
| The last and fourth class is <i>CImgException</i>, which is only few lines long and is obviously required in almost all methods of CImg. |
| Including this one is <i>mandatory</i>.\n |
| As a consequence, having a single header file instead of several ones is just a way for you to avoid including all of them, |
| without any consequences on compilation time. This is both good technical and practical reasons to do like this. |
| |
| - Third, having a single header file has plenty of advantages : Simplicity for the user, and for the developers (maintenance is in fact easier). |
| Look at the <tt>CImg.h</tt> file, it looks like a mess at a first glance, but it is in fact very well organized and structured. |
| Finding pieces of code in CImg functions or methods is particularly easy and fast. |
| Also, how about the fact that library installation problems just disappear ? |
| Just bring <tt>CImg.h</tt> with you, put it in your source directory, and the library is ready to go ! |
| |
| I admit the compilation time of CImg-based programs can be sometime long, but don't think that it is due to the fact that you are |
| using a single header file. Using several header files wouldn't arrange anything since you would need all of them. |
| Having a pre-compiled library object would be the only solution to speed up compilation time, but it is not possible at all, |
| due to the too much generic nature of the library. |
| |
| \section sf3 3. Other resources |
| \subsection ssf31 3.1 Translations |
| |
| This FAQ has been translated to <a href="http://science.webhostinggeeks.com/cimg-biblioteka">Serbo-Croatian</a> language by <a href="http://webhostinggeeks.com/"> Web Geeks </a>. |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| Setting Environment Variables |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_environment Setting Environment Variables */ |
| /*@{*/ |
| /** |
| \page foo1 |
| |
| The CImg library is a multiplatform library, working on a wide variety of systems. |
| This implies the existence of some \e environment \e variables that must be correctly defined |
| depending on your current system. |
| Most of the time, the %CImg Library defines these variables automatically |
| (for popular systems). Anyway, if your system is not recognized, you will have to set the environment |
| variables by hand. Here is a quick explanations of environment variables.\n |
| |
| Setting the environment variables is done with the <tt>\#define</tt> keyword. |
| This setting must be done <i>before including the file <tt>CImg.h</tt></i> in your source code. |
| For instance, |
| defining the environment variable \c cimg_display would be done like this : |
| \code |
| #define cimg_display 0 |
| #include "CImg.h" |
| ... |
| \endcode |
| |
| Here are the different environment variables used by the %CImg Library : |
| |
| - \b \c cimg_OS : This variable defines the type of your Operating System. It can be set to \b 1 (\e Unix), |
| \b 2 (\e Windows), or \b 0 (\e Other \e configuration). |
| It should be actually auto-detected by the CImg library. If this is not the case (<tt>cimg_OS=0</tt>), you |
| will probably have to tune the environment variables described below. |
| |
| - \b \c cimg_display : This variable defines the type of graphical library used to |
| display images in windows. It can be set to 0 (no display library available), \b 1 (X11-based display) or |
| \b 2 (Windows-GDI display). |
| If you are running on a system without X11 or Windows-GDI ability, please set this variable to \c 0. |
| This will disable the display support, since the %CImg Library doesn't contain the necessary code to display |
| images on systems other than X11 or Windows GDI. |
| |
| - \b \c cimg_use_vt100 : This variable tells the library if the system terminal has VT100 color capabilities. |
| It can be \e defined or \e not \e defined. Define this variable to get colored output on your terminal, |
| when using the %CImg Library. |
| |
| - \b \c cimg_verbosity : This variable defines the level of run-time debug messages that will be displayed by |
| the %CImg Library. It can be set to 0 (no debug messages), 1 (normal debug messages displayed on |
| standard error), 2 (normal debug messages displayed in modal windows, which is |
| the default value), or 3 (high debug messages). Note that setting this value to 3 may slow down your |
| program since more debug tests are made by the library (particularly to check if pixel access is made outside |
| image boundaries). See also CImgException to better understand how debug messages are working. |
| |
| - \b \c cimg_plugin : This variable tells the library to use a plugin file to add features to the CImg<T> class. |
| Define it with the path of your plugin file, if you want to add member functions to the CImg<T> class, |
| without having to modify directly the \c "<tt>CImg.h</tt>" file. An include of the plugin file is performed in the CImg<T> |
| class. If \c cimg_plugin if not specified (default), no include is done. |
| |
| - \b \c cimglist_plugin : Same as \c cimg_plugin, but to add features to the CImgList<T> class. |
| |
| - \b \c cimgdisplay_plugin : Same as \c cimg_plugin, but to add features to the CImgDisplay<T> class. |
| |
| All these compilation variables can be checked, using the function cimg_library::cimg::info(), which |
| displays a list of the different configuration variables and their values on the standard error output. |
| **/ |
| /*@}*/ |
| |
| |
| /** \addtogroup cimg_visual2005 How to use CImg library with Visual C++ 2005 Express Edition ?. */ |
| /*@{*/ |
| /** |
| \page foo89198 |
| |
| \section s13968 How to use CImg library with Visual C++ 2005 Express Edition ? |
| |
| This section has been written by Vincent Garcia and Alexandre Fournier from I3S/Sophia_Antipolis. |
| |
| - Download CImg library |
| - Download and install Visual C++ 2005 Express Edition |
| - Download and install Microsoft Windows SDK |
| - Configure Visual C++ to take into account Microsoft SDK |
| - 1. Go to menu "Tools -> options" |
| - 2. Select option "Projects and Solutions -> VC++ Directories" |
| - 3. In the select liste "Show directories for", choose "include files", and add C:\\Program Files\\Microsoft Platform SDK\\Include (adapt if needed) |
| - 4. In the select liste "Show directories for", choose "library files", and add C:\\Program Files\\Microsoft Platform SDK\\Lib |
| (adapt if needed) Edit file C:\\Program Files\\Microsoft Visual Studio 8\\VC\\VCProjectDefaults\\corewin_express.vsprops (adapt if needed) |
| - 6. 7. Remplace the line AdditionalDependencies="kernel32.lib" /> by AdditionalDependencies="kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib" /> |
| - Restart Visual C++ |
| - Import CImg library in your main file |
| |
| **/ |
| /*@}*/ |
| |
| |
| /*----------------------------------- |
| |
| Tutorial : Getting started |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_tutorial Tutorial : Getting Started. */ |
| /*@{*/ |
| /** |
| \page foo3 |
| |
| Let's start to write our first program to get the idea. This will demonstrate how to load and create images, as well as handle image |
| display and mouse events. |
| Assume we want to load a color image <tt>lena.jpg</tt>, smooth it, display it in a windows, and enter an event loop so that clicking a |
| point in the image will draw the (R,G,B) intensity profiles of the corresponding image line (in another window). |
| Yes, that sounds quite complex for a first code, but don't worry, it will be very simple using the CImg library ! Well, just look |
| at the code below, it does the task : |
| |
| \code |
| #include "CImg.h" |
| using namespace cimg_library; |
| |
| int main() { |
| CImg<unsigned char> image("lena.jpg"), visu(500,400,1,3,0); |
| const unsigned char red[] = { 255,0,0 }, green[] = { 0,255,0 }, blue[] = { 0,0,255 }; |
| image.blur(2.5); |
| CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile"); |
| while (!main_disp.is_closed() && !draw_disp.is_closed()) { |
| main_disp.wait(); |
| if (main_disp.button() && main_disp.mouse_y()>=0) { |
| const int y = main_disp.mouse_y(); |
| visu.fill(0).draw_graph(image.get_crop(0,y,0,0,image.width()-1,y,0,0),red,1,1,0,255,0); |
| visu.draw_graph(image.get_crop(0,y,0,1,image.width()-1,y,0,1),green,1,1,0,255,0); |
| visu.draw_graph(image.get_crop(0,y,0,2,image.width()-1,y,0,2),blue,1,1,0,255,0).display(draw_disp); |
| } |
| } |
| return 0; |
| } |
| \endcode |
| |
| Here is a screenshot of the resulting program : |
| |
| <img SRC="../img/tutorial.jpg"> |
| |
| And here is the detailled explanation of the source, line by line : |
| |
| \code #include "CImg.h" \endcode |
| Include the main and only header file of the CImg library. |
| \code using namespace cimg_library; \endcode |
| Use the library namespace to ease the declarations afterward. |
| \code int main() { \endcode |
| Definition of the main function. |
| \code CImg<unsigned char> image("lena.jpg"), visu(500,400,1,3,0); \endcode |
| Creation of two instances of images of \c unsigned \c char pixels. |
| The first image \c image is initialized by reading an image file from the disk. |
| Here, <tt>lena.jpg</tt> must be in the same directory as the current program. |
| Note that you must also have installed the \e ImageMagick package in order to be able to read JPG images. |
| The second image \c visu is initialized as a black color image with dimension <tt>dx=500</tt>, <tt>dy=400</tt>, |
| <tt>dz=1</tt> (here, it is a 2D image, not a 3D one), and <tt>dv=3</tt> (each pixel has 3 'vector' channels R,G,B). |
| The last argument in the constructor defines the default value of the pixel values |
| (here \c 0, which means that \c visu will be initially black). |
| \code const unsigned char red[] = { 255,0,0 }, green[] = { 0,255,0 }, blue[] = { 0,0,255 }; \endcode |
| Definition of three different colors as array of unsigned char. This will be used to draw plots with different colors. |
| \code image.blur(2.5); \endcode |
| Blur the image, with a gaussian blur and a standard variation of 2.5. Note that most of the CImg functions have two versions : |
| one that acts in-place (which is the case of blur), and one that returns the result as a new image (the name of the function |
| begins then with <tt>get_</tt> ). In this case, one could have also written <tt>image = image.get_blur(2.5);</tt> |
| (more expensive, since it needs an additional copy operation). |
| \code CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile"); \endcode |
| Creation of two display windows, one for the input image image, and one for the image visu which will be display intensity profiles. |
| By default, CImg displays handles events (mouse,keyboard,..). On Windows, there is a way to create fullscreen displays. |
| \code while (!main_disp.is_closed() && !draw_disp.is_closed()) { \endcode |
| Enter the event loop, the code will exit when one of the two display windows is closed. |
| \code main_disp.wait(); \endcode |
| Wait for an event (mouse, keyboard,..) in the display window \c main_disp. |
| \code if (main_disp.button() && main_disp.mouse_y()>=0) { \endcode |
| Test if the mouse button has been clicked on the image area. |
| One may distinguish between the 3 different mouse buttons, |
| but in this case it is not necessary |
| \code const int y = main_disp.mouse_y(); \endcode |
| Get the image line y-coordinate that has been clicked. |
| \code visu.fill(0).draw_graph(image.get_crop(0,y,0,0,image.width()-1,y,0,0),red,1,0,256,0); \endcode |
| This line illustrates the pipeline property of most of the CImg class functions. The first function <tt>fill(0)</tt> simply sets |
| all pixel values with 0 (i.e. clear the image \c visu). The interesting thing is that it returns a reference to |
| \c visu and then, can be pipelined with the function \c draw_graph() which draws a plot in the image \c visu. |
| The plot data are given by another image (the first argument of \c draw_graph()). In this case, the given image is |
| the red-component of the line y of the original image, retrieved by the function \c get_crop() which returns a |
| sub-image of the image \c image. Remember that images coordinates are 4D (x,y,z,c) and for color images, |
| the R,G,B channels are respectively given by <tt>v=0, v=1</tt> and <tt>v=2</tt>. |
| \code visu.draw_graph(image.get_crop(0,y,0,1,image.width()-1,y,0,1),green,1,0,256,0); \endcode |
| Plot the intensity profile for the green channel of the clicked line. |
| \code visu.draw_graph(image.get_crop(0,y,0,2,image.width()-1,y,0,2),blue,1,0,256,0).display(draw_disp); \endcode |
| Same thing for the blue channel. Note how the function (which return a reference to \c visu) is pipelined with the function |
| \c display() that just paints the image visu in the corresponding display window. |
| \code ...till the end \endcode |
| I don't think you need more explanations ! |
| |
| As you have noticed, the CImg library allows to write very small and intuitive code. Note also that this source will perfectly |
| work on Unix and Windows systems. Take also a look to the examples provided in the CImg package ( |
| directory \c examples/ ). It will show you how CImg-based code can be surprisingly small. |
| Moreover, there is surely one example close to what you want to do. |
| A good start will be to look at the file <tt>CImg_demo.cpp</tt> which contains small and various examples of what you can do |
| with the %CImg Library. All CImg classes are used in this source, and the code can be easily modified to see what happens. |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| Using drawing functions |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_drawing Using Drawing Functions. */ |
| /*@{*/ |
| /** |
| \page foo5 |
| |
| \section s5 Using Drawing Functions. |
| |
| This section tells more about drawing features in CImg images. |
| Drawing functions list can be found in <a href="structCImg.html">the CImg functions list</a> |
| (section \b Drawing Functions), |
| and are all defined on a common basis. Here are the important points to understand before using |
| drawing functions : |
| |
| - Drawing is performed on the instance image. Drawing functions parameters |
| are defined as \e const variables and return a reference to the current instance <tt>(*this)</tt>, |
| so that drawing functions can be pipelined (see examples below). |
| Drawing is usually done in 2D color images but can be performed in 3D images with any vector-valued dimension, |
| and with any possible pixel type. |
| |
| - A color parameter is always needed to draw features in an image. The color must be defined as a C-style array |
| whose dimension is at least |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| Using image loops |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_loops Using Image Loops. */ |
| /*@{*/ |
| /** |
| \page foo_lo |
| The %CImg Library provides different macros that define useful iterative loops over an image. |
| Basically, it can be used to replace one or several <tt>for(..)</tt> instructions, but it also proposes |
| interesting extensions to classical loops. |
| Below is a list of all existing loop macros, classified in four different categories : |
| - \ref lo1 |
| - \ref lo4 |
| - \ref lo5 |
| - \ref lo6 |
| |
| \section lo1 Loops over the pixel buffer |
| |
| Loops over the pixel buffer are really basic loops that iterate a pointer on the pixel data buffer |
| of a \c cimg_library::CImg image. Two macros are defined for this purpose : |
| |
| - \b cimg_for(img,ptr,T) : |
| This macro loops over the pixel data buffer of the image \c img, using a pointer <tt>T* ptr</tt>, |
| starting from the beginning of the buffer (first pixel) till the end of the buffer (last pixel). |
| - \c img must be a (non empty) \c cimg_library::CImg image of pixels \c T. |
| - \c ptr is a pointer of type \c T*. |
| This kind of loop should not appear a lot in your own source code, since this is a low-level loop |
| and many functions of the CImg class may be used instead. Here is an example of use : |
| \code |
| CImg<float> img(320,200); |
| cimg_for(img,ptr,float) { *ptr=0; } // Equivalent to 'img.fill(0);' |
| \endcode |
| |
| - \b cimg_rof(img,ptr,T) : |
| This macro does the same as \c cimg_for() but from the end to the beginning of the pixel buffer. |
| |
| - \b cimg_foroff(img,off) : |
| This macro loops over the pixel data buffer of the image \c img, using an offset \c , |
| starting from the beginning of the buffer (first pixel, \c off=0) |
| till the end of the buffer (last pixel value, <tt>off = img.size()-1</tt>). |
| - \c img must be a (non empty) cimg_library::CImg<T> image of pixels \c T. |
| - \c off is an inner-loop variable, only defined inside the scope of the loop. |
| |
| Here is an example of use : |
| \code |
| CImg<float> img(320,200); |
| cimg_foroff(img,off) { img[off]=0; } // Equivalent to 'img.fill(0);' |
| \endcode |
| |
| \section lo4 Loops over image dimensions |
| |
| The following loops are probably the most used loops in image processing programs. |
| They allow to loop over the image along one or several dimensions, along a raster scan course. |
| Here is the list of such loop macros for a single dimension : |
| - \b cimg_forX(img,x) : equivalent to : <tt>for (int x = 0; x<img.width(); ++x)</tt>. |
| - \b cimg_forY(img,y) : equivalent to : <tt>for (int y = 0; y<img.height(); ++y)</tt>. |
| - \b cimg_forZ(img,z) : equivalent to : <tt>for (int z = 0; z<img.depth(); ++z)</tt>. |
| - \b cimg_forC(img,c) : equivalent to : <tt>for (int c = 0; c<img.spectrum(); ++c)</tt>. |
| |
| Combinations of these macros are also defined as other loop macros, allowing to loop directly over 2D, 3D or 4D images : |
| - \b cimg_forXY(img,x,y) : equivalent to : \c cimg_forY(img,y) \c cimg_forX(img,x). |
| - \b cimg_forXZ(img,x,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forX(img,x). |
| - \b cimg_forYZ(img,y,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forY(img,y). |
| - \b cimg_forXC(img,x,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forX(img,x). |
| - \b cimg_forYC(img,y,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forY(img,y). |
| - \b cimg_forZC(img,z,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forZ(img,z). |
| - \b cimg_forXYZ(img,x,y,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forXY(img,x,y). |
| - \b cimg_forXYC(img,x,y,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forXY(img,x,y). |
| - \b cimg_forXZC(img,x,z,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forXZ(img,x,z). |
| - \b cimg_forYZC(img,y,z,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forYZ(img,y,z). |
| - \b cimg_forXYZC(img,x,y,z,c) : equivalent to : \c cimg_forC(img,c) \c cimg_forXYZ(img,x,y,z). |
| |
| - For all these loops, \c x,\c y,\c z and \c v are inner-defined variables only visible inside the scope of the loop. |
| They don't have to be defined before the call of the macro. |
| - \c img must be a (non empty) cimg_library::CImg image. |
| |
| Here is an example of use that creates an image with a smooth color gradient : |
| \code |
| CImg<unsigned char> img(256,256,1,3); // Define a 256x256 color image |
| cimg_forXYC(img,x,y,c) { img(x,y,c) = (x+y)*(c+1)/6; } |
| img.display("Color gradient"); |
| \endcode |
| |
| \section lo5 Loops over interior regions and borders. |
| |
| Similar macros are also defined to loop only on the border of an image, or inside the image (excluding the border). |
| The border may be several pixel wide : |
| |
| - \b cimg_for_insideX(img,x,n) : Loop along the x-axis, except for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_insideY(img,y,n) : Loop along the y-axis, except for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_insideZ(img,z,n) : Loop along the z-axis, except for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_insideC(img,c,n) : Loop along the c-axis, except for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_insideXY(img,x,y,n) : Loop along the (x,y)-axes, excepted for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_insideXYZ(img,x,y,z,n) : Loop along the (x,y,z)-axes, excepted for pixels inside a border of \p n pixels wide. |
| |
| And also : |
| |
| - \b cimg_for_borderX(img,x,n) : Loop along the x-axis, only for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_borderY(img,y,n) : Loop along the y-axis, only for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_borderZ(img,z,n) : Loop along the z-axis, only for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_borderC(img,c,n) : Loop along the c-axis, only for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_borderXY(img,x,y,n) : Loop along the (x,y)-axes, only for pixels inside a border of \p n pixels wide. |
| - \b cimg_for_borderXYZ(img,x,y,z,n) : Loop along the (x,y,z)-axes, only for pixels inside a border of \p n pixels wide. |
| |
| - For all these loops, \c x,\c y,\c z and \c c are inner-defined variables only visible inside the scope of the loop. |
| They don't have to be defined before the call of the macro. |
| - \c img must be a (non empty) cimg_library::CImg image. |
| - The constant \c n stands for the size of the border. |
| |
| Here is an example of use, to create a 2d grayscale image with two different intensity gradients : |
| \code |
| CImg<> img(256,256); |
| cimg_for_insideXY(img,x,y,50) img(x,y) = x+y; |
| cimg_for_borderXY(img,x,y,50) img(x,y) = x-y; |
| img.display(); |
| \endcode |
| |
| \section lo6 Loops using neighborhoods. |
| |
| Inside an image loop, it is often useful to get values of neighborhood pixels of the |
| current pixel at the loop location. |
| The %CImg Library provides a very smart and fast mechanism for this purpose, with the definition |
| of several loop macros that remember the neighborhood values of the pixels. |
| The use of these macros can highly optimize your code, and also simplify your program. |
| |
| \subsection lo7 Neighborhood-based loops for 2D images |
| |
| For 2D images, the neighborhood-based loop macros are : |
| |
| - \b cimg_for2x2(img,x,y,z,c,I,T) : Loop along the (x,y)-axes using a centered 2x2 neighborhood. |
| - \b cimg_for3x3(img,x,y,z,c,I,T) : Loop along the (x,y)-axes using a centered 3x3 neighborhood. |
| - \b cimg_for4x4(img,x,y,z,c,I,T) : Loop along the (x,y)-axes using a centered 4x4 neighborhood. |
| - \b cimg_for5x5(img,x,y,z,c,I,T) : Loop along the (x,y)-axes using a centered 5x5 neighborhood. |
| |
| For all these loops, \c x and \c y are inner-defined variables only visible inside the scope of the loop. |
| They don't have to be defined before the call of the macro. |
| \c img is a non empty CImg<T> image. \c z and \c c are constants that define on which image slice and |
| vector channel the loop must apply (usually both 0 for grayscale 2D images). |
| Finally, \c I is the 2x2, 3x3, 4x4 or 5x5 neighborhood of type \c T that will be updated with the correct pixel values |
| during the loop (see \ref lo9). |
| |
| \subsection lo8 Neighborhood-based loops for 3D images |
| |
| For 3D images, the neighborhood-based loop macros are : |
| |
| - \b cimg_for2x2x2(img,x,y,z,c,I,T) : Loop along the (x,y,z)-axes using a centered 2x2x2 neighborhood. |
| - \b cimg_for3x3x3(img,x,y,z,c,I,T) : Loop along the (x,y,z)-axes using a centered 3x3x3 neighborhood. |
| |
| For all these loops, \c x, \c y and \c z are inner-defined variables only visible inside the scope of the loop. |
| They don't have to be defined before the call of the macro. |
| \c img is a non empty CImg<T> image. \c c is a constant that defines on which image channel |
| the loop must apply (usually 0 for grayscale 3D images). |
| Finally, \c I is the 2x2x2 or 3x3x3 neighborhood of type \c T that will be updated with the correct pixel values |
| during the loop (see \ref lo9). |
| |
| \subsection lo9 Defining neighborhoods |
| |
| A neighborhood is defined as an instance of a class having operator[] defined. |
| This particularly includes classical C-array, as well as CImg<T> objects. |
| |
| For instance, a 3x3 neighborhood can be defined either as a 'float[9]' or a |
| 'CImg<float>(3,3)' variable. |
| |
| \subsection lo10 Using alternate variable names |
| |
| There are also some useful macros that can be used to define variables that |
| reference the neighborhood elements. There are : |
| |
| - \b CImg_2x2(I,type) : Define a 2x2 neighborhood named \c I, of type \c type. |
| - \b CImg_3x3(I,type) : Define a 3x3 neighborhood named \c I, of type \c type. |
| - \b CImg_4x4(I,type) : Define a 4x4 neighborhood named \c I, of type \c type. |
| - \b CImg_5x5(I,type) : Define a 5x5 neighborhood named \c I, of type \c type. |
| - \b CImg_2x2x2(I,type) : Define a 2x2x2 neighborhood named \c I, of type \c type. |
| - \b CImg_3x3x3(I,type) : Define a 3x3x3 neighborhood named \c I, of type \c type. |
| |
| Actually, \c I is a \e generic \e name for the neighborhood. In fact, these macros declare |
| a \e set of new variables. |
| For instance, defining a 3x3 neighborhood \c CImg_3x3(I,float) declares 9 different float variables |
| \c Ipp,\c Icp,\c Inp,\c Ipc,\c Icc,\c Inc,\c Ipn,\c Icn,\c Inn which correspond to each pixel value of |
| a 3x3 neighborhood. |
| Variable indices are \c p,\c c or \c n, and stand respectively for \e 'previous', \e 'current' and \e 'next'. |
| First indice denotes the \c x-axis, second indice denotes the \c y-axis. |
| Then, the names of the variables are directly related to the position of the corresponding pixels |
| in the neighborhood. For 3D neighborhoods, a third indice denotes the \c z-axis. |
| Then, inside a neighborhood loop, you will have the following equivalence : |
| - <tt>Ipp = img(x-1,y-1)</tt> |
| - <tt>Icn = img(x,y+1)</tt> |
| - <tt>Inp = img(x+1,y-1)</tt> |
| - <tt>Inpc = img(x+1,y-1,z)</tt> |
| - <tt>Ippn = img(x-1,y-1,z+1)</tt> |
| - and so on... |
| |
| For bigger neighborhoods, such as 4x4 or 5x5 neighborhoods, two additionnal indices are introduced : |
| \c a (stands for \e 'after') and \c b (stands for \e 'before'), so that : |
| - <tt>Ibb = img(x-2,y-2)</tt> |
| - <tt>Ina = img(x+1,y+2)</tt> |
| - and so on... |
| |
| The value of a neighborhood pixel outside the image range (image border problem) is automatically set to the same |
| values as the nearest valid pixel in the image (this is also called the \e Neumann \e border \e condition). |
| |
| \subsection lo11 Example codes |
| More than a long discussion, the above example will demonstrate how to compute the gradient norm of a 3D volume |
| using the \c cimg_for3x3x3() loop macro : |
| |
| \code |
| CImg<float> volume("IRM.hdr"); // Load an IRM volume from an Analyze7.5 file |
| CImg_3x3x3(I,float); // Define a 3x3x3 neighborhood |
| CImg<float> gradnorm(volume); // Create an image with same size as 'volume' |
| cimg_for3x3x3(volume,x,y,z,0,I,float) { // Loop over the volume, using the neighborhood I |
| const float ix = 0.5f*(Incc-Ipcc); // Compute the derivative along the x-axis. |
| const float iy = 0.5f*(Icnc-Icpc); // Compute the derivative along the y-axis. |
| const float iz = 0.5f*(Iccn-Iccp); // Compute the derivative along the z-axis. |
| gradnorm(x,y,z) = std::sqrt(ix*ix+iy*iy+iz*iz); // Set the gradient norm in the destination image |
| } |
| gradnorm.display("Gradient norm"); |
| \endcode |
| |
| And the following example shows how to deal with neighborhood references to blur a color image by averaging |
| pixel values on a 5x5 neighborhood. |
| |
| \code |
| CImg<unsigned char> src("image_color.jpg"), dest(src,false); // Image definitions. |
| typedef unsigned char uchar; // Avoid space in the second parameter of the macro CImg_5x5x1 below. |
| CImg<> N(5,5); // Define a 5x5 neighborhood as a 5x5 image. |
| cimg_forC(src,k) // Standard loop on color channels |
| cimg_for5x5(src,x,y,0,k,N,float) // 5x5 neighborhood loop. |
| dest(x,y,k) = N.sum()/(5*5); // Averaging pixels to filter the color image. |
| CImgList<unsigned char> visu(src,dest); |
| visu.display("Original + Filtered"); // Display both original and filtered image. |
| \endcode |
| |
| As you can see, explaining the use of the CImg neighborhood macros is actually more difficult than using them ! |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| Using display windows |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_displays Using Display Windows. */ |
| /*@{*/ |
| /** |
| \page foo_di |
| |
| When opening a display window, you can choose the way the pixel values will be normalized |
| before being displayed on the screen. Screen displays only support color values between [0,255], |
| and some |
| |
| When displaying an image into the display window using CImgDisplay::display(), values of |
| the image pixels can be eventually linearly normalized between [0,255] for visualization purposes. |
| This may be useful for instance when displaying \p CImg<double> images with pixel values |
| between [0,1]. |
| The normalization behavior depends on the value of \p normalize which can be either \p 0,\p 1 or \p 2 : |
| - \p 0 : No pixel normalization is performed when displaying an image. This is the fastest |
| process, but you must be sure your displayed image have pixel values inside the range [0,255]. |
| - \p 1 : Pixel value normalization is done for each new image display. Image pixels are |
| not modified themselves, only displayed pixels are normalized. |
| - \p 2 : Pixel value normalization is done for the first image display, then the |
| normalization parameters are kept and used for all the next image displays. |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| How pixel data are stored |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_storage How pixel data are stored with CImg. */ |
| /*@{*/ |
| /** |
| \page foo_store |
| |
| First, CImg<T> are *very* basic structures, which means that there are no memory tricks, weird memory alignments or |
| disk caches used to store pixel data of images. When an image is instanced, all its pixel values are stored in memory at |
| the same time (yes, you should avoid working with huge images when dealing with CImg, if you have only 64kb of RAM). |
| |
| A CImg<T> is basically a 4th-dimensional array (width,height,depth,dim), and its pixel data are stored linearly in a single |
| memory buffer of general size (width*height*depth*dim). Nothing more, nothing less. The address of this memory buffer can be |
| retrieved by the function CImg<T>::data(). |
| As each image value is stored as a type T (T being known by the programmer of course), this pointer is a 'T*', or a 'const T*' if your image is 'const'. |
| so, 'T *ptr = img.data()' gives you the pointer to the first value of the image 'img'. The overall size of the used memory for one |
| instance image (in bytes) is then 'width*height*depth*dim*sizeof(T)'. |
| |
| Now, the ordering of the pixel values in this buffer follows these rules : |
| The values are *not* interleaved, and are ordered first along the X,Y,Z and V axis respectively (corresponding to the width,height,depth,dim dimensions), |
| starting from the upper-left pixel to the bottom-right pixel of the instane image, with a classical scanline run. |
| |
| So, a color image with dim=3 and depth=1, will be stored in memory as : |
| |
| R1R2R3R4R5R6......G1G2G3G4G5G6.......B1B2B3B4B5B6.... (i.e following a 'planar' structure) |
| |
| and *not* as R1G1B1R2G2B2R3G3B3... (interleaved channels), |
| where R1 = img(0,0,0,0) is the first upper-left pixel of the red component of the image, |
| R2 is img(1,0,0,0), G1 = img(0,0,0,1), G2 = img(1,0,0,1), B1 = img(0,0,0,2), and so on... |
| |
| Another example, a (1x5x1x1) CImg<T> (column vector A) will be stored as : A1A2A3A4A5 |
| where A1 = img(0,0), A2 = img(0,1), ... , A5 = img(0,4). |
| |
| As you see, it is *very* simple and intuitive : no interleaving, no padding, just simple. |
| This is cool not only because it is simple, but this has in fact a number of interesting properties. For instance, a 2D color image |
| is stored in memory exactly as a 3D scalar image having a depth=3, meaning that when you are dealing with 2D color images, you can write 'img(x,y,k)' |
| instead of 'img(x,y,0,k)' to access the kth channel of the (x,y) pixel. More generally, if you have one dimension that is 1 in |
| your image, you can just skip it in the call to the operator(). Similarly, values of a column vector stored as an image with |
| width=depth=spectrum=1 can be accessed by 'img(y)' instead of 'img(0,y)'. This is very convenient. |
| |
| Another cool thing is that it allows you to work easily with 'shared' images. A shared image is a CImg<T> instance that shares |
| its memory with another one (the 'base' image). Destroying a shared image does nothing in fact. Shared images is a convenient |
| way of modifying only *portions* (consecutive in memory) of an image. For instance, if 'img' is a 2D color image, you can write : |
| |
| img.get_shared_channel(0).blur(2); |
| img.get_shared_channels(1,2).mirror('x'); |
| |
| which just blur the red channel of the image, and mirror the two others along the X-axis. |
| This is possible since channels of an image are not interleaved but are stored as different consecutive planes in memory, so you see that constructing a shared image is possible (and trivial). |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| Files IO |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_files_io Files IO in CImg. */ |
| /*@{*/ |
| /** |
| \page foo_fi |
| |
| The %CImg Library can NATIVELY handle the following file formats : |
| - RAW : consists in a very simple header (in ascii), then the image data. |
| - ASC (Ascii) |
| - HDR (Analyze 7.5) |
| - INR (Inrimage) |
| - PPM/PGM (Portable Pixmap) |
| - BMP (uncompressed) |
| - PAN (Pandore-5) |
| - DLM (Matlab ASCII) |
| |
| If ImageMagick is installed, The %CImg Library can save image in formats handled by ImageMagick : JPG, GIF, PNG, TIF,... |
| |
| **/ |
| /*@}*/ |
| |
| /*----------------------------------- |
| |
| Retrieving command line arguments |
| |
| -------------------------------------*/ |
| |
| /** \addtogroup cimg_options Retrieving Command Line Arguments. */ |
| /*@{*/ |
| /** |
| \page foo_so |
| |
| The CImg library offers facilities to retrieve command line arguments in a console-based |
| program, as it is a commonly needed operation. |
| Three macros \c cimg_usage(), \c cimg_help() and \c cimg_option() are defined for this purpose. |
| Using these macros allows to easily retrieve options values from the command line. |
| Invoking the compiled executable with the option \c -h or \c --help will |
| automatically display the program usage, followed by the list of requested options. |
| |
| \section so1 The cimg_usage() macro |
| |
| The macro \c cimg_usage(usage) may be used to describe the program goal and usage. |
| It is generally inserted one time after the <tt>int main(int argc,char **argv)</tt> definition. |
| |
| \param usage : A string describing the program goal and usage. |
| \pre The function where \c cimg_usage() is used must have correctly defined \c argc and \c argv variables. |
| |
| \section so1_5 The cimg_help() macro |
| |
| The macro \c cimg_help(str) will display the string \c str only if the \c -help or \c --help option |
| are invoked when running the programm. |
| |
| \section so2 The cimg_option() macro |
| |
| The macro \c cimg_option(name,default,usage) may be used to retrieve an option value from the command line. |
| |
| \param name : The name of the option to be retrieved from the command line. |
| \param default : The default value returned by the macro if no options \p name has been specified when running the program. |
| \param usage : A brief explanation of the option. If \c usage==0, the option won't appear on the option list |
| when invoking the executable with options \c -h or \c --help (hidden option). |
| |
| \return \c cimg_option() returns an object that has the \e same \e type as the default value \c default. |
| The return value is equal to the one specified on the command line. If no such option have been specified, |
| the return value is equal to the default value \c default. |
| Warning, this can be confusing in some situations (look at the end of the next section). |
| \pre The function where \c cimg_option() is used must have correctly defined \c argc and \c argv variables. |
| |
| \section so3 Example of use |
| |
| The code below uses the macros \c cimg_usage() and \c cimg_option(). |
| It loads an image, smoothes it an quantifies it with a specified number of values. |
| \code |
| #include "CImg.h" |
| using namespace cimg_library; |
| int main(int argc,char **argv) { |
| cimg_usage("Retrieve command line arguments"); |
| const char* filename = cimg_option("-i","image.gif","Input image file"); |
| const char* output = cimg_option("-o",(char*)0,"Output image file"); |
| const double sigma = cimg_option("-s",1.0,"Standard variation of the gaussian smoothing"); |
| const int nblevels = cimg_option("-n",16,"Number of quantification levels"); |
| const bool hidden = cimg_option("-hidden",false,0); // This is a hidden option |
| |
| CImg<unsigned char> img(filename); |
| img.blur(sigma).quantize(nblevels); |
| if (output) img.save(output); else img.display("Output image"); |
| if (hidden) std::fprintf(stderr,"You found me !\n"); |
| return 0; |
| } |
| \endcode |
| |
| Invoking the corresponding executable with <tt>test -h -hidden -n 20 -i foo.jpg</tt> will display : |
| \verbatim |
| ./test -h -hidden -n 20 -i foo.jpg |
| |
| test : Retrieve command line arguments (Oct 16 2004, 12:34:26) |
| |
| -i = foo.jpg : Input image file |
| -o = 0 : Output image file |
| -s = 1 : Standard variation of the gaussian smoothing |
| -n = 20 : Number of quantification levels |
| |
| You found me ! |
| \endverbatim |
| |
| \warning As the type of object returned by the macro \c cimg_option(option,default,usage) |
| is defined by the type of \c default, undesired casts may appear when writting code such as : |
| \code |
| const double sigma = cimg_option("-val",0,"A floating point value"); |
| \endcode |
| In this case, \c sigma will always be equal to an integer (since the default value \c 0 is an integer). |
| When passing a float value on the command line, a \e float \e to \e integer cast is then done, |
| truncating the given parameter to an integer value (this is surely not a desired behavior). |
| You must specify <tt>0.0</tt> as the default value in this case. |
| |
| \section so4 How to learn more about command line options ? |
| You should take a look at the examples <tt>examples/gmic.cpp</tt> provided in the %CImg Library package. |
| This is a command line based image converter which intensively uses the \c cimg_option() and \c cimg_usage() |
| macros to retrieve command line parameters. |
| **/ |
| /*@}*/ |