Wed, 05 Aug 2009 17:10:56 +0100
add README
1 /*------------------------------------------------------------------------
2 #
3 # File : CImg_documentation.h
4 #
5 # Description : Extra documentation file for the CImg Library.
6 # Used by doxygen to generate the reference documentation.
7 # ( http://cimg.sourceforge.net )
8 #
9 # Copyright : David Tschumperle
10 # ( http://www.greyc.ensicaen.fr/~dtschump/ )
11 #
12 #
13 -------------------------------------------------------------------------*/
15 /*-----------------------------------
17 Main reference documentation page
19 -------------------------------------*/
21 /**
22 \mainpage
24 This is the reference documentation of <a href="http://cimg.sourceforge.net">the CImg Library</a>,
25 the C++ template image processing library.
26 This documentation have been generated using the tool <a href="http://www.doxygen.org">doxygen</a>.
27 It contains a detailed description of all classes and functions of the %CImg Library.
28 If you have downloaded the CImg package, you actually have a local copy of these pages in the
29 \c CImg/html/reference/ directory.
31 Use the menu above to navigate through the documentation pages.
32 As a first step, you may look at the list of <a href="modules.html">available modules</a>.
34 A complete PDF version of this reference documentation is
35 <a href="../CImg_reference.pdf">available here</a> for off-line reading.
37 A partial translation in Chinese is <a href="../CImg_reference_chinese.pdf">available here</a>.
39 You may be interested also in the
40 <a href="../CImg_slides.pdf">presentation slides</a> presenting an overview
41 of the %CImg Library capabilities.
43 **/
45 /*-----------------------------------
47 CImg Library overview
49 -------------------------------------*/
51 /** \addtogroup cimg_overview CImg Library Overview */
52 /*@{*/
53 /**
54 \page foo2
56 The <b>CImg Library</b> is an image processing library, designed for C++ programmers.
57 It provides useful classes and functions to load/save, display and process various types of images.
59 \section s1 Library structure
61 The %CImg Library consists in a <b>single header file</b> CImg.h providing a set of C++ template classes that
62 can be used in your own sources, to load/save, process and display images or list of images.
63 Very portable (Unix/X11,Windows, MacOS X, FreeBSD,..), efficient, simple to use, it's a pleasant toolkit
64 for coding image processing stuffs in C++.
66 The header file CImg.h contains all the classes and functions that compose the library itself.
67 This is one originality of the %CImg Library. This particularly means that :
68 - No pre-compilation of the library is needed, since the compilation of the CImg functions is done at the same time as
69 the compilation of your own C++ code.
70 - No complex dependencies have to be handled : Just include the CImg.h file, and you get a working C++ image processing toolkit.
71 - The compilation is done on the fly : only CImg functionalities really used by your program are compiled and appear in the
72 compiled executable program. This leads to very compact code, without any unused stuffs.
73 - Class members and functions are inlined, leading to better performance during the program execution.
75 The %CImg Library is structured as follows :
77 - All library classes and functions are defined in the namespace \ref cimg_library. This namespace
78 encapsulates the library functionalities and avoid any class name collision that could happen with
79 other includes. Generally, one uses this namespace as a default namespace :
80 \code
81 #include "CImg.h"
82 using namespace cimg_library;
83 ...
84 \endcode
86 - The namespace \ref cimg_library::cimg defines a set of \e low-level functions and variables used by the library.
87 Documented functions in this namespace can be safely used in your own program. But, \b never use the
88 \ref cimg_library::cimg namespace as a default namespace, since it contains functions whose names are already
89 defined in the standard C/C++ library.
91 - The class \ref cimg_library::CImg<T> represents images up to 4-dimensions wide, containing pixels of type \c T
92 (template parameter). This is actually the main class of the library.
94 - The class \ref cimg_library::CImgList<T> represents lists of cimg_library::CImg<T> images. It can be used for instance
95 to store different frames of an image sequence.
97 - The class \ref cimg_library::CImgDisplay is able to display images or image lists into graphical display windows.
98 As you may guess, the code of this class is highly system-dependent but this is transparent for the programmer,
99 as environment variables are automatically set by the CImg library (see also \ref cimg_environment).
101 - The class \ref cimg_library::CImgException (and its subclasses) are used by the library to throw exceptions
102 when errors occur. Those exceptions can be catched with a bloc <tt>try { ..} catch (CImgException) { .. }</tt>.
103 Subclasses define precisely the type of encountered errors.
105 Knowing these four classes is \b enough to get benefit of the %CImg Library functionalities.
108 \section s2 CImg version of "Hello world".
110 Below is a very simple code that creates a "Hello World" image. This shows you basically how a CImg program looks like.
112 \code
113 #include "CImg.h"
114 using namespace cimg_library;
116 int main() {
117 CImg<unsigned char> img(640,400,1,3); // Define a 640x400 color image with 8 bits per color component.
118 img.fill(0); // Set pixel values to 0 (color : black)
119 unsigned char purple[] = { 255,0,255 }; // Define a purple color
120 img.draw_text("Hello World",100,100,purple); // Draw a purple "Hello world" at coordinates (100,100).
121 img.display("My first CImg code"); // Display the image in a display window.
122 return 0;
123 }
124 \endcode
126 Which can be also written in a more compact way as :
128 \code
129 #include "CImg.h"
130 using namespace cimg_library;
132 int main() {
133 const unsigned char purple[] = { 255,0,255 };
134 CImg<unsigned char>(640,400,1,3,0).draw_text("Hello World",100,100,purple).display("My first CImg code");
135 return 0;
136 }
137 \endcode
139 Generally, you can write very small code that performs complex image processing tasks. The %CImg Library is very simple
140 to use and provide a lot of interesting algorithms for image manipulation.
142 \section s3 How to compile ?
144 The CImg library is a very light and user-friendly library : only standard system libraries are used.
145 It avoid to handle complex dependancies and problems with library compatibility.
146 The only thing you need is a (quite modern) C++ compiler :
148 - <b>Microsoft Visual C++ 6.0, Visual Studio.NET and Visual Express Edition</b> : Use project files and solution files provided in the
149 %CImg Library package (directory 'compilation/') to see how it works.
150 - <b>Intel ICL compiler</b> : Use the following command to compile a CImg-based program with ICL :
151 \code
152 icl /Ox hello_world.cpp user32.lib gdi32.lib
153 \endcode
154 - <b>g++ (MingW windows version)</b> : Use the following command to compile a CImg-based program with g++, on Windows :
155 \code
156 g++ -o hello_word.exe hello_word.cpp -O2 -lgdi32
157 \endcode
158 - <b>g++ (Linux version)</b> : Use the following command to compile a CImg-based program with g++, on Linux :
159 \code
160 g++ -o hello_word.exe hello_world.cpp -O2 -L/usr/X11R6/lib -lm -lpthread -lX11
161 \endcode
162 - <b>g++ (Solaris version)</b> : Use the following command to compile a CImg-based program with g++, on Solaris :
163 \code
164 g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -R/usr/X11R6/lib -lrt -lnsl -lsocket
165 \endcode
166 - <b>g++ (Mac OS X version)</b> : Use the following command to compile a CImg-based program with g++, on Mac OS X :
167 \code
168 g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -L/usr/X11R6/lib -lm -lpthread -lX11
169 \endcode
170 - <b>Dev-Cpp</b> : Use the project file provided in the CImg library package to see how it works.
172 If you are using another compilers and encounter problems, please
173 <a href="http://www.greyc.ensicaen.fr/~dtschump">write me</a> since maintaining compatibility is one
174 of the priority of the %CImg Library. Nevertheless, old compilers that does not respect the C++ norm will not
175 support the %CImg Library.
177 \section s4 What's next ?
179 If you are ready to get more, and to start writing more serious programs
180 with CImg, you are invited to go to the \ref cimg_tutorial section.
182 **/
183 /*@}*/
185 /*----------------------------------
187 CImg<T> : The image structure
189 --------------------------------*/
191 /** \addtogroup cimg_structure CImg<T> : The image structure. */
192 /*@{*/
193 /**
194 Description of the CImg<T> structure
196 \page foo_cs
198 \section cs0 Structure overview
200 \section cs1 Image construction/destruction/copy
202 \section cs2 Image methods
204 \section cs3 Shared images
206 \section cs4 Low-level structure
208 **/
209 /*@}*/
211 /*----------------------------------------
213 CImgList<T> : The image list structure
215 ---------------------------------------*/
217 /** \addtogroup cimglist_structure CImgList<T> : The image list structure. */
218 /*@{*/
219 /**
220 Description of the CImgList<T> structure
222 \page foo_cls
224 \section cls0 Structure overview
226 \section cls1 Image list construction/destruction/copy
228 \section cls2 Image methods
230 \section cls4 Low-level structure
232 **/
233 /*@}*/
235 /*----------------------------------------------
237 CImgDisplay : The image display structure
239 --------------------------------------------*/
241 /** \addtogroup cimgdisplay_structure CImgDisplay : The image display structure. */
242 /*@{*/
243 /**
244 Description of the CImgDisplay structure
246 \page foo_cds
248 \section cds0 Structure overview
250 \section cds1 Image display construction/destruction/copy
252 \section cds2 Image methods
254 \section cds4 Low-level structure
256 **/
257 /*@}*/
259 /*----------------------------------------------
261 CImgException : The library exception structure
263 --------------------------------------------*/
265 /** \addtogroup cimgexception_structure CImgException : The library exception structure. */
266 /*@{*/
267 /**
268 Description of the CImgException structure
270 \page foo_ces
272 \section ces0 Structure overview
275 **/
276 /*@}*/
279 /*-----------------------------------
281 FAQ : Frequently Asked Questions
283 -------------------------------------*/
285 /** \addtogroup cimg_faq FAQ : Frequently Asked Questions. */
286 /*@{*/
287 /**
288 \page foofaq
290 \section ssf0 FAQ Summary
292 - <a href="#sf1">General information and availability</a>
293 - <a href="#ssf11">What is the CImg Library ?</a>
294 - <a href="#ssf12">What platforms are supported ?</a>
295 - <a href="#ssf13">How is CImg distributed ?</a>
296 - <a href="#ssf14">What kind of people are concerned by CImg ?</a>
297 - <a href="#ssf15">What are the specificities of the CeCILL license ?</a>
298 - <a href="#ssf16">Who is behind CImg ?</a>
300 - <a href="#sf2">C++ related questions</a>
301 - <a href="#ssf21">What is the level of C++ knowledge needed to use CImg ?</a>
302 - <a href="#ssf22">How to use CImg in my own C++ program ?</a>
303 - <a href="#ssf23">Why is CImg entirely contained in a single header file ?</a>
305 \section sf1 1. General information and availability
307 \subsection ssf11 1.1. What is the CImg Library ?
309 The CImg Library is an <i>open-source C++ toolkit for image processing</i>.\n
311 It mainly consists in a (big) single header file
312 <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>
313 providing a set of C++ classes and functions that can be used in your own sources,
314 to load/save, manage/process and display generic images.
315 It's actually a very simple and pleasant toolkit for coding image processing stuffs in C++ :
316 Just include the header file <i>CImg.h</i>, and you are ready to handle images in your C++ programs.
318 \subsection ssf12 1.2. What platforms are supported ?
320 CImg has been designed with <i>portability</i> in mind.
321 It is regularly tested on different architectures and compilers,
322 and should also work on any decent OS having a decent C++ compiler.
323 Before each release, the CImg Library is compiled under these different configurations :
324 \li PC Linux 32 bits, with g++.
325 \li PC Windows 32 bits, with Visual C++ 6.0.
326 \li PC Windows 32 bits, with Visual C++ Express Edition.
327 \li Sun SPARC Solaris 32 bits, with g++.
328 \li Mac PPC with OS X and g++.
330 CImg has a minimal number of dependencies. In its minimal version, it can be compiled only with standard C++ headers.
331 Anyway, it has interesting extension capabilities and can use external libraries to perform specific tasks more
332 efficiently (Fourier Transform computation using FFTW for instance).
334 \subsection ssf13 1.3. How is CImg distributed ?
336 The CImg Library is freely distributed as a complete .zip compressed package, hosted at the
337 <a href="http://sourceforge.net/project/showfiles.php?group_id=96492">Sourceforge servers</a>.\n
338 The package is distributed under the <a href="http://www.cecill.info">CeCILL license</a>.
340 This package contains :
341 - The main library file <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a> (C++ header file).
342 - Several C++ source code showing <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/examples/">examples of using CImg</a>.
343 - A complete library documentation, in <a href="index.html">HTML</a> and <a href="../CImg_reference.pdf">PDF</a> formats.
344 - Additional <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/plugins/">library plug-ins</a> that can be used to extend
345 library capabilities for specific uses.
347 The CImg Library is a quite lightweight library which is easy to maintain (due to its particular structure), and thus
348 has a fast rythm of release. A new version of the CImg package is released approximately every three months.
350 \subsection ssf14 1.4. What kind of people are concerned by CImg ?
352 The CImg library is an <i>image processing</i> library, primarily intended for computer scientists or students working in the fields
353 of image processing or computer vision, and knowing bases of C++.
354 As the library is handy and really easy to use, it can be also used by any programmer
355 needing occasional tools for dealing with images in C++, since there are no standard library yet
356 for this purpose.
358 \subsection ssf15 1.5. What are the specificities of the CeCILL license ?
360 The <a href="http://www.cecill.info">CeCILL license</a> governs the use of the CImg Library.
361 This is an <i>open-source</i> license which gives you rights to access, use, modify and redistribute the source code,
362 under certains conditions.
363 There are two different variants of the CeCILL license used in CImg
364 (namely
365 <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> and
366 <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a>, all open-source),
367 corresponding to different constraints on the source files :
368 - 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
369 the <i>GNU LGPL license</i>, and <i>applies <b>only</b> on the main library file
370 <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a></i>.
371 Basically, this license allows to use <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>
372 in a closed-source product without forcing you to redistribute the entire software source code. Anyway,
373 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
374 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.
376 - The <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> license applies to all other files
377 (source examples, plug-ins and documentation) of the CImg Library package, and is close (even <i>compatible</i>)
378 with the <i>GNU GPL license</i>. It <i>does not allow</i> the use of these files in closed-source products.
380 You are invited to read the complete descriptions of the
381 the <a href="http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html">CeCILL-C</a>
382 and <a href="http://www.cecill.info/licences/Licence_CeCILL_V2-en.html">CeCILL</a> licenses before releasing a
383 software based on the CImg Library.
385 \subsection ssf16 1.6. Who is behind CImg ?
387 CImg has been started by
388 <a href="http://www.greyc.ensicaen.fr/~dtschump/">David Tschumperle</a> at the beginning of his PhD thesis, in October 1999.
389 He is still the main coordinator of the project.
390 Since the first release at Sourceforge, a growing number of contributors has appeared.
391 Due to the very simple and compact form of the library, submitting a contribution is quite easy and can be
392 fastly integrated into the supported releases.
393 List of contributors can be found on the front page.
395 \section sf2 2. C++ related questions
397 \subsection ssf21 2.1 What is the level of C++ knowledge needed to use CImg ?
399 The CImg Library has been designed using C++ templates and object-oriented programming techniques,
400 but in a very accessible level.
401 There are only public classes without any derivation (just like C structures) and
402 there is at most one template parameter for each CImg class (defining the pixel type of the images).
403 The design is simple but clean, making the library accessible even for non professional C++ programmers, while proposing
404 strong extension capabilities for C++ experts.
406 \subsection ssf22 2.2 How to use CImg in my own C++ program ?
408 Basically, you need to add these two lines in your C++ source code, in order
409 to be able to work with CImg images :
410 \code
411 #include "CImg.h"
412 using namespace cimg_library;
413 \endcode
415 \subsection ssf23 2.3 Why is CImg entirely contained in a single header file ?
417 People are often surprised to see that the complete code of the library is contained in a single (big) C++ header file
418 <a href="http://cimg.cvs.sourceforge.net/cimg/CImg/CImg.h?view=markup">CImg.h</a>.
419 There are good practical and technical reasons to do that. Some arguments are listed below to justify this approach,
420 so (I hope) you won't think this is a awkwardly C++ design of the CImg library :\n
422 - First, the library is based on <i>template datatypes</i> (images with generic pixel type),
423 meaning that the programmer is free to decide what type of image he instanciates in his code.
424 Even if there are roughly a limited number of fully supported types (basically, the "atomic" types of C++ : <i>unsigned char, int, float, ...</i>),
425 this is <i>not imaginable</i> to pre-compile the library classes and functions for <i>all possible atomic datatypes</i>,
426 since many functions and methods can have two or three arguments having different template parameters.
427 This really means <i>a huge number</i> of possible combinations. The size of the object binary file generated to cover all possible cases
428 would be just <i>colossal</i>. Is the STL library a pre-compiled one ? No, CImg neither.
429 CImg is not using a classical <i>.cpp</i> and <i>.h</i> mechanism, just like the STL.
430 Architectures of C++ <i>template-based</i> libraries are somewhat special in this sense. This is a proven technical fact.
432 - Second, why CImg does not have several header files, just like the STL does (one for each class for instance) ?
433 This would be possible of course.
434 There are only 4 classes in CImg, the two most important being <i>CImg<T></i> and <i>CImgList<T></i> representing respectively
435 an image and a collection of images.
436 But contrary to the STL library, these two CImg classes are strongly <i>inter-dependent</i>. All CImg algorithms
437 are actually not defined as separate functions acting on containers (as the STL does with his header <algorithm>),
438 but are directly methods of the image and image collection classes. This inter-dependence practically means that you
439 will undoubtly need these two main classes at the same time if you are using CImg.
440 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
441 Concerning the two other classes : You can disable the third most important class <i>CImgDisplay</i> of the CImg library, by setting the compilation
442 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.
443 But to be honest, this is a quite small class and doing this doesn't save much compilation time.
444 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.
445 Including this one is <i>mandatory</i>.\n
446 As a consequence, having a single header file instead of several ones is just a way for you to avoid including all of them,
447 without any consequences on compilation time. This is both good technical and practical reasons to do like this.
449 - Third, having a single header file has plenty of advantages : Simplicity for the user, and for the developers (maintenance is in fact easier).
450 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.
451 Finding pieces of code in CImg functions or methods is particularly easy and fast.
452 Also, how about the fact that library installation problems just disappear ?
453 Just bring <i>CImg.h</i> with you, put it in your source directory, and the library is ready to go !
455 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
456 using a single header file. Using several header files wouldn't arrange anything since you would need all of them.
457 Having a pre-compiled library object would be the only solution to speed up compilation time, but it is not possible at all,
458 due to the too much generic nature of the library.
459 Think seriously about it, and if you have a better solution to provide, let me know so we can discuss about it.
461 **/
462 /*@}*/
464 /*-----------------------------------
466 Setting Environment Variables
468 -------------------------------------*/
470 /** \addtogroup cimg_environment Setting Environment Variables */
471 /*@{*/
472 /**
473 \page foo1
475 The CImg library is a multiplatform library, working on a wide variety of systems.
476 This implies the existence of some \e environment \e variables that must be correctly defined
477 depending on your current system.
478 Most of the time, the %CImg Library defines these variables automatically
479 (for popular systems). Anyway, if your system is not recognized, you will have to set the environment
480 variables by hand. Here is a quick explanations of environment variables.\n
482 Setting the environment variables is done with the <tt>#define</tt> keyword.
483 This setting must be done <i>before including the file CImg.h</i> in your source code.
484 For instance,
485 defining the environment variable \c cimg_display would be done like this :
486 \code
487 #define cimg_display 0
488 #include "CImg.h"
489 ...
490 \endcode
492 Here are the different environment variables used by the %CImg Library :
494 - \b \c cimg_OS : This variable defines the type of your Operating System. It can be set to \b 1 (\e Unix),
495 \b 2 (\e Windows), or \b 0 (\e Other \e configuration).
496 It should be actually auto-detected by the CImg library. If this is not the case (<tt>cimg_OS=0</tt>), you
497 will probably have to tune the environment variables described below.
499 - \b \c cimg_display : This variable defines the type of graphical library used to
500 display images in windows. It can be set to 0 (no display library available), \b 1 (X11-based display) or
501 \b 2 (Windows-GDI display).
502 If you are running on a system without X11 or Windows-GDI ability, please set this variable to \c 0.
503 This will disable the display support, since the %CImg Library doesn't contain the necessary code to display
504 images on systems other than X11 or Windows GDI.
506 - \b \c cimg_color_terminal : This variable tells the library if the system terminal has VT100 color capabilities.
507 It can be \e defined or \e not \e defined. Define this variable to get colored output on your terminal,
508 when using the %CImg Library.
510 - \b \c cimg_debug : This variable defines the level of run-time debug messages that will be displayed by
511 the %CImg Library. It can be set to 0 (no debug messages), 1 (normal debug messages displayed on
512 standard error), 2 (normal debug messages displayed in modal windows, which is
513 the default value), or 3 (high debug messages). Note that setting this value to 3 may slow down your
514 program since more debug tests are made by the library (particularly to check if pixel access is made outside
515 image boundaries). See also CImgException to better understand how debug messages are working.
517 - \b \c cimg_convert_path : This variables tells the library where the ImageMagick's \e convert tool is located.
518 Setting this variable should not be necessary if ImageMagick is installed on a standard directory, or
519 if \e convert is in your system PATH variable. This macro should be defined only if the ImageMagick's
520 \e convert tool is not found automatically, when trying to read compressed image format (GIF,PNG,...).
521 See also cimg_library::CImg::get_load_convert() and cimg_library::CImg::save_convert() for more informations.
523 - \b \c cimg_temporary_path : This variable tells the library where it can find a directory to store
524 temporary files. Setting this variable should not be necessary if you are running on a standard system.
525 This macro should be defined only when troubles are encountered when trying to read
526 compressed image format (GIF,PNG,...).
527 See also cimg_library::CImg::get_load_convert() and cimg_library::CImg::save_convert() for more informations.
529 - \b \c cimg_plugin : This variable tells the library to use a plugin file to add features to the CImg<T> class.
530 Define it with the path of your plugin file, if you want to add member functions to the CImg<T> class,
531 without having to modify directly the \c "CImg.h" file. An include of the plugin file is performed in the CImg<T>
532 class. If \c cimg_plugin if not specified (default), no include is done.
534 - \b \c cimglist_plugin : Same as \c cimg_plugin, but to add features to the CImgList<T> class.
536 - \b \c cimgdisplay_plugin : Same as \c cimg_plugin, but to add features to the CImgDisplay<T> class.
538 All these compilation variables can be checked, using the function cimg_library::cimg::info(), which
539 displays a list of the different configuration variables and their values on the standard error output.
540 **/
541 /*@}*/
543 /*-----------------------------------
545 Using drawing functions
547 -------------------------------------*/
549 /** \addtogroup cimg_visual2005 How to use CImg library with Visual C++ 2005 Express Edition ?. */
550 /*@{*/
551 /**
552 \page foo89198
554 \section s13968 How to use CImg library with Visual C++ 2005 Express Edition ?
556 This section has been written by Vincent Garcia and Alexandre Fournier from I3S/Sophia_Antipolis.
558 - Download CImg library
559 - Download and install Visual C++ 2005 Express Edition
560 - Download and install Microsoft Windows SDK
561 - Configure Visual C++ to take into account Microsoft SDK
562 - 1. Go to menu "Tools -> options"
563 - 2. Select option "Projects and Solutions -> VC++ Directories"
564 - 3. In the select liste "Show directories for", choose "include files", and add C:\Program Files\Microsoft Platform SDK\Include (adapt if needed)
565 - 4. In the select liste "Show directories for", choose "library files", and add C:\Program Files\Microsoft Platform SDK\Lib
566 (adapt if needed) Edit file C:\Program Files\Microsoft Visual Studio 8\VC\VCProjectDefaults\corewin_express.vsprops (adapt if needed)
567 - 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" />
568 - Restart Visual C++
569 - Import CImg library in your main file
571 **/
572 /*@}*/
575 /*-----------------------------------
577 Tutorial : Getting started
579 -------------------------------------*/
581 /** \addtogroup cimg_tutorial Tutorial : Getting Started. */
582 /*@{*/
583 /**
584 \page foo3
586 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
587 display and mouse events.
588 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
589 point in the image will draw the (R,G,B) intensity profiles of the corresponding image line (in another window).
590 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
591 at the code below, it does the task :
593 \code
594 #include "CImg.h"
595 using namespace cimg_library;
597 int main() {
598 CImg<unsigned char> image("lena.jpg"), visu(500,400,1,3,0);
599 const unsigned char red[] = { 255,0,0 }, green[] = { 0,255,0 }, blue[] = { 0,0,255 };
600 image.blur(2.5);
601 CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile");
602 while (!main_disp.is_closed && !draw_disp.is_closed) {
603 main_disp.wait();
604 if (main_disp.button && main_disp.mouse_y>=0) {
605 const int y = main_disp.mouse_y;
606 visu.fill(0).draw_graph(image.get_crop(0,y,0,0,image.dimx()-1,y,0,0),red,1,1,0,255,0);
607 visu.draw_graph(image.get_crop(0,y,0,1,image.dimx()-1,y,0,1),green,1,1,0,255,0);
608 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);
609 }
610 }
611 return 0;
612 }
613 \endcode
615 Here is a screenshot of the resulting program :
617 <img SRC="../img/tutorial.jpg">
619 And here is the detailled explanation of the source, line by line :
621 \code #include "CImg.h" \endcode
622 Include the main and only header file of the CImg library.
623 \code using namespace cimg_library; \endcode
624 Use the library namespace to ease the declarations afterward.
625 \code int main() { \endcode
626 Definition of the main function.
627 \code CImg<unsigned char> image("lena.jpg"), visu(500,400,1,3,0); \endcode
628 Creation of two instances of images of \c unsigned \c char pixels.
629 The first image \c image is initialized by reading an image file from the disk.
630 Here, <tt>lena.jpg</tt> must be in the same directory than the current program.
631 Note that you must also have installed the \e ImageMagick package in order to be able to read JPG images.
632 The second image \c visu is initialized as a black color image with dimension <tt>dx=500</tt>, <tt>dy=400</tt>,
633 <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).
634 The last argument in the constructor defines the default value of the pixel values
635 (here \c 0, which means that \c visu will be initially black).
636 \code const unsigned char red[] = { 255,0,0 }, green[] = { 0,255,0 }, blue[] = { 0,0,255 }; \endcode
637 Definition of three different colors as array of unsigned char. This will be used to draw plots with different colors.
638 \code image.blur(2.5); \endcode
639 Blur the image, with a gaussian blur and a standard variation of 2.5. Note that most of the CImg functions have two versions :
640 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
641 begins then with <tt>get_</tt> ). In this case, one could have also written <tt>image = image.get_blur(2.5);</tt>
642 (more expensive, since it needs an additional copy operation).
643 \code CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile"); \endcode
644 Creation of two display windows, one for the input image image, and one for the image visu which will be display intensity profiles.
645 By default, CImg displays handles events (mouse,keyboard,..). On Windows, there is a way to create fullscreen displays.
646 \code while (!main_disp.is_closed && !draw_disp.is_closed) { \endcode
647 Enter the event loop, the code will exit when one of the two display windows is closed.
648 \code main_disp.wait(); \endcode
649 Wait for an event (mouse, keyboard,..) in the display window \c main_disp.
650 \code if (main_disp.button && main_disp.mouse_y>=0) { \endcode
651 Test if the mouse button has been clicked on the image area.
652 One may distinguish between the 3 different mouse buttons,
653 but in this case it is not necessary
654 \code const int y = main_disp.mouse_y; \endcode
655 Get the image line y-coordinate that has been clicked.
656 \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
657 This line illustrates the pipeline property of most of the CImg class functions. The first function <tt>fill(0)</tt> simply sets
658 all pixel values with 0 (i.e. clear the image \c visu). The interesting thing is that it returns a reference to
659 \c visu and then, can be pipelined with the function \c draw_graph() which draws a plot in the image \c visu.
660 The plot data are given by another image (the first argument of \c draw_graph()). In this case, the given image is
661 the red-component of the line y of the original image, retrieved by the function \c get_crop() which returns a
662 sub-image of the image \c image. Remember that images coordinates are 4D (x,y,z,v) and for color images,
663 the R,G,B channels are respectively given by <tt>v=0, v=1</tt> and <tt>v=2</tt>.
664 \code visu.draw_graph(image.get_crop(0,y,0,1,image.dimx()-1,y,0,1),green,1,0,256,0); \endcode
665 Plot the intensity profile for the green channel of the clicked line.
666 \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
667 Same thing for the blue channel. Note how the function (which return a reference to \c visu) is pipelined with the function
668 \c display() that just paints the image visu in the corresponding display window.
669 \code ...till the end \endcode
670 I don't think you need more explanations !
672 As you have noticed, the CImg library allows to write very small and intuitive code. Note also that this source will perfectly
673 work on Unix and Windows systems. Take also a look to the examples provided in the CImg package (
674 directory \c examples/ ). It will show you how CImg-based code can be surprisingly small.
675 Moreover, there is surely one example close to what you want to do.
676 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
677 with the %CImg Library. All CImg classes are used in this source, and the code can be easily modified to see what happens.
679 **/
680 /*@}*/
682 /*-----------------------------------
684 Using drawing functions
686 -------------------------------------*/
688 /** \addtogroup cimg_drawing Using Drawing Functions. */
689 /*@{*/
690 /**
691 \page foo5
693 \section s5 Using Drawing Functions.
695 This section tells more about drawing features in CImg images.
696 Drawing functions list can be found in <a href="structCImg.html">the CImg functions list</a>
697 (section \b Drawing Functions),
698 and are all defined on a common basis. Here are the important points to understand before using
699 drawing functions :
701 - Drawing is performed on the instance image. Drawing functions parameters
702 are defined as \e const variables and return a reference to the current instance <tt>(*this)</tt>,
703 so that drawing functions can be pipelined (see examples below).
704 Drawing is usually done in 2D color images but can be performed in 3D images with any vector-valued dimension,
705 and with any possible pixel type.
707 - A color parameter is always needed to draw features in an image. The color must be defined as a C-style array
708 whose dimension is at least
710 **/
711 /*@}*/
713 /*-----------------------------------
715 Using image loops
717 -------------------------------------*/
719 /** \addtogroup cimg_loops Using Image Loops. */
720 /*@{*/
721 /**
722 \page foo_lo
723 The %CImg Library provides different macros that define useful iterative loops over an image.
724 Basically, it can be used to replace one or several <tt>for(..)</tt> instructions, but it also proposes
725 interesting extensions to classical loops.
726 Below is a list of all existing loop macros, classified in four different categories :
727 - \ref lo1
728 - \ref lo4
729 - \ref lo5
730 - \ref lo6
732 \section lo1 Loops over the pixel buffer
734 Loops over the pixel buffer are really basic loops that iterate a pointer on the pixel data buffer
735 of a \c cimg_library::CImg image. Two macros are defined for this purpose :
737 - \b cimg_for(img,ptr,T) :
738 This macro loops over the pixel data buffer of the image \c img, using a pointer <tt>T* ptr</tt>,
739 starting from the end of the buffer (last pixel) till the beginning of the buffer (first pixel).
740 - \c img must be a (non empty) \c cimg_library::CImg image of pixels \c T.
741 - \c ptr is a pointer of type \c T*.
742 This kind of loop should not appear a lot in your own source code, since this is a low-level loop
743 and many functions of the CImg class may be used instead. Here is an example of use :
744 \code
745 CImg<float> img(320,200);
746 cimg_for(img,ptr,float) { *ptr=0; } // Equivalent to 'img.fill(0);'
747 \endcode
749 - \b cimg_foroff(img,off) :
750 This macro loops over the pixel data buffer of the image \c img, using an offset \c ,
751 starting from the beginning of the buffer (first pixel, \c off=0)
752 till the end of the buffer (last pixel value, <tt>off = img.size()-1</tt>).
753 - \c img must be a (non empty) cimg_library::CImg<T> image of pixels \c T.
754 - \c off is an inner-loop variable, only defined inside the scope of the loop.
756 Here is an example of use :
757 \code
758 CImg<float> img(320,200);
759 cimg_foroff(img,off) { img[off]=0; } // Equivalent to 'img.fill(0);'
760 \endcode
762 \section lo4 Loops over image dimensions
764 The following loops are probably the most used loops in image processing programs.
765 They allow to loop over the image along one or several dimensions, along a raster scan course.
766 Here is the list of such loop macros for a single dimension :
767 - \b cimg_forX(img,x) : equivalent to : <tt>for (int x=0; x<img.dimx(); x++)</tt>.
768 - \b cimg_forY(img,y) : equivalent to : <tt>for (int y=0; y<img.dimy(); y++)</tt>.
769 - \b cimg_forZ(img,z) : equivalent to : <tt>for (int z=0; z<img.dimz(); z++)</tt>.
770 - \b cimg_forV(img,v) : equivalent to : <tt>for (int v=0; v<img.dimv(); v++)</tt>.
772 Combinations of these macros are also defined as other loop macros, allowing to loop directly over 2D, 3D or 4D images :
773 - \b cimg_forXY(img,x,y) : equivalent to : \c cimg_forY(img,y) \c cimg_forX(img,x).
774 - \b cimg_forXZ(img,x,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forX(img,x).
775 - \b cimg_forYZ(img,y,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forY(img,y).
776 - \b cimg_forXV(img,x,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forX(img,x).
777 - \b cimg_forYV(img,y,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forY(img,y).
778 - \b cimg_forZV(img,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forZ(img,z).
779 - \b cimg_forXYZ(img,x,y,z) : equivalent to : \c cimg_forZ(img,z) \c cimg_forXY(img,x,y).
780 - \b cimg_forXYV(img,x,y,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forXY(img,x,y).
781 - \b cimg_forXZV(img,x,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forXZ(img,x,z).
782 - \b cimg_forYZV(img,y,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forYZ(img,y,z).
783 - \b cimg_forXYZV(img,x,y,z,v) : equivalent to : \c cimg_forV(img,v) \c cimg_forXYZ(img,x,y,z).
785 - 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.
786 They don't have to be defined before the call of the macro.
787 - \c img must be a (non empty) cimg_library::CImg image.
789 Here is an example of use that creates an image with a smooth color gradient :
790 \code
791 CImg<unsigned char> img(256,256,1,3); // Define a 256x256 color image
792 cimg_forXYV(img,x,y,v) { img(x,y,v) = (x+y)*(v+1)/6; }
793 img.display("Color gradient");
794 \endcode
796 \section lo5 Loops over interior regions and borders.
798 Similar macros are also defined to loop only on the border of an image, or inside the image (excluding the border).
799 The border may be several pixel wide :
801 - \b cimg_for_insideX(img,x,n) : Loop along the x-axis, except for pixels inside a border of \p n pixels wide.
802 - \b cimg_for_insideY(img,y,n) : Loop along the y-axis, except for pixels inside a border of \p n pixels wide.
803 - \b cimg_for_insideZ(img,z,n) : Loop along the z-axis, except for pixels inside a border of \p n pixels wide.
804 - \b cimg_for_insideV(img,v,n) : Loop along the v-axis, except for pixels inside a border of \p n pixels wide.
805 - \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.
806 - \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.
808 And also :
810 - \b cimg_for_borderX(img,x,n) : Loop along the x-axis, only for pixels inside a border of \p n pixels wide.
811 - \b cimg_for_borderY(img,y,n) : Loop along the y-axis, only for pixels inside a border of \p n pixels wide.
812 - \b cimg_for_borderZ(img,z,n) : Loop along the z-axis, only for pixels inside a border of \p n pixels wide.
813 - \b cimg_for_borderV(img,v,n) : Loop along the z-axis, only for pixels inside a border of \p n pixels wide.
814 - \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.
815 - \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.
817 - 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.
818 They don't have to be defined before the call of the macro.
819 - \c img must be a (non empty) cimg_library::CImg image.
820 - The constant \c n stands for the size of the border.
822 Here is an example of use, to create a 2d grayscale image with two different intensity gradients :
823 \code
824 CImg<> img(256,256);
825 cimg_for_insideXY(img,x,y,50) img(x,y) = x+y;
826 cimg_for_borderXY(img,x,y,50) img(x,y) = x-y;
827 img.display();
828 \endcode
830 \section lo6 Loops using neighborhoods.
832 Inside an image loop, it is often useful to get values of neighborhood pixels of the
833 current pixel at the loop location.
834 The %CImg Library provides a very smart and fast mechanism for this purpose, with the definition
835 of several loop macros that remember the neighborhood values of the pixels.
836 The use of these macros can highly optimize your code, and also simplify your program.
838 \subsection lo7 Neighborhood-based loops for 2D images
840 For 2D images, the neighborhood-based loop macros are :
842 - \b cimg_for2x2(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 2x2 neighborhood.
843 - \b cimg_for3x3(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 3x3 neighborhood.
844 - \b cimg_for4x4(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 4x4 neighborhood.
845 - \b cimg_for5x5(img,x,y,z,v,I) : Loop along the (x,y)-axes using a centered 5x5 neighborhood.
847 For all these loops, \c x and \c y are inner-defined variables only visible inside the scope of the loop.
848 They don't have to be defined before the call of the macro.
849 \c img is a non empty CImg<T> image. \c z and \c v are constants that define on which image slice and
850 vector channel the loop must apply (usually both 0 for grayscale 2D images).
851 Finally, \c I is the 2x2, 3x3, 4x4 or 5x5 neighborhood that will be updated with the correct pixel values
852 during the loop (see \ref lo9).
854 \subsection lo8 Neighborhood-based loops for 3D images
856 For 3D images, the neighborhood-based loop macros are :
858 - \b cimg_for2x2x2(img,x,y,z,v,I) : Loop along the (x,y,z)-axes using a centered 2x2x2 neighborhood.
859 - \b cimg_for3x3x3(img,x,y,z,v,I) : Loop along the (x,y,z)-axes using a centered 3x3x3 neighborhood.
861 For all these loops, \c x, \c y and \c z are inner-defined variables only visible inside the scope of the loop.
862 They don't have to be defined before the call of the macro.
863 \c img is a non empty CImg<T> image. \c v is a constant that defines on which image channel
864 the loop must apply (usually 0 for grayscale 3D images).
865 Finally, \c I is the 2x2x2 or 3x3x3 neighborhood that will be updated with the correct pixel values
866 during the loop (see \ref lo9).
868 \subsection lo9 Defining neighborhoods
870 A neighborhood is defined as an instance of a class having operator[] defined.
871 This particularly includes classical C-array, as well as CImg<T> objects.
873 For instance, a 3x3 neighborhood can be defined either as a 'float[9]' or a
874 'CImg<float>(3,3)' variable.
876 \subsection lo10 Using alternate variable names
878 There are also some useful macros that can be used to define variables that
879 reference the neighborhood elements. There are :
881 - \b CImg_2x2(I,type) : Define a 2x2 neighborhood named \c I, of type \c type.
882 - \b CImg_3x3(I,type) : Define a 3x3 neighborhood named \c I, of type \c type.
883 - \b CImg_4x4(I,type) : Define a 4x4 neighborhood named \c I, of type \c type.
884 - \b CImg_5x5(I,type) : Define a 5x5 neighborhood named \c I, of type \c type.
885 - \b CImg_2x2x2(I,type) : Define a 2x2x2 neighborhood named \c I, of type \c type.
886 - \b CImg_3x3x3(I,type) : Define a 3x3x3 neighborhood named \c I, of type \c type.
888 Actually, \c I is a \e generic \e name for the neighborhood. In fact, these macros declare
889 a \e set of new variables.
890 For instance, defining a 3x3 neighborhood \c CImg_3x3(I,float) declares 9 different float variables
891 \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
892 a 3x3 neighborhood.
893 Variable indices are \c p,\c c or \c n, and stand respectively for \e 'previous', \e 'current' and \e 'next'.
894 First indice denotes the \c x-axis, second indice denotes the \c y-axis.
895 Then, the names of the variables are directly related to the position of the corresponding pixels
896 in the neighborhood. For 3D neighborhoods, a third indice denotes the \c z-axis.
897 Then, inside a neighborhood loop, you will have the following equivalence :
898 - <tt>Ipp = img(x-1,y-1)</tt>
899 - <tt>Icn = img(x,y+1)</tt>
900 - <tt>Inp = img(x+1,y-1)</tt>
901 - <tt>Inpc = img(x+1,y-1,z)</tt>
902 - <tt>Ippn = img(x-1,y-1,z+1)</tt>
903 - and so on...
905 For bigger neighborhoods, such as 4x4 or 5x5 neighborhoods, two additionnal indices are introduced :
906 \c a (stands for \e 'after') and \c b (stands for \e 'before'), so that :
907 - <tt>Ibb = img(x-2,y-2)</tt>
908 - <tt>Ina = img(x+1,y+2)</tt>
909 - and so on...
911 The value of a neighborhood pixel outside the image range (image border problem) is automatically set to the same
912 values than the nearest valid pixel in the image (this is also called the \e Neumann \e border \e condition).
914 \subsection lo11 Example codes
915 More than a long discussion, the above example will demonstrate how to compute the gradient norm of a 3D volume
916 using the \c cimg_for3x3x3() loop macro :
918 \code
919 CImg<float> volume("IRM.hdr"); // Load an IRM volume from an Analyze7.5 file
920 CImg_3x3x3(I,float); // Define a 3x3x3 neighborhood
921 CImg<float> gradnorm(volume); // Create an image with same size as 'volume'
922 cimg_for3x3x3(volume,x,y,z,0,I) { // Loop over the volume, using the neighborhood I
923 const float ix = 0.5f*(Incc-Ipcc); // Compute the derivative along the x-axis.
924 const float iy = 0.5f*(Icnc-Icpc); // Compute the derivative along the y-axis.
925 const float iz = 0.5f*(Iccn-Iccp); // Compute the derivative along the z-axis.
926 gradnorm(x,y,z) = std::sqrt(ix*ix+iy*iy+iz*iz); // Set the gradient norm in the destination image
927 }
928 gradnorm.display("Gradient norm");
929 \endcode
931 And the following example shows how to deal with neighborhood references to blur a color image by averaging
932 pixel values on a 5x5 neighborhood.
934 \code
935 CImg<unsigned char> src("image_color.jpg"), dest(src,false), neighbor(5,5); // Image definitions.
936 typedef unsigned char uchar; // Avoid space in the second parameter of the macro CImg_5x5x1 below.
937 CImg<> N(5,5); // Define a 5x5 neighborhood as a 5x5 image.
938 cimg_forV(src,k) // Standard loop on color channels
939 cimg_for5x5(src,x,y,0,k,N) // 5x5 neighborhood loop.
940 dest(x,y,k) = N.sum()/(5*5); // Averaging pixels to filter the color image.
941 CImgList<unsigned char> visu(src,dest);
942 visu.display("Original + Filtered"); // Display both original and filtered image.
943 \endcode
945 As you can see, explaining the use of the CImg neighborhood macros is actually more difficult than using them !
947 **/
948 /*@}*/
950 /*-----------------------------------
952 Using display windows
954 -------------------------------------*/
956 /** \addtogroup cimg_displays Using Display Windows. */
957 /*@{*/
958 /**
959 \page foo_di
961 When opening a display window, you can choose the way the pixel values will be normalized
962 before being displayed on the screen. Screen displays only support color values between [0,255],
963 and some
965 When displaying an image into the display window using CImgDisplay::display(), values of
966 the image pixels can be eventually linearly normalized between [0,255] for visualization purposes.
967 This may be useful for instance when displaying \p CImg<double> images with pixel values
968 between [0,1].
969 The normalization behavior depends on the value of \p normalize which can be either \p 0,\p 1 or \p 2 :
970 - \p 0 : No pixel normalization is performed when displaying an image. This is the fastest
971 process, but you must be sure your displayed image have pixel values inside the range [0,255].
972 - \p 1 : Pixel value normalization is done for each new image display. Image pixels are
973 not modified themselves, only displayed pixels are normalized.
974 - \p 2 : Pixel value normalization is done for the first image display, then the
975 normalization parameters are kept and used for all the next image displays.
977 **/
978 /*@}*/
980 /*-----------------------------------
982 How pixel data are stored
984 -------------------------------------*/
986 /** \addtogroup cimg_storage How pixel data are stored with CImg. */
987 /*@{*/
988 /**
989 \page foo_store
991 First, CImg<T> are *very* basic structures, which means that there are no memory tricks, weird memory alignments or
992 disk caches used to store pixel data of images. When an image is instanced, all its pixel values are stored in memory at
993 the same time (yes, you should avoid working with huge images when dealing with CImg, if you have only 64kb of RAM).
995 A CImg<T> is basically a 4th-dimensional array (width,height,depth,dim), and its pixel data are stored linearly in a single
996 memory buffer of general size (width*height*depth*dim). Nothing more, nothing less. The address of this memory buffer can be
997 retrieved by the function CImg<T>::ptr().
998 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'.
999 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
1000 instance image (in bytes) is then 'width*height*depth*dim*sizeof(T)'.
1002 Now, the ordering of the pixel values in this buffer follows these rules :
1003 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),
1004 starting from the upper-left pixel to the bottom-right pixel of the instane image, with a classical scanline run.
1006 So, a color image with dim=3 and depth=1, will be stored in memory as :
1008 R1R2R3R4R5R6......G1G2G3G4G5G6.......B1B2B3B4B5B6.... (i.e following a 'planar' structure)
1010 and *not* as R1G1B1R2G2B2R3G3B3... (interleaved channels),
1011 where R1 = img(0,0,0,0) is the first upper-left pixel of the red component of the image,
1012 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...
1014 Another example, a (1x5x1x1) CImg<T> (column vector A) will be stored as : A1A2A3A4A5
1015 where A1 = img(0,0), A2 = img(0,1), ... , A5 = img(0,4).
1017 As you see, it is *very* simple and intuitive : no interleaving, no padding, just simple.
1018 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
1019 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)'
1020 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
1021 your image, you can just skip it in the call to the operator(). Similarly, values of a column vector stored as an image with
1022 width=depth=dim=1 can be accessed by 'img(y)' instead of 'img(0,y)'. This is very convenient.
1024 Another cool thing is that it allows you to work easily with 'shared' images. A shared image is a CImg<T> instance that shares
1025 its memory with another one (the 'base' image). Destroying a shared image does nothing in fact. Shared images is a convenient
1026 way of modifying only *portions* (consecutive in memory) of an image. For instance, if 'img' is a 2D color image, you can write :
1028 img.get_shared_channel(0).blur(2);
1029 img.get_shared_channels(1,2).mirror('x');
1031 which just blur the red channel of the image, and mirror the two others along the X-axis.
1032 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).
1034 **/
1035 /*@}*/
1037 /*-----------------------------------
1039 Files IO
1041 -------------------------------------*/
1043 /** \addtogroup cimg_files_io Files IO in CImg. */
1044 /*@{*/
1045 /**
1046 \page foo_fi
1048 The %CImg Library can NATIVELY handle the following file formats :
1049 - RAW : consists in a very simple header (in ascii), then the image data.
1050 - ASC (Ascii)
1051 - HDR (Analyze 7.5)
1052 - INR (Inrimage)
1053 - PPM/PGM (Portable Pixmap)
1054 - BMP (uncompressed)
1055 - PAN (Pandore-5)
1056 - DLM (Matlab ASCII)
1058 If ImageMagick is installed, The %CImg Library can save image in formats handled by ImageMagick : JPG, GIF, PNG, TIF,...
1060 **/
1061 /*@}*/
1063 /*-----------------------------------
1065 Retrieving command line arguments
1067 -------------------------------------*/
1069 /** \addtogroup cimg_options Retrieving Command Line Arguments. */
1070 /*@{*/
1071 /**
1072 \page foo_so
1074 The CImg library offers facilities to retrieve command line arguments in a console-based
1075 program, as it is a commonly needed operation.
1076 Three macros \c cimg_usage(), \c cimg_help() and \c cimg_option() are defined for this purpose.
1077 Using these macros allows to easily retrieve options values from the command line.
1078 Invoking the compiled executable with the option \c -h or \c --help will
1079 automatically display the program usage, followed by the list of requested options.
1081 \section so1 The cimg_usage() macro
1083 The macro \c cimg_usage(usage) may be used to describe the program goal and usage.
1084 It is generally inserted one time after the <tt>int main(int argc,char **argv)</tt> definition.
1086 \param usage : A string describing the program goal and usage.
1087 \pre The function where \c cimg_usage() is used must have correctly defined \c argc and \c argv variables.
1089 \section so1_5 The cimg_help() macro
1091 The macro \c cimg_help(str) will display the string \c str only if the \c -help or \c --help option
1092 are invoked when running the programm.
1094 \section so2 The cimg_option() macro
1096 The macro \c cimg_option(name,default,usage) may be used to retrieve an option value from the command line.
1098 \param name : The name of the option to be retrieved from the command line.
1099 \param default : The default value returned by the macro if no options \p name has been specified when running the program.
1100 \param usage : A brief explanation of the option. If \c usage==0, the option won't appear on the option list
1101 when invoking the executable with options \c -h or \c --help (hidden option).
1103 \return \c cimg_option() returns an object that has the \e same \e type than the default value \c default.
1104 The return value is equal to the one specified on the command line. If no such option have been specified,
1105 the return value is equal to the default value \c default.
1106 Warning, this can be confusing in some situations (look at the end of the next section).
1107 \pre The function where \c cimg_option() is used must have correctly defined \c argc and \c argv variables.
1109 \section so3 Example of use
1111 The code below uses the macros \c cimg_usage() and \c cimg_option().
1112 It loads an image, smoothes it an quantifies it with a specified number of values.
1113 \code
1114 #include "CImg.h"
1115 using namespace cimg_library;
1116 int main(int argc,char **argv) {
1117 cimg_usage("Retrieve command line arguments");
1118 const char* filename = cimg_option("-i","image.gif","Input image file");
1119 const char* output = cimg_option("-o",(char*)0,"Output image file");
1120 const double sigma = cimg_option("-s",1.0,"Standard variation of the gaussian smoothing");
1121 const int nblevels = cimg_option("-n",16,"Number of quantification levels");
1122 const bool hidden = cimg_option("-hidden",false,0); // This is a hidden option
1124 CImg<unsigned char> img(filename);
1125 img.blur(sigma).quantize(nblevels);
1126 if (output) img.save(output); else img.display("Output image");
1127 if (hidden) std::fprintf(stderr,"You found me !\n");
1128 return 0;
1129 }
1130 \endcode
1132 Invoking the corresponding executable with <tt>test -h -hidden -n 20 -i foo.jpg</tt> will display :
1133 \verbatim
1134 ./test -h -hidden -n 20 -i foo.jpg
1136 test : Retrieve command line arguments (Oct 16 2004, 12:34:26)
1138 -i = foo.jpg : Input image file
1139 -o = 0 : Output image file
1140 -s = 1 : Standard variation of the gaussian smoothing
1141 -n = 20 : Number of quantification levels
1143 You found me !
1144 \endverbatim
1146 \warning As the type of object returned by the macro \c cimg_option(option,default,usage)
1147 is defined by the type of \c default, undesired casts may appear when writting code such as :
1148 \code
1149 const double sigma = cimg_option("-val",0,"A floating point value");
1150 \endcode
1151 In this case, \c sigma will always be equal to an integer (since the default value \c 0 is an integer).
1152 When passing a float value on the command line, a \e float \e to \e integer cast is then done,
1153 truncating the given parameter to an integer value (this is surely not a desired behavior).
1154 You must specify <tt>0.0</tt> as the default value in this case.
1156 \section so4 How to learn more about command line options ?
1157 You should take a look at the examples <tt>examples/gmic.cpp</tt> provided in the %CImg Library package.
1158 This is a command line based image converter which intensively uses the \c cimg_option() and \c cimg_usage()
1159 macros to retrieve command line parameters.
1160 **/
1161 /*@}*/