group__cimg__loops.html

this a image processing program

<li>For all these loops, <code>x</code>,<code>y</code>,<code>z</code> and <code>v</code> are inner-defined variables only visible inside the scope of the loop. They don't have to be defined before the call of the macro.</li><li><code>img</code> must be a (non empty) <a class="el" href="structcimg__library_1_1_c_img.html">cimg_library::CImg</a> image.</li></ul>
<p>
Here is an example of use that creates an image with a smooth color gradient : <div class="fragment"><pre class="fragment">  CImg&lt;unsigned char&gt; img(256,256,1,3);       <span class="comment">// Define a 256x256 color image</span>
  cimg_forXYV(img,x,y,v) { img(x,y,v) = (x+y)*(v+1)/6; }
  img.display(<span class="stringliteral">"Color gradient"</span>);
</pre></div><h2><a class="anchor" name="lo5">
Loops over interior regions and borders.</a></h2>
Similar macros are also defined to loop only on the border of an image, or inside the image (excluding the border). The border may be several pixel wide :<p>
<ul>
<li><b>cimg_for_insideX(img,x,n)</b> : Loop along the x-axis, except for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_insideY(img,y,n)</b> : Loop along the y-axis, except for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_insideZ(img,z,n)</b> : Loop along the z-axis, except for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_insideV(img,v,n)</b> : Loop along the v-axis, except for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_insideXY(img,x,y,n)</b> : Loop along the (x,y)-axes, excepted for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_insideXYZ(img,x,y,z,n)</b> : Loop along the (x,y,z)-axes, excepted for pixels inside a border of <code>n</code> pixels wide.</li></ul>
<p>
And also :<p>
<ul>
<li><b>cimg_for_borderX(img,x,n)</b> : Loop along the x-axis, only for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_borderY(img,y,n)</b> : Loop along the y-axis, only for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_borderZ(img,z,n)</b> : Loop along the z-axis, only for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_borderV(img,v,n)</b> : Loop along the z-axis, only for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_borderXY(img,x,y,n)</b> : Loop along the (x,y)-axes, only for pixels inside a border of <code>n</code> pixels wide.</li><li><b>cimg_for_borderXYZ(img,x,y,z,n)</b> : Loop along the (x,y,z)-axes, only for pixels inside a border of <code>n</code> pixels wide.</li></ul>
<p>
<ul>
<li>For all these loops, <code>x</code>,<code>y</code>,<code>z</code> and <code>v</code> are inner-defined variables only visible inside the scope of the loop. They don't have to be defined before the call of the macro.</li><li><code>img</code> must be a (non empty) <a class="el" href="structcimg__library_1_1_c_img.html">cimg_library::CImg</a> image.</li><li>The constant <code>n</code> stands for the size of the border.</li></ul>
<p>
Here is an example of use, to create a 2d grayscale image with two different intensity gradients : <div class="fragment"><pre class="fragment">  CImg&lt;&gt; img(256,256);
  cimg_for_insideXY(img,x,y,50) img(x,y) = x+y;
  cimg_for_borderXY(img,x,y,50) img(x,y) = x-y;
  img.display();
