![]()
|
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 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.
usage | : A string describing the program goal and usage. |
cimg_usage()
is used must have correctly defined argc
and argv
variables.The macro cimg_help(str)
will display the string str
only if the -help
or --help
option are invoked when running the programm.
The macro cimg_option(name,default,usage)
may be used to retrieve an option value from the command line.
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). |
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). cimg_option()
is used must have correctly defined argc
and argv
variables.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 !
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");
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.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.