A short tutorial on using CImg under Xcode

CImg is a powerful library allows you to manage images in your own C++ code. In this tutorial I will show you how to set up CImg library under Xcode in several steps as it can be problematic (at least for me).

(You need to install command line tool for Xcode and also X11 on your mac.)

The first step is to download the latest version (current version is 1.5.6) of CImg from its website (http://cimg.sourceforge.net/download.shtml). Inside the downloaded folder, there is one file called CImg.h and this one is all we need. The plugins folder adds extensions for CImg library as I will cover in later section. After copying the CImg header file into the same folder of your project, use #include "CImg.h" to include this header file.

The second step is set header search path as Xcode will likely to fail to find the other header files declared in CImg.h (many linked to X11 like Xlib.h). This failure is due to mis-location of these header files. One solution is to find the real location of the these header files (by searching with finder) and then add this path to "Header Search Paths" in "Build Setting" of your project information. In my case, X11 headers are not found so I added "/opt/X11/include"to "Header Search Paths" and therefore solved this problem.

The third step is to include the framework. Framework does function declarations and thus avoid errors like "Apple Math-O Linker ID error". Adding framework option also relies in "Build Setting" of your project information. In my case, the framework required is libX11.6.dylib (by searching through my mac with finder).

Finally, CImg is well set and ready to use. However, CImg natively supports only a few image formats like png and bmp and you may not be happy with this. To support more commonly used image formats, CImg allows you to install external tools (for example ImageMagick). After installing one of these tools/libraries, CImg would be able to read and write any file formats that are supported by the installed tool by triggering the option (in my case, #define cimg_use_magick). Note that the same problem in step two and three could happen for the external library. The solutions would be the same and also remember to include stdlib.h as the external library may need it. Besides header search error and linker id error, Xcode might fail to find the convert tool provided by third party library. If this happens, you need to specify the tool path. In my case, cimg::imagemagick_path("/usr/local/bin/convert");

To sum up, Xcode need extra cares on header search path and framework when using CImg library. Once set, you can start doing your image processing project.

Here is one example code of using CImg library. This code simply loads an image called lena and then displays it using X11 (default on Mac OSX).

#include "CImg.h"
#include <stdlib.h>
#define cimg_use_magick

using namespace cimg_library;

int main() {

CImg<unsigned char> image("lena.jpg");

image.display();

return 0;

}