</pre></div><h2><a class="anchor" name="lo6">
Loops using neighborhoods.</a></h2>
Inside an image loop, it is often useful to get values of neighborhood pixels of the current pixel at the loop location. The CImg Library provides a very smart and fast mechanism for this purpose, with the definition of several loop macros that remember the neighborhood values of the pixels. The use of these macros can highly optimize your code, and also simplify your program.<h3><a class="anchor" name="lo7">
Neighborhood-based loops for 2D images</a></h3>
For 2D images, the neighborhood-based loop macros are :<p>
<ul>
<li><b>cimg_for2x2(img,x,y,z,v,I)</b> : Loop along the (x,y)-axes using a centered 2x2 neighborhood.</li><li><b>cimg_for3x3(img,x,y,z,v,I)</b> : Loop along the (x,y)-axes using a centered 3x3 neighborhood.</li><li><b>cimg_for4x4(img,x,y,z,v,I)</b> : Loop along the (x,y)-axes using a centered 4x4 neighborhood.</li><li><b>cimg_for5x5(img,x,y,z,v,I)</b> : Loop along the (x,y)-axes using a centered 5x5 neighborhood.</li></ul>
<p>
For all these loops, <code>x</code> and <code>y</code> are inner-defined variables only visible inside the scope of the loop. They don't have to be defined before the call of the macro. <code>img</code> is a non empty CImg&lt;T&gt; image. <code>z</code> and <code>v</code> are constants that define on which image slice and vector channel the loop must apply (usually both 0 for grayscale 2D images). Finally, <code>I</code> is the 2x2, 3x3, 4x4 or 5x5 neighborhood that will be updated with the correct pixel values during the loop (see <a class="el" href="group__cimg__loops.html#lo9">Defining neighborhoods</a>).<h3><a class="anchor" name="lo8">
Neighborhood-based loops for 3D images</a></h3>
For 3D images, the neighborhood-based loop macros are :<p>
<ul>
<li><b>cimg_for2x2x2(img,x,y,z,v,I)</b> : Loop along the (x,y,z)-axes using a centered 2x2x2 neighborhood.</li><li><b>cimg_for3x3x3(img,x,y,z,v,I)</b> : Loop along the (x,y,z)-axes using a centered 3x3x3 neighborhood.</li></ul>
<p>
For all these loops, <code>x</code>, <code>y</code> and <code>z</code> are inner-defined variables only visible inside the scope of the loop. They don't have to be defined before the call of the macro. <code>img</code> is a non empty CImg&lt;T&gt; image. <code>v</code> is a constant that defines on which image channel the loop must apply (usually 0 for grayscale 3D images). Finally, <code>I</code> is the 2x2x2 or 3x3x3 neighborhood that will be updated with the correct pixel values during the loop (see <a class="el" href="group__cimg__loops.html#lo9">Defining neighborhoods</a>).<h3><a class="anchor" name="lo9">
Defining neighborhoods</a></h3>
The CImg library defines a neighborhood as a set of named <em>variables</em> or <em>references</em>, declared using specific CImg macros :<p>
<ul>
<li><b>CImg_2x2(I,type)</b> : Define a 2x2 neighborhood named <code>I</code>, of type <code>type</code>.</li><li><b>CImg_3x3(I,type)</b> : Define a 3x3 neighborhood named <code>I</code>, of type <code>type</code>.</li><li><b>CImg_4x4(I,type)</b> : Define a 4x4 neighborhood named <code>I</code>, of type <code>type</code>.</li><li><b>CImg_5x5(I,type)</b> : Define a 5x5 neighborhood named <code>I</code>, of type <code>type</code>.</li><li><b>CImg_2x2x2(I,type)</b> : Define a 2x2x2 neighborhood named <code>I</code>, of type <code>type</code>.</li><li><b>CImg_3x3x3(I,type)</b> : Define a 3x3x3 neighborhood named <code>I</code>, of type <code>type</code>.</li></ul>
<p>
Actually, <code>I</code> is a <em>generic</em> <em>name</em> for the neighborhood. In fact, these macros declare a <em>set</em> of new variables. For instance, defining a 3x3 neighborhood <code>CImg_3x3(I,float)</code> declares 9 different float variables <code>Ipp</code>,<code>Icp</code>,<code>Inp</code>,<code>Ipc</code>,<code>Icc</code>,<code>Inc</code>,<code>Ipn</code>,<code>Icn</code>,<code>Inn</code> which correspond to each pixel value of a 3x3 neighborhood. Variable indices are <code>p</code>,<code>c</code> or <code>n</code>, and stand respectively for <em>'previous'</em>, <em>'current'</em> and <em>'next'</em>. First indice denotes the <code>x-axis</code>, second indice denotes the <code>y-axis</code>. Then, the names of the variables are directly related to the position of the corresponding pixels in the neighborhood. For 3D neighborhoods, a third indice denotes the <code>z-axis</code>. Then, inside a neighborhood loop, you will have the following equivalence :<ul>
<li><code>Ipp = img(x-1,y-1)</code></li><li><code>Icn = img(x,y+1)</code></li><li><code>Inp = img(x+1,y-1)</code></li><li><code>Inpc = img(x+1,y-1,z)</code></li><li><code>Ippn = img(x-1,y-1,z+1)</code></li><li>and so on...</li></ul>
<p>
For bigger neighborhoods, such as 4x4 or 5x5 neighborhoods, two additionnal indices are introduced : <code>a</code> (stands for <em>'after'</em>) and <code>b</code> (stands for <em>'before'</em>), so that :<ul>
<li><code>Ibb = img(x-2,y-2)</code></li><li><code>Ina = img(x+1,y+2)</code></li><li>and so on...</li></ul>
<p>
The value of a neighborhood pixel outside the image range (image border problem) is automatically set to the same values than the nearest valid pixel in the image (this is also called the <em>Neumann</em> <em>border</em> <em>condition</em>).<h3><a class="anchor" name="lo10">
Neighborhood as a reference</a></h3>
It is also possible to define neighborhood variables as references to classical C-arrays or CImg&lt;T&gt; images, instead of allocating new variables. This is done by adding <code>_ref</code> to the macro names used for the neighborhood definition :<p>
<ul>
<li><b>CImg_2x2_ref(I,type,tab)</b> : Define a 2x2 neighborhood named <code>I</code>, of type <code>type</code>, as a reference to <code>tab</code>.</li><li><b>CImg_3x3_ref(I,type,tab)</b> : Define a 3x3 neighborhood named <code>I</code>, of type <code>type</code>, as a reference to <code>tab</code>.</li><li><b>CImg_4x4_ref(I,type,tab)</b> : Define a 4x4 neighborhood named <code>I</code>, of type <code>type</code>, as a reference to <code>tab</code>.</li><li><b>CImg_5x5_ref(I,type,tab)</b> : Define a 5x5 neighborhood named <code>I</code>, of type <code>type</code>, as a reference to <code>tab</code>.</li><li><b>CImg_2x2x2_ref(I,type,tab)</b> : Define a 2x2x2 neighborhood named <code>I</code>, of type <code>type</code>, as a reference to <code>tab</code>.</li><li><b>CImg_3x3x3_ref(I,type,tab)</b> : Define a 3x3x3 neighborhood named <code>I</code>, of type <code>type</code>, as a reference to <code>tab</code>.</li></ul>
<p>
<code>tab</code> can be a one-dimensionnal C-style array, or a non empty <code>CImg&lt;T&gt;</code> image. Both objects must have same sizes as the considered neighborhoods.<h3><a class="anchor" name="lo11">
Example codes</a></h3>
More than a long discussion, the above example will demonstrate how to compute the gradient norm of a 3D volume using the <code>cimg_for3x3x3()</code> loop macro :<p>
<div class="fragment"><pre class="fragment">  CImg&lt;float&gt; volume(<span class="stringliteral">"IRM.hdr"</span>);        <span class="comment">// Load an IRM volume from an Analyze7.5 file</span>
  CImg_3x3x3(I,<span class="keywordtype">float</span>);                  <span class="comment">// Define a 3x3x3 neighborhood</span>
  CImg&lt;float&gt; gradnorm(volume);         <span class="comment">// Create an image with same size as 'volume'</span>
  cimg_for3x3x3(volume,x,y,z,0,I) {     <span class="comment">// Loop over the volume, using the neighborhood I</span>
    <span class="keyword">const</span> <span class="keywordtype">float</span> ix = 0.5f*(Incc-Ipcc);  <span class="comment">// Compute the derivative along the x-axis.</span>
    <span class="keyword">const</span> <span class="keywordtype">float</span> iy = 0.5f*(Icnc-Icpc);  <span class="comment">// Compute the derivative along the y-axis.</span>
    <span class="keyword">const</span> <span class="keywordtype">float</span> iz = 0.5f*(Iccn-Iccp);  <span class="comment">// Compute the derivative along the z-axis.</span>
    gradnorm(x,y,z) = std::sqrt(ix*ix+iy*iy+iz*iz);  <span class="comment">// Set the gradient norm in the destination image</span>
  }
  gradnorm.display(<span class="stringliteral">"Gradient norm"</span>);
