1.1 diff -r 5edfbd3e7a46 -r 1204ebf9340d PTdecode/CImg-1.3.0/html/CImg_documentation.h 1.2 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.3 +++ b/PTdecode/CImg-1.3.0/html/CImg_documentation.h Mon Aug 03 14:09:20 2009 +0100 1.4 @@ -0,0 +1,1162 @@ 1.5 +/*------------------------------------------------------------------------ 1.6 +# 1.7 +# File : CImg_documentation.h 1.8 +# 1.9 +# Description : Extra documentation file for the CImg Library. 1.10 +# Used by doxygen to generate the reference documentation. 1.11 +# ( http://cimg.sourceforge.net ) 1.12 +# 1.13 +# Copyright : David Tschumperle 1.14 +# ( http://www.greyc.ensicaen.fr/~dtschump/ ) 1.15 +# 1.16 +# 1.17 +-------------------------------------------------------------------------*/ 1.18 + 1.19 +/*----------------------------------- 1.20 + 1.21 + Main reference documentation page 1.22 + 1.23 + -------------------------------------*/ 1.24 + 1.25 +/** 1.26 + \mainpage 1.27 + 1.28 + This is the reference documentation of <a href="http://cimg.sourceforge.net">the CImg Library</a>, 1.29 + the C++ template image processing library. 1.30 + This documentation have been generated using the tool <a href="http://www.doxygen.org">doxygen</a>. 1.31 + It contains a detailed description of all classes and functions of the %CImg Library. 1.32 + If you have downloaded the CImg package, you actually have a local copy of these pages in the 1.33 + \c CImg/html/reference/ directory. 1.34 + 1.35 + Use the menu above to navigate through the documentation pages. 1.36 + As a first step, you may look at the list of <a href="modules.html">available modules</a>. 1.37 + 1.38 + A complete PDF version of this reference documentation is 1.39 + <a href="../CImg_reference.pdf">available here</a> for off-line reading. 1.40 + 1.41 + A partial translation in Chinese is <a href="../CImg_reference_chinese.pdf">available here</a>. 1.42 + 1.43 + You may be interested also in the 1.44 + <a href="../CImg_slides.pdf">presentation slides</a> presenting an overview 1.45 + of the %CImg Library capabilities. 1.46 + 1.47 +**/ 1.48 + 1.49 +/*----------------------------------- 1.50 + 1.51 + CImg Library overview 1.52 + 1.53 + -------------------------------------*/ 1.54 + 1.55 +/** \addtogroup cimg_overview CImg Library Overview */ 1.56 +/*@{*/ 1.57 +/** 1.58 + \page foo2 1.59 + 1.60 + The <b>CImg Library</b> is an image processing library, designed for C++ programmers. 1.61 + It provides useful classes and functions to load/save, display and process various types of images. 1.62 + 1.63 + \section s1 Library structure 1.64 + 1.65 + The %CImg Library consists in a <b>single header file</b> CImg.h providing a set of C++ template classes that 1.66 + can be used in your own sources, to load/save, process and display images or list of images. 1.67 + Very portable (Unix/X11,Windows, MacOS X, FreeBSD,..), efficient, simple to use, it's a pleasant toolkit 1.68 + for coding image processing stuffs in C++. 1.69 + 1.70 + The header file CImg.h contains all the classes and functions that compose the library itself. 1.71 + This is one originality of the %CImg Library. This particularly means that : 1.72 + - No pre-compilation of the library is needed, since the compilation of the CImg functions is done at the same time as 1.73 + the compilation of your own C++ code. 1.74 + - No complex dependencies have to be handled : Just include the CImg.h file, and you get a working C++ image processing toolkit. 1.75 + - The compilation is done on the fly : only CImg functionalities really used by your program are compiled and appear in the 1.76 + compiled executable program. This leads to very compact code, without any unused stuffs. 1.77 + - Class members and functions are inlined, leading to better performance during the program execution. 1.78 + 1.79 + The %CImg Library is structured as follows : 1.80 + 1.81 + - All library classes and functions are defined in the namespace \ref cimg_library. This namespace 1.82 + encapsulates the library functionalities and avoid any class name collision that could happen with 1.83 + other includes. Generally, one uses this namespace as a default namespace : 1.84 + \code 1.85 + #include "CImg.h" 1.86 + using namespace cimg_library; 1.87 + ... 1.88 + \endcode 1.89 + 1.90 + - The namespace \ref cimg_library::cimg defines a set of \e low-level functions and variables used by the library. 1.91 + Documented functions in this namespace can be safely used in your own program. But, \b never use the 1.92 + \ref cimg_library::cimg namespace as a default namespace, since it contains functions whose names are already 1.93 + defined in the standard C/C++ library. 1.94 + 1.95 + - The class \ref cimg_library::CImg<T> represents images up to 4-dimensions wide, containing pixels of type \c T 1.96 + (template parameter). This is actually the main class of the library. 1.97 + 1.98 + - The class \ref cimg_library::CImgList<T> represents lists of cimg_library::CImg<T> images. It can be used for instance 1.99 + to store different frames of an image sequence. 1.100 + 1.101 + - The class \ref cimg_library::CImgDisplay is able to display images or image lists into graphical display windows. 1.102 + As you may guess, the code of this class is highly system-dependent but this is transparent for the programmer, 1.103 + as environment variables are automatically set by the CImg library (see also \ref cimg_environment). 1.104 + 1.105 + - The class \ref cimg_library::CImgException (and its subclasses) are used by the library to throw exceptions 1.106 + when errors occur. Those exceptions can be catched with a bloc <tt>try { ..} catch (CImgException) { .. }</tt>. 1.107 + Subclasses define precisely the type of encountered errors. 1.108 + 1.109 + Knowing these four classes is \b enough to get benefit of the %CImg Library functionalities. 1.110 + 1.111 + 1.112 + \section s2 CImg version of "Hello world". 1.113 + 1.114 + Below is a very simple code that creates a "Hello World" image. This shows you basically how a CImg program looks like. 1.115 + 1.116 + \code 1.117 + #include "CImg.h" 1.118 + using namespace cimg_library; 1.119 + 1.120 + int main() { 1.121 + CImg<unsigned char> img(640,400,1,3); // Define a 640x400 color image with 8 bits per color component. 1.122 + img.fill(0); // Set pixel values to 0 (color : black) 1.123 + unsigned char purple[] = { 255,0,255 }; // Define a purple color 1.124 + img.draw_text("Hello World",100,100,purple); // Draw a purple "Hello world" at coordinates (100,100). 1.125 + img.display("My first CImg code"); // Display the image in a display window. 1.126 + return 0; 1.127 + } 1.128 + \endcode 1.129 + 1.130 + Which can be also written in a more compact way as : 1.131 + 1.132 + \code 1.133 + #include "CImg.h" 1.134 + using namespace cimg_library; 1.135 + 1.136 + int main() { 1.137 + const unsigned char purple[] = { 255,0,255 }; 1.138 + CImg<unsigned char>(640,400,1,3,0).draw_text("Hello World",100,100,purple).display("My first CImg code"); 1.139 + return 0; 1.140 + } 1.141 + \endcode 1.142 + 1.143 + Generally, you can write very small code that performs complex image processing tasks. The %CImg Library is very simple 1.144 + to use and provide a lot of interesting algorithms for image manipulation. 1.145 + 1.146 + \section s3 How to compile ? 1.147 + 1.148 + The CImg library is a very light and user-friendly library : only standard system libraries are used. 1.149 + It avoid to handle complex dependancies and problems with library compatibility. 1.150 + The only thing you need is a (quite modern) C++ compiler : 1.151 + 1.152 + - <b>Microsoft Visual C++ 6.0, Visual Studio.NET and Visual Express Edition</b> : Use project files and solution files provided in the 1.153 + %CImg Library package (directory 'compilation/') to see how it works. 1.154 + - <b>Intel ICL compiler</b> : Use the following command to compile a CImg-based program with ICL : 1.155 + \code 1.156 + icl /Ox hello_world.cpp user32.lib gdi32.lib 1.157 + \endcode 1.158 + - <b>g++ (MingW windows version)</b> : Use the following command to compile a CImg-based program with g++, on Windows : 1.159 + \code 1.160 + g++ -o hello_word.exe hello_word.cpp -O2 -lgdi32 1.161 + \endcode 1.162 + - <b>g++ (Linux version)</b> : Use the following command to compile a CImg-based program with g++, on Linux : 1.163 + \code 1.164 + g++ -o hello_word.exe hello_world.cpp -O2 -L/usr/X11R6/lib -lm -lpthread -lX11 1.165 + \endcode 1.166 + - <b>g++ (Solaris version)</b> : Use the following command to compile a CImg-based program with g++, on Solaris : 1.167 + \code 1.168 + g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -R/usr/X11R6/lib -lrt -lnsl -lsocket 1.169 + \endcode 1.170 + - <b>g++ (Mac OS X version)</b> : Use the following command to compile a CImg-based program with g++, on Mac OS X : 1.171 + \code 1.172 + g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -L/usr/X11R6/lib -lm -lpthread -lX11 1.173 + \endcode 1.174 + - <b>Dev-Cpp</b> : Use the project file provided in the CImg library package to see how it works. 1.175 + 1.176 + If you are using another compilers and encounter problems, please 1.177 + <a href="http://www.greyc.ensicaen.fr/~dtschump">write me</a> since maintaining compatibility is one 1.178 + of the priority of the %CImg Library. Nevertheless, old compilers that does not respect the C++ norm will not 1.179 + support the %CImg Library. 1.180 + 1.181 + \section s4 What's next ? 1.182 + 1.183 + If you are ready to get more, and to start writing more serious programs 1.184 + with CImg, you are invited to go to the \ref cimg_tutorial section. 1.185 + 1.186 +**/ 1.187 +/*@}*/ 1.188 + 1.189 +/*---------------------------------- 1.190 + 1.191 + CImg<T> : The image structure 1.192 + 1.193 + --------------------------------*/ 1.194 + 1.195 +/** \addtogroup cimg_structure CImg<T> : The image structure. */ 1.196 +/*@{*/ 1.197 +/** 1.198 + Description of the CImg<T> structure 1.199 + 1.200 + \page foo_cs 1.201 + 1.202 + \section cs0 Structure overview 1.203 + 1.204 + \section cs1 Image construction/destruction/copy 1.205 + 1.206 + \section cs2 Image methods 1.207 + 1.208 + \section cs3 Shared images 1.209 + 1.210 + \section cs4 Low-level structure 1.211 + 1.212 +**/ 1.213 +/*@}*/ 1.214 + 1.215 +/*---------------------------------------- 1.216 + 1.217 + CImgList<T> : The image list structure 1.218 + 1.219 + ---------------------------------------*/ 1.220 + 1.221 +/** \addtogroup cimglist_structure CImgList<T> : The image list structure. */ 1.222 +/*@{*/ 1.223 +/** 1.224 + Description of the CImgList<T> structure 1.225 + 1.226 + \page foo_cls 1.227 + 1.228 + \section cls0 Structure overview 1.229 + 1.230 + \section cls1 Image list construction/destruction/copy 1.231 + 1.232 + \section cls2 Image methods 1.233 + 1.234 + \section cls4 Low-level structure 1.235 + 1.236 +**/ 1.237 +/*@}*/ 1.238 + 1.239 +/*---------------------------------------------- 1.240 + 1.241 + CImgDisplay : The image display structure 1.242 + 1.243 + --------------------------------------------*/ 1.244 + 1.245 +/** \addtogroup cimgdisplay_structure CImgDisplay : The image display structure. */ 1.246 +/*@{*/ 1.247 +/** 1.248 + Description of the CImgDisplay structure 1.249 + 1.250 + \page foo_cds 1.251 + 1.252 + \section cds0 Structure overview 1.253 + 1.254 + \section cds1 Image display construction/destruction/copy 1.255 + 1.256 + \section cds2 Image methods 1.257 + 1.258 + \section cds4 Low-level structure 1.259 + 1.260 +**/ 1.261 +/*@}*/ 1.262 + 1.263 +/*---------------------------------------------- 1.264 + 1.265 + CImgException : The library exception structure 1.266 + 1.267 + --------------------------------------------*/ 1.268 + 1.269 +/** \addtogroup cimgexception_structure CImgException : The library exception structure. */ 1.270 +/*@{*/ 1.271 +/** 1.272 + Description of the CImgException structure 1.273 + 1.274 + \page foo_ces 1.275 + 1.276 + \section ces0 Structure overview 1.277 + 1.278 + 1.279 +**/ 1.280 +/*@}*/ 1.281 + 1.282 + 1.283 +/*----------------------------------- 1.284 + 1.285 + FAQ : Frequently Asked Questions 1.286 + 1.287 + -------------------------------------*/ 1.288 + 1.289 +/** \addtogroup cimg_faq FAQ : Frequently Asked Questions. */ 1.290 +/*@{*/ 1.291 +/** 1.292 + \page foofaq 1.293 + 1.294 + \section ssf0 FAQ Summary 1.295 + 1.296 + - <a href="#sf1">General information and availability</a> 1.297 + - <a href="#ssf11">What is the CImg Library ?</a> 1.298 + - <a href="#ssf12">What platforms are supported ?</a> 1.299 + - <a href="#ssf13">How is CImg distributed ?</a> 1.300 + - <a href="#ssf14">What kind of people are concerned by CImg ?</a> 1.301 + - <a href="#ssf15">What are the specificities of the CeCILL license ?</a> 1.302 + - <a href="#ssf16">Who is behind CImg ?</a> 1.303 + 1.304 + - <a href="#sf2">C++ related questions</a> 1.305 + - <a href="#ssf21">What is the level of C++ knowledge needed to use CImg ?</a> 1.306 + - <a href="#ssf22">How to use CImg in my own C++ program ?</a> 1.307 + - <a href="#ssf23">Why is CImg entirely contained in a single header file ?</a> 1.308 + 1.309 + \section sf1 1. General information and availability 1.310 + 1.311 + \subsection ssf11 1.1. What is the CImg Library ? 1.312 + 1.313 + The CImg Library is an <i>open-source C++ toolkit for image processing</i>.\n 1.314 + 1.315 + It mainly consists in a (big) single header file 1.316 + <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> 1.317 + providing a set of C++ classes and functions that can be used in your own sources, 1.318 + to load/save, manage/process and display generic images. 1.319 + It's actually a very simple and pleasant toolkit for coding image processing stuffs in C++ : 1.320 + Just include the header file <i>CImg.h</i>, and you are ready to handle images in your C++ programs. 1.321 + 1.322 + \subsection ssf12 1.2. What platforms are supported ? 1.323 + 1.324 + CImg has been designed with <i>portability</i> in mind. 1.325 + It is regularly tested on different architectures and compilers, 1.326 + and should also work on any decent OS having a decent C++ compiler. 1.327 + Before each release, the CImg Library is compiled under these different configurations : 1.328 + \li PC Linux 32 bits, with g++. 1.329 + \li PC Windows 32 bits, with Visual C++ 6.0. 1.330 + \li PC Windows 32 bits, with Visual C++ Express Edition. 1.331 + \li Sun SPARC Solaris 32 bits, with g++. 1.332 + \li Mac PPC with OS X and g++. 1.333 + 1.334 + CImg has a minimal number of dependencies. In its minimal version, it can be compiled only with standard C++ headers. 1.335 + Anyway, it has interesting extension capabilities and can use external libraries to perform specific tasks more 1.336 + efficiently (Fourier Transform computation using FFTW for instance). 1.337 + 1.338 + \subsection ssf13 1.3. How is CImg distributed ? 1.339 + 1.340 + The CImg Library is freely distributed as a complete .zip compressed package, hosted at the 1.341 + <a href="http://sourceforge.net/project/showfiles.php?group_id=96492">Sourceforge servers</a>.\n 1.342 + The package is distributed under the <a href="http://www.cecill.info">CeCILL license</a>. 1.343 + 1.344 + This package contains : 1.345 + - The main library file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> (C++ header file). 1.346 + - Several C++ source code showing <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/examples/">examples of using CImg</a>. 1.347 + - A complete library documentation, in <a href="index.html">HTML</a> and <a href="../CImg_reference.pdf">PDF</a> formats. 1.348 + - Additional <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/plugins/">library plug-ins</a> that can be used to extend 1.349 + library capabilities for specific uses. 1.350 + 1.351 + The CImg Library is a quite lightweight library which is easy to maintain (due to its particular structure), and thus 1.352 + has a fast rythm of release. A new version of the CImg package is released approximately every three months. 1.353 + 1.354 + \subsection ssf14 1.4. What kind of people are concerned by CImg ? 1.355 + 1.356 + The CImg library is an <i>image processing</i> library, primarily intended for computer scientists or students working in the fields 1.357 + of image processing or computer vision, and knowing bases of C++. 1.358 + As the library is handy and really easy to use, it can be also used by any programmer 1.359 + needing occasional tools for dealing with images in C++, since there are no standard library yet 1.360 + for this purpose. 1.361 + 1.362 + \subsection ssf15 1.5. What are the specificities of the CeCILL license ? 1.363 + 1.364 + The <a href="http://www.cecill.info">CeCILL license</a> governs the use of the CImg Library. 1.365 + This is an <i>open-source</i> license which gives you rights to access, use, modify and redistribute the source code, 1.366 + under certains conditions. 1.367 + There are two different variants of the CeCILL license used in CImg 1.368 + (namely 1.369 + <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> and 1.370 + <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a>, all open-source), 1.371 + corresponding to different constraints on the source files : 1.372 + - 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 1.373 + the <i>GNU LGPL license</i>, and <i>applies <b>only</b> on the main library file 1.374 + <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a></i>. 1.375 + Basically, this license allows to use <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> 1.376 + in a closed-source product without forcing you to redistribute the entire software source code. Anyway, 1.377 + 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 1.378 + 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. 1.379 + 1.380 + - The <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> license applies to all other files 1.381 + (source examples, plug-ins and documentation) of the CImg Library package, and is close (even <i>compatible</i>) 1.382 + with the <i>GNU GPL license</i>. It <i>does not allow</i> the use of these files in closed-source products. 1.383 + 1.384 + You are invited to read the complete descriptions of the 1.385 + the <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a> 1.386 + and <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> licenses before releasing a 1.387 + software based on the CImg Library. 1.388 + 1.389 + \subsection ssf16 1.6. Who is behind CImg ? 1.390 + 1.391 + CImg has been started by 1.392 + <a href="http://www.greyc.ensicaen.fr/~dtschump/">David Tschumperle</a> at the beginning of his PhD thesis, in October 1999. 1.393 + He is still the main coordinator of the project. 1.394 + Since the first release at Sourceforge, a growing number of contributors has appeared. 1.395 + Due to the very simple and compact form of the library, submitting a contribution is quite easy and can be 1.396 + fastly integrated into the supported releases. 1.397 + List of contributors can be found on the front page. 1.398 + 1.399 + \section sf2 2. C++ related questions 1.400 + 1.401 + \subsection ssf21 2.1 What is the level of C++ knowledge needed to use CImg ? 1.402 + 1.403 + The CImg Library has been designed using C++ templates and object-oriented programming techniques, 1.404 + but in a very accessible level. 1.405 + There are only public classes without any derivation (just like C structures) and 1.406 + there is at most one template parameter for each CImg class (defining the pixel type of the images). 1.407 + The design is simple but clean, making the library accessible even for non professional C++ programmers, while proposing 1.408 + strong extension capabilities for C++ experts. 1.409 + 1.410 + \subsection ssf22 2.2 How to use CImg in my own C++ program ? 1.411 + 1.412 + Basically, you need to add these two lines in your C++ source code, in order 1.413 + to be able to work with CImg images : 1.414 + \code 1.415 + #include "CImg.h" 1.416 + using namespace cimg_library; 1.417 + \endcode 1.418 + 1.419 + \subsection ssf23 2.3 Why is CImg entirely contained in a single header file ? 1.420 + 1.421 + People are often surprised to see that the complete code of the library is contained in a single (big) C++ header file 1.422 + <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>. 1.423 + There are good practical and technical reasons to do that. Some arguments are listed below to justify this approach, 1.424 + so (I hope) you won't think this is a awkwardly C++ design of the CImg library :\n 1.425 + 1.426 + - First, the library is based on <i>template datatypes</i> (images with generic pixel type), 1.427 + meaning that the programmer is free to decide what type of image he instanciates in his code. 1.428 + Even if there are roughly a limited number of fully supported types (basically, the "atomic" types of C++ : <i>unsigned char, int, float, ...</i>), 1.429 + this is <i>not imaginable</i> to pre-compile the library classes and functions for <i>all possible atomic datatypes</i>, 1.430 + since many functions and methods can have two or three arguments having different template parameters. 1.431 + This really means <i>a huge number</i> of possible combinations. The size of the object binary file generated to cover all possible cases 1.432 + would be just <i>colossal</i>. Is the STL library a pre-compiled one ? No, CImg neither. 1.433 + CImg is not using a classical <i>.cpp</i> and <i>.h</i> mechanism, just like the STL. 1.434 + Architectures of C++ <i>template-based</i> libraries are somewhat special in this sense. This is a proven technical fact. 1.435 + 1.436 + - Second, why CImg does not have several header files, just like the STL does (one for each class for instance) ? 1.437 + This would be possible of course. 1.438 + There are only 4 classes in CImg, the two most important being <i>CImg<T></i> and <i>CImgList<T></i> representing respectively 1.439 + an image and a collection of images. 1.440 + But contrary to the STL library, these two CImg classes are strongly <i>inter-dependent</i>. All CImg algorithms 1.441 + are actually not defined as separate functions acting on containers (as the STL does with his header <algorithm>), 1.442 + but are directly methods of the image and image collection classes. This inter-dependence practically means that you 1.443 + will undoubtly need these two main classes at the same time if you are using CImg. 1.444 + 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 1.445 + Concerning the two other classes : You can disable the third most important class <i>CImgDisplay</i> of the CImg library, by setting the compilation 1.446 + 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. 1.447 + But to be honest, this is a quite small class and doing this doesn't save much compilation time. 1.448 + 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. 1.449 + Including this one is <i>mandatory</i>.\n 1.450 + As a consequence, having a single header file instead of several ones is just a way for you to avoid including all of them, 1.451 + without any consequences on compilation time. This is both good technical and practical reasons to do like this. 1.452 + 1.453 + - Third, having a single header file has plenty of advantages : Simplicity for the user, and for the developers (maintenance is in fact easier). 1.454 + Look at the <i>CImg.h</i> file, it looks like a mess at a first glance, but it is in fact very well organized and structured. 1.455 + Finding pieces of code in CImg functions or methods is particularly easy and fast. 1.456 + Also, how about the fact that library installation problems just disappear ? 1.457 + Just bring <i>CImg.h</i> with you, put it in your source directory, and the library is ready to go ! 1.458 + 1.459 + 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 1.460 + using a single header file. Using several header files wouldn't arrange anything since you would need all of them. 1.461 + Having a pre-compiled library object would be the only solution to speed up compilation time, but it is not possible at all, 1.462 + due to the too much generic nature of the library. 1.463 + Think seriously about it, and if you have a better solution to provide, let me know so we can discuss about it. 1.464 + 1.465 +**/ 1.466 +/*@}*/ 1.467 + 1.468 +/*----------------------------------- 1.469 + 1.470 + Setting Environment Variables 1.471 + 1.472 + -------------------------------------*/ 1.473 + 1.474 +/** \addtogroup cimg_environment Setting Environment Variables */ 1.475 +/*@{*/ 1.476 +/** 1.477 + \page foo1 1.478 + 1.479 + The CImg library is a multiplatform library, working on a wide variety of systems. 1.480 + This implies the existence of some \e environment \e variables that must be correctly defined 1.481 + depending on your current system. 1.482 + Most of the time, the %CImg Library defines these variables automatically 1.483 + (for popular systems). Anyway, if your system is not recognized, you will have to set the environment 1.484 + variables by hand. Here is a quick explanations of environment variables.\n 1.485 + 1.486 + Setting the environment variables is done with the <tt>#define</tt> keyword. 1.487 + This setting must be done <i>before including the file CImg.h</i> in your source code. 1.488 + For instance, 1.489 + defining the environment variable \c cimg_display would be done like this : 1.490 + \code 1.491 + #define cimg_display 0 1.492 + #include "CImg.h" 1.493 + ... 1.494 + \endcode 1.495 + 1.496 + Here are the different environment variables used by the %CImg Library : 1.497 + 1.498 + - \b \c cimg_OS : This variable defines the type of your Operating System. It can be set to \b 1 (\e Unix), 1.499 + \b 2 (\e Windows), or \b 0 (\e Other \e configuration). 1.500 + It should be actually auto-detected by the CImg library. If this is not the case (<tt>cimg_OS=0</tt>), you 1.501 + will probably have to tune the environment variables described below. 1.502 + 1.503 + - \b \c cimg_display : This variable defines the type of graphical library used to 1.504 + display images in windows. It can be set to 0 (no display library available), \b 1 (X11-based display) or 1.505 + \b 2 (Windows-GDI display). 1.506 + If you are running on a system without X11 or Windows-GDI ability, please set this variable to \c 0. 1.507 + This will disable the display support, since the %CImg Library doesn't contain the necessary code to display 1.508 + images on systems other than X11 or Windows GDI. 1.509 + 1.510 + - \b \c cimg_color_terminal : This variable tells the library if the system terminal has VT100 color capabilities. 1.511 + It can be \e defined or \e not \e defined. Define this variable to get colored output on your terminal, 1.512 + when using the %CImg Library. 1.513 + 1.514 + - \b \c cimg_debug : This variable defines the level of run-time debug messages that will be displayed by 1.515 + the %CImg Library. It can be set to 0 (no debug messages), 1 (normal debug messages displayed on 1.516 + standard error), 2 (normal debug messages displayed in modal windows, which is 1.517 + the default value), or 3 (high debug messages). Note that setting this value to 3 may slow down your 1.518 + program since more debug tests are made by the library (particularly to check if pixel access is made outside 1.519 + image boundaries). See also CImgException to better understand how debug messages are working. 1.520 + 1.521 + - \b \c cimg_convert_path : This variables tells the library where the ImageMagick's \e convert tool is located. 1.522 + Setting this variable should not be necessary if ImageMagick is installed on a standard directory, or 1.523 + if \e convert is in your system PATH variable. This macro should be defined only if the ImageMagick's 1.524 + \e convert tool is not found automatically, when trying to read compressed image format (GIF,PNG,...). 1.525 + See also cimg_library::CImg::get_load_convert() and cimg_library::CImg::save_convert() for more informations. 1.526 + 1.527 + - \b \c cimg_temporary_path : This variable tells the library where it can find a directory to store 1.528 + temporary files. Setting this variable should not be necessary if you are running on a standard system. 1.529 + This macro should be defined only when troubles are encountered when trying to read 1.530 + compressed image format (GIF,PNG,...). 1.531 + See also cimg_library::CImg::get_load_convert() and cimg_library::CImg::save_convert() for more informations. 1.532 + 1.533 + - \b \c cimg_plugin : This variable tells the library to use a plugin file to add features to the CImg<T> class. 1.534 + Define it with the path of your plugin file, if you want to add member functions to the CImg<T> class, 1.535 + without having to modify directly the \c "CImg.h" file. An include of the plugin file is performed in the CImg<T> 1.536 + class. If \c cimg_plugin if not specified (default), no include is done. 1.537 + 1.538 + - \b \c cimglist_plugin : Same as \c cimg_plugin, but to add features to the CImgList<T> class. 1.539 + 1.540 + - \b \c cimgdisplay_plugin : Same as \c cimg_plugin, but to add features to the CImgDisplay<T> class. 1.541 + 1.542 + All these compilation variables can be checked, using the function cimg_library::cimg::info(), which 1.543 + displays a list of the different configuration variables and their values on the standard error output. 1.544 +**/ 1.545 +/*@}*/ 1.546 + 1.547 +/*----------------------------------- 1.548 + 1.549 + Using drawing functions 1.550 + 1.551 + -------------------------------------*/ 1.552 + 1.553 +/** \addtogroup cimg_visual2005 How to use CImg library with Visual C++ 2005 Express Edition ?. */ 1.554 +/*@{*/ 1.555 +/** 1.556 + \page foo89198 1.557 + 1.558 + \section s13968 How to use CImg library with Visual C++ 2005 Express Edition ? 1.559 + 1.560 + This section has been written by Vincent Garcia and Alexandre Fournier from I3S/Sophia_Antipolis. 1.561 + 1.562 + - Download CImg library 1.563 + - Download and install Visual C++ 2005 Express Edition 1.564 + - Download and install Microsoft Windows SDK 1.565 + - Configure Visual C++ to take into account Microsoft SDK 1.566 + - 1. Go to menu "Tools -> options" 1.567 + - 2. Select option "Projects and Solutions -> VC++ Directories" 1.568 + - 3. In the select liste "Show directories for", choose "include files", and add C:\Program Files\Microsoft Platform SDK\Include (adapt if needed) 1.569 + - 4. In the select liste "Show directories for", choose "library files", and add C:\Program Files\Microsoft Platform SDK\Lib 1.570 + (adapt if needed) Edit file C:\Program Files\Microsoft Visual Studio 8\VC\VCProjectDefaults\corewin_express.vsprops (adapt if needed) 1.571 + - 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" /> 1.572 + - Restart Visual C++ 1.573 + - Import CImg library in your main file 1.574 + 1.575 +**/ 1.576 +/*@}*/ 1.577 + 1.578 + 1.579 +/*----------------------------------- 1.580 + 1.581 + Tutorial : Getting started 1.582 + 1.583 + -------------------------------------*/ 1.584 + 1.585 +/** \addtogroup cimg_tutorial Tutorial : Getting Started. */ 1.586 +/*@{*/ 1.587 +/** 1.588 + \page foo3 1.589 + 1.590 + 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 1.591 + display and mouse events. 1.592 + 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 1.593 + point in the image will draw the (R,G,B) intensity profiles of the corresponding image line (in another window). 1.594 + 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 1.595 + at the code below, it does the task : 1.596 + 1.597 + \code 1.598 + #include "CImg.h" 1.599 + using namespace cimg_library; 1.600 + 1.601 + int main() { 1.602 + CImg<unsigned char> image("lena.jpg"), visu(500,400,1,3,0); 1.603 + const unsigned char red[] = { 255,0,0 }, green[] = { 0,255,0 }, blue[] = { 0,0,255 }; 1.604 + image.blur(2.5); 1.605 + CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile"); 1.606 + while (!main_disp.is_closed && !draw_disp.is_closed) { 1.607 + main_disp.wait(); 1.608 + if (main_disp.button && main_disp.mouse_y>=0) { 1.609 + const int y = main_disp.mouse_y; 1.610 + visu.fill(0).draw_graph(image.get_crop(0,y,0,0,image.dimx()-1,y,0,0),red,1,1,0,255,0); 1.611 + visu.draw_graph(image.get_crop(0,y,0,1,image.dimx()-1,y,0,1),green,1,1,0,255,0); 1.612 + visu.draw_graph(image.get_crop(0,y,0,2,image.dimx()-1,y,0,2),blue,1,1,0,255,0).display(draw_disp); 1.613 + } 1.614 + } 1.615 + return 0; 1.616 + } 1.617 + \endcode 1.618 + 1.619 + Here is a screenshot of the resulting program : 1.620 + 1.621 + <img SRC="../img/tutorial.jpg"> 1.622 + 1.623 + And here is the detailled explanation of the source, line by line : 1.624 + 1.625 + \code #include "CImg.h" \endcode 1.626 + Include the main and only header file of the CImg library. 1.627 + \code using namespace cimg_library; \endcode 1.628 + Use the library namespace to ease the declarations afterward. 1.629 + \code int main() { \endcode 1.630 + Definition of the main function. 1.631 + \code CImg<unsigned char> image("lena.jpg"), visu(500,400,1,3,0); \endcode 1.632 + Creation of two instances of images of \c unsigned \c char pixels. 1.633 + The first image \c image is initialized by reading an image file from the disk. 1.634 + Here, <tt>lena.jpg</tt> must be in the same directory than the current program. 1.635 + Note that you must also have installed the \e ImageMagick package in order to be able to read JPG images. 1.636 + The second image \c visu is initialized as a black color image with dimension <tt>dx=500</tt>, <tt>dy=400</tt>, 1.637 + <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). 1.638 + The last argument in the constructor defines the default value of the pixel values 1.639 + (here \c 0, which means that \c visu will be initially black). 1.640 + \code const unsigned char red[] = { 255,0,0 }, green[] = { 0,255,0 }, blue[] = { 0,0,255 }; \endcode 1.641 + Definition of three different colors as array of unsigned char. This will be used to draw plots with different colors. 1.642 + \code image.blur(2.5); \endcode 1.643 + Blur the image, with a gaussian blur and a standard variation of 2.5. Note that most of the CImg functions have two versions : 1.644 + 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 1.645 + begins then with <tt>get_</tt> ). In this case, one could have also written <tt>image = image.get_blur(2.5);</tt> 1.646 + (more expensive, since it needs an additional copy operation). 1.647 + \code CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile"); \endcode 1.648 + Creation of two display windows, one for the input image image, and one for the image visu which will be display intensity profiles. 1.649 + By default, CImg displays handles events (mouse,keyboard,..). On Windows, there is a way to create fullscreen displays. 1.650 + \code while (!main_disp.is_closed && !draw_disp.is_closed) { \endcode 1.651 + Enter the event loop, the code will exit when one of the two display windows is closed. 1.652 + \code main_disp.wait(); \endcode 1.653 + Wait for an event (mouse, keyboard,..) in the display window \c main_disp. 1.654 + \code if (main_disp.button && main_disp.mouse_y>=0) { \endcode 1.655 + Test if the mouse button has been clicked on the image area. 1.656 + One may distinguish between the 3 different mouse buttons, 1.657 + but in this case it is not necessary 1.658 + \code const int y = main_disp.mouse_y; \endcode 1.659 + Get the image line y-coordinate that has been clicked. 1.660 + \code visu.fill(0).draw_graph(image.get_crop(0,y,0,0,image.dimx()-1,y,0,0),red,1,0,256,0); \endcode 1.661 + This line illustrates the pipeline property of most of the CImg class functions. The first function <tt>fill(0)</tt> simply sets 1.662 + all pixel values with 0 (i.e. clear the image \c visu). The interesting thing is that it returns a reference to 1.663 + \c visu and then, can be pipelined with the function \c draw_graph() which draws a plot in the image \c visu. 1.664 + The plot data are given by another image (the first argument of \c draw_graph()). In this case, the given image is 1.665 + the red-component of the line y of the original image, retrieved by the function \c get_crop() which returns a 1.666 + sub-image of the image \c image. Remember that images coordinates are 4D (x,y,z,v) and for color images, 1.667 + the R,G,B channels are respectively given by <tt>v=0, v=1</tt> and <tt>v=2</tt>. 1.668 + \code visu.draw_graph(image.get_crop(0,y,0,1,image.dimx()-1,y,0,1),green,1,0,256,0); \endcode 1.669 + Plot the intensity profile for the green channel of the clicked line. 1.670 + \code visu.draw_graph(image.get_crop(0,y,0,2,image.dimx()-1,y,0,2),blue,1,0,256,0).display(draw_disp); \endcode 1.671 + Same thing for the blue channel. Note how the function (which return a reference to \c visu) is pipelined with the function 1.672 + \c display() that just paints the image visu in the corresponding display window. 1.673 + \code ...till the end \endcode 1.674 + I don't think you need more explanations ! 1.675 + 1.676 + As you have noticed, the CImg library allows to write very small and intuitive code. Note also that this source will perfectly 1.677 + work on Unix and Windows systems. Take also a look to the examples provided in the CImg package ( 1.678 + directory \c examples/ ). It will show you how CImg-based code can be surprisingly small. 1.679 + Moreover, there is surely one example close to what you want to do. 1.680 + 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 1.681 + with the %CImg Library. All CImg classes are used in this source, and the code can be easily modified to see what happens. 1.682 + 1.683 +**/ 1.684 +/*@}*/ 1.685 + 1.686 +/*----------------------------------- 1.687 + 1.688 + Using drawing functions 1.689 + 1.690 + -------------------------------------*/ 1.691 + 1.692 +/** \addtogroup cimg_drawing Using Drawing Functions. */ 1.693 +/*@{*/ 1.694 +/** 1.695 + \page foo5 1.696 + 1.697 + \section s5 Using Drawing Functions. 1.698 + 1.699 + This section tells more about drawing features in CImg images. 1.700 + Drawing functions list can be found in <a href="structCImg.html">the CImg functions list</a> 1.701 + (section \b Drawing Functions), 1.702 + and are all defined on a common basis. Here are the important points to understand before using 1.703 + drawing functions : 1.704 + 1.705 + - Drawing is performed on the instance image. Drawing functions parameters 1.706 + are defined as \e const variables and return a reference to the current instance <tt>(*this)</tt>, 1.707 + so that drawing functions can be pipelined (see examples below). 1.708 + Drawing is usually done in 2D color images but can be performed in 3D images with any vector-valued dimension, 1.709 + and with any possible pixel type. 1.710 + 1.711 + - A color parameter is always needed to draw features in an image. The color must be defined as a C-style array 1.712 + whose dimension is at least 1.713 + 1.714 +**/ 1.715 +/*@}*/ 1.716 + 1.717 +/*----------------------------------- 1.718 + 1.719 + Using image loops 1.720 + 1.721 + -------------------------------------*/ 1.722 + 1.723 +/** \addtogroup cimg_loops Using Image Loops. */ 1.724 +/*@{*/ 1.725 +/** 1.726 + \page foo_lo 1.727 + The %CImg Library provides different macros that define useful iterative loops over an image. 1.728 + Basically, it can be used to replace one or several <tt>for(..)</tt> instructions, but it also proposes 1.729 + interesting extensions to classical loops. 1.730 + Below is a list of all existing loop macros, classified in four different categories : 1.731 + - \ref lo1 1.732 + - \ref lo4 1.733 + - \ref lo5 1.734 + - \ref lo6 1.735 + 1.736 + \section lo1 Loops over the pixel buffer 1.737 + 1.738 + Loops over the pixel buffer are really basic loops that iterate a pointer on the pixel data buffer 1.739 + of a \c cimg_library::CImg image. Two macros are defined for this purpose : 1.740 + 1.741 + - \b cimg_for(img,ptr,T) : 1.742 + This macro loops over the pixel data buffer of the image \c img, using a pointer <tt>T* ptr</tt>, 1.743 + starting from the end of the buffer (last pixel) till the beginning of the buffer (first pixel). 1.744 + - \c img must be a (non empty) \c cimg_library::CImg image of pixels \c T. 1.745 + - \c ptr is a pointer of type \c T*. 1.746 + This kind of loop should not appear a lot in your own source code, since this is a low-level loop 1.747 + and many functions of the CImg class may be used instead. Here is an example of use : 1.748 + \code 1.749 + CImg<float> img(320,200); 1.750 + cimg_for(img,ptr,float) { *ptr=0; } // Equivalent to 'img.fill(0);' 1.751 + \endcode 1.752 + 1.753 + - \b cimg_foroff(img,off) : 1.754 + This macro loops over the pixel data buffer of the image \c img, using an offset \c , 1.755 + starting from the beginning of the buffer (first pixel, \c off=0) 1.756 + till the end of the buffer (last pixel value, <tt>off = img.size()-1</tt>). 1.757 + - \c img must be a (non empty) cimg_library::CImg<T> image of pixels \c T. 1.758 + - \c off is an inner-loop variable, only defined inside the scope of the loop. 1.759 + 1.760 + Here is an example of use : 1.761 + \code 1.762 + CImg<float> img(320,200); 1.763 + cimg_foroff(img,off) { img[off]=0; } // Equivalent to 'img.fill(0);' 1.764 + \endcode 1.765 + 1.766 + \section lo4 Loops over image dimensions 1.767 + 1.768 + The following loops are probably the most used loops in image processing programs. 1.769 + They allow to loop over the image along one or several dimensions, along a raster scan course. 1.770 + Here is the list of such loop macros for a single dimension : 1.771 + - \b cimg_forX(img,x) : equivalent to : <tt>for (int x=0; x<img.dimx(); x++)</tt>. 1.772 + - \b cimg_forY(img,y) : equivalent to : <tt>for (int y=0; y<img.dimy(); y++)</tt>. 1.773 + - \b cimg_forZ(img,z) : equivalent to : <tt>for (int z=0; z<img.dimz(); z++)</tt>. 1.774 + - \b cimg_forV(img,v) : equivalent to : <tt>for (int v=0; v<img.dimv(); v++)</tt>. 1.775 + 1.776 + Combinations of these macros are also defined as other loop macros, allowing to loop directly over 2D, 3D or 4D images : 1.777 + - \b cimg_forXY(img,x,y) : equivalent to : \c cimg_forY(img,y) \c cimg_forX(img,x). 1.778 + - \b cimg_forXZ(img,x,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forX(img,x). 1.779 + - \b cimg_forYZ(img,y,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forY(img,y). 1.780 + - \b cimg_forXV(img,x,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forX(img,x). 1.781 + - \b cimg_forYV(img,y,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forY(img,y). 1.782 + - \b cimg_forZV(img,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forZ(img,z). 1.783 + - \b cimg_forXYZ(img,x,y,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forXY(img,x,y). 1.784 + - \b cimg_forXYV(img,x,y,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forXY(img,x,y). 1.785 + - \b cimg_forXZV(img,x,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forXZ(img,x,z). 1.786 + - \b cimg_forYZV(img,y,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forYZ(img,y,z). 1.787 + - \b cimg_forXYZV(img,x,y,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forXYZ(img,x,y,z). 1.788 + 1.789 + - 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. 1.790 + They don't have to be defined before the call of the macro. 1.791 + - \c img must be a (non empty) cimg_library::CImg image. 1.792 + 1.793 + Here is an example of use that creates an image with a smooth color gradient : 1.794 + \code 1.795 + CImg<unsigned char> img(256,256,1,3); // Define a 256x256 color image 1.796 + cimg_forXYV(img,x,y,v) { img(x,y,v) = (x+y)*(v+1)/6; } 1.797 + img.display("Color gradient"); 1.798 + \endcode 1.799 + 1.800 + \section lo5 Loops over interior regions and borders. 1.801 + 1.802 + Similar macros are also defined to loop only on the border of an image, or inside the image (excluding the border). 1.803 + The border may be several pixel wide : 1.804 + 1.805 + - \b cimg_for_insideX(img,x,n) : Loop along the x-axis, except for pixels inside a border of \p n pixels wide. 1.806 + - \b cimg_for_insideY(img,y,n) : Loop along the y-axis, except for pixels inside a border of \p n pixels wide. 1.807 + - \b cimg_for_insideZ(img,z,n) : Loop along the z-axis, except for pixels inside a border of \p n pixels wide. 1.808 + - \b cimg_for_insideV(img,v,n) : Loop along the v-axis, except for pixels inside a border of \p n pixels wide. 1.809 + - \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. 1.810 + - \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. 1.811 + 1.812 + And also : 1.813 + 1.814 + - \b cimg_for_borderX(img,x,n) : Loop along the x-axis, only for pixels inside a border of \p n pixels wide. 1.815 + - \b cimg_for_borderY(img,y,n) : Loop along the y-axis, only for pixels inside a border of \p n pixels wide. 1.816 + - \b cimg_for_borderZ(img,z,n) : Loop along the z-axis, only for pixels inside a border of \p n pixels wide. 1.817 + - \b cimg_for_borderV(img,v,n) : Loop along the z-axis, only for pixels inside a border of \p n pixels wide. 1.818 + - \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. 1.819 + - \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. 1.820 + 1.821 + - 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. 1.822 + They don't have to be defined before the call of the macro. 1.823 + - \c img must be a (non empty) cimg_library::CImg image. 1.824 + - The constant \c n stands for the size of the border. 1.825 + 1.826 + Here is an example of use, to create a 2d grayscale image with two different intensity gradients : 1.827 + \code 1.828 + CImg<> img(256,256); 1.829 + cimg_for_insideXY(img,x,y,50) img(x,y) = x+y; 1.830 + cimg_for_borderXY(img,x,y,50) img(x,y) = x-y; 1.831 + img.display(); 1.832 + \endcode 1.833 + 1.834 + \section lo6 Loops using neighborhoods. 1.835 + 1.836 + Inside an image loop, it is often useful to get values of neighborhood pixels of the 1.837 + current pixel at the loop location. 1.838 + The %CImg Library provides a very smart and fast mechanism for this purpose, with the definition 1.839 + of several loop macros that remember the neighborhood values of the pixels. 1.840 + The use of these macros can highly optimize your code, and also simplify your program. 1.841 + 1.842 + \subsection lo7 Neighborhood-based loops for 2D images 1.843 + 1.844 + For 2D images, the neighborhood-based loop macros are : 1.845 + 1.846 + - \b cimg_for2x2(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 2x2 neighborhood. 1.847 + - \b cimg_for3x3(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 3x3 neighborhood. 1.848 + - \b cimg_for4x4(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 4x4 neighborhood. 1.849 + - \b cimg_for5x5(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 5x5 neighborhood. 1.850 + 1.851 + For all these loops, \c x and \c y are inner-defined variables only visible inside the scope of the loop. 1.852 + They don't have to be defined before the call of the macro. 1.853 + \c img is a non empty CImg<T> image. \c z and \c v are constants that define on which image slice and 1.854 + vector channel the loop must apply (usually both 0 for grayscale 2D images). 1.855 + Finally, \c I is the 2x2, 3x3, 4x4 or 5x5 neighborhood that will be updated with the correct pixel values 1.856 + during the loop (see \ref lo9). 1.857 + 1.858 + \subsection lo8 Neighborhood-based loops for 3D images 1.859 + 1.860 + For 3D images, the neighborhood-based loop macros are : 1.861 + 1.862 + - \b cimg_for2x2x2(img,x,y,z,v,I) : Loop along the (x,y,z)-axes using a centered 2x2x2 neighborhood. 1.863 + - \b cimg_for3x3x3(img,x,y,z,v,I) : Loop along the (x,y,z)-axes using a centered 3x3x3 neighborhood. 1.864 + 1.865 + For all these loops, \c x, \c y and \c z are inner-defined variables only visible inside the scope of the loop. 1.866 + They don't have to be defined before the call of the macro. 1.867 + \c img is a non empty CImg<T> image. \c v is a constant that defines on which image channel 1.868 + the loop must apply (usually 0 for grayscale 3D images). 1.869 + Finally, \c I is the 2x2x2 or 3x3x3 neighborhood that will be updated with the correct pixel values 1.870 + during the loop (see \ref lo9). 1.871 + 1.872 + \subsection lo9 Defining neighborhoods 1.873 + 1.874 + A neighborhood is defined as an instance of a class having operator[] defined. 1.875 + This particularly includes classical C-array, as well as CImg<T> objects. 1.876 + 1.877 + For instance, a 3x3 neighborhood can be defined either as a 'float[9]' or a 1.878 + 'CImg<float>(3,3)' variable. 1.879 + 1.880 + \subsection lo10 Using alternate variable names 1.881 + 1.882 + There are also some useful macros that can be used to define variables that 1.883 + reference the neighborhood elements. There are : 1.884 + 1.885 + - \b CImg_2x2(I,type) : Define a 2x2 neighborhood named \c I, of type \c type. 1.886 + - \b CImg_3x3(I,type) : Define a 3x3 neighborhood named \c I, of type \c type. 1.887 + - \b CImg_4x4(I,type) : Define a 4x4 neighborhood named \c I, of type \c type. 1.888 + - \b CImg_5x5(I,type) : Define a 5x5 neighborhood named \c I, of type \c type. 1.889 + - \b CImg_2x2x2(I,type) : Define a 2x2x2 neighborhood named \c I, of type \c type. 1.890 + - \b CImg_3x3x3(I,type) : Define a 3x3x3 neighborhood named \c I, of type \c type. 1.891 + 1.892 + Actually, \c I is a \e generic \e name for the neighborhood. In fact, these macros declare 1.893 + a \e set of new variables. 1.894 + For instance, defining a 3x3 neighborhood \c CImg_3x3(I,float) declares 9 different float variables 1.895 + \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 1.896 + a 3x3 neighborhood. 1.897 + Variable indices are \c p,\c c or \c n, and stand respectively for \e 'previous', \e 'current' and \e 'next'. 1.898 + First indice denotes the \c x-axis, second indice denotes the \c y-axis. 1.899 + Then, the names of the variables are directly related to the position of the corresponding pixels 1.900 + in the neighborhood. For 3D neighborhoods, a third indice denotes the \c z-axis. 1.901 + Then, inside a neighborhood loop, you will have the following equivalence : 1.902 + - <tt>Ipp = img(x-1,y-1)</tt> 1.903 + - <tt>Icn = img(x,y+1)</tt> 1.904 + - <tt>Inp = img(x+1,y-1)</tt> 1.905 + - <tt>Inpc = img(x+1,y-1,z)</tt> 1.906 + - <tt>Ippn = img(x-1,y-1,z+1)</tt> 1.907 + - and so on... 1.908 + 1.909 + For bigger neighborhoods, such as 4x4 or 5x5 neighborhoods, two additionnal indices are introduced : 1.910 + \c a (stands for \e 'after') and \c b (stands for \e 'before'), so that : 1.911 + - <tt>Ibb = img(x-2,y-2)</tt> 1.912 + - <tt>Ina = img(x+1,y+2)</tt> 1.913 + - and so on... 1.914 + 1.915 + The value of a neighborhood pixel outside the image range (image border problem) is automatically set to the same 1.916 + values than the nearest valid pixel in the image (this is also called the \e Neumann \e border \e condition). 1.917 + 1.918 + \subsection lo11 Example codes 1.919 + More than a long discussion, the above example will demonstrate how to compute the gradient norm of a 3D volume 1.920 + using the \c cimg_for3x3x3() loop macro : 1.921 + 1.922 + \code 1.923 + CImg<float> volume("IRM.hdr"); // Load an IRM volume from an Analyze7.5 file 1.924 + CImg_3x3x3(I,float); // Define a 3x3x3 neighborhood 1.925 + CImg<float> gradnorm(volume); // Create an image with same size as 'volume' 1.926 + cimg_for3x3x3(volume,x,y,z,0,I) { // Loop over the volume, using the neighborhood I 1.927 + const float ix = 0.5f*(Incc-Ipcc); // Compute the derivative along the x-axis. 1.928 + const float iy = 0.5f*(Icnc-Icpc); // Compute the derivative along the y-axis. 1.929 + const float iz = 0.5f*(Iccn-Iccp); // Compute the derivative along the z-axis. 1.930 + gradnorm(x,y,z) = std::sqrt(ix*ix+iy*iy+iz*iz); // Set the gradient norm in the destination image 1.931 + } 1.932 + gradnorm.display("Gradient norm"); 1.933 + \endcode 1.934 + 1.935 + And the following example shows how to deal with neighborhood references to blur a color image by averaging 1.936 + pixel values on a 5x5 neighborhood. 1.937 + 1.938 + \code 1.939 + CImg<unsigned char> src("image_color.jpg"), dest(src,false), neighbor(5,5); // Image definitions. 1.940 + typedef unsigned char uchar; // Avoid space in the second parameter of the macro CImg_5x5x1 below. 1.941 + CImg<> N(5,5); // Define a 5x5 neighborhood as a 5x5 image. 1.942 + cimg_forV(src,k) // Standard loop on color channels 1.943 + cimg_for5x5(src,x,y,0,k,N) // 5x5 neighborhood loop. 1.944 + dest(x,y,k) = N.sum()/(5*5); // Averaging pixels to filter the color image. 1.945 + CImgList<unsigned char> visu(src,dest); 1.946 + visu.display("Original + Filtered"); // Display both original and filtered image. 1.947 + \endcode 1.948 + 1.949 + As you can see, explaining the use of the CImg neighborhood macros is actually more difficult than using them ! 1.950 + 1.951 +**/ 1.952 +/*@}*/ 1.953 + 1.954 +/*----------------------------------- 1.955 + 1.956 + Using display windows 1.957 + 1.958 + -------------------------------------*/ 1.959 + 1.960 +/** \addtogroup cimg_displays Using Display Windows. */ 1.961 +/*@{*/ 1.962 +/** 1.963 + \page foo_di 1.964 + 1.965 + When opening a display window, you can choose the way the pixel values will be normalized 1.966 + before being displayed on the screen. Screen displays only support color values between [0,255], 1.967 + and some 1.968 + 1.969 + When displaying an image into the display window using CImgDisplay::display(), values of 1.970 + the image pixels can be eventually linearly normalized between [0,255] for visualization purposes. 1.971 + This may be useful for instance when displaying \p CImg<double> images with pixel values 1.972 + between [0,1]. 1.973 + The normalization behavior depends on the value of \p normalize which can be either \p 0,\p 1 or \p 2 : 1.974 + - \p 0 : No pixel normalization is performed when displaying an image. This is the fastest 1.975 + process, but you must be sure your displayed image have pixel values inside the range [0,255]. 1.976 + - \p 1 : Pixel value normalization is done for each new image display. Image pixels are 1.977 + not modified themselves, only displayed pixels are normalized. 1.978 + - \p 2 : Pixel value normalization is done for the first image display, then the 1.979 + normalization parameters are kept and used for all the next image displays. 1.980 + 1.981 +**/ 1.982 +/*@}*/ 1.983 + 1.984 +/*----------------------------------- 1.985 + 1.986 + How pixel data are stored 1.987 + 1.988 + -------------------------------------*/ 1.989 + 1.990 +/** \addtogroup cimg_storage How pixel data are stored with CImg. */ 1.991 +/*@{*/ 1.992 +/** 1.993 + \page foo_store 1.994 + 1.995 + First, CImg<T> are *very* basic structures, which means that there are no memory tricks, weird memory alignments or 1.996 + disk caches used to store pixel data of images. When an image is instanced, all its pixel values are stored in memory at 1.997 + the same time (yes, you should avoid working with huge images when dealing with CImg, if you have only 64kb of RAM). 1.998 + 1.999 + A CImg<T> is basically a 4th-dimensional array (width,height,depth,dim), and its pixel data are stored linearly in a single 1.1000 + memory buffer of general size (width*height*depth*dim). Nothing more, nothing less. The address of this memory buffer can be 1.1001 + retrieved by the function CImg<T>::ptr(). 1.1002 + 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'. 1.1003 + so, 'T *ptr = img.ptr()' gives you the pointer to the first value of the image 'img'. The overall size of the used memory for one 1.1004 + instance image (in bytes) is then 'width*height*depth*dim*sizeof(T)'. 1.1005 + 1.1006 + Now, the ordering of the pixel values in this buffer follows these rules : 1.1007 + 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), 1.1008 + starting from the upper-left pixel to the bottom-right pixel of the instane image, with a classical scanline run. 1.1009 + 1.1010 + So, a color image with dim=3 and depth=1, will be stored in memory as : 1.1011 + 1.1012 + R1R2R3R4R5R6......G1G2G3G4G5G6.......B1B2B3B4B5B6.... (i.e following a 'planar' structure) 1.1013 + 1.1014 + and *not* as R1G1B1R2G2B2R3G3B3... (interleaved channels), 1.1015 + where R1 = img(0,0,0,0) is the first upper-left pixel of the red component of the image, 1.1016 + 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... 1.1017 + 1.1018 + Another example, a (1x5x1x1) CImg<T> (column vector A) will be stored as : A1A2A3A4A5 1.1019 + where A1 = img(0,0), A2 = img(0,1), ... , A5 = img(0,4). 1.1020 + 1.1021 + As you see, it is *very* simple and intuitive : no interleaving, no padding, just simple. 1.1022 + 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 1.1023 + 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)' 1.1024 + 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 1.1025 + your image, you can just skip it in the call to the operator(). Similarly, values of a column vector stored as an image with 1.1026 + width=depth=dim=1 can be accessed by 'img(y)' instead of 'img(0,y)'. This is very convenient. 1.1027 + 1.1028 + Another cool thing is that it allows you to work easily with 'shared' images. A shared image is a CImg<T> instance that shares 1.1029 + its memory with another one (the 'base' image). Destroying a shared image does nothing in fact. Shared images is a convenient 1.1030 + way of modifying only *portions* (consecutive in memory) of an image. For instance, if 'img' is a 2D color image, you can write : 1.1031 + 1.1032 + img.get_shared_channel(0).blur(2); 1.1033 + img.get_shared_channels(1,2).mirror('x'); 1.1034 + 1.1035 + which just blur the red channel of the image, and mirror the two others along the X-axis. 1.1036 + 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). 1.1037 + 1.1038 +**/ 1.1039 +/*@}*/ 1.1040 + 1.1041 +/*----------------------------------- 1.1042 + 1.1043 + Files IO 1.1044 + 1.1045 + -------------------------------------*/ 1.1046 + 1.1047 +/** \addtogroup cimg_files_io Files IO in CImg. */ 1.1048 +/*@{*/ 1.1049 +/** 1.1050 + \page foo_fi 1.1051 + 1.1052 + The %CImg Library can NATIVELY handle the following file formats : 1.1053 + - RAW : consists in a very simple header (in ascii), then the image data. 1.1054 + - ASC (Ascii) 1.1055 + - HDR (Analyze 7.5) 1.1056 + - INR (Inrimage) 1.1057 + - PPM/PGM (Portable Pixmap) 1.1058 + - BMP (uncompressed) 1.1059 + - PAN (Pandore-5) 1.1060 + - DLM (Matlab ASCII) 1.1061 + 1.1062 + If ImageMagick is installed, The %CImg Library can save image in formats handled by ImageMagick : JPG, GIF, PNG, TIF,... 1.1063 + 1.1064 +**/ 1.1065 +/*@}*/ 1.1066 + 1.1067 +/*----------------------------------- 1.1068 + 1.1069 + Retrieving command line arguments 1.1070 + 1.1071 + -------------------------------------*/ 1.1072 + 1.1073 +/** \addtogroup cimg_options Retrieving Command Line Arguments. */ 1.1074 +/*@{*/ 1.1075 +/** 1.1076 + \page foo_so 1.1077 + 1.1078 + The CImg library offers facilities to retrieve command line arguments in a console-based 1.1079 + program, as it is a commonly needed operation. 1.1080 + Three macros \c cimg_usage(), \c cimg_help() and \c cimg_option() are defined for this purpose. 1.1081 + Using these macros allows to easily retrieve options values from the command line. 1.1082 + Invoking the compiled executable with the option \c -h or \c --help will 1.1083 + automatically display the program usage, followed by the list of requested options. 1.1084 + 1.1085 + \section so1 The cimg_usage() macro 1.1086 + 1.1087 + The macro \c cimg_usage(usage) may be used to describe the program goal and usage. 1.1088 + It is generally inserted one time after the <tt>int main(int argc,char **argv)</tt> definition. 1.1089 + 1.1090 + \param usage : A string describing the program goal and usage. 1.1091 + \pre The function where \c cimg_usage() is used must have correctly defined \c argc and \c argv variables. 1.1092 + 1.1093 + \section so1_5 The cimg_help() macro 1.1094 + 1.1095 + The macro \c cimg_help(str) will display the string \c str only if the \c -help or \c --help option 1.1096 + are invoked when running the programm. 1.1097 + 1.1098 + \section so2 The cimg_option() macro 1.1099 + 1.1100 + The macro \c cimg_option(name,default,usage) may be used to retrieve an option value from the command line. 1.1101 + 1.1102 + \param name : The name of the option to be retrieved from the command line. 1.1103 + \param default : The default value returned by the macro if no options \p name has been specified when running the program. 1.1104 + \param usage : A brief explanation of the option. If \c usage==0, the option won't appear on the option list 1.1105 + when invoking the executable with options \c -h or \c --help (hidden option). 1.1106 + 1.1107 + \return \c cimg_option() returns an object that has the \e same \e type than the default value \c default. 1.1108 + The return value is equal to the one specified on the command line. If no such option have been specified, 1.1109 + the return value is equal to the default value \c default. 1.1110 + Warning, this can be confusing in some situations (look at the end of the next section). 1.1111 + \pre The function where \c cimg_option() is used must have correctly defined \c argc and \c argv variables. 1.1112 + 1.1113 + \section so3 Example of use 1.1114 + 1.1115 + The code below uses the macros \c cimg_usage() and \c cimg_option(). 1.1116 + It loads an image, smoothes it an quantifies it with a specified number of values. 1.1117 + \code 1.1118 + #include "CImg.h" 1.1119 + using namespace cimg_library; 1.1120 + int main(int argc,char **argv) { 1.1121 + cimg_usage("Retrieve command line arguments"); 1.1122 + const char* filename = cimg_option("-i","image.gif","Input image file"); 1.1123 + const char* output = cimg_option("-o",(char*)0,"Output image file"); 1.1124 + const double sigma = cimg_option("-s",1.0,"Standard variation of the gaussian smoothing"); 1.1125 + const int nblevels = cimg_option("-n",16,"Number of quantification levels"); 1.1126 + const bool hidden = cimg_option("-hidden",false,0); // This is a hidden option 1.1127 + 1.1128 + CImg<unsigned char> img(filename); 1.1129 + img.blur(sigma).quantize(nblevels); 1.1130 + if (output) img.save(output); else img.display("Output image"); 1.1131 + if (hidden) std::fprintf(stderr,"You found me !\n"); 1.1132 + return 0; 1.1133 + } 1.1134 + \endcode 1.1135 + 1.1136 + Invoking the corresponding executable with <tt>test -h -hidden -n 20 -i foo.jpg</tt> will display : 1.1137 + \verbatim 1.1138 + ./test -h -hidden -n 20 -i foo.jpg 1.1139 + 1.1140 + test : Retrieve command line arguments (Oct 16 2004, 12:34:26) 1.1141 + 1.1142 + -i = foo.jpg : Input image file 1.1143 + -o = 0 : Output image file 1.1144 + -s = 1 : Standard variation of the gaussian smoothing 1.1145 + -n = 20 : Number of quantification levels 1.1146 + 1.1147 + You found me ! 1.1148 +\endverbatim 1.1149 + 1.1150 + \warning As the type of object returned by the macro \c cimg_option(option,default,usage) 1.1151 + is defined by the type of \c default, undesired casts may appear when writting code such as : 1.1152 + \code 1.1153 + const double sigma = cimg_option("-val",0,"A floating point value"); 1.1154 + \endcode 1.1155 + In this case, \c sigma will always be equal to an integer (since the default value \c 0 is an integer). 1.1156 + When passing a float value on the command line, a \e float \e to \e integer cast is then done, 1.1157 + truncating the given parameter to an integer value (this is surely not a desired behavior). 1.1158 + You must specify <tt>0.0</tt> as the default value in this case. 1.1159 + 1.1160 + \section so4 How to learn more about command line options ? 1.1161 + You should take a look at the examples <tt>examples/gmic.cpp</tt> provided in the %CImg Library package. 1.1162 + This is a command line based image converter which intensively uses the \c cimg_option() and \c cimg_usage() 1.1163 + macros to retrieve command line parameters. 1.1164 +**/ 1.1165 +/*@}*/ 1.1166 +