\hypertarget{group__cimg__options}{\section{Retrieving Command Line Arguments.}
\label{group__cimg__options}\index{Retrieving Command Line Arguments.@{Retrieving Command Line Arguments.}}
}
The C\+Img library offers facilities to retrieve command line arguments in a console-\/based program, as it is a commonly needed operation. Three macros {\ttfamily cimg\+\_\+usage()}, {\ttfamily cimg\+\_\+help()} and {\ttfamily 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 {\ttfamily -\/h} or {\ttfamily --help} will automatically display the program usage, followed by the list of requested options.\hypertarget{group__cimg__options_so1}{}\subsection{The cimg\+\_\+usage() macro}\label{group__cimg__options_so1}
The macro {\ttfamily cimg\+\_\+usage(usage)} may be used to describe the program goal and usage. It is generally inserted one time after the {\ttfamily int main(int argc,char $\ast$$\ast$argv)} definition.


\begin{DoxyParams}{Parameters}
{\em usage} & \+: A string describing the program goal and usage. \\
\hline
\end{DoxyParams}
\begin{DoxyPrecond}{Precondition}
The function where {\ttfamily cimg\+\_\+usage()} is used must have correctly defined {\ttfamily argc} and {\ttfamily argv} variables.
\end{DoxyPrecond}
\hypertarget{group__cimg__options_so1_5}{}\subsection{The cimg\+\_\+help() macro}\label{group__cimg__options_so1_5}
The macro {\ttfamily cimg\+\_\+help(str)} will display the string {\ttfamily str} only if the {\ttfamily -\/help} or {\ttfamily --help} option are invoked when running the programm.\hypertarget{group__cimg__options_so2}{}\subsection{The cimg\+\_\+option() macro}\label{group__cimg__options_so2}
The macro {\ttfamily cimg\+\_\+option(name,default,usage)} may be used to retrieve an option value from the command line.


\begin{DoxyParams}{Parameters}
{\em name} & \+: The name of the option to be retrieved from the command line. \\
\hline
{\em default} & \+: The default value returned by the macro if no options {\ttfamily name} has been specified when running the program. \\
\hline
{\em usage} & \+: A brief explanation of the option. If {\ttfamily usage==0}, the option won't appear on the option list when invoking the executable with options {\ttfamily -\/h} or {\ttfamily --help} (hidden option).\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
{\ttfamily cimg\+\_\+option()} returns an object that has the {\itshape same} {\itshape type} than the default value {\ttfamily 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 {\ttfamily default}. Warning, this can be confusing in some situations (look at the end of the next section). 
\end{DoxyReturn}
\begin{DoxyPrecond}{Precondition}
The function where {\ttfamily cimg\+\_\+option()} is used must have correctly defined {\ttfamily argc} and {\ttfamily argv} variables.
\end{DoxyPrecond}
\hypertarget{group__cimg__options_so3}{}\subsection{Example of use}\label{group__cimg__options_so3}
The code below uses the macros {\ttfamily cimg\+\_\+usage()} and {\ttfamily cimg\+\_\+option()}. It loads an image, smoothes it an quantifies it with a specified number of values. 
\begin{DoxyCode}
\textcolor{preprocessor}{#include "CImg.h"}
\textcolor{keyword}{using namespace }\hyperlink{namespacecimg__library}{cimg\_library};
\textcolor{keywordtype}{int} main(\textcolor{keywordtype}{int} argc,\textcolor{keywordtype}{char} **argv) \{
  cimg\_usage(\textcolor{stringliteral}{"Retrieve command line arguments"});
  \textcolor{keyword}{const} \textcolor{keywordtype}{char}* filename = cimg\_option(\textcolor{stringliteral}{"-i"},\textcolor{stringliteral}{"image.gif"},\textcolor{stringliteral}{"Input image file"});
  \textcolor{keyword}{const} \textcolor{keywordtype}{char}* output   = cimg\_option(\textcolor{stringliteral}{"-o"},(\textcolor{keywordtype}{char}*)0,\textcolor{stringliteral}{"Output image file"});
  \textcolor{keyword}{const} \textcolor{keywordtype}{double} sigma   = cimg\_option(\textcolor{stringliteral}{"-s"},1.0,\textcolor{stringliteral}{"Standard variation of the gaussian smoothing"});
  \textcolor{keyword}{const}  \textcolor{keywordtype}{int} nblevels  = cimg\_option(\textcolor{stringliteral}{"-n"},16,\textcolor{stringliteral}{"Number of quantification levels"});
  \textcolor{keyword}{const} \textcolor{keywordtype}{bool} hidden    = cimg\_option(\textcolor{stringliteral}{"-hidden"},\textcolor{keyword}{false},0);      \textcolor{comment}{// This is a hidden option}

  \hyperlink{structcimg__library_1_1CImg}{CImg<unsigned char>} img(filename);
  img.blur(sigma).quantize(nblevels);
  \textcolor{keywordflow}{if} (output) img.save(output); \textcolor{keywordflow}{else} img.display(\textcolor{stringliteral}{"Output image"});
  \textcolor{keywordflow}{if} (hidden) std::fprintf(stderr,\textcolor{stringliteral}{"You found me !\(\backslash\)n"});
  \textcolor{keywordflow}{return} 0;
\}
\end{DoxyCode}


Invoking the corresponding executable with {\ttfamily test -\/h -\/hidden -\/n 20 -\/i foo.\+jpg} will display \+: \begin{DoxyVerb}   ./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 !
\end{DoxyVerb}


\begin{DoxyWarning}{Warning}
As the type of object returned by the macro {\ttfamily cimg\+\_\+option(option,default,usage)} is defined by the type of {\ttfamily default}, undesired casts may appear when writting code such as \+: 
\begin{DoxyCode}
\textcolor{keyword}{const} \textcolor{keywordtype}{double} sigma = cimg\_option(\textcolor{stringliteral}{"-val"},0,\textcolor{stringliteral}{"A floating point value"});
\end{DoxyCode}
 In this case, {\ttfamily sigma} will always be equal to an integer (since the default value {\ttfamily 0} is an integer). When passing a float value on the command line, a {\itshape float} {\itshape to} {\itshape integer} cast is then done, truncating the given parameter to an integer value (this is surely not a desired behavior). You must specify {\ttfamily 0.\+0} as the default value in this case.
\end{DoxyWarning}
\hypertarget{group__cimg__options_so4}{}\subsection{How to learn more about command line options ?}\label{group__cimg__options_so4}
You should take a look at the examples {\ttfamily examples/gmic.\+cpp} provided in the C\+Img Library package. This is a command line based image converter which intensively uses the {\ttfamily cimg\+\_\+option()} and {\ttfamily cimg\+\_\+usage()} macros to retrieve command line parameters.