[ Main ] [ Download ] [ Screenshots ] [ FAQ ] [ Tutorial ] [ Documentation ] [ Forum ] [ Links ]
  Main Page Modules Namespaces Classes 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.