PTdecode/CImg-1.3.0/html/reference/group__cimg__options.html

 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></meta>
<title>The CImg Library - C++ Template Image Processing Toolkit</title>
<meta content="David Tschumperle" name="author"></meta>
<link rel="shortcut icon" type="image/x-icon" href="http://cimg.sourceforge.net/favicon.ico"></link>
<link rel="icon" type="image/png" href="favicon.png"></link>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<style type="text/css">
<!--
body {background-color:white; font-family:sans-serif; }
a:active{text-decoration:none; color:#303090}
a:link{text-decoration:none; color:#303090}
a:visited{text-decoration:none; color:#303090}
a:hover{text-decoration:underline; color:#4E9F71}
-->
</style>
<script language="JavaScript" type="text/javascript">
  <!-- Original:  Eric King (eric_andrew_king@hotmail.com) is used to display images in popup windows -->
  <!-- Web Site:  http://redrival.com/eak/ -->
  <!-- This script and many more are available free online at -->
  <!-- The JavaScript Source!! http://javascript.internet.com -->
  <!-- Begin
  function NewWindow(mypage, myname, w, h, scroll) {
  var winl = (screen.width - w) / 2;
  var wint = (screen.height - h) / 2;
  winprops = 'height='+h+',width='+w+',top='+wint+',left='+winl+',scrollbars='+scroll+',resizable'
  win = window.open(mypage, myname, winprops)
  if (parseInt(navigator.appVersion) >= 4) { win.window.focus(); }
  }
  //  End -->
</script>
</head>
<body>
 <table align="center" border="0" cellpadding="0" cellspacing="0" width="100%">
  <tbody><tr><td>
   <hr noshade="noshade" size="1" width="90%"></hr>
   <center>
   <br/>
   <a href="http://cimg.sourceforge.net"><img src="http://cimg.sourceforge.net/img/CImgLogo.jpg" alt="" border="0"></img></a><br/>
   <br/>
   </center>
   <hr noshade="noshade" size="1" width="90%"></hr>
   <center>
   <table bgcolor="#EEEEFF" style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="3" cellspacing="0">
   <tbody><tr><td style="text-align: center; vertical-align: top;">
   <font color="#FFFFFF" face="Arial,Helvetica" size="-1">
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/index.shtml">Main</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/news.shtml">News</a><b>] </b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/download.shtml">Download</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/screenshots.shtml">Screenshots</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/reference/group__cimg__faq.html">FAQ</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/reference/group__cimg__tutorial.html">Tutorial</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/reference/index.html">Documentation</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://sourceforge.net/forum/forum.php?forum_id=334630">Forum</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/chat.shtml">Chat</a> <b>]</b>
   <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/links.shtml">Links</a> <b>]</b>
   </font>
   </td></tr></tbody>
   </table>
   </center>
   <hr noshade="noshade" size="1" width="90%"></hr>
  </td></tr></tbody>
</table>
<!-- Generated by Doxygen 1.5.7.1 -->
<script type="text/javascript">
<!--
function changeDisplayState (e){
  var num=this.id.replace(/[^[0-9]/g,'');
  var button=this.firstChild;
  var sectionDiv=document.getElementById('dynsection'+num);
  if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){
    sectionDiv.style.display='block';
    button.src='open.gif';
  }else{
    sectionDiv.style.display='none';
    button.src='closed.gif';
  }
}
function initDynSections(){
  var divs=document.getElementsByTagName('div');
  var sectionCounter=1;
  for(var i=0;i<divs.length-1;i++){
    if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){
      var header=divs[i];
      var section=divs[i+1];
      var button=header.firstChild;
      if (button!='IMG'){
        divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild);
        button=document.createElement('img');
        divs[i].insertBefore(button,divs[i].firstChild);
      }
      header.style.cursor='pointer';
      header.onclick=changeDisplayState;
      header.id='dynheader'+sectionCounter;
      button.src='closed.gif';
      section.id='dynsection'+sectionCounter;
      section.style.display='none';
      section.style.marginLeft='14px';
      sectionCounter++;
    }
  }
}
window.onload = initDynSections;
-->
</script>
<div class="navigation" id="top">
  <div class="tabs">
    <ul>
      <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
    </ul>
  </div>
</div>
<div class="contents">
<h1>Retrieving Command Line Arguments.</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
</table>
The CImg library offers facilities to retrieve command line arguments in a console-based program, as it is a commonly needed operation. Three macros <code>cimg_usage()</code>, <code>cimg_help()</code> and <code>cimg_option()</code> 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 <code>-h</code> or <code>--help</code> will automatically display the program usage, followed by the list of requested options.<h2><a class="anchor" name="so1">
The cimg_usage() macro</a></h2>
The macro <code>cimg_usage(usage)</code> may be used to describe the program goal and usage. It is generally inserted one time after the <code>int main(int argc,char **argv)</code> definition.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>usage</em>&nbsp;</td><td>: A string describing the program goal and usage. </td></tr>
  </table>
</dl>
<dl class="pre" compact><dt><b>Precondition:</b></dt><dd>The function where <code>cimg_usage()</code> is used must have correctly defined <code>argc</code> and <code>argv</code> variables.</dd></dl>
<h2><a class="anchor" name="so1_5">
The cimg_help() macro</a></h2>
The macro <code>cimg_help(str)</code> will display the string <code>str</code> only if the <code>-help</code> or <code>--help</code> option are invoked when running the programm.<h2><a class="anchor" name="so2">
The cimg_option() macro</a></h2>
The macro <code>cimg_option(name,default,usage)</code> may be used to retrieve an option value from the command line.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>name</em>&nbsp;</td><td>: The name of the option to be retrieved from the command line. </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>default</em>&nbsp;</td><td>: The default value returned by the macro if no options <code>name</code> has been specified when running the program. </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>usage</em>&nbsp;</td><td>: A brief explanation of the option. If <code>usage==0</code>, the option won't appear on the option list when invoking the executable with options <code>-h</code> or <code>--help</code> (hidden option).</td></tr>
  </table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd><code>cimg_option()</code> returns an object that has the <em>same</em> <em>type</em> than the default value <code>default</code>. 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 <code>default</code>. Warning, this can be confusing in some situations (look at the end of the next section). </dd></dl>
<dl class="pre" compact><dt><b>Precondition:</b></dt><dd>The function where <code>cimg_option()</code> is used must have correctly defined <code>argc</code> and <code>argv</code> variables.</dd></dl>
<h2><a class="anchor" name="so3">
Example of use</a></h2>
The code below uses the macros <code>cimg_usage()</code> and <code>cimg_option()</code>. It loads an image, smoothes it an quantifies it with a specified number of values. <div class="fragment"><pre class="fragment"><span class="preprocessor">   #include "CImg.h"</span>
   <span class="keyword">using namespace </span>cimg_library;
   <span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc,<span class="keywordtype">char</span> **argv) {
     cimg_usage(<span class="stringliteral">"Retrieve command line arguments"</span>);
     <span class="keyword">const</span> <span class="keywordtype">char</span>* filename = cimg_option(<span class="stringliteral">"-i"</span>,<span class="stringliteral">"image.gif"</span>,<span class="stringliteral">"Input image file"</span>);
     <span class="keyword">const</span> <span class="keywordtype">char</span>* output   = cimg_option(<span class="stringliteral">"-o"</span>,(<span class="keywordtype">char</span>*)0,<span class="stringliteral">"Output image file"</span>);
     <span class="keyword">const</span> <span class="keywordtype">double</span> sigma   = cimg_option(<span class="stringliteral">"-s"</span>,1.0,<span class="stringliteral">"Standard variation of the gaussian smoothing"</span>);
     <span class="keyword">const</span>  <span class="keywordtype">int</span> nblevels  = cimg_option(<span class="stringliteral">"-n"</span>,16,<span class="stringliteral">"Number of quantification levels"</span>);
     <span class="keyword">const</span> <span class="keywordtype">bool</span> hidden    = cimg_option(<span class="stringliteral">"-hidden"</span>,<span class="keyword">false</span>,0);      <span class="comment">// This is a hidden option</span>

     CImg&lt;unsigned char&gt; img(filename);
     img.blur(sigma).quantize(nblevels);
     <span class="keywordflow">if</span> (output) img.save(output); <span class="keywordflow">else</span> img.display(<span class="stringliteral">"Output image"</span>);
     <span class="keywordflow">if</span> (hidden) std::fprintf(stderr,<span class="stringliteral">"You found me !\n"</span>);
     <span class="keywordflow">return</span> 0;
   }
