libs/gil/doc/html/design/image_view.html

   1
   2
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   8
   9     <title>Image View - Boost.GIL  documentation</title>
  10     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  11     <link rel="stylesheet" href="../_static/style.css" type="text/css" />
  12     <script type="text/javascript">
  13       var DOCUMENTATION_OPTIONS = {
  14           URL_ROOT:    '../',
  15           VERSION:     '',
  16           COLLAPSE_MODINDEX: false,
  17           FILE_SUFFIX: '.html'
  18       };
  19     </script>
  20     <script type="text/javascript" src="../_static/jquery.js"></script>
  21     <script type="text/javascript" src="../_static/underscore.js"></script>
  22     <script type="text/javascript" src="../_static/doctools.js"></script>
  23     <link rel="index" title="Index" href="../genindex.html" />
  24     <link rel="search" title="Search" href="../search.html" />
  25     <link rel="top" title="Boost.GIL  documentation" href="../index.html" />
  26     <link rel="up" title="Design Guide" href="index.html" />
  27     <link rel="next" title="Image" href="image.html" />
  28     <link rel="prev" title="Pixel Locator" href="pixel_locator.html" />
  29   </head>
  30   <body>
  31     <div class="header">
  32     <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  33     "header">
  34       <tr>
  35         <td valign="top" width="300">
  36           <h3><a href="../index.html"><img
  37           alt="C++ Boost" src="../_static/gil.png" border="0"></a></h3>
  38         </td>
  39
  40         <td >
  41           <h1 align="center"><a href="../index.html"></a></h1>
  42         </td>
  43         <td>
  44       <div id="searchbox" style="display: none">
  45         <form class="search" action="../search.html" method="get">
  46           <input type="text" name="q" size="18" />
  47           <input type="submit" value="Search" />
  48           <input type="hidden" name="check_keywords" value="yes" />
  49           <input type="hidden" name="area" value="default" />
  50         </form>
  51       </div>
  52       <script type="text/javascript">$('#searchbox').show(0);</script>
  53         </td>
  54       </tr>
  55     </table>
  56     </div>
  57     <hr/>
  58     <div class="content">
  59     <div class="navbar" style="text-align:right;">
  60
  61
  62       <a class="prev" title="Pixel Locator" href="pixel_locator.html"><img src="../_static/prev.png" alt="prev"/></a>
  63       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
  64       <a class="next" title="Image" href="image.html"><img src="../_static/next.png" alt="next"/></a>
  65
  66     </div>
  67
  68   <div class="section" id="image-view">
  69 <h1>Image View</h1>
  70 <div class="contents local topic" id="contents">
  71 <ul class="simple">
  72 <li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
  73 <li><a class="reference internal" href="#models" id="id2">Models</a></li>
  74 <li><a class="reference internal" href="#algorithms" id="id3">Algorithms</a><ul>
  75 <li><a class="reference internal" href="#creating-views-from-raw-pixels" id="id4">Creating Views from Raw Pixels</a></li>
  76 <li><a class="reference internal" href="#creating-image-views-from-other-image-views" id="id5">Creating Image Views from Other Image Views</a></li>
  77 <li><a class="reference internal" href="#stl-style-algorithms-on-image-views" id="id6">STL-Style Algorithms on Image Views</a></li>
  78 </ul>
  79 </li>
  80 </ul>
  81 </div>
  82 <div class="section" id="overview">
  83 <h2><a class="toc-backref" href="#id1">Overview</a></h2>
  84 <p>An image view is a generalization of STL range concept to multiple dimensions.
  85 Similar to ranges (and iterators), image views are shallow, don&#8217;t own the
  86 underlying data and don&#8217;t propagate their constness over the data.
  87 For example, a constant image view cannot be resized, but may allow modifying
  88 the pixels. For pixel-immutable operations, use constant-value image view
  89 (also called non-mutable image view). Most general N-dimensional views satisfy
  90 the following concept:</p>
  91 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">RandomAccessNDImageViewConcept</span><span class="o">&lt;</span><span class="n">Regular</span> <span class="n">View</span><span class="o">&gt;</span>
  92 <span class="p">{</span>
  93   <span class="k">typename</span> <span class="n">value_type</span><span class="p">;</span>      <span class="c1">// for pixel-based views, the pixel type</span>
  94   <span class="k">typename</span> <span class="n">reference</span><span class="p">;</span>       <span class="c1">// result of dereferencing</span>
  95   <span class="k">typename</span> <span class="n">difference_type</span><span class="p">;</span> <span class="c1">// result of operator-(iterator,iterator) (1-dimensional!)</span>
  96   <span class="k">typename</span> <span class="n">const_t</span><span class="p">;</span>  <span class="n">where</span> <span class="n">RandomAccessNDImageViewConcept</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;</span><span class="p">;</span> <span class="c1">// same as View, but over immutable values</span>
  97   <span class="k">typename</span> <span class="n">point_t</span><span class="p">;</span>  <span class="n">where</span> <span class="n">PointNDConcept</span><span class="o">&lt;</span><span class="n">point_t</span><span class="o">&gt;</span><span class="p">;</span> <span class="c1">// N-dimensional point</span>
  98   <span class="k">typename</span> <span class="n">locator</span><span class="p">;</span>  <span class="n">where</span> <span class="n">RandomAccessNDLocatorConcept</span><span class="o">&lt;</span><span class="n">locator</span><span class="o">&gt;</span><span class="p">;</span> <span class="c1">// N-dimensional locator.</span>
  99   <span class="k">typename</span> <span class="n">iterator</span><span class="p">;</span> <span class="n">where</span> <span class="n">RandomAccessTraversalConcept</span><span class="o">&lt;</span><span class="n">iterator</span><span class="o">&gt;</span><span class="p">;</span> <span class="c1">// 1-dimensional iterator over all values</span>
 100   <span class="k">typename</span> <span class="n">reverse_iterator</span><span class="p">;</span> <span class="n">where</span> <span class="n">RandomAccessTraversalConcept</span><span class="o">&lt;</span><span class="n">reverse_iterator</span><span class="o">&gt;</span><span class="p">;</span>
 101   <span class="k">typename</span> <span class="n">size_type</span><span class="p">;</span>       <span class="c1">// the return value of size()</span>
 102
 103   <span class="c1">// Equivalent to RandomAccessNDLocatorConcept::axis</span>
 104   <span class="k">template</span> <span class="o">&lt;</span><span class="kt">size_t</span> <span class="n">D</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">axis</span> <span class="p">{</span>
 105       <span class="k">typename</span> <span class="n">coord_t</span> <span class="o">=</span> <span class="n">point_t</span><span class="o">::</span><span class="n">axis</span><span class="o">&lt;</span><span class="n">D</span><span class="o">&gt;::</span><span class="n">coord_t</span><span class="p">;</span>
 106       <span class="k">typename</span> <span class="n">iterator</span><span class="p">;</span> <span class="n">where</span> <span class="n">RandomAccessTraversalConcept</span><span class="o">&lt;</span><span class="n">iterator</span><span class="o">&gt;</span><span class="p">;</span>   <span class="c1">// iterator along D-th axis.</span>
 107       <span class="n">where</span> <span class="n">SameType</span><span class="o">&lt;</span><span class="n">coord_t</span><span class="p">,</span> <span class="n">iterator</span><span class="o">::</span><span class="n">difference_type</span><span class="o">&gt;</span><span class="p">;</span>
 108       <span class="n">where</span> <span class="n">SameType</span><span class="o">&lt;</span><span class="n">iterator</span><span class="o">::</span><span class="n">value_type</span><span class="p">,</span><span class="n">value_type</span><span class="o">&gt;</span><span class="p">;</span>
 109   <span class="p">};</span>
 110
 111   <span class="c1">// Defines the type of a view similar to this type, except it invokes Deref upon dereferencing</span>
 112   <span class="k">template</span> <span class="o">&lt;</span><span class="n">PixelDereferenceAdaptorConcept</span> <span class="n">Deref</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="n">add_deref</span> <span class="p">{</span>
 113       <span class="k">typename</span> <span class="n">type</span><span class="p">;</span>        <span class="n">where</span> <span class="n">RandomAccessNDImageViewConcept</span><span class="o">&lt;</span><span class="n">type</span><span class="o">&gt;</span><span class="p">;</span>
 114       <span class="k">static</span> <span class="n">type</span> <span class="nf">make</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">v</span><span class="p">,</span> <span class="k">const</span> <span class="n">Deref</span><span class="o">&amp;</span> <span class="n">deref</span><span class="p">);</span>
 115   <span class="p">};</span>
 116
 117   <span class="k">static</span> <span class="k">const</span> <span class="kt">size_t</span> <span class="n">num_dimensions</span> <span class="o">=</span> <span class="n">point_t</span><span class="o">::</span><span class="n">num_dimensions</span><span class="p">;</span>
 118
 119   <span class="c1">// Create from a locator at the top-left corner and dimensions</span>
 120   <span class="n">View</span><span class="o">::</span><span class="n">View</span><span class="p">(</span><span class="k">const</span> <span class="n">locator</span><span class="o">&amp;</span><span class="p">,</span> <span class="k">const</span> <span class="n">point_type</span><span class="o">&amp;</span><span class="p">);</span>
 121
 122   <span class="n">size_type</span>        <span class="n">View</span><span class="o">::</span><span class="n">size</span><span class="p">()</span>       <span class="k">const</span><span class="p">;</span> <span class="c1">// total number of elements</span>
 123   <span class="n">reference</span>        <span class="k">operator</span><span class="p">[](</span><span class="n">View</span><span class="p">,</span> <span class="k">const</span> <span class="n">difference_type</span><span class="o">&amp;</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span> <span class="c1">// 1-dimensional reference</span>
 124   <span class="n">iterator</span>         <span class="n">View</span><span class="o">::</span><span class="n">begin</span><span class="p">()</span>      <span class="k">const</span><span class="p">;</span>
 125   <span class="n">iterator</span>         <span class="n">View</span><span class="o">::</span><span class="n">end</span><span class="p">()</span>        <span class="k">const</span><span class="p">;</span>
 126   <span class="n">reverse_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">rbegin</span><span class="p">()</span>     <span class="k">const</span><span class="p">;</span>
 127   <span class="n">reverse_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">rend</span><span class="p">()</span>       <span class="k">const</span><span class="p">;</span>
 128   <span class="n">iterator</span>         <span class="n">View</span><span class="o">::</span><span class="n">at</span><span class="p">(</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span><span class="p">);</span>
 129   <span class="n">point_t</span>          <span class="n">View</span><span class="o">::</span><span class="n">dimensions</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> <span class="c1">// number of elements along each dimension</span>
 130   <span class="kt">bool</span>             <span class="n">View</span><span class="o">::</span><span class="n">is_1d_traversable</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>   <span class="c1">// Does an iterator over the first dimension visit each value?</span>
 131
 132   <span class="c1">// iterator along a given dimension starting at a given point</span>
 133   <span class="k">template</span> <span class="o">&lt;</span><span class="kt">size_t</span> <span class="n">D</span><span class="o">&gt;</span> <span class="n">View</span><span class="o">::</span><span class="n">axis</span><span class="o">&lt;</span><span class="n">D</span><span class="o">&gt;::</span><span class="n">iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">axis_iterator</span><span class="p">(</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 134
 135   <span class="n">reference</span> <span class="nf">operator</span><span class="p">()(</span><span class="n">View</span><span class="p">,</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 136 <span class="p">};</span>
 137
 138 <span class="n">concept</span> <span class="n">MutableRandomAccessNDImageViewConcept</span><span class="o">&lt;</span><span class="n">RandomAccessNDImageViewConcept</span> <span class="n">View</span><span class="o">&gt;</span>
 139 <span class="p">{</span>
 140   <span class="n">where</span> <span class="n">Mutable</span><span class="o">&lt;</span><span class="n">reference</span><span class="o">&gt;</span><span class="p">;</span>
 141 <span class="p">};</span>
 142 </pre></div>
 143 </div>
 144 <p>Two-dimensional image views have the following extra requirements:</p>
 145 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">RandomAccess2DImageViewConcept</span><span class="o">&lt;</span><span class="n">RandomAccessNDImageViewConcept</span> <span class="n">View</span><span class="o">&gt;</span>
 146 <span class="p">{</span>
 147   <span class="n">where</span> <span class="n">num_dimensions</span><span class="o">==</span><span class="mi">2</span><span class="p">;</span>
 148
 149   <span class="k">typename</span> <span class="n">x_iterator</span> <span class="o">=</span> <span class="n">axis</span><span class="o">&lt;</span><span class="mi">0</span><span class="o">&gt;::</span><span class="n">iterator</span><span class="p">;</span>
 150   <span class="k">typename</span> <span class="n">y_iterator</span> <span class="o">=</span> <span class="n">axis</span><span class="o">&lt;</span><span class="mi">1</span><span class="o">&gt;::</span><span class="n">iterator</span><span class="p">;</span>
 151   <span class="k">typename</span> <span class="n">x_coord_t</span>  <span class="o">=</span> <span class="n">axis</span><span class="o">&lt;</span><span class="mi">0</span><span class="o">&gt;::</span><span class="n">coord_t</span><span class="p">;</span>
 152   <span class="k">typename</span> <span class="n">y_coord_t</span>  <span class="o">=</span> <span class="n">axis</span><span class="o">&lt;</span><span class="mi">1</span><span class="o">&gt;::</span><span class="n">coord_t</span><span class="p">;</span>
 153   <span class="k">typename</span> <span class="n">xy_locator</span> <span class="o">=</span> <span class="n">locator</span><span class="p">;</span>
 154
 155   <span class="n">x_coord_t</span> <span class="n">View</span><span class="o">::</span><span class="n">width</span><span class="p">()</span>  <span class="k">const</span><span class="p">;</span>
 156   <span class="n">y_coord_t</span> <span class="n">View</span><span class="o">::</span><span class="n">height</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
 157
 158   <span class="c1">// X-navigation</span>
 159   <span class="n">x_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">x_at</span><span class="p">(</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 160   <span class="n">x_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">row_begin</span><span class="p">(</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 161   <span class="n">x_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">row_end</span>  <span class="p">(</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 162
 163   <span class="c1">// Y-navigation</span>
 164   <span class="n">y_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">y_at</span><span class="p">(</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 165   <span class="n">y_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">col_begin</span><span class="p">(</span><span class="n">x_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 166   <span class="n">y_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">col_end</span>  <span class="p">(</span><span class="n">x_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 167
 168   <span class="c1">// navigating in 2D</span>
 169   <span class="n">xy_locator</span> <span class="n">View</span><span class="o">::</span><span class="n">xy_at</span><span class="p">(</span><span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 170
 171   <span class="c1">// (x,y) versions of all methods taking point_t</span>
 172   <span class="n">View</span><span class="o">::</span><span class="n">View</span><span class="p">(</span><span class="n">x_coord_t</span><span class="p">,</span><span class="n">y_coord_t</span><span class="p">,</span><span class="k">const</span> <span class="n">locator</span><span class="o">&amp;</span><span class="p">);</span>
 173   <span class="n">iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">at</span><span class="p">(</span><span class="n">x_coord_t</span><span class="p">,</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 174   <span class="n">reference</span> <span class="nf">operator</span><span class="p">()(</span><span class="n">View</span><span class="p">,</span><span class="n">x_coord_t</span><span class="p">,</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 175   <span class="n">xy_locator</span> <span class="n">View</span><span class="o">::</span><span class="n">xy_at</span><span class="p">(</span><span class="n">x_coord_t</span><span class="p">,</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 176   <span class="n">x_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">x_at</span><span class="p">(</span><span class="n">x_coord_t</span><span class="p">,</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 177   <span class="n">y_iterator</span> <span class="n">View</span><span class="o">::</span><span class="n">y_at</span><span class="p">(</span><span class="n">x_coord_t</span><span class="p">,</span><span class="n">y_coord_t</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
 178 <span class="p">};</span>
 179
 180 <span class="n">concept</span> <span class="n">MutableRandomAccess2DImageViewConcept</span><span class="o">&lt;</span><span class="n">RandomAccess2DImageViewConcept</span> <span class="n">View</span><span class="o">&gt;</span>
 181   <span class="o">:</span> <span class="n">MutableRandomAccessNDImageViewConcept</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;</span> <span class="p">{};</span>
 182 </pre></div>
 183 </div>
 184 <p>Image views that GIL typically uses operate on value types that model
 185 <code class="docutils literal"><span class="pre">PixelValueConcept</span></code> and have some additional requirements:</p>
 186 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">ImageViewConcept</span><span class="o">&lt;</span><span class="n">RandomAccess2DImageViewConcept</span> <span class="n">View</span><span class="o">&gt;</span>
 187 <span class="p">{</span>
 188   <span class="n">where</span> <span class="n">PixelValueConcept</span><span class="o">&lt;</span><span class="n">value_type</span><span class="o">&gt;</span><span class="p">;</span>
 189   <span class="n">where</span> <span class="n">PixelIteratorConcept</span><span class="o">&lt;</span><span class="n">x_iterator</span><span class="o">&gt;</span><span class="p">;</span>
 190   <span class="n">where</span> <span class="n">PixelIteratorConcept</span><span class="o">&lt;</span><span class="n">y_iterator</span><span class="o">&gt;</span><span class="p">;</span>
 191   <span class="n">where</span> <span class="n">x_coord_t</span> <span class="o">==</span> <span class="n">y_coord_t</span><span class="p">;</span>
 192
 193   <span class="k">typename</span> <span class="n">coord_t</span> <span class="o">=</span> <span class="n">x_coord_t</span><span class="p">;</span>
 194
 195   <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">View</span><span class="o">::</span><span class="n">num_channels</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
 196 <span class="p">};</span>
 197
 198
 199 <span class="n">concept</span> <span class="n">MutableImageViewConcept</span><span class="o">&lt;</span><span class="n">ImageViewConcept</span> <span class="n">View</span><span class="o">&gt;</span>
 200   <span class="o">:</span> <span class="n">MutableRandomAccess2DImageViewConcept</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;</span>
 201 <span class="p">{};</span>
 202 </pre></div>
 203 </div>
 204 <p>Two image views are compatible if they have compatible pixels and the same
 205 number of dimensions:</p>
 206 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">ViewsCompatibleConcept</span><span class="o">&lt;</span><span class="n">ImageViewConcept</span> <span class="n">V1</span><span class="p">,</span> <span class="n">ImageViewConcept</span> <span class="n">V2</span><span class="o">&gt;</span>
 207 <span class="p">{</span>
 208   <span class="n">where</span> <span class="n">PixelsCompatibleConcept</span><span class="o">&lt;</span><span class="n">V1</span><span class="o">::</span><span class="n">value_type</span><span class="p">,</span> <span class="n">V2</span><span class="o">::</span><span class="n">value_type</span><span class="o">&gt;</span><span class="p">;</span>
 209   <span class="n">where</span> <span class="n">V1</span><span class="o">::</span><span class="n">num_dimensions</span> <span class="o">==</span> <span class="n">V2</span><span class="o">::</span><span class="n">num_dimensions</span><span class="p">;</span>
 210 <span class="p">};</span>
 211 </pre></div>
 212 </div>
 213 <p>Compatible views must also have the same dimensions (i.e. the same width and
 214 height). Many algorithms taking multiple views require that they be pairwise
 215 compatible.</p>
 216 <div class="admonition seealso">
 217 <p class="first admonition-title">See also</p>
 218 <ul class="last simple">
 219 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_random_access_n_d_image_view_concept.html">RandomAccessNDImageViewConcept&lt;View&gt;</a></li>
 220 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_random_access_n_d_image_view_concept.html">MutableRandomAccessNDImageViewConcept&lt;View&gt;</a></li>
 221 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_random_access2_d_image_view_concept.html">RandomAccess2DImageViewConcept&lt;View&gt;</a></li>
 222 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_random_access2_d_image_view_concept.html">MutableRandomAccess2DImageViewConcept&lt;View&gt;</a></li>
 223 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_image_view_concept.html">ImageViewConcept&lt;View&gt;</a></li>
 224 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_image_view_concept.html">MutableImageViewConcept&lt;View&gt;</a></li>
 225 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_views_compatible_concept.html">ViewsCompatibleConcept&lt;View1,View2&gt;</a></li>
 226 </ul>
 227 </div>
 228 </div>
 229 <div class="section" id="models">
 230 <h2><a class="toc-backref" href="#id2">Models</a></h2>
 231 <p>GIL provides a model for <code class="docutils literal"><span class="pre">ImageViewConcept</span></code> called <code class="docutils literal"><span class="pre">image_view</span></code>. It is
 232 templated over a model of <code class="docutils literal"><span class="pre">PixelLocatorConcept</span></code>. (If instantiated with a
 233 model of <code class="docutils literal"><span class="pre">MutablePixelLocatorConcept</span></code>, it models
 234 <code class="docutils literal"><span class="pre">MutableImageViewConcept</span></code>). Synopsis:</p>
 235 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// Locator models PixelLocatorConcept, could be MutablePixelLocatorConcept</span>
 236 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Locator</span><span class="o">&gt;</span>
 237 <span class="k">class</span> <span class="nc">image_view</span>
 238 <span class="p">{</span>
 239 <span class="k">public</span><span class="o">:</span>
 240   <span class="k">typedef</span> <span class="n">Locator</span> <span class="n">xy_locator</span><span class="p">;</span>
 241   <span class="k">typedef</span> <span class="n">iterator_from_2d</span><span class="o">&lt;</span><span class="n">Locator</span><span class="o">&gt;</span> <span class="n">iterator</span><span class="p">;</span>
 242   <span class="p">...</span>
 243 <span class="k">private</span><span class="o">:</span>
 244   <span class="n">xy_locator</span> <span class="n">_pixels</span><span class="p">;</span>     <span class="c1">// 2D pixel locator at the top left corner of the image view range</span>
 245   <span class="n">point_t</span>    <span class="n">_dimensions</span><span class="p">;</span> <span class="c1">// width and height</span>
 246 <span class="p">};</span>
 247 </pre></div>
 248 </div>
 249 <p>Image views are lightweight objects. A regular interleaved view is typically
 250 16 bytes long - two integers for the width and height (inside dimensions) one
 251 for the number of bytes between adjacent rows (inside the locator) and one
 252 pointer to the beginning of the pixel block.</p>
 253 </div>
 254 <div class="section" id="algorithms">
 255 <h2><a class="toc-backref" href="#id3">Algorithms</a></h2>
 256 <p>GIL provides algorithms constructing views from raw data or other views.</p>
 257 <div class="section" id="creating-views-from-raw-pixels">
 258 <h3><a class="toc-backref" href="#id4">Creating Views from Raw Pixels</a></h3>
 259 <p>Standard image views can be constructed from raw data of any supported color
 260 space, bit depth, channel ordering or planar vs. interleaved structure.
 261 Interleaved views are constructed using <code class="docutils literal"><span class="pre">interleaved_view</span></code>, supplying the
 262 image dimensions, number of bytes per row, and a pointer to the first pixel:</p>
 263 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// Iterator models pixel iterator (e.g. rgb8_ptr_t or rgb8c_ptr_t)</span>
 264 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Iterator</span><span class="o">&gt;</span>
 265 <span class="n">image_view</span><span class="o">&lt;</span><span class="p">...</span><span class="o">&gt;</span> <span class="n">interleaved_view</span><span class="p">(</span><span class="kt">ptrdiff_t</span> <span class="n">width</span><span class="p">,</span> <span class="kt">ptrdiff_t</span> <span class="n">height</span><span class="p">,</span> <span class="n">Iterator</span> <span class="n">pixels</span><span class="p">,</span> <span class="kt">ptrdiff_t</span> <span class="n">rowsize</span><span class="p">)</span>
 266 </pre></div>
 267 </div>
 268 <p>Planar views are defined for every color space and take each plane separately.
 269 Here is the RGB one:</p>
 270 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// Iterator models channel iterator (e.g. bits8* or bits8 const*)</span>
 271 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">Iterator</span><span class="o">&gt;</span>
 272 <span class="n">image_view</span><span class="o">&lt;</span><span class="p">...</span><span class="o">&gt;</span> <span class="n">planar_rgb_view</span><span class="p">(</span>
 273     <span class="kt">ptrdiff_t</span> <span class="n">width</span><span class="p">,</span> <span class="kt">ptrdiff_t</span> <span class="n">height</span><span class="p">,</span>
 274     <span class="n">IC</span> <span class="n">r</span><span class="p">,</span> <span class="n">IC</span> <span class="n">g</span><span class="p">,</span> <span class="n">IC</span> <span class="n">b</span><span class="p">,</span> <span class="kt">ptrdiff_t</span> <span class="n">rowsize</span><span class="p">);</span>
 275 </pre></div>
 276 </div>
 277 <p>Note that the supplied pixel/channel iterators could be constant (read-only),
 278 in which case the returned view is a constant-value (immutable) view.</p>
 279 </div>
 280 <div class="section" id="creating-image-views-from-other-image-views">
 281 <h3><a class="toc-backref" href="#id5">Creating Image Views from Other Image Views</a></h3>
 282 <p>It is possible to construct one image view from another by changing some
 283 policy of how image data is interpreted. The result could be a view whose type
 284 is derived from the type of the source. GIL uses the following metafunctions
 285 to get the derived types:</p>
 286 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// Some result view types</span>
 287 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span>
 288 <span class="k">struct</span> <span class="nl">dynamic_xy_step_type</span> <span class="p">:</span> <span class="k">public</span> <span class="n">dynamic_y_step_type</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">dynamic_x_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span><span class="o">&gt;</span> <span class="p">{};</span>
 289
 290 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span>
 291 <span class="k">struct</span> <span class="nl">dynamic_xy_step_transposed_type</span> <span class="p">:</span> <span class="k">public</span> <span class="n">dynamic_xy_step_type</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">transposed_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span><span class="o">&gt;</span> <span class="p">{};</span>
 292
 293 <span class="c1">// color and bit depth converted view to match pixel type P</span>
 294 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">SrcView</span><span class="p">,</span> <span class="c1">// Models ImageViewConcept</span>
 295         <span class="k">typename</span> <span class="n">DstP</span><span class="p">,</span>    <span class="c1">// Models PixelConcept</span>
 296         <span class="k">typename</span> <span class="n">ColorConverter</span><span class="o">=</span><span class="n">gil</span><span class="o">::</span><span class="n">default_color_converter</span><span class="o">&gt;</span>
 297 <span class="k">struct</span> <span class="n">color_converted_view_type</span>
 298 <span class="p">{</span>
 299   <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span>     <span class="c1">// image view adaptor with value type DstP, over SrcView</span>
 300 <span class="p">};</span>
 301
 302 <span class="c1">// single-channel view of the N-th channel of a given view</span>
 303 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">SrcView</span><span class="o">&gt;</span>
 304 <span class="k">struct</span> <span class="n">nth_channel_view_type</span>
 305 <span class="p">{</span>
 306   <span class="k">typedef</span> <span class="p">...</span> <span class="n">type</span><span class="p">;</span>
 307 <span class="p">};</span>
 308 </pre></div>
 309 </div>
 310 <p>GIL Provides the following view transformations:</p>
 311 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// flipped upside-down, left-to-right, transposed view</span>
 312 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_y_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span>             <span class="n">flipped_up_down_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 313 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_x_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span>             <span class="n">flipped_left_right_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 314 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_xy_step_transposed_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">transposed_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 315
 316 <span class="c1">// rotations</span>
 317 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span>            <span class="n">rotated180_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 318 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_xy_step_transposed_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">rotated90cw_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 319 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_xy_step_transposed_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">rotated90ccw_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 320
 321 <span class="c1">// view of an axis-aligned rectangular area within an image</span>
 322 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="n">View</span>                                                 <span class="n">subimage_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span>
 323            <span class="k">const</span> <span class="n">View</span><span class="o">::</span><span class="n">point_t</span><span class="o">&amp;</span> <span class="n">top_left</span><span class="p">,</span> <span class="k">const</span> <span class="n">View</span><span class="o">::</span><span class="n">point_t</span><span class="o">&amp;</span> <span class="n">dimensions</span><span class="p">);</span>
 324
 325 <span class="c1">// subsampled view (skipping pixels in X and Y)</span>
 326 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span> <span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span>            <span class="n">subsampled_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span>
 327            <span class="k">const</span> <span class="n">View</span><span class="o">::</span><span class="n">point_t</span><span class="o">&amp;</span> <span class="n">step</span><span class="p">);</span>
 328
 329 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="p">,</span> <span class="k">typename</span> <span class="n">P</span><span class="o">&gt;</span>
 330 <span class="n">color_converted_view_type</span><span class="o">&lt;</span><span class="n">View</span><span class="p">,</span><span class="n">P</span><span class="o">&gt;::</span><span class="n">type</span>                                       <span class="n">color_converted_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 331 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="p">,</span> <span class="k">typename</span> <span class="n">P</span><span class="p">,</span> <span class="k">typename</span> <span class="n">CCV</span><span class="o">&gt;</span> <span class="c1">// with a custom color converter</span>
 332 <span class="n">color_converted_view_type</span><span class="o">&lt;</span><span class="n">View</span><span class="p">,</span><span class="n">P</span><span class="p">,</span><span class="n">CCV</span><span class="o">&gt;::</span><span class="n">type</span>                                   <span class="n">color_converted_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">);</span>
 333
 334 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span>
 335 <span class="n">nth_channel_view_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">view_t</span>                                           <span class="n">nth_channel_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">view</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">);</span>
 336 </pre></div>
 337 </div>
 338 <p>The implementations of most of these view factory methods are straightforward.
 339 Here is, for example, how the flip views are implemented. The flip upside-down
 340 view creates a view whose first pixel is the bottom left pixel of the original
 341 view and whose y-step is the negated step of the source.</p>
 342 <div class="highlight-cpp"><div class="highlight"><pre><span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">View</span><span class="o">&gt;</span>
 343 <span class="k">typename</span> <span class="n">dynamic_y_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">flipped_up_down_view</span><span class="p">(</span><span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">)</span>
 344 <span class="p">{</span>
 345   <span class="n">gil_function_requires</span><span class="o">&lt;</span><span class="n">ImageViewConcept</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;</span> <span class="o">&gt;</span><span class="p">();</span>
 346   <span class="k">typedef</span> <span class="k">typename</span> <span class="n">dynamic_y_step_type</span><span class="o">&lt;</span><span class="n">View</span><span class="o">&gt;::</span><span class="n">type</span> <span class="n">RView</span><span class="p">;</span>
 347   <span class="k">return</span> <span class="nf">RView</span><span class="p">(</span><span class="n">src</span><span class="p">.</span><span class="n">dimensions</span><span class="p">(),</span><span class="k">typename</span> <span class="n">RView</span><span class="o">::</span><span class="n">xy_locator</span><span class="p">(</span><span class="n">src</span><span class="p">.</span><span class="n">xy_at</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="n">src</span><span class="p">.</span><span class="n">height</span><span class="p">()</span><span class="o">-</span><span class="mi">1</span><span class="p">),</span><span class="o">-</span><span class="mi">1</span><span class="p">));</span>
 348 <span class="p">}</span>
 349 </pre></div>
 350 </div>
 351 <p>The call to <code class="docutils literal"><span class="pre">gil_function_requires</span></code> ensures (at compile time) that the
 352 template parameter is a valid model of <code class="docutils literal"><span class="pre">ImageViewConcept</span></code>. Using it
 353 generates easier to track compile errors, creates no extra code and has no
 354 run-time performance impact. We are using the <code class="docutils literal"><span class="pre">boost::concept_check</span> <span class="pre">library</span></code>,
 355 but wrapping it in <code class="docutils literal"><span class="pre">gil_function_requires</span></code>, which performs the check if the
 356 <code class="docutils literal"><span class="pre">BOOST_GIL_USE_CONCEPT_CHECK</span></code> is set. It is unset by default, because there
 357 is a significant increase in compile time when using concept checks. We will
 358 skip <code class="docutils literal"><span class="pre">gil_function_requires</span></code> in the code examples in this guide for the sake
 359 of succinctness.</p>
 360 <p>Image views can be freely composed (see section <a class="reference internal" href="metafunctions.html"><span class="doc">Metafunctions</span></a> for
 361 explanation of the typedefs <code class="docutils literal"><span class="pre">rgb16_image_t</span></code> and <code class="docutils literal"><span class="pre">gray16_step_view_t)</span></code>:</p>
 362 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">rgb16_image_t</span> <span class="nf">img</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span><span class="mi">100</span><span class="p">);</span>    <span class="c1">// an RGB interleaved image</span>
 363
 364 <span class="c1">// grayscale view over the green (index 1) channel of img</span>
 365 <span class="n">gray16_step_view_t</span> <span class="n">green</span><span class="o">=</span><span class="n">nth_channel_view</span><span class="p">(</span><span class="n">view</span><span class="p">(</span><span class="n">img</span><span class="p">),</span><span class="mi">1</span><span class="p">);</span>
 366
 367 <span class="c1">// 50x50 view of the green channel of img, upside down and taking every other pixel in X and in Y</span>
 368 <span class="n">gray16_step_view_t</span> <span class="n">ud_fud</span><span class="o">=</span><span class="n">flipped_up_down_view</span><span class="p">(</span><span class="n">subsampled_view</span><span class="p">(</span><span class="n">green</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">));</span>
 369 </pre></div>
 370 </div>
 371 <p>As previously stated, image views are fast, constant-time, shallow views over
 372 the pixel data. The above code does not copy any pixels; it operates on the
 373 pixel data allocated when <code class="docutils literal"><span class="pre">img</span></code> was created.</p>
 374 </div>
 375 <div class="section" id="stl-style-algorithms-on-image-views">
 376 <h3><a class="toc-backref" href="#id6">STL-Style Algorithms on Image Views</a></h3>
 377 <p>Image views provide 1D iteration of their pixels via <code class="docutils literal"><span class="pre">begin()</span></code> and <code class="docutils literal"><span class="pre">end()</span></code>
 378 methods, which makes it possible to use STL algorithms with them. However,
 379 using nested loops over X and Y is in many cases more efficient.
 380 The algorithms in this section resemble STL algorithms, but they abstract away
 381 the nested loops and take views (as opposed to ranges) as input.</p>
 382 <div class="highlight-cpp"><div class="highlight"><pre><span class="c1">// Equivalents of std::copy and std::uninitialized_copy</span>
 383 <span class="c1">// where ImageViewConcept&lt;V1&gt;, MutableImageViewConcept&lt;V2&gt;, ViewsCompatibleConcept&lt;V1,V2&gt;</span>
 384 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="o">&gt;</span>
 385 <span class="kt">void</span> <span class="n">copy_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">);</span>
 386 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="o">&gt;</span>
 387 <span class="kt">void</span> <span class="n">uninitialized_copy_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">);</span>
 388
 389 <span class="c1">// Equivalents of std::fill and std::uninitialized_fill</span>
 390 <span class="c1">// where MutableImageViewConcept&lt;V&gt;, PixelConcept&lt;Value&gt;, PixelsCompatibleConcept&lt;Value,V::value_type&gt;</span>
 391 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Value</span><span class="o">&gt;</span>
 392 <span class="kt">void</span> <span class="n">fill_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="k">const</span> <span class="n">Value</span><span class="o">&amp;</span> <span class="n">val</span><span class="p">);</span>
 393 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V</span><span class="p">,</span> <span class="k">typename</span> <span class="n">Value</span><span class="o">&gt;</span>
 394 <span class="kt">void</span> <span class="n">uninitialized_fill_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="k">const</span> <span class="n">Value</span><span class="o">&amp;</span> <span class="n">val</span><span class="p">);</span>
 395
 396 <span class="c1">// Equivalent of std::for_each</span>
 397 <span class="c1">// where ImageViewConcept&lt;V&gt;, boost::UnaryFunctionConcept&lt;F&gt;</span>
 398 <span class="c1">// where PixelsCompatibleConcept&lt;V::reference, F::argument_type&gt;</span>
 399 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 400 <span class="n">F</span> <span class="n">for_each_pixel</span><span class="p">(</span><span class="k">const</span> <span class="n">V</span><span class="o">&amp;</span> <span class="n">view</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 401 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 402 <span class="n">F</span> <span class="n">for_each_pixel_position</span><span class="p">(</span><span class="k">const</span> <span class="n">V</span><span class="o">&amp;</span> <span class="n">view</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 403
 404 <span class="c1">// Equivalent of std::generate</span>
 405 <span class="c1">// where MutableImageViewConcept&lt;V&gt;, boost::UnaryFunctionConcept&lt;F&gt;</span>
 406 <span class="c1">// where PixelsCompatibleConcept&lt;V::reference, F::argument_type&gt;</span>
 407 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 408 <span class="kt">void</span> <span class="n">generate_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 409
 410 <span class="c1">// Equivalent of std::transform with one source</span>
 411 <span class="c1">// where ImageViewConcept&lt;V1&gt;, MutableImageViewConcept&lt;V2&gt;</span>
 412 <span class="c1">// where boost::UnaryFunctionConcept&lt;F&gt;</span>
 413 <span class="c1">// where PixelsCompatibleConcept&lt;V1::const_reference, F::argument_type&gt;</span>
 414 <span class="c1">// where PixelsCompatibleConcept&lt;F::result_type, V2::reference&gt;</span>
 415 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 416 <span class="n">F</span> <span class="n">transform_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 417 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 418 <span class="n">F</span> <span class="n">transform_pixel_positions</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 419
 420 <span class="c1">// Equivalent of std::transform with two sources</span>
 421 <span class="c1">// where ImageViewConcept&lt;V1&gt;, ImageViewConcept&lt;V2&gt;, MutableImageViewConcept&lt;V3&gt;</span>
 422 <span class="c1">// where boost::BinaryFunctionConcept&lt;F&gt;</span>
 423 <span class="c1">// where PixelsCompatibleConcept&lt;V1::const_reference, F::first_argument_type&gt;</span>
 424 <span class="c1">// where PixelsCompatibleConcept&lt;V2::const_reference, F::second_argument_type&gt;</span>
 425 <span class="c1">// where PixelsCompatibleConcept&lt;F::result_type, V3::reference&gt;</span>
 426 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V3</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 427 <span class="n">F</span> <span class="n">transform_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src1</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">src2</span><span class="p">,</span> <span class="k">const</span> <span class="n">V3</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 428 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V3</span><span class="p">,</span> <span class="k">typename</span> <span class="n">F</span><span class="o">&gt;</span>
 429 <span class="n">F</span> <span class="n">transform_pixel_positions</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src1</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">src2</span><span class="p">,</span> <span class="k">const</span> <span class="n">V3</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="n">F</span> <span class="n">fun</span><span class="p">);</span>
 430
 431 <span class="c1">// Copies a view into another, color converting the pixels if needed, with the default or user-defined color converter</span>
 432 <span class="c1">// where ImageViewConcept&lt;V1&gt;, MutableImageViewConcept&lt;V2&gt;</span>
 433 <span class="c1">// V1::value_type must be convertible to V2::value_type.</span>
 434 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="o">&gt;</span>
 435 <span class="kt">void</span> <span class="n">copy_and_convert_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">);</span>
 436 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="p">,</span> <span class="k">typename</span> <span class="n">ColorConverter</span><span class="o">&gt;</span>
 437 <span class="kt">void</span> <span class="n">copy_and_convert_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">dst</span><span class="p">,</span> <span class="n">ColorConverter</span> <span class="n">ccv</span><span class="p">);</span>
 438
 439 <span class="c1">// Equivalent of std::equal</span>
 440 <span class="c1">// where ImageViewConcept&lt;V1&gt;, ImageViewConcept&lt;V2&gt;, ViewsCompatibleConcept&lt;V1,V2&gt;</span>
 441 <span class="k">template</span> <span class="o">&lt;</span><span class="k">typename</span> <span class="n">V1</span><span class="p">,</span> <span class="k">typename</span> <span class="n">V2</span><span class="o">&gt;</span>
 442 <span class="kt">bool</span> <span class="n">equal_pixels</span><span class="p">(</span><span class="k">const</span> <span class="n">V1</span><span class="o">&amp;</span> <span class="n">view1</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&amp;</span> <span class="n">view2</span><span class="p">);</span>
 443 </pre></div>
 444 </div>
 445 <p>Algorithms that take multiple views require that they have the same
 446 dimensions. <code class="docutils literal"><span class="pre">for_each_pixel_position</span></code> and <code class="docutils literal"><span class="pre">transform_pixel_positions</span></code> pass
 447 pixel locators, as opposed to pixel references, to their function objects.
 448 This allows for writing algorithms that use pixel neighbours, as the tutorial
 449 demonstrates.</p>
 450 <p>Most of these algorithms check whether the image views are 1D-traversable.
 451 A 1D-traversable image view has no gaps at the end of the rows.
 452 In other words, if an x_iterator of that view is advanced past the last pixel
 453 in a row it will move to the first pixel of the next row. When image views are
 454 1D-traversable, the algorithms use a single loop and run more efficiently.
 455 If one or more of the input views are not 1D-traversable, the algorithms
 456 fall-back to an X-loop nested inside a Y-loop.</p>
 457 <p>The algorithms typically delegate the work to their corresponding STL
 458 algorithms. For example, <code class="docutils literal"><span class="pre">copy_pixels</span></code> calls <code class="docutils literal"><span class="pre">std::copy</span></code> either for each
 459 row, or, when the images are 1D-traversable, once for all pixels.</p>
 460 <p>In addition, overloads are sometimes provided for the STL algorithms.
 461 For example, <code class="docutils literal"><span class="pre">std::copy</span></code> for planar iterators is overloaded to perform
 462 <code class="docutils literal"><span class="pre">std::copy</span></code> for each of the planes. <code class="docutils literal"><span class="pre">std::copy</span></code> over bitwise-copyable
 463 pixels results in <code class="docutils literal"><span class="pre">std::copy</span></code> over unsigned char, which STL
 464 implements via <code class="docutils literal"><span class="pre">memmove</span></code>.</p>
 465 <p>As a result <code class="docutils literal"><span class="pre">copy_pixels</span></code> may result in a single call to <code class="docutils literal"><span class="pre">memmove</span></code> for
 466 interleaved 1D-traversable views, or one per each plane of planar
 467 1D-traversable views, or one per each row of interleaved non-1D-traversable
 468 images, etc.</p>
 469 <p>GIL also provides some beta-versions of image processing algorithms, such as
 470 resampling and convolution in a numerics extension available on
 471 <a class="reference external" href="http://stlab.adobe.com/gil/download.html">http://stlab.adobe.com/gil/download.html</a>. This code is in early stage of
 472 development and is not optimized for speed</p>
 473 </div>
 474 </div>
 475 </div>
 476
 477
 478     <div class="navbar" style="text-align:right;">
 479
 480
 481       <a class="prev" title="Pixel Locator" href="pixel_locator.html"><img src="../_static/prev.png" alt="prev"/></a>
 482       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
 483       <a class="next" title="Image" href="image.html"><img src="../_static/next.png" alt="next"/></a>
 484
 485     </div>
 486     </div>
 487     <div class="footer" role="contentinfo">
 488       Last updated on 2019-12-10 00:12:10.
 489       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
 490     </div>
 491   </body>
 492 </html>