The C++ Template Image Processing Library.
Initially developped in the Odyssée Lab, at the INRIA-Sophia Antipolis.

[Introduction]- [Latest News]- [Download]- [Screenshots]- [Tutorial]- [Forums]- [Library Reference]- [SourceForge Repository ]

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

Tutorial : Getting started.

Let's start to write our first program to get the idea. This will demonstrate how to load and create images, as well as handle image display and mouse events. Assume we want to load a color image 'toto.jpg', smooth it, display it in a windows, and enter an event loop so that clicking a point in the image with the mouse will draw the intensity profiles of (R,G,B) of the corresponding image line (in another window). Yes, that sounds quite complex for a first code, but don't worry, it will be very simple using the CImg library ! Well, just look at the code below, it does the task :

1. #include "CImg.h"
2. int main() {
3.   CImg<uchar> image("toto.jpg"), visu(500,400,1,3,0);
4.   const uchar red[3]={255,0,0}, green[3]={0,255,0}, blue[3]={0,0,255};
5.   image.blur(2.5);
6.   CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile");
7.   while (!main_disp.closed && !draw_disp.closed) {
8.     main_disp.wait();
9.     if (main_disp.button) {
10.         const int y = main_disp.mousey;
11.         visu.fill(0).draw_plot(image.get_sprite(0,y,0,0,image.dimx()-1,y,0,0),red,0,256);
12.         visu.draw_plot(image.get_sprite(0,y,0,1,image.dimx()-1,y,0,1),green,0,256);
13.         visu.draw_plot(image.get_sprite(0,y,0,2,image.dimx()-1,y,0,2),blue,0,256).display(draw_disp);
14.       }
15.     }
16.   return 0;
17. }

Note that the CImg specific functions has been set to bold face.

tutorial.jpg

Here is the complete explanation of the source, line by line :

  1. #include "CImg.h"
    Include the main and only header file of the CImg library.
  2. int main() {
    Definition of the main function.
  3. CImg<uchar> image("toto.jpg"), visu(500,400,1,3,0);
    Creation of two instances of images of unsigned char pixels.
    The first one image is initialized by reading an image file from the disk. Here, toto.jpg must be in the same directory than the current program. Note that you must also have installed the ImageMagick package in order to be able to read JPG images. The second one visu is initialized as a black color image with dimension dx=500, dy=400, dz=1 (here, it is a 2D image, not a 3D one), and dv=3 (each pixel has 3 'vector' channels R,G,B). The last argument in the constructor defines the default value of the pixel values (here 0, which means that visu will be initially black).
  4. const uchar red[3]={255,0,0}, green[3]={0,255,0}, blue[3]={0,0,255};
    Definition of three different colors as array of unsigned char. This will be used to draw plots with different colors.
  5. image.blur(2.5);
    Blur the image, with a gaussian blur and a variance of 2.5. Note that most of the CImg functions have two versions : one that acts in-place (which is the case of blur), and one that returns the result as a new image (the name of the function begins then with get_ ). In this case, one could have also written image = image.get_blur(2.5); (more expensive, since it needs an additional copy operation).
  6. CImgDisplay main_disp(image,"Click a point"), draw_disp(visu,"Intensity profile");
    Creation of two display windows, one for the input image image, and one for the image visu which will be display intensity profiles. By default, CImg displays handles events (mouse,keyboard,..). On Windows, there is a way to create fullscreen displays.
  7. while (!main_disp.closed && !draw_disp.closed) {
    Enter the event loop, the code will exit when one of the two display windows is closed.
  8. main_disp.wait();
    Wait for an event (mouse, keyboard,..) in the display window main_disp.
  9. if (main_disp.button) {
    Test if the mouse button is clicked. One may distinguish between the 3 different mouse buttons, but in this case it is not necessary
  10. const int y = main_disp.mousey;
    Get the image line y-coordinate that has been clicked.
  11. visu.fill(0).draw_plot(image.get_sprite(0,y,0,0,image.dimx()-1,y,0,0),red,0,256);
    This line illustrates the pipeline property of most of the CImg class functions. The first function fill(0) simply sets all pixel values with 0 (i.e. clear the image visu). The interesting thing is that it returns a reference to visu and then, can be pipelined with the function draw_plot() which draws a plot in the image visu. The plot data are given by another image (the first argument of draw_plot()). In this case, the given image is the red-component of the line y of the original image, retrieved by the function get_sprite() which returns a sub-image of the image image. Remember that images coordinates are 4D (x,y,z,v) and for color images, the R,G,B channels are respectively given by v=0, v=1 and v=2.
  12. visu.draw_plot(image.get_sprite(0,y,0,1,image.dimx()-1,y,0,1),green,0,256);
    Plot the intensity profile for the green channel of the clicked line.
  13. visu.draw_plot(image.get_sprite(0,y,0,2,image.dimx()-1,y,0,2),blue,0,256).display(draw_disp);
    Same thing for the blue channel. Note how the function (which return a reference to visu) is pipelined with the function display() that just paints the image visu in the corresponding display window.
  14. till the end
    I don't think you need more explanations !

As you have noticed, the CImg library allows to write very small and intuitive code. Note also that this source will perfectly work on Unix and Windows systems. Take also a look to this examples provided in the CImg package (particularly the one in the file CImg_test.cpp). It will show you how code can be small with the CImg library.

How to compile ?

The CImg library is a very light and user-friendly library. No use of huge and complex dependancies is done, in order to ease the compilation. The library examples are compiled with many different C++ compilers before each release : Microsoft Visual C++, Visual Studio.NET, Intel IA32 compiler, DMC, G++, ... It may happens that some compilers has problems. But in this case, please e-mail me, the portability of the library is one of my main goal, so be sure I'll answer quickly.

To compile the code above (and generally all code using CImg), you need to link it with the standart visualization library (GDI32 on Windows, and X11 on Unix/Mac OS). Here are some examples of compilation commands that are valid :

Well, there are surely plenty of variants, but believe me, that's very simple since only standart C and system libraries are used by CImg.

Where to find more sources and tutorials ?

Take a look at the various examples provided in the CImg Library package. There is surely one example that is close of what you want to do (if this is a basic image processing thing of course !). A good start will be to look at the file CImg_test.cpp which contains small and various examples of what you can do with the CImg Library. All CImg classes are used in this source, and the code can be easily modified to see what happens.
Generated on Tue Aug 10 17:35:47 2004 for The CImg Library by doxygen 1.3.8