## Latest stable version: 3.5.1 Current pre-release: 3.5.2 (2025/01/28)

- Home
- Download
- Screenshots
- Tutorial
- Documentation
- Report Issue
- Links
- Book

Reference

CImg Library Overview

The CImg Library is an image processing library, designed for C++ programmers. It provides useful classes and functions to load/save, display and process various types of images.

# Library structure

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

The header file CImg.h contains all the classes and functions that compose the library itself. This is one originality of the CImg Library. This particularly means that :

- No pre-compilation of the library is needed, since the compilation of the CImg functions is done at the same time as the compilation of your own C++ code.
- No complex dependencies have to be handled : Just include the CImg.h file, and you get a working C++ image processing toolkit.
- The compilation is done on the fly : only CImg functionalities really used by your program are compiled and appear in the compiled executable program. This leads to very compact code, without any unused stuff.
- Class members and functions are inlined, leading to better performance during the program execution.

The CImg Library is structured as follows :

- All library classes and functions are defined in the namespace cimg_library. This namespace encapsulates the 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;
  ...
  cimg_library
  Contains all classes and functions of the CImg library.
  Definition CImg.h:2324
- The namespace 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 namespace as a default namespace, since it contains functions whose names are already defined in the standard C/C++ library.
- The class CImg represents images up to 4-dimensions wide, containing pixels of type `T` (template parameter). This is actually the main class of the library.
- The class CImgList represents lists of cimg_library::CImg<T> images. It can be used for instance to store different frames of an image sequence.
- The class CImgDisplay is able to display images or image lists into graphical display windows. As you may guess, the code of this class is highly system-dependent but this is transparent for the programmer, as environment variables are automatically set by the CImg library (see also Setting Environment Variables).
- The class CImgException (and its subclasses) are used by the library to throw exceptions when errors occur. Those exceptions can be caught with a try { ..} catch (CImgException) { .. } block. Subclasses define precisely the type of encountered errors.

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

# CImg version of "Hello world".

Below is some 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 with 8 bits per color component.
img.fill(0); // Set pixel values to 0 (color : black)
unsigned char purple[] = { 255,0,255 }; // Define a purple color
img.draw_text(100,100,"Hello World",purple); // Draw a purple "Hello world" at coordinates (100,100).
img.display("My first CImg code"); // Display the image in a display window.
return 0;
}
cimg_library::CImg
Class representing an image (up to 4 dimensions wide), each pixel being of type T.
Definition CImg.h:11829

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

#include "CImg.h"
using namespace cimg_library;
int main() {
const unsigned char purple[] = { 255,0,255 };
CImg<unsigned char>(640,400,1,3,0).draw_text(100,100,"Hello World",purple).display("My first CImg code");
return 0;
}
cimg_library::CImg::draw_text
CImg< T > & draw_text(const int x0, const int y0, const char *const text, const tc1 *const foreground_color, const tc2 *const background_color, const float opacity, const CImgList< t > *const font,...)
Draw a text string.
Definition CImg.h:51709

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

# How to compile ?

The CImg library is a very light and user-friendly library : only standard system libraries are used. It avoids handling complex dependencies and problems with library compatibility. The only thing you need is a C++ compiler :

- Microsoft Visual Studio.NET and Visual Express Edition : Use the project files and solution files provided in the CImg Library package (directory 'compilation/') 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
- g++ (MingW windows version) : Use the following command to compile a CImg-based program with g++, on Windows :
  g++ -o hello_world.exe hello_world.cpp -O2 -lgdi32
- g++ (Linux version) : Use the following command to compile a CImg-based program with g++, on Linux :
  g++ -o hello_world.exe hello_world.cpp -O2 -L/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_world.exe hello_world.cpp -O2 -lm -lpthread -R/usr/X11R6/lib -lrt -lnsl -lsocket
- g++ (Mac OS X version) : Use the following command to compile a CImg-based program with g++, on Mac OS X :
  g++ -o hello_world.exe hello_world.cpp -O2 -lm -lpthread -I/usr/X11R6/include -L/usr/X11R6/lib -lm -lpthread -lX11
- Dev-Cpp : Use the project file provided in the CImg library package to see how it works.

If you are using other compilers and encounter problems, please write me since maintaining compatibility is one of the priorities of the CImg Library. Nevertheless, old compilers that do not respect the C++ standard will not support the CImg Library.

# 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.

Copyrights (C) From october 2004, David Tschumperlé - GREYC UMR CNRS 6072, Image team.
Copyrights (C) January->September 2004, David Tschumperlé.
Copyrights (C) 2000->2003, David Tschumperlé - INRIA Sophia-Antipolis. Odyssée group.