Mon, 03 Aug 2009 23:41:04 +0100
added dep/*.d and obj/*.o to hgignore
1 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></meta>
4 <title>The CImg Library - C++ Template Image Processing Toolkit</title>
5 <meta content="David Tschumperle" name="author"></meta>
6 <link rel="shortcut icon" type="image/x-icon" href="http://cimg.sourceforge.net/favicon.ico"></link>
7 <link rel="icon" type="image/png" href="favicon.png"></link>
8 <link href="doxygen.css" rel="stylesheet" type="text/css">
9 <link href="tabs.css" rel="stylesheet" type="text/css">
10 <style type="text/css">
11 <!--
12 body {background-color:white; font-family:sans-serif; }
13 a:active{text-decoration:none; color:#303090}
14 a:link{text-decoration:none; color:#303090}
15 a:visited{text-decoration:none; color:#303090}
16 a:hover{text-decoration:underline; color:#4E9F71}
17 -->
18 </style>
19 <script language="JavaScript" type="text/javascript">
20 <!-- Original: Eric King (eric_andrew_king@hotmail.com) is used to display images in popup windows -->
21 <!-- Web Site: http://redrival.com/eak/ -->
22 <!-- This script and many more are available free online at -->
23 <!-- The JavaScript Source!! http://javascript.internet.com -->
24 <!-- Begin
25 function NewWindow(mypage, myname, w, h, scroll) {
26 var winl = (screen.width - w) / 2;
27 var wint = (screen.height - h) / 2;
28 winprops = 'height='+h+',width='+w+',top='+wint+',left='+winl+',scrollbars='+scroll+',resizable'
29 win = window.open(mypage, myname, winprops)
30 if (parseInt(navigator.appVersion) >= 4) { win.window.focus(); }
31 }
32 // End -->
33 </script>
34 </head>
35 <body>
36 <table align="center" border="0" cellpadding="0" cellspacing="0" width="100%">
37 <tbody><tr><td>
38 <hr noshade="noshade" size="1" width="90%"></hr>
39 <center>
40 <br/>
41 <a href="http://cimg.sourceforge.net"><img src="http://cimg.sourceforge.net/img/CImgLogo.jpg" alt="" border="0"></img></a><br/>
42 <br/>
43 </center>
44 <hr noshade="noshade" size="1" width="90%"></hr>
45 <center>
46 <table bgcolor="#EEEEFF" style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="3" cellspacing="0">
47 <tbody><tr><td style="text-align: center; vertical-align: top;">
48 <font color="#FFFFFF" face="Arial,Helvetica" size="-1">
49 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/index.shtml">Main</a> <b>]</b>
50 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/news.shtml">News</a><b>] </b>
51 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/download.shtml">Download</a> <b>]</b>
52 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/screenshots.shtml">Screenshots</a> <b>]</b>
53 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/reference/group__cimg__faq.html">FAQ</a> <b>]</b>
54 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/reference/group__cimg__tutorial.html">Tutorial</a> <b>]</b>
55 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/reference/index.html">Documentation</a> <b>]</b>
56 <b>[</b> <a target="_parent" href="http://sourceforge.net/forum/forum.php?forum_id=334630">Forum</a> <b>]</b>
57 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/chat.shtml">Chat</a> <b>]</b>
58 <b>[</b> <a target="_parent" href="http://cimg.sourceforge.net/links.shtml">Links</a> <b>]</b>
59 </font>
60 </td></tr></tbody>
61 </table>
62 </center>
63 <hr noshade="noshade" size="1" width="90%"></hr>
64 </td></tr></tbody>
65 </table>
66 <!-- Generated by Doxygen 1.5.7.1 -->
67 <script type="text/javascript">
68 <!--
69 function changeDisplayState (e){
70 var num=this.id.replace(/[^[0-9]/g,'');
71 var button=this.firstChild;
72 var sectionDiv=document.getElementById('dynsection'+num);
73 if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){
74 sectionDiv.style.display='block';
75 button.src='open.gif';
76 }else{
77 sectionDiv.style.display='none';
78 button.src='closed.gif';
79 }
80 }
81 function initDynSections(){
82 var divs=document.getElementsByTagName('div');
83 var sectionCounter=1;
84 for(var i=0;i<divs.length-1;i++){
85 if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){
86 var header=divs[i];
87 var section=divs[i+1];
88 var button=header.firstChild;
89 if (button!='IMG'){
90 divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild);
91 button=document.createElement('img');
92 divs[i].insertBefore(button,divs[i].firstChild);
93 }
94 header.style.cursor='pointer';
95 header.onclick=changeDisplayState;
96 header.id='dynheader'+sectionCounter;
97 button.src='closed.gif';
98 section.id='dynsection'+sectionCounter;
99 section.style.display='none';
100 section.style.marginLeft='14px';
101 sectionCounter++;
102 }
103 }
104 }
105 window.onload = initDynSections;
106 -->
107 </script>
108 <div class="navigation" id="top">
109 <div class="tabs">
110 <ul>
111 <li><a href="index.html"><span>Main Page</span></a></li>
112 <li><a href="modules.html"><span>Modules</span></a></li>
113 <li><a href="namespaces.html"><span>Namespaces</span></a></li>
114 <li><a href="annotated.html"><span>Classes</span></a></li>
115 </ul>
116 </div>
117 </div>
118 <div class="contents">
119 <h1>Retrieving Command Line Arguments.</h1><table border="0" cellpadding="0" cellspacing="0">
120 <tr><td></td></tr>
121 </table>
122 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">
123 The cimg_usage() macro</a></h2>
124 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>
125 <dl compact><dt><b>Parameters:</b></dt><dd>
126 <table border="0" cellspacing="2" cellpadding="0">
127 <tr><td valign="top"></td><td valign="top"><em>usage</em> </td><td>: A string describing the program goal and usage. </td></tr>
128 </table>
129 </dl>
130 <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>
131 <h2><a class="anchor" name="so1_5">
132 The cimg_help() macro</a></h2>
133 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">
134 The cimg_option() macro</a></h2>
135 The macro <code>cimg_option(name,default,usage)</code> may be used to retrieve an option value from the command line.<p>
136 <dl compact><dt><b>Parameters:</b></dt><dd>
137 <table border="0" cellspacing="2" cellpadding="0">
138 <tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>: The name of the option to be retrieved from the command line. </td></tr>
139 <tr><td valign="top"></td><td valign="top"><em>default</em> </td><td>: The default value returned by the macro if no options <code>name</code> has been specified when running the program. </td></tr>
140 <tr><td valign="top"></td><td valign="top"><em>usage</em> </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>
141 </table>
142 </dl>
143 <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>
144 <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>
145 <h2><a class="anchor" name="so3">
146 Example of use</a></h2>
147 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>
148 <span class="keyword">using namespace </span>cimg_library;
149 <span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc,<span class="keywordtype">char</span> **argv) {
150 cimg_usage(<span class="stringliteral">"Retrieve command line arguments"</span>);
151 <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>);
152 <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>);
153 <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>);
154 <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>);
155 <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>
157 CImg<unsigned char> img(filename);
158 img.blur(sigma).quantize(nblevels);
159 <span class="keywordflow">if</span> (output) img.save(output); <span class="keywordflow">else</span> img.display(<span class="stringliteral">"Output image"</span>);
160 <span class="keywordflow">if</span> (hidden) std::fprintf(stderr,<span class="stringliteral">"You found me !\n"</span>);
161 <span class="keywordflow">return</span> 0;
162 }
163 </pre></div><p>
164 Invoking the corresponding executable with <code>test -h -hidden -n 20 -i foo.jpg</code> will display : <div class="fragment"><pre class="fragment">
165 ./test -h -hidden -n 20 -i foo.jpg
167 test : Retrieve command line arguments (Oct 16 2004, 12:34:26)
169 -i = foo.jpg : Input image file
170 -o = 0 : Output image file
171 -s = 1 : Standard variation of the gaussian smoothing
172 -n = 20 : Number of quantification levels
174 You found me !
175 </pre></div><p>
176 <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>);
177 </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>
178 <h2><a class="anchor" name="so4">
179 How to learn more about command line options ?</a></h2>
180 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>
181 <hr noshade="noshade" size="1" width="100%">
182 <a href="http://sourceforge.net">
183 <img src="http://sourceforge.net/sflogo.php?group_id=96492&type=3" border="0" height="37" width="125"></img>
184 </a>
185 <!-- Start of StatCounter Code -->
186 <script type="text/javascript" language="javascript">
187 <!--
188 var sc_project=895001;
189 var sc_invisible=1;
190 var sc_partition=7;
191 var sc_security="5ea85181";
192 //-->
193 </script>
194 <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&java=0&security=5ea85181&invisible=1" alt="counter stats" border="0"></a> </noscript>
195 <!-- End of StatCounter Code -->
196 </body>
197 </html>