xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

[ Main ] [ News] [ Download ] [ Screenshots ] [ FAQ ] [ Tutorial ] [ Documentation ] [ Forum ] [ Chat ] [ Links ]

# Retrieving Command Line Arguments.

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