Image Analysis and Computer Vision

Short Tutorial to the CImg & Argstream Libraries

The CImg Library

The CImg library is a modern image library for c++ which greatly simplifies programming, as one can access the
image pixels naturally by their 2d position, i.e. imgVariable(x,y), contrary to the somewhat tedious linear accessing,
i.e. imgVariable[x+y*width], of low level libraries.

1.1

Declaration of Images

First of all, to use the libarary in your code you have to include one single header file CImg.h and indicate that
its namespace cimg library has to be used. The declaration of an image is then simply given by CImg<type>
where the type stands for the variable type used for the pixels. We suggest to use the type float. Instead of only
declaring an image, one can directly allocate the desired image size, initialize the image from a file or clone it from
a previous image.
#include "CImg.h"
using namespace cimg_library;
CImg<float>
CImg<float>
CImg<float>
CImg<float>

1.2

myEmptyFloatImg
/* pure declaration of image (no size) */
myFloatImg (300,200);
/* 300x200 float pixel image */
myFloatImg1 ("demo.png"); /* directly loading a file */
myFloatImg2 (myFloatImg); /* copying a previous image */

Loading of Images

Loading and saving of images is very simple and a vast of image formats are supported (basically everything the
command convert can handle):
string testFilename="testImage.png";
myFloatImg.load (testFilename.c_str());
/* loading from file */
myFloatImg.save ("outputImage.png"); /* saving to file */
Obviously, when loading an image any content in the variable myFloatImg will be lost. Moreover, as this library
is ready to deal with color images but in this course we mainly deal with greyscale images you might need to
convert an image to grey scale which is achieved by
/* conversion to greyscale images (does not change non-color images) */
myFloatImg = myFloatImg.get_norm_pointwise(1) / (float)myFloatImg.dimv();
As it does not change an image which is already in greyscale format, we suggest that you always do that unless you
really want to deal with colour images.

1.3

Image inspection

You might also be interested in viewing the content of an image variable during the execution of your program
which is achieved by

myFloatImg.display ("Window Title");

/* displaying the image */

which opens a window (with specified title) on your screen. The program execution is then blocked until you press
any key (while that window has focus). It also gives you a little interface to inspect the pixel values of the image
at particular position which might be helpful.

1.4

Processing the image

After having dealt with the variable declaration, input/output matters, one can actually start processing the image.
The dimensions of the image can be accessed by
/* .. .. .. do some processing .. .. .. */
unsigned width = myFloatImg.dimx();
// access image width
unsigned height = myFloatImg.dimy(); // access image height
Sometimes it is necessary to initialize the image, such that all pixels have a particular value. This can be
achieved by the function call
myFloatImg.fill(0.0f);
which, in this example, sets every pixel to zero.
As already mentioned, the access of the pixels is intuitively like one would access a 2-dimensional array, i.e.
for (unsigned y=0; y < height; y++) {
for (unsigned x=0; x < width; x++) {
myFloatImg(x,y) = x*y;
}
}

1.5

Compilation and Linking

For convenience, we provide a simple script which deals with all matters of compiling and linking a source-code to
an executable. This is achieved by invoking the command
biwicompile

yourSourceFile.cc

where the argument obviously is the file containing your code. The resulting binary will have the same name, but
without the extension, in this example it would be yourSourceFile.

Argument Reading using Argstream

argstream.h is a c++-template based library designed for simple command line argument reading. Its usage is
very simple and is explained by the following code snippet:
1
2
3
5
6
7
8
9
10
11
12
13
14
15
16
17

#include "argstream.h"
int main(int argc, char**argv) {
argstream as(argc, argv);
string sFilename="defaultFile.png";
int
nNumber=3;
float dFloat;
as >> parameter("i", sFilename, "Path to a local file ", true);
as >> parameter("n", nNumber, "some number ", false);
as >> parameter("d", dFloat, "a floating point", false);
as >> help();
as.defaultErrorHandling();
return 0;
}
2

