The C++ Template Image Processing Library. |
[Introduction]- [News]- [Download]- [Screenshots]- [Tutorial]- [Forums]- [Reference]- [SourceForge Repository ]

Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members

# Introduction to the CImg Library

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

## Library structure

The file CImg.h contains all the classes and functions that compose the library itself. It is organized as follows :

- All library classes and functions are defined in the namespace cimg_library. This namespace encapsulates all library functionalities and avoid any class name collision that could happen with other includes. Generally, one uses this namespace as a default namespace :

        #include "CImg.h"
        using namespace cimg_library;

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

- The class cimg_library::CImg represents images up to 4-dimensions wide, containing pixels of type `T`. This is actually the main class of the library.

- The class cimg_library::CImgl represents lists of cimg_library::CImg images. It can be used for instance to store different frames of an image sequence.

- The class cimg_library::CImgDisplay is able to display images or image lists into graphical windows. As you may guess, the code of this class is highly system-dependant (see `cimg_display_type` in Setting Environment Variables ).

- The class cimg_library::CImgStats represents simple image statistics. Use it to compute the minimum, maximum, mean and variance of pixel values of images.

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

Knowing these five classes is enough to get benefit of most of the CImg Library functionalities.

As you can see, all the library functions and classes are defined in a single header file CImg.h. This may sound strange, but it is actually one major advantage of the CImg library :

- The compilation is done on the fly : Only functions really used in your program are compiled and appear in the final program. This leads to very compact executables, without any unused functions code.
- Class members and functions are inlined, leading to better performance during execution.
- No complex dependancies have to be handled : Just include the CImg.h file, and you get a working toolkit that processes images.

## CImg version of "Hello world".

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

      #include "CImg.h"
      using namespace cimg_library;

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

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

      #include "CImg.h"
      using namespace cimg_library;

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

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

## How to compile ?

The CImg library is a very light and user-friendly library : only standart system libraries are used. this avoid to handle complex dependancies and problems with library compatibility. The only thing you need is a (quite modern) C++ compiler. Before each release, the CImg library is successfully compiled with the following compilers :

- Microsoft Visual C++ 6.0 and Visual Studio.NET : Use project files and solution files provided in the CImg Library package to see how it works.
- Intel ICL compiler : Use the following command to compile a CImg-based program with ICL :

        icl /Ox hello_world.cpp user32.lib gdi32.lib

- Digital Mars Compiler : Use the following command to compile a CImg-based program with DMC :

        dmc -Ae hello_world.cpp gdi32.lib

- g++ (MingW windows version) : Use the following command to compile a CImg-based program with g++, on Windows :

        g++ -o hello_word.exe hello_word.cpp -O2 -lgdi32

- g++ (Linux version) : Use the following command to compile a CImg-based program with g++, on Linux :

        g++ -o hello_word.exe hello_world.cpp -O2 -Wl,-rpath /usr/X11R6/lib -lm -lpthread -lX11

- g++ (Solaris version) : Use the following command to compile a CImg-based program with g++, on Solaris :

        g++ -o hello_word.exe hello_world.cpp -O2 -lm -lpthread -R/usr/X11R6/lib -lrt -lnsl -lsocket

- Dev-Cpp : Use the project file provided in the CImg library package to see how it works.

If you are using another compilers and encounter problems, please write me since maintaining compatibility is one of my priority.

## What's next ?

If you are ready to get more, and to start writing more serious programs with CImg, you are invited to go to the Tutorial : Getting Started. section.