</pre></div><p>
Invoking the corresponding executable with <code>test -h -hidden -n 20 -i foo.jpg</code> will display : <div class="fragment"><pre class="fragment">
   ./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 !
</pre></div><p>
<dl class="warning" compact><dt><b>Warning:</b></dt><dd>As the type of object returned by the macro <code>cimg_option(option,default,usage)</code> is defined by the type of <code>default</code>, undesired casts may appear when writting code such as : <div class="fragment"><pre class="fragment">   <span class="keyword">const</span> <span class="keywordtype">double</span> sigma = cimg_option(<span class="stringliteral">"-val"</span>,0,<span class="stringliteral">"A floating point value"</span>);
</pre></div> In this case, <code>sigma</code> will always be equal to an integer (since the default value <code>0</code> is an integer). When passing a float value on the command line, a <em>float</em> <em>to</em> <em>integer</em> cast is then done, truncating the given parameter to an integer value (this is surely not a desired behavior). You must specify <code>0.0</code> as the default value in this case.</dd></dl>
<h2><a class="anchor" name="so4">
How to learn more about command line options ?</a></h2>
You should take a look at the examples <code>examples/gmic.cpp</code> provided in the CImg Library package. This is a command line based image converter which intensively uses the <code>cimg_option()</code> and <code>cimg_usage()</code> macros to retrieve command line parameters. </div>
<hr noshade="noshade" size="1" width="100%">
<a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=96492&amp;type=3" border="0" height="37" width="125"></img>
</a>
<!-- Start of StatCounter Code -->
<script type="text/javascript" language="javascript">
<!--
var sc_project=895001;
var sc_invisible=1;
var sc_partition=7;
var sc_security="5ea85181";
//-->
</script>
<script type="text/javascript" language="javascript" src="http://www.statcounter.com/counter/counter.js"></script><noscript><a href="http://www.statcounter.com/" target="_blank"><img  src="http://c8.statcounter.com/counter.php?sc_project=895001&amp;java=0&amp;security=5ea85181&amp;invisible=1" alt="counter stats" border="0"></a> </noscript>
<!-- End of StatCounter Code -->
</body>
</html>