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);
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.