Firstly, to use the library one has to include its header file argstream.h (line 1). Line 5 defines an argstream object
and the lines 14 and 15 deal with the error handling and displaying of an automatically generated usage text which
is displayed when the program is called with the option help. This lines will always be the same and you do not
have to care about them; just copy them as they are!
The interesting part is in the middle, i.e. lines 7 to 12. Basically, for every command line option you have
to declare a variable. You may already initialize it with some value (which will result in a default value for that
option). Then, the actual argument reading is achieved by the lines 10..12. The syntax is identical for all types of
variables youd like to read from cmdline and is simply
as >> parameter (<Name: string>,
<Var: variable of some type>,
<Description: String>,
<Mandatory?: bool>);
where the first argument indicates the option name (which will be given on the command line, eg. Name value)
the second specifies the variable where the value provided on the command line has to be stored. The third argument
gives a short description about the option (which is displayed when giving the option help) and the last argument
indicates whether the user always has to provide that command line option, i.e. it is mandatory, or if it is optional.
In case of an optional variable you have to put false and if it s mandatory, the argument has to be set to true.

References

Further, more detailed information for the two libraries can be found on the web at the following two web sites:
http://cimg.sourceforge.net/
http://artis.imag.fr/ Xavier.Decoret/resources/argstream/

Sample Program

/
warp . cc
compile with :

b i w i c o m p i l e warp . cc
e x e c u t e t h e program ( example ) :

warp i c v c o u r s e / p i c / s t p e t e r . r g i o warped . r g i s t r e n g t h 5 . 3
S t r e n g t h s h o u l d be a v a l u e bet w e e n 0 and 16 ( d e f a u l t : 8 ) .
/
#include <s t r i n g >
#include <i o s t r e a m >
#include a r g s t r e a m . h
// command l i n e parameter r e a d i n g
#include CImg . h
// C++ image l i b r a r y
using namespace c i m g l i b r a r y ;
using namespace s t d ;
int main ( int argc , char argv ) {
a r g s t r e a m a s ( argc , argv ) ;
s t r i n g i n f i l e = ,
o u t f i l e= out . r g i ;
f l o a t s t r e n g t h =8.0 f ;
a s >> parameter ( i , i n f i l e , i n p u t f i l e name , true ) ;
a s >> parameter ( o , o u t f i l e , output f i l e name , f a l s e ) ;
a s >> parameter ( s t r e n g t h , s t r e n g t h , warp s t r e n g t h , f a l s e ) ;
a s >> h e l p ( ) ;
as . defaultErrorHandling ( ) ;
CImg<f l o a t > i n ( i n f i l e . c s t r ( ) ) ;
const int width = i n . dimx ( ) ;
const int h e i g h t = i n . dimy ( ) ;
i f ( ( width==0) | | ( h e i g h t ==0)) {
c e r r << E r r o r when l o a d i n g image . << e n d l ;
return 1;
}
i n = i n . g e t n o r m p o i n t w i s e ( 1 ) / ( f l o a t ) i n . dimv ( ) ; // e n s u r e g r e y s c a l e img !
// warp t h e image
CImg<f l o a t > out ( i n ) ; out . f i l l ( 0 . 0 ) ;
const int xmax = width 1 ;
const int ymax = h e i g h t 1 ;
f o r ( int y = 0 ; y < h e i g h t ; y++)
f o r ( int x = 0 ; x < width ; x++) {
f l o a t w e i g h t = s t r e n g t h x ( xmaxx ) y ( ymaxy ) / ( xmaxxmax ) / ( ymaxymax ) ;
y xmax/ymax ) ;
int new x = ( int ) ((1 w e i g h t ) x + w e i g h t
int new y = ( int ) ((1 w e i g h t ) y + w e i g h t ( xmaxx ) ymax/xmax ) ;
out ( x , y ) = i n ( new x , new y ) ;
}
// w r i t e t h e o u t p u t image
out . s a v e ( o u t f i l e . c s t r ( ) ) ;
out . d i s p l a y ( warped ) ;
return 0 ;
}