libs/gil/doc/html/design/image.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 - 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="Dynamic images and image views" href="dynamic_image.html" />
  28     <link rel="prev" title="Image View" href="image_view.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="Image View" href="image_view.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="Dynamic images and image views" href="dynamic_image.html"><img src="../_static/next.png" alt="next"/></a>
  65
  66     </div>
  67
  68   <div class="section" id="image">
  69 <h1>Image</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 </ul>
  75 </div>
  76 <div class="section" id="overview">
  77 <h2><a class="toc-backref" href="#id1">Overview</a></h2>
  78 <p>An image is a container that owns the pixels of a given image view
  79 It allocates them in its constructor and deletes them in the destructor.
  80 It has a deep assignment operator and copy constructor. Images are used
  81 rarely, just when data ownership is important. Most STL algorithms operate on
  82 ranges, not containers. Similarly most GIL algorithms operate on image views
  83 (which images provide).</p>
  84 <p>In the most general form images are N-dimensional and satisfy the following
  85 concept:</p>
  86 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">RandomAccessNDImageConcept</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">Img</span><span class="o">&gt;</span> <span class="o">:</span> <span class="n">Regular</span><span class="o">&lt;</span><span class="n">Img</span><span class="o">&gt;</span>
  87 <span class="p">{</span>
  88   <span class="k">typename</span> <span class="n">view_t</span><span class="p">;</span> <span class="n">where</span> <span class="n">MutableRandomAccessNDImageViewConcept</span><span class="o">&lt;</span><span class="n">view_t</span><span class="o">&gt;</span><span class="p">;</span>
  89   <span class="k">typename</span> <span class="n">const_view_t</span> <span class="o">=</span> <span class="n">view_t</span><span class="o">::</span><span class="n">const_t</span><span class="p">;</span>
  90   <span class="k">typename</span> <span class="n">point_t</span>      <span class="o">=</span> <span class="n">view_t</span><span class="o">::</span><span class="n">point_t</span><span class="p">;</span>
  91   <span class="k">typename</span> <span class="n">value_type</span>   <span class="o">=</span> <span class="n">view_t</span><span class="o">::</span><span class="n">value_type</span><span class="p">;</span>
  92   <span class="k">typename</span> <span class="n">allocator_type</span><span class="p">;</span>
  93
  94   <span class="n">Img</span><span class="o">::</span><span class="n">Img</span><span class="p">(</span><span class="n">point_t</span> <span class="n">dims</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="o">=</span><span class="mi">0</span><span class="p">);</span>
  95   <span class="n">Img</span><span class="o">::</span><span class="n">Img</span><span class="p">(</span><span class="n">point_t</span> <span class="n">dims</span><span class="p">,</span> <span class="n">value_type</span> <span class="n">fill_value</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="p">);</span>
  96
  97   <span class="kt">void</span> <span class="n">Img</span><span class="o">::</span><span class="n">recreate</span><span class="p">(</span><span class="n">point_t</span> <span class="n">new_dims</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="o">=</span><span class="mi">0</span><span class="p">);</span>
  98   <span class="kt">void</span> <span class="n">Img</span><span class="o">::</span><span class="n">recreate</span><span class="p">(</span><span class="n">point_t</span> <span class="n">new_dims</span><span class="p">,</span> <span class="n">value_type</span> <span class="n">fill_value</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="p">);</span>
  99
 100   <span class="k">const</span> <span class="n">point_t</span><span class="o">&amp;</span>        <span class="n">Img</span><span class="o">::</span><span class="n">dimensions</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
 101   <span class="k">const</span> <span class="n">const_view_t</span><span class="o">&amp;</span>   <span class="n">const_view</span><span class="p">(</span><span class="k">const</span> <span class="n">Img</span><span class="o">&amp;</span><span class="p">);</span>
 102   <span class="k">const</span> <span class="n">view_t</span><span class="o">&amp;</span>         <span class="n">view</span><span class="p">(</span><span class="n">Img</span><span class="o">&amp;</span><span class="p">);</span>
 103 <span class="p">};</span>
 104 </pre></div>
 105 </div>
 106 <p>Two-dimensional images have additional requirements:</p>
 107 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">RandomAccess2DImageConcept</span><span class="o">&lt;</span><span class="n">RandomAccessNDImageConcept</span> <span class="n">Img</span><span class="o">&gt;</span>
 108 <span class="p">{</span>
 109   <span class="k">typename</span> <span class="n">x_coord_t</span> <span class="o">=</span> <span class="n">const_view_t</span><span class="o">::</span><span class="n">x_coord_t</span><span class="p">;</span>
 110   <span class="k">typename</span> <span class="n">y_coord_t</span> <span class="o">=</span> <span class="n">const_view_t</span><span class="o">::</span><span class="n">y_coord_t</span><span class="p">;</span>
 111
 112   <span class="n">Img</span><span class="o">::</span><span class="n">Img</span><span class="p">(</span><span class="n">x_coord_t</span> <span class="n">width</span><span class="p">,</span> <span class="n">y_coord_t</span> <span class="n">height</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="o">=</span><span class="mi">0</span><span class="p">);</span>
 113   <span class="n">Img</span><span class="o">::</span><span class="n">Img</span><span class="p">(</span><span class="n">x_coord_t</span> <span class="n">width</span><span class="p">,</span> <span class="n">y_coord_t</span> <span class="n">height</span><span class="p">,</span> <span class="n">value_type</span> <span class="n">fill_value</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="p">);</span>
 114
 115   <span class="n">x_coord_t</span> <span class="n">Img</span><span class="o">::</span><span class="n">width</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
 116   <span class="n">y_coord_t</span> <span class="n">Img</span><span class="o">::</span><span class="n">height</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
 117
 118   <span class="kt">void</span> <span class="n">Img</span><span class="o">::</span><span class="n">recreate</span><span class="p">(</span><span class="n">x_coord_t</span> <span class="n">width</span><span class="p">,</span> <span class="n">y_coord_t</span> <span class="n">height</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="o">=</span><span class="mi">1</span><span class="p">);</span>
 119   <span class="kt">void</span> <span class="n">Img</span><span class="o">::</span><span class="n">recreate</span><span class="p">(</span><span class="n">x_coord_t</span> <span class="n">width</span><span class="p">,</span> <span class="n">y_coord_t</span> <span class="n">height</span><span class="p">,</span> <span class="n">value_type</span> <span class="n">fill_value</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="kt">size_t</span> <span class="n">alignment</span><span class="p">);</span>
 120 <span class="p">};</span>
 121 </pre></div>
 122 </div>
 123 <p>GIL images have views that model <code class="docutils literal"><span class="pre">ImageViewConcept</span></code> and operate on pixels.</p>
 124 <div class="highlight-cpp"><div class="highlight"><pre><span class="n">concept</span> <span class="n">ImageConcept</span><span class="o">&lt;</span><span class="n">RandomAccess2DImageConcept</span> <span class="n">Img</span><span class="o">&gt;</span>
 125 <span class="p">{</span>
 126   <span class="n">where</span> <span class="n">MutableImageViewConcept</span><span class="o">&lt;</span><span class="n">view_t</span><span class="o">&gt;</span><span class="p">;</span>
 127   <span class="k">typename</span> <span class="n">coord_t</span>  <span class="o">=</span> <span class="n">view_t</span><span class="o">::</span><span class="n">coord_t</span><span class="p">;</span>
 128 <span class="p">};</span>
 129 </pre></div>
 130 </div>
 131 <p>Images, unlike locators and image views, don&#8217;t have &#8216;mutable&#8217; set of concepts
 132 because immutable images are not very useful.</p>
 133 <div class="admonition seealso">
 134 <p class="first admonition-title">See also</p>
 135 <ul class="last simple">
 136 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_random_access_n_d_image_concept.html">RandomAccessNDImageConcept&lt;Image&gt;</a></li>
 137 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_random_access2_d_image_concept.html">RandomAccess2DImageConcept&lt;Image&gt;</a></li>
 138 <li><a class="reference external" href="reference/structboost_1_1gil_1_1_image_concept.html">ImageConcept&lt;Image&gt;</a></li>
 139 </ul>
 140 </div>
 141 </div>
 142 <div class="section" id="models">
 143 <h2><a class="toc-backref" href="#id2">Models</a></h2>
 144 <p>GIL provides a class, <code class="docutils literal"><span class="pre">image</span></code>, which is templated over the value type
 145 (the pixel) and models <code class="docutils literal"><span class="pre">ImageConcept</span></code>:</p>
 146 <div class="highlight-cpp"><div class="highlight"><pre> <span class="k">template</span>
 147  <span class="o">&lt;</span>
 148      <span class="k">typename</span> <span class="n">Pixel</span><span class="p">,</span> <span class="c1">// Models PixelValueConcept</span>
 149      <span class="kt">bool</span> <span class="n">IsPlanar</span><span class="p">,</span>  <span class="c1">// planar or interleaved image</span>
 150      <span class="k">typename</span> <span class="n">A</span><span class="o">=</span><span class="n">std</span><span class="o">::</span><span class="n">allocator</span><span class="o">&lt;</span><span class="kt">unsigned</span> <span class="kt">char</span><span class="o">&gt;</span>
 151  <span class="o">&gt;</span>
 152 <span class="k">class</span> <span class="nc">image</span><span class="p">;</span>
 153 </pre></div>
 154 </div>
 155 <p>The image constructor takes an alignment parameter which allows for
 156 constructing images that are word-aligned or 8-byte aligned. The alignment is
 157 specified in bytes. The default value for alignment is 0, which means there is
 158 no padding at the end of rows. Many operations are faster using such
 159 1D-traversable images, because <code class="docutils literal"><span class="pre">image_view::x_iterator</span></code> can be used to
 160 traverse the pixels, instead of the more complicated <code class="docutils literal"><span class="pre">image_view::iterator</span></code>.
 161 Note that when alignment is 0, packed images are aligned to the bit - i.e.
 162 there are no padding bits at the end of rows of packed images.</p>
 163 </div>
 164 </div>
 165
 166
 167     <div class="navbar" style="text-align:right;">
 168
 169
 170       <a class="prev" title="Image View" href="image_view.html"><img src="../_static/prev.png" alt="prev"/></a>
 171       <a class="up" title="Design Guide" href="index.html"><img src="../_static/up.png" alt="up"/></a>
 172       <a class="next" title="Dynamic images and image views" href="dynamic_image.html"><img src="../_static/next.png" alt="next"/></a>
 173
 174     </div>
 175     </div>
 176     <div class="footer" role="contentinfo">
 177       Last updated on 2019-12-10 00:12:10.
 178       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
 179     </div>
 180   </body>
 181 </html>