The CImg library offers facilities to retrieve command line arguments in a console-based program, as it is a commonly needed operation. Three macros cimg_usage(), cimg_help() and cimg_option() are defined for this purpose. Using these macros allows to easily retrieve options values from the command line. Invoking the compiled executable with the option -h or –help will automatically display the program usage, followed by the list of requested options.

The cimg_usage() macro

The macro cimg_usage(usage) may be used to describe the program goal and usage. It is generally inserted one time after the int main(int argc,char **argv) definition.

Parameters

usage : A string describing the program goal and usage.

Precondition: The function where cimg_usage() is used must have correctly defined argc and argv variables.

The cimg_help() macro

The macro cimg_help(str) will display the string str only if the -help or –help option are invoked when running the programm.

The cimg_option() macro

The macro cimg_option(name,default,usage) may be used to retrieve an option value from the command line.

Parameters

name	: The name of the option to be retrieved from the command line.
default	: The default value returned by the macro if no options `name` has been specified when running the program.
usage	: A brief explanation of the option. If `usage==0`, the option won't appear on the option list when invoking the executable with options `-h` or `–help` (hidden option).

Returns: cimg_option() returns an object that has the same type as the default value default. The return value is equal to the one specified on the command line. If no such option have been specified, the return value is equal to the default value default. Warning, this can be confusing in some situations (look at the end of the next section).

Precondition: The function where cimg_option() is used must have correctly defined argc and argv variables.

Example of use

The code below uses the macros cimg_usage() and cimg_option(). It loads an image, smoothes it an quantifies it with a specified number of values.

#include "CImg.h"
using namespace cimg_library;
int main(int argc,char **argv) {
  cimg_usage("Retrieve command line arguments");
  const char* filename = cimg_option("-i","image.gif","Input image file");
  const char* output   = cimg_option("-o",(char*)0,"Output image file");
  const double sigma   = cimg_option("-s",1.0,"Standard variation of the gaussian smoothing");
  const  int nblevels  = cimg_option("-n",16,"Number of quantification levels");
  const bool hidden    = cimg_option("-hidden",false,0);      // This is a hidden option
  CImg<unsigned char> img(filename);
  img.blur(sigma).quantize(nblevels);
  if (output) img.save(output); else img.display("Output image");
  if (hidden) std::fprintf(stderr,"You found me !\n");
  return 0;
}

Invoking the corresponding executable with test -h -hidden -n 20 -i foo.jpg will display :

   ./test -h -hidden -n 20 -i foo.jpg

 test : Retrieve command line arguments (Oct 16 2004, 12:34:26)

    -i       = foo.jpg      : Input image file
    -o       = 0            : Output image file
    -s       = 1            : Standard variation of the gaussian smoothing
    -n       = 20           : Number of quantification levels

   You found me !

Warning: As the type of object returned by the macro cimg_option(option,default,usage) is defined by the type of default, undesired casts may appear when writting code such as :
const double sigma = cimg_option("-val",0,"A floating point value");
In this case, sigma will always be equal to an integer (since the default value 0 is an integer). When passing a float value on the command line, a float to integer cast is then done, truncating the given parameter to an integer value (this is surely not a desired behavior). You must specify 0.0 as the default value in this case.

How to learn more about command line options ?

You should take a look at the examples examples/gmic.cpp provided in the CImg Library package. This is a command line based image converter which intensively uses the cimg_option() and cimg_usage() macros to retrieve command line parameters.