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