</pre></div><p>
And the following example shows how to deal with neighborhood references to blur a color image by averaging pixel values on a 5x5 neighborhood.<p>
<div class="fragment"><pre class="fragment">  CImg&lt;unsigned char&gt; src(<span class="stringliteral">"image_color.jpg"</span>), dest(src,<span class="keyword">false</span>), neighbor(5,5);  <span class="comment">// Image definitions.</span>
  <span class="keyword">typedef</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> uchar;             <span class="comment">// Avoid space in the second parameter of the macro CImg_5x5x1 below.</span>
  CImg_5x5_ref(N,uchar,neighbor);          <span class="comment">// Define a 5x5 neighborhood as a reference to the 5x5 image neighbor.</span>
  cimg_forV(src,k)                         <span class="comment">// Standard loop on color channels</span>
     cimg_for5x5(src,x,y,0,k,N)            <span class="comment">// 5x5 neighborhood loop.</span>
       dest(x,y,k) = neighbor.sum()/(5*5); <span class="comment">// Averaging pixels to filter the color image.</span>
  CImgList&lt;<span class="keywordtype">unsigned</span> <span class="keywordtype">char</span>&gt; visu(src,dest);
  visu.display("Original + Filtered");     <span class="comment">// Display both original and filtered image.</span>
</pre></div><p>
Note that in this example, we didn't use directly the variables Nbb,Nbp,..,Ncc,... since there are only references to the neighborhood image <code>neighbor</code>. We rather used a member function of <code>neighbor</code>.<p>
As you can see, explaining the use of the CImg neighborhood macros is actually more difficult than using them ! <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <title>The CImg Library - C++ Template Image Processing Library</title>
    <meta content="David Tschumperle" name="author">
    <link rel="shortcut icon" type="image/x-icon" href="http://cimg.sourceforge.net/favicon.ico" />
    <link rel="icon" type="image/png" href="favicon.png" />
    <link href="doxygen.css" rel="stylesheet" type="text/css">
  </head>
  <body bgcolor="#ffffff" fgcolor="#000000" alink="#ff0000" link="#0000ee" vlink="#551a8b">

  <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"></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>