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. 85Similar to ranges (and iterators), image views are shallow, don’t own the 86underlying data and don’t propagate their constness over the data. 87For example, a constant image view cannot be resized, but may allow modifying 88the pixels. For pixel-immutable operations, use constant-value image view 89(also called non-mutable image view). Most general N-dimensional views satisfy 90the 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"><</span><span class="n">Regular</span> <span class="n">View</span><span class="o">></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"><</span><span class="n">View</span><span class="o">></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"><</span><span class="n">point_t</span><span class="o">></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"><</span><span class="n">locator</span><span class="o">></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"><</span><span class="n">iterator</span><span class="o">></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"><</span><span class="n">reverse_iterator</span><span class="o">></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"><</span><span class="kt">size_t</span> <span class="n">D</span><span class="o">></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"><</span><span class="n">D</span><span class="o">>::</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"><</span><span class="n">iterator</span><span class="o">></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"><</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">></span><span class="p">;</span> 108 <span class="n">where</span> <span class="n">SameType</span><span class="o"><</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">></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"><</span><span class="n">PixelDereferenceAdaptorConcept</span> <span class="n">Deref</span><span class="o">></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"><</span><span class="n">type</span><span class="o">></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">&</span> <span class="n">v</span><span class="p">,</span> <span class="k">const</span> <span class="n">Deref</span><span class="o">&</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">&</span><span class="p">,</span> <span class="k">const</span> <span class="n">point_type</span><span class="o">&</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">&</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">&</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"><</span><span class="kt">size_t</span> <span class="n">D</span><span class="o">></span> <span class="n">View</span><span class="o">::</span><span class="n">axis</span><span class="o"><</span><span class="n">D</span><span class="o">>::</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">&</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">&</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"><</span><span class="n">RandomAccessNDImageViewConcept</span> <span class="n">View</span><span class="o">></span> 139<span class="p">{</span> 140 <span class="n">where</span> <span class="n">Mutable</span><span class="o"><</span><span class="n">reference</span><span class="o">></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"><</span><span class="n">RandomAccessNDImageViewConcept</span> <span class="n">View</span><span class="o">></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"><</span><span class="mi">0</span><span class="o">>::</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"><</span><span class="mi">1</span><span class="o">>::</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"><</span><span class="mi">0</span><span class="o">>::</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"><</span><span class="mi">1</span><span class="o">>::</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">&</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">&</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">&</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">&</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"><</span><span class="n">RandomAccess2DImageViewConcept</span> <span class="n">View</span><span class="o">></span> 181 <span class="o">:</span> <span class="n">MutableRandomAccessNDImageViewConcept</span><span class="o"><</span><span class="n">View</span><span class="o">></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"><</span><span class="n">RandomAccess2DImageViewConcept</span> <span class="n">View</span><span class="o">></span> 187<span class="p">{</span> 188 <span class="n">where</span> <span class="n">PixelValueConcept</span><span class="o"><</span><span class="n">value_type</span><span class="o">></span><span class="p">;</span> 189 <span class="n">where</span> <span class="n">PixelIteratorConcept</span><span class="o"><</span><span class="n">x_iterator</span><span class="o">></span><span class="p">;</span> 190 <span class="n">where</span> <span class="n">PixelIteratorConcept</span><span class="o"><</span><span class="n">y_iterator</span><span class="o">></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"><</span><span class="n">ImageViewConcept</span> <span class="n">View</span><span class="o">></span> 200 <span class="o">:</span> <span class="n">MutableRandomAccess2DImageViewConcept</span><span class="o"><</span><span class="n">View</span><span class="o">></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 205number 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"><</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">></span> 207<span class="p">{</span> 208 <span class="n">where</span> <span class="n">PixelsCompatibleConcept</span><span class="o"><</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">></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 214height). Many algorithms taking multiple views require that they be pairwise 215compatible.</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<View></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<View></a></li> 221<li><a class="reference external" href="reference/structboost_1_1gil_1_1_random_access2_d_image_view_concept.html">RandomAccess2DImageViewConcept<View></a></li> 222<li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_random_access2_d_image_view_concept.html">MutableRandomAccess2DImageViewConcept<View></a></li> 223<li><a class="reference external" href="reference/structboost_1_1gil_1_1_image_view_concept.html">ImageViewConcept<View></a></li> 224<li><a class="reference external" href="reference/structboost_1_1gil_1_1_mutable_image_view_concept.html">MutableImageViewConcept<View></a></li> 225<li><a class="reference external" href="reference/structboost_1_1gil_1_1_views_compatible_concept.html">ViewsCompatibleConcept<View1,View2></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 232templated over a model of <code class="docutils literal"><span class="pre">PixelLocatorConcept</span></code>. (If instantiated with a 233model 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"><</span><span class="k">typename</span> <span class="n">Locator</span><span class="o">></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"><</span><span class="n">Locator</span><span class="o">></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 25016 bytes long - two integers for the width and height (inside dimensions) one 251for the number of bytes between adjacent rows (inside the locator) and one 252pointer 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 260space, bit depth, channel ordering or planar vs. interleaved structure. 261Interleaved views are constructed using <code class="docutils literal"><span class="pre">interleaved_view</span></code>, supplying the 262image 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"><</span><span class="k">typename</span> <span class="n">Iterator</span><span class="o">></span> 265<span class="n">image_view</span><span class="o"><</span><span class="p">...</span><span class="o">></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. 269Here 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"><</span><span class="k">typename</span> <span class="n">Iterator</span><span class="o">></span> 272<span class="n">image_view</span><span class="o"><</span><span class="p">...</span><span class="o">></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), 278in 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 283policy of how image data is interpreted. The result could be a view whose type 284is derived from the type of the source. GIL uses the following metafunctions 285to 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"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></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"><</span><span class="k">typename</span> <span class="n">dynamic_x_step_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</span><span class="n">type</span><span class="o">></span> <span class="p">{};</span> 289 290<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></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"><</span><span class="k">typename</span> <span class="n">transposed_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</span><span class="n">type</span><span class="o">></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"><</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">></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"><</span><span class="k">typename</span> <span class="n">SrcView</span><span class="o">></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"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_y_step_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</span> <span class="n">src</span><span class="p">);</span> 313<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_x_step_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</span> <span class="n">src</span><span class="p">);</span> 314<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_xy_step_transposed_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</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"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</span> <span class="n">src</span><span class="p">);</span> 318<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_xy_step_transposed_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</span> <span class="n">src</span><span class="p">);</span> 319<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_xy_step_transposed_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</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"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></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">&</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">&</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">&</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"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> <span class="k">typename</span> <span class="n">dynamic_xy_step_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</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">&</span> <span class="n">step</span><span class="p">);</span> 328 329<span class="k">template</span> <span class="o"><</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">></span> 330<span class="n">color_converted_view_type</span><span class="o"><</span><span class="n">View</span><span class="p">,</span><span class="n">P</span><span class="o">>::</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">&</span> <span class="n">src</span><span class="p">);</span> 331<span class="k">template</span> <span class="o"><</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">></span> <span class="c1">// with a custom color converter</span> 332<span class="n">color_converted_view_type</span><span class="o"><</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">>::</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">&</span> <span class="n">src</span><span class="p">);</span> 333 334<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> 335<span class="n">nth_channel_view_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</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. 339Here is, for example, how the flip views are implemented. The flip upside-down 340view creates a view whose first pixel is the bottom left pixel of the original 341view 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"><</span><span class="k">typename</span> <span class="n">View</span><span class="o">></span> 343<span class="k">typename</span> <span class="n">dynamic_y_step_type</span><span class="o"><</span><span class="n">View</span><span class="o">>::</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">&</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"><</span><span class="n">ImageViewConcept</span><span class="o"><</span><span class="n">View</span><span class="o">></span> <span class="o">></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"><</span><span class="n">View</span><span class="o">>::</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 352template parameter is a valid model of <code class="docutils literal"><span class="pre">ImageViewConcept</span></code>. Using it 353generates easier to track compile errors, creates no extra code and has no 354run-time performance impact. We are using the <code class="docutils literal"><span class="pre">boost::concept_check</span> <span class="pre">library</span></code>, 355but 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 357is a significant increase in compile time when using concept checks. We will 358skip <code class="docutils literal"><span class="pre">gil_function_requires</span></code> in the code examples in this guide for the sake 359of 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 361explanation 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 372the pixel data. The above code does not copy any pixels; it operates on the 373pixel 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> 378methods, which makes it possible to use STL algorithms with them. However, 379using nested loops over X and Y is in many cases more efficient. 380The algorithms in this section resemble STL algorithms, but they abstract away 381the 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<V1>, MutableImageViewConcept<V2>, ViewsCompatibleConcept<V1,V2></span> 384<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</span> <span class="n">dst</span><span class="p">);</span> 386<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</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<V>, PixelConcept<Value>, PixelsCompatibleConcept<Value,V::value_type></span> 391<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">dst</span><span class="p">,</span> <span class="k">const</span> <span class="n">Value</span><span class="o">&</span> <span class="n">val</span><span class="p">);</span> 393<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">dst</span><span class="p">,</span> <span class="k">const</span> <span class="n">Value</span><span class="o">&</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<V>, boost::UnaryFunctionConcept<F></span> 398<span class="c1">// where PixelsCompatibleConcept<V::reference, F::argument_type></span> 399<span class="k">template</span> <span class="o"><</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">></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">&</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"><</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">></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">&</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<V>, boost::UnaryFunctionConcept<F></span> 406<span class="c1">// where PixelsCompatibleConcept<V::reference, F::argument_type></span> 407<span class="k">template</span> <span class="o"><</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">></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">&</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<V1>, MutableImageViewConcept<V2></span> 412<span class="c1">// where boost::UnaryFunctionConcept<F></span> 413<span class="c1">// where PixelsCompatibleConcept<V1::const_reference, F::argument_type></span> 414<span class="c1">// where PixelsCompatibleConcept<F::result_type, V2::reference></span> 415<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</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"><</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">></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">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</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<V1>, ImageViewConcept<V2>, MutableImageViewConcept<V3></span> 422<span class="c1">// where boost::BinaryFunctionConcept<F></span> 423<span class="c1">// where PixelsCompatibleConcept<V1::const_reference, F::first_argument_type></span> 424<span class="c1">// where PixelsCompatibleConcept<V2::const_reference, F::second_argument_type></span> 425<span class="c1">// where PixelsCompatibleConcept<F::result_type, V3::reference></span> 426<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">src1</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</span> <span class="n">src2</span><span class="p">,</span> <span class="k">const</span> <span class="n">V3</span><span class="o">&</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"><</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">></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">&</span> <span class="n">src1</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</span> <span class="n">src2</span><span class="p">,</span> <span class="k">const</span> <span class="n">V3</span><span class="o">&</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<V1>, MutableImageViewConcept<V2></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"><</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">></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">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</span> <span class="n">dst</span><span class="p">);</span> 436<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</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<V1>, ImageViewConcept<V2>, ViewsCompatibleConcept<V1,V2></span> 441<span class="k">template</span> <span class="o"><</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">></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">&</span> <span class="n">view1</span><span class="p">,</span> <span class="k">const</span> <span class="n">V2</span><span class="o">&</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 446dimensions. <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 447pixel locators, as opposed to pixel references, to their function objects. 448This allows for writing algorithms that use pixel neighbours, as the tutorial 449demonstrates.</p> 450<p>Most of these algorithms check whether the image views are 1D-traversable. 451A 1D-traversable image view has no gaps at the end of the rows. 452In other words, if an x_iterator of that view is advanced past the last pixel 453in a row it will move to the first pixel of the next row. When image views are 4541D-traversable, the algorithms use a single loop and run more efficiently. 455If one or more of the input views are not 1D-traversable, the algorithms 456fall-back to an X-loop nested inside a Y-loop.</p> 457<p>The algorithms typically delegate the work to their corresponding STL 458algorithms. 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 459row, or, when the images are 1D-traversable, once for all pixels.</p> 460<p>In addition, overloads are sometimes provided for the STL algorithms. 461For 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 463pixels results in <code class="docutils literal"><span class="pre">std::copy</span></code> over unsigned char, which STL 464implements 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 466interleaved 1D-traversable views, or one per each plane of planar 4671D-traversable views, or one per each row of interleaved non-1D-traversable 468images, etc.</p> 469<p>GIL also provides some beta-versions of image processing algorithms, such as 470resampling 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 472development 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 2020-08-11 15:08:48. 489 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6. 490 </div> 491 </body> 492</html>
