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