libs/gil/doc/html/io.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>IO extensions - 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="next" title="ToolBox extension" href="toolbox.html" />
  27     <link rel="prev" title="Affine region detectors" href="image_processing/affine-region-detectors.html" />
  28   </head>
  29   <body>
  30     <div class="header">
  31     <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  32     "header">
  33       <tr>
  34         <td valign="top" width="300">
  35           <h3><a href="index.html"><img
  36           alt="C++ Boost" src="_static/gil.png" border="0"></a></h3>
  37         </td>
  38
  39         <td >
  40           <h1 align="center"><a href="index.html"></a></h1>
  41         </td>
  42         <td>
  43       <div id="searchbox" style="display: none">
  44         <form class="search" action="search.html" method="get">
  45           <input type="text" name="q" size="18" />
  46           <input type="submit" value="Search" />
  47           <input type="hidden" name="check_keywords" value="yes" />
  48           <input type="hidden" name="area" value="default" />
  49         </form>
  50       </div>
  51       <script type="text/javascript">$('#searchbox').show(0);</script>
  52         </td>
  53       </tr>
  54     </table>
  55     </div>
  56     <hr/>
  57     <div class="content">
  58     <div class="navbar" style="text-align:right;">
  59
  60
  61       <a class="prev" title="Affine region detectors" href="image_processing/affine-region-detectors.html"><img src="_static/prev.png" alt="prev"/></a>
  62       <a class="next" title="ToolBox extension" href="toolbox.html"><img src="_static/next.png" alt="next"/></a>
  63
  64     </div>
  65
  66   <div class="section" id="io-extensions">
  67 <h1>IO extensions</h1>
  68 <div class="section" id="overview">
  69 <h2>Overview</h2>
  70 <p>This extension to boost::gil provides an easy to use interface for reading and
  71 writing various image formats. It also includes a framework for adding
  72 new formats.</p>
  73 <p>Please see section 3.3 for all supported image formats. A basic tutorial is
  74 provided in section [link gil.io.tutorial Tutorial].
  75 Also, this extension requires Boost version 1.42 and up.
  76 Furthermore the GIL extension Toolbox is used.</p>
  77 <p>For adding new image formats please refer to section
  78 [link gil.io.using_io.extending_gil__io_with_new_formats Extending GIL::IO with new Formats].</p>
  79 </div>
  80 <div class="section" id="supported-platforms">
  81 <h2>Supported Platforms</h2>
  82 <p>All platforms supported by Boost which have a decent C++ compiler.
  83 Depending on the image format one or more of the following image
  84 libraries might be needed:</p>
  85 <ul class="simple">
  86 <li>libtiff</li>
  87 <li>libjpeg</li>
  88 <li>libpng</li>
  89 <li>libraw</li>
  90 <li>zlib</li>
  91 </ul>
  92 <p>The library is designed to support as many formats as required by the user.
  93 For instance, if the user only needs bmp support none of the above mentioned
  94 dependencies are required.</p>
  95 <p>There are more details available in this documentation on the image format
  96 dependencies. Please see section
  97 [link gil.io.using_io.supported_image_formats Supported Image Formats].</p>
  98 </div>
  99 <div class="section" id="tutorial">
 100 <h2>Tutorial</h2>
 101 <p>Thanks to modern C++ programming techniques the interface for this library
 102 is rather small and easy to use. In this tutorial I&#8217;ll give you a short
 103 walk-around on how to use this boost::gil extension.
 104 For more details please refer to section 3.</p>
 105 <p>For each supported IO format a single top-level header file is provided.
 106 For instance, include <cite>boost/gil/extension/io/tiff.hpp</cite> to be able
 107 to read or write TIFF files.</p>
 108 <div class="section" id="reading-an-image">
 109 <h3>Reading An Image</h3>
 110 <p>Probably the most common case to read a tiff image can be done as follows:</p>
 111 <div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">filename</span><span class="p">(</span> <span class="s">&quot;image.tif&quot;</span> <span class="p">);</span>
 112 <span class="n">rgb8_image_t</span> <span class="n">img</span><span class="p">;</span>
 113 <span class="n">read_image</span><span class="p">(</span> <span class="n">filename</span><span class="p">,</span> <span class="n">img</span><span class="p">,</span> <span class="n">tiff_tag</span><span class="p">()</span> <span class="p">);</span>
 114 </pre></div>
 115 </div>
 116 <p>The code would be same for all other image formats. The only thing that needs
 117 to change is the tag type ( tiff_tag ) in the read_image call.
 118 The read_image() expects the supplied image type to be compatible with the
 119 image stored in the file. If the user doesn&#8217;t know what format an image has she
 120 can use read_and_convert_image().
 121 Another important fact is that read_image() will allocate the appropriate
 122 memory needed for the read operation. There are <code class="docutils literal"><span class="pre">read_view</span></code> or
 123 <code class="docutils literal"><span class="pre">read_and_convert_view</span></code> counterparts, if the memory is already allocated.</p>
 124 <p>Sometimes the user only wants to read a sub-part of an image,
 125 then the above call would look as follows:</p>
 126 <div class="highlight-c++"><div class="highlight"><pre><span class="n">read_image</span><span class="p">(</span> <span class="n">filename</span>
 127           <span class="p">,</span> <span class="n">img</span>
 128           <span class="p">,</span> <span class="n">image_read_settings</span><span class="o">&lt;</span> <span class="n">tiff_tag</span> <span class="o">&gt;</span><span class="p">(</span> <span class="n">point_t</span><span class="p">(</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span> <span class="p">),</span> <span class="n">point_t</span><span class="p">(</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span> <span class="p">)</span> <span class="p">)</span>
 129           <span class="p">);</span>
 130 </pre></div>
 131 </div>
 132 <p>The image_read_settings class will provide the user with image format
 133 independent reading setting but can also serves as a pointer for format
 134 dependent settings.
 135 Please see the specific image format sections
 136 [link gil.io.using_io.supported_image_formats Supported Image Formats]
 137 for more details.</p>
 138 </div>
 139 <div class="section" id="writing-an-image">
 140 <h3>Writing An Image</h3>
 141 <p>Besides reading the information also writing is the second part of this
 142 Boost.GIL extension. Writing is a lot simpler than reading since an existing
 143 image view contains all the information.</p>
 144 <p>For instance writing an image can be done as follows:</p>
 145 <div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">filename</span><span class="p">(</span> <span class="s">&quot;image.tif&quot;</span> <span class="p">);</span>
 146 <span class="n">rgb8_image_t</span> <span class="nf">img</span><span class="p">(</span> <span class="mi">640</span><span class="p">,</span> <span class="mi">480</span> <span class="p">);</span>
 147
 148 <span class="c1">// write data into image</span>
 149
 150 <span class="n">write_view</span><span class="p">(</span> <span class="n">filename</span>
 151           <span class="p">,</span> <span class="n">view</span><span class="p">(</span> <span class="n">img</span> <span class="p">)</span>
 152           <span class="p">,</span> <span class="n">tiff_tag</span><span class="p">()</span>
 153           <span class="p">);</span>
 154 </pre></div>
 155 </div>
 156 <p>The interface is similar to reading an image. To add image format specific
 157 parameter the user can use <code class="docutils literal"><span class="pre">image_write_info</span></code> class.
 158 For instance, a user can specify the JPEG quality when writing like this:</p>
 159 <div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">filename</span><span class="p">(</span> <span class="s">&quot;image.jpg&quot;</span> <span class="p">);</span>
 160 <span class="n">rgb8_image_t</span> <span class="nf">img</span><span class="p">(</span> <span class="mi">640</span><span class="p">,</span> <span class="mi">480</span> <span class="p">);</span>
 161
 162 <span class="c1">// write data into image</span>
 163
 164 <span class="n">write_view</span><span class="p">(</span> <span class="n">filename</span>
 165           <span class="p">,</span> <span class="n">view</span><span class="p">(</span> <span class="n">img</span> <span class="p">)</span>
 166           <span class="p">,</span> <span class="n">image_write_info</span><span class="o">&lt;</span> <span class="n">jpeg_tag</span> <span class="o">&gt;</span><span class="p">(</span> <span class="mi">95</span> <span class="p">)</span>
 167           <span class="p">);</span>
 168 </pre></div>
 169 </div>
 170 <p>The above example will write an image where the jpeg quality is
 171 set to 95 percent.</p>
 172 </div>
 173 <div class="section" id="reading-and-writing-in-memory-buffers">
 174 <h3>Reading And Writing In-Memory Buffers</h3>
 175 <p>Reading and writing in-memory buffers are supported as well. See as follows:</p>
 176 <div class="highlight-c++"><div class="highlight"><pre><span class="c1">// 1. Read an image.</span>
 177 <span class="n">ifstream</span> <span class="nf">in</span><span class="p">(</span> <span class="s">&quot;test.tif&quot;</span><span class="p">,</span> <span class="n">ios</span><span class="o">::</span><span class="n">binary</span> <span class="p">);</span>
 178
 179 <span class="n">rgb8_image_t</span> <span class="n">img</span><span class="p">;</span>
 180 <span class="n">read_image</span><span class="p">(</span> <span class="n">in</span><span class="p">,</span> <span class="n">img</span><span class="p">,</span> <span class="n">tiff_tag</span><span class="p">()</span> <span class="p">);</span>
 181
 182 <span class="c1">// 2. Write image to in-memory buffer.</span>
 183 <span class="n">stringstream</span> <span class="nf">out_buffer</span><span class="p">(</span> <span class="n">ios_base</span><span class="o">::</span><span class="n">out</span> <span class="o">|</span> <span class="n">ios_base</span><span class="o">::</span><span class="n">binary</span> <span class="p">);</span>
 184
 185 <span class="n">rgb8_image_t</span> <span class="n">src</span><span class="p">;</span>
 186 <span class="n">write_view</span><span class="p">(</span> <span class="n">out_buffer</span><span class="p">,</span> <span class="n">view</span><span class="p">(</span> <span class="n">src</span> <span class="p">),</span> <span class="n">tiff_tag</span><span class="p">()</span> <span class="p">);</span>
 187
 188 <span class="c1">// 3. Copy in-memory buffer to another.</span>
 189 <span class="n">stringstream</span> <span class="nf">in_buffer</span><span class="p">(</span> <span class="n">ios_base</span><span class="o">::</span><span class="n">in</span> <span class="o">|</span> <span class="n">ios_base</span><span class="o">::</span><span class="n">binary</span> <span class="p">);</span>
 190 <span class="n">in_buffer</span> <span class="o">&lt;&lt;</span> <span class="n">out_buffer</span><span class="p">.</span><span class="n">rdbuf</span><span class="p">();</span>
 191
 192 <span class="c1">// 4. Read in-memory buffer to gil image</span>
 193 <span class="n">rgb8_image_t</span> <span class="n">dst</span><span class="p">;</span>
 194 <span class="n">read_image</span><span class="p">(</span> <span class="n">in_buffer</span><span class="p">,</span> <span class="n">dst</span><span class="p">,</span> <span class="n">tag_t</span><span class="p">()</span> <span class="p">);</span>
 195
 196 <span class="c1">// 5. Write out image.</span>
 197 <span class="n">string</span> <span class="nf">filename</span><span class="p">(</span> <span class="s">&quot;out.tif&quot;</span> <span class="p">);</span>
 198 <span class="n">ofstream</span> <span class="nf">out</span><span class="p">(</span> <span class="n">filename</span><span class="p">.</span><span class="n">c_str</span><span class="p">(),</span> <span class="n">ios_base</span><span class="o">::</span><span class="n">binary</span> <span class="p">);</span>
 199 <span class="n">write_view</span><span class="p">(</span> <span class="n">out</span><span class="p">,</span> <span class="n">view</span><span class="p">(</span> <span class="n">dst</span> <span class="p">),</span> <span class="n">tiff_tag</span><span class="p">()</span> <span class="p">);</span>
 200 </pre></div>
 201 </div>
 202 <p>In case the user is using his own stream classes he has to make sure it
 203 has the common interface read, write, seek, close, etc. Interface.</p>
 204 </div>
 205 </div>
 206 <div class="section" id="using-io">
 207 <h2>Using IO</h2>
 208 <div class="section" id="general-overview">
 209 <h3>General Overview</h3>
 210 <p>The tutorial pointed out some use cases for reading and writing images in
 211 various image formats. This section will provide a more thorough overview.</p>
 212 <p>The next sections will introduce the Read and Write interface. But it might be
 213 worth pointing out that by using some advanced metaprogramming techniques the
 214 interface is rather small and hopefully easy to understand.</p>
 215 <p>Besides the general interface the user also has the ability to interface
 216 directly with the underlying image format. For that each reader or writer
 217 provides access to the so-called backend.</p>
 218 <p>For instance:</p>
 219 <div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">get_reader_backend</span><span class="o">&lt;</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span>
 220                           <span class="p">,</span> <span class="n">tag_t</span>
 221                           <span class="o">&gt;::</span><span class="n">type</span> <span class="n">backend_t</span><span class="p">;</span>
 222
 223 <span class="n">backend_t</span> <span class="n">backend</span> <span class="o">=</span> <span class="n">read_image_info</span><span class="p">(</span> <span class="n">bmp_filename</span>
 224                                    <span class="p">,</span> <span class="n">tag_t</span><span class="p">()</span>
 225                                    <span class="p">);</span>
 226
 227 <span class="n">BOOST_CHECK_EQUAL</span><span class="p">(</span> <span class="n">backend</span><span class="p">.</span><span class="n">_info</span><span class="p">.</span><span class="n">_width</span> <span class="p">,</span> <span class="mi">127</span> <span class="p">);</span>
 228 <span class="n">BOOST_CHECK_EQUAL</span><span class="p">(</span> <span class="n">backend</span><span class="p">.</span><span class="n">_info</span><span class="p">.</span><span class="n">_height</span><span class="p">,</span> <span class="mi">64</span> <span class="p">);</span>
 229 </pre></div>
 230 </div>
 231 <p>Of course, the typedef can be removed when using c++11&#8217;s auto feature.</p>
 232 </div>
 233 <div class="section" id="read-interface">
 234 <h3>Read Interface</h3>
 235 <p>As the Tutorial demonstrated there are a few ways to read images.
 236 Here is an enumeration of all read functions with a short description:</p>
 237 <ul class="simple">
 238 <li><code class="docutils literal"><span class="pre">read_image</span></code> - read into a gil image with no conversion.
 239 Memory is allocated.</li>
 240 <li><code class="docutils literal"><span class="pre">read_view</span></code> - read into a gil view with no conversion.</li>
 241 <li><code class="docutils literal"><span class="pre">read_and_convert_image</span></code> - read and convert into a gil image.
 242 Memory is allocated.</li>
 243 <li><code class="docutils literal"><span class="pre">read_and_convert_view</span></code> - read and convert into a gil view.</li>
 244 <li><code class="docutils literal"><span class="pre">read_image_info</span></code> - read the image header.</li>
 245 </ul>
 246 <p>Conversion in this context is necessary if the source (file) has an
 247 incompatible color space with the destination (gil image type).
 248 If that&#8217;s the case the user has to use the xxx_and_convert_xxx variants.</p>
 249 <p>All functions take the filename or a device as the first parameter.
 250 The filename can be anything from a C-string, <code class="docutils literal"><span class="pre">std::string</span></code>,
 251 <code class="docutils literal"><span class="pre">std::wstring</span></code> and <code class="docutils literal"><span class="pre">boost::filesystem</span></code> path. When using the path
 252 object the user needs to define the ADD_FS_PATH_SUPPORT compiler symbol to
 253 include the boost::filesystem dependency.
 254 Devices could be a <code class="docutils literal"><span class="pre">FILE*</span></code>, <code class="docutils literal"><span class="pre">std::ifstream</span></code>, and <code class="docutils literal"><span class="pre">TIFF*</span></code> for TIFF images.</p>
 255 <p>The second parameter is either an image or view type depending on the
 256 <code class="docutils literal"><span class="pre">read_xxx</span></code> function.
 257 The third and last parameter is either an instance of the
 258 <code class="docutils literal"><span class="pre">image_read_settings&lt;FormatTag&gt;</span></code> or just the <code class="docutils literal"><span class="pre">FormatTag</span></code>.
 259 The settings can be various depending on the format which is being read.
 260 But the all share settings for reading a partial image area.
 261 The first point describes the top left image coordinate whereas the second
 262 are the dimensions in x and y directions.</p>
 263 <p>Here an example of setting up partial read:</p>
 264 <div class="highlight-c++"><div class="highlight"><pre><span class="n">read_image</span><span class="p">(</span> <span class="n">filename</span>
 265           <span class="p">,</span> <span class="n">img</span>
 266           <span class="p">,</span> <span class="n">image_read_settings</span><span class="o">&lt;</span> <span class="n">tiff_tag</span> <span class="o">&gt;</span><span class="p">(</span> <span class="n">point_t</span><span class="p">(</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span> <span class="p">),</span> <span class="n">point_t</span><span class="p">(</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span> <span class="p">)</span> <span class="p">)</span>
 267           <span class="p">);</span>
 268 </pre></div>
 269 </div>
 270 <p>Each format supports reading just the header information,
 271 using <code class="docutils literal"><span class="pre">read_image_info</span></code>. Please refer to the format specific sections
 272 under 3.3. A basic example follows:</p>
 273 <div class="highlight-c++"><div class="highlight"><pre><span class="n">image_read_info</span><span class="o">&lt;</span> <span class="n">tiff_t</span> <span class="o">&gt;</span> <span class="n">info</span> <span class="o">=</span> <span class="n">read_image_info</span><span class="p">(</span> <span class="n">filename</span>
 274                                                 <span class="p">,</span> <span class="n">tiff_t</span><span class="p">()</span>
 275                                                 <span class="p">);</span>
 276 </pre></div>
 277 </div>
 278 <p>GIL also comes with a dynamic image extension.
 279 In the context of GIL.IO a user can define an <code class="docutils literal"><span class="pre">any_image</span></code> type based on
 280 several image types. The IO extension would then pick the matching image type
 281 to the current image file.
 282 The following example shows this feature:</p>
 283 <div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector</span><span class="o">&lt;</span> <span class="n">gray8_image_t</span>
 284                    <span class="p">,</span> <span class="n">gray16_image_t</span>
 285                    <span class="p">,</span> <span class="n">rgb8_image_t</span>
 286                    <span class="p">,</span> <span class="n">rgba_image_t</span>
 287                    <span class="o">&gt;</span> <span class="n">my_img_types</span><span class="p">;</span>
 288
 289 <span class="n">any_image</span><span class="o">&lt;</span> <span class="n">my_img_types</span> <span class="o">&gt;</span> <span class="n">runtime_image</span><span class="p">;</span>
 290
 291 <span class="n">read_image</span><span class="p">(</span> <span class="n">filename</span>
 292           <span class="p">,</span> <span class="n">runtime_image</span>
 293           <span class="p">,</span> <span class="n">tiff_tag</span><span class="p">()</span>
 294           <span class="p">);</span>
 295 </pre></div>
 296 </div>
 297 <p>During the review it became clear that there is a need to read big images
 298 scanline by scanline. To support such use case a <code class="docutils literal"><span class="pre">scanline_reader</span></code> is
 299 implemented for all supported image formats.
 300 The <code class="docutils literal"><span class="pre">scanline_read_iterators</span></code> will then allow to traverse through the image.
 301 The following code sample shows the usage:</p>
 302 <div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">tiff_tag</span> <span class="n">tag_t</span><span class="p">;</span>
 303
 304 <span class="k">typedef</span> <span class="n">scanline_reader</span><span class="o">&lt;</span> <span class="k">typename</span> <span class="n">get_read_device</span><span class="o">&lt;</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span>
 305                                                  <span class="p">,</span> <span class="n">tag_t</span>
 306                                                  <span class="o">&gt;::</span><span class="n">type</span>
 307                         <span class="p">,</span> <span class="n">tag_t</span>
 308                         <span class="o">&gt;</span> <span class="n">reader_t</span><span class="p">;</span>
 309
 310 <span class="n">reader_t</span> <span class="n">reader</span> <span class="o">=</span> <span class="n">make_scanline_reader</span><span class="p">(</span> <span class="s">&quot;C:/boost/libs/gil/test/extension/io/images/tiff/test.tif&quot;</span><span class="p">,</span> <span class="n">tag_t</span><span class="p">()</span> <span class="p">);</span>
 311
 312 <span class="k">typedef</span> <span class="n">rgba8_image_t</span> <span class="n">image_t</span><span class="p">;</span>
 313
 314 <span class="n">image_t</span> <span class="nf">dst</span><span class="p">(</span> <span class="n">reader</span><span class="p">.</span><span class="n">_info</span><span class="p">.</span><span class="n">_width</span><span class="p">,</span> <span class="n">reader</span><span class="p">.</span><span class="n">_info</span><span class="p">.</span><span class="n">_height</span> <span class="p">);</span>
 315 <span class="n">fill_pixels</span><span class="p">(</span> <span class="n">view</span><span class="p">(</span><span class="n">dst</span><span class="p">),</span> <span class="n">image_t</span><span class="o">::</span><span class="n">value_type</span><span class="p">()</span> <span class="p">);</span>
 316
 317 <span class="k">typedef</span> <span class="n">reader_t</span><span class="o">::</span><span class="n">iterator_t</span> <span class="n">iterator_t</span><span class="p">;</span>
 318
 319 <span class="n">iterator_t</span> <span class="n">it</span>  <span class="o">=</span> <span class="n">reader</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
 320 <span class="n">iterator_t</span> <span class="n">end</span> <span class="o">=</span> <span class="n">reader</span><span class="p">.</span><span class="n">end</span><span class="p">();</span>
 321
 322 <span class="k">for</span><span class="p">(</span> <span class="kt">int</span> <span class="n">row</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">it</span> <span class="o">!=</span> <span class="n">end</span><span class="p">;</span> <span class="o">++</span><span class="n">it</span><span class="p">,</span> <span class="o">++</span><span class="n">row</span> <span class="p">)</span>
 323 <span class="p">{</span>
 324     <span class="n">copy_pixels</span><span class="p">(</span> <span class="n">interleaved_view</span><span class="p">(</span> <span class="n">reader</span><span class="p">.</span><span class="n">_info</span><span class="p">.</span><span class="n">_width</span>
 325                                     <span class="p">,</span> <span class="mi">1</span>
 326                                     <span class="p">,</span> <span class="p">(</span> <span class="n">image_t</span><span class="o">::</span><span class="n">view_t</span><span class="o">::</span><span class="n">x_iterator</span> <span class="p">)</span> <span class="o">*</span><span class="n">it</span>
 327                                     <span class="p">,</span> <span class="n">reader</span><span class="p">.</span><span class="n">_scanline_length</span>
 328                                     <span class="p">)</span>
 329                 <span class="p">,</span> <span class="n">subimage_view</span><span class="p">(</span> <span class="n">view</span><span class="p">(</span> <span class="n">dst</span> <span class="p">)</span>
 330                                 <span class="p">,</span> <span class="mi">0</span>
 331                                 <span class="p">,</span> <span class="n">row</span>
 332                                 <span class="p">,</span> <span class="n">reader</span><span class="p">.</span><span class="n">_info</span><span class="p">.</span><span class="n">_width</span>
 333                                 <span class="p">,</span> <span class="mi">1</span>
 334                                 <span class="p">)</span>
 335                 <span class="p">);</span>
 336 <span class="p">}</span>
 337 </pre></div>
 338 </div>
 339 <p>There are many ways to traverse an image but for as of now only by
 340 scanline is supported.</p>
 341 </div>
 342 <div class="section" id="write-interface">
 343 <h3>Write Interface</h3>
 344 <p>There is only one function for writing out images, write_view.
 345 Similar to reading the first parameter is either a filename or a device.
 346 The filename can be anything from a C-string, <code class="docutils literal"><span class="pre">std::string</span></code>,
 347 <code class="docutils literal"><span class="pre">std::wstring</span></code>, and <code class="docutils literal"><span class="pre">boost::filesystem</span></code> path. When using the path object
 348 the user needs to define the <code class="docutils literal"><span class="pre">ADD_FS_PATH_SUPPORT</span></code> compiler symbol to
 349 include the <code class="docutils literal"><span class="pre">boost::filesystem</span></code> dependency.
 350 Devices could be <code class="docutils literal"><span class="pre">FILE*</span></code>, <code class="docutils literal"><span class="pre">std::ifstream</span></code>, and <code class="docutils literal"><span class="pre">TIFF*</span></code> for TIFF images.</p>
 351 <p>The second parameter is an view object to image being written.
 352 The third and last parameter is either a tag or an
 353 <code class="docutils literal"><span class="pre">image_write_info&lt;FormatTag&gt;</span></code> object containing more settings.
 354 One example for instance is the JPEG quality.
 355 Refer to the format specific sections under 3.3. to have a list of all
 356 the possible settings.</p>
 357 <p>Writing an any_image&lt;...&gt; is supported. See the following example:</p>
 358 <div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="n">mpl</span><span class="o">::</span><span class="n">vector</span><span class="o">&lt;</span> <span class="n">gray8_image_t</span>
 359                    <span class="p">,</span> <span class="n">gray16_image_t</span>
 360                    <span class="p">,</span> <span class="n">rgb8_image_t</span>
 361                    <span class="p">,</span> <span class="n">rgba_image_t</span>
 362                    <span class="o">&gt;</span> <span class="n">my_img_types</span><span class="p">;</span>
 363
 364
 365 <span class="n">any_image</span><span class="o">&lt;</span> <span class="n">my_img_types</span> <span class="o">&gt;</span> <span class="n">runtime_image</span><span class="p">;</span>
 366
 367 <span class="c1">// fill any_image</span>
 368
 369 <span class="n">write_view</span><span class="p">(</span> <span class="n">filename</span>
 370           <span class="p">,</span> <span class="n">view</span><span class="p">(</span> <span class="n">runtime_image</span> <span class="p">)</span>
 371           <span class="p">,</span> <span class="n">tiff_tag</span><span class="p">()</span>
 372           <span class="p">);</span>
 373 </pre></div>
 374 </div>
 375 </div>
 376 <div class="section" id="compiler-symbols">
 377 <h3>Compiler Symbols</h3>
 378 <p>The following table gives an overview of all supported compiler symbols
 379 that can be set by the user:</p>
 380 <table border="1" class="docutils">
 381 <colgroup>
 382 <col width="34%" />
 383 <col width="66%" />
 384 </colgroup>
 385 <thead valign="bottom">
 386 <tr class="row-odd"><th class="head">Symbol</th>
 387 <th class="head">Description</th>
 388 </tr>
 389 </thead>
 390 <tbody valign="top">
 391 <tr class="row-even"><td>BOOST_GIL_IO_ENABLE_GRAY_ALPHA</td>
 392 <td>Enable the color space &#8220;gray_alpha&#8221;.</td>
 393 </tr>
 394 <tr class="row-odd"><td>BOOST_GIL_IO_ADD_FS_PATH_SUPPORT</td>
 395 <td>Enable boost::filesystem 3.0 library.</td>
 396 </tr>
 397 <tr class="row-even"><td>BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED</td>
 398 <td>Use libpng in floating point mode. This symbol is incompatible with BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED.</td>
 399 </tr>
 400 <tr class="row-odd"><td>BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED</td>
 401 <td>Use libpng in integer mode. This symbol is incompatible with BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED.</td>
 402 </tr>
 403 <tr class="row-even"><td>BOOST_GIL_IO_PNG_DITHERING_SUPPORTED</td>
 404 <td>Look up &#8220;dithering&#8221; in libpng manual for explanation.</td>
 405 </tr>
 406 <tr class="row-odd"><td>BOOST_GIL_IO_PNG_1_4_OR_LOWER</td>
 407 <td>Allow compiling with libpng 1.4 or lower.</td>
 408 </tr>
 409 <tr class="row-even"><td>BOOST_GIL_EXTENSION_IO_JPEG_C_LIB_COMPILED_AS_CPLUSPLUS</td>
 410 <td>libjpeg is compiled as c++ lib.</td>
 411 </tr>
 412 <tr class="row-odd"><td>BOOST_GIL_EXTENSION_IO_PNG_C_LIB_COMPILED_AS_CPLUSPLUS</td>
 413 <td>libpng is compiled as c++ lib.</td>
 414 </tr>
 415 <tr class="row-even"><td>BOOST_GIL_EXTENSION_IO_TIFF_C_LIB_COMPILED_AS_CPLUSPLUS</td>
 416 <td>libtiff is compiled as c++ lib.</td>
 417 </tr>
 418 <tr class="row-odd"><td>BOOST_GIL_EXTENSION_IO_ZLIB_C_LIB_COMPILED_AS_CPLUSPLUS</td>
 419 <td>zlib is compiled as c++ lib.</td>
 420 </tr>
 421 <tr class="row-even"><td>BOOST_GIL_IO_TEST_ALLOW_READING_IMAGES</td>
 422 <td>Allow basic test images to be read from local hard drive. The paths can be set in paths.hpp</td>
 423 </tr>
 424 <tr class="row-odd"><td>BOOST_GIL_IO_TEST_ALLOW_WRITING_IMAGES</td>
 425 <td>Allow images to be written to the local hard drive. The paths can be set in paths.hpp</td>
 426 </tr>
 427 <tr class="row-even"><td>BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES</td>
 428 <td>Run tests using the bmp test images suite. See _BMP_TEST_FILES</td>
 429 </tr>
 430 <tr class="row-odd"><td>BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES</td>
 431 <td>Run tests using the png test images suite. See _PNG_TEST_FILES</td>
 432 </tr>
 433 <tr class="row-even"><td>BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES</td>
 434 <td>Run tests using the pnm test images suite. Send me an email for accessing the files.</td>
 435 </tr>
 436 <tr class="row-odd"><td>BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES</td>
 437 <td>Run tests using the targa file format test images suite. See _TARGA_TEST_FILES</td>
 438 </tr>
 439 <tr class="row-even"><td>BOOST_GIL_IO_USE_TIFF_LIBTIFF_TEST_SUITE_IMAGES</td>
 440 <td>Run tests using the targa file format test images suite. See _TIFF_LIB_TIFF_TEST_FILES</td>
 441 </tr>
 442 <tr class="row-odd"><td>BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES</td>
 443 <td>Run tests using the targa file format test images suite. See _TIFF_GRAPHICSMAGICK_TEST_FILES</td>
 444 </tr>
 445 </tbody>
 446 </table>
 447 </div>
 448 <div class="section" id="supported-image-formats">
 449 <h3>Supported Image Formats</h3>
 450 <div class="section" id="bmp">
 451 <h4>BMP</h4>
 452 <p>For a general overview of the BMP image file format go to the
 453 following <a class="reference external" href="http://en.wikipedia.org/wiki/BMP_file_format">BMP_Wiki</a>.</p>
 454 <p>Please note, the code has not been tested on X Windows System variations
 455 of the BMP format which are usually referred to XBM and XPM formats.</p>
 456 <p>Here, only the MS Windows and OS/2 format is relevant.</p>
 457 <p>Currently the code is able to read and write the following image types:</p>
 458 <table class="docutils field-list" frame="void" rules="none">
 459 <col class="field-name" />
 460 <col class="field-body" />
 461 <tbody valign="top">
 462 <tr class="field-odd field"><th class="field-name">Read:</th><td class="field-body"><code class="docutils literal"><span class="pre">gray1_image_t</span></code>, <code class="docutils literal"><span class="pre">gray4_image_t</span></code>, <code class="docutils literal"><span class="pre">gray8_image_t</span></code>, <code class="docutils literal"><span class="pre">rgb8_image_t</span></code> and, <code class="docutils literal"><span class="pre">rgba8_image_t</span></code></td>
 463 </tr>
 464 <tr class="field-even field"><th class="field-name">Write:</th><td class="field-body"><code class="docutils literal"><span class="pre">rgb8_image_t</span></code> and, <code class="docutils literal"><span class="pre">rgba8_image_t</span></code></td>
 465 </tr>
 466 </tbody>
 467 </table>
 468 <p>The lack of having an indexed image type in gil restricts the current
 469 interface to only write out non-indexed images.
 470 This is subject to change soon.</p>
 471 </div>
 472 <div class="section" id="jpeg">
 473 <h4>JPEG</h4>
 474 <p>For a general overview of the JPEG image file format go to the
 475 following <a class="reference external" href="http://en.wikipedia.org/wiki/JPEG">JPEG_Wiki</a>.</p>
 476 <p>This jpeg extension is based on the libjpeg library which can be
 477 found here, <a class="reference external" href="http://www.ijg.org/">JPEG_Lib</a>.</p>
 478 <p>All versions starting from 8x are supported.</p>
 479 <p>The user has to make sure this library is properly installed.
 480 I strongly recommend the user to build the library yourself.
 481 It could potentially save you a lot of trouble.</p>
 482 <p>Currently the code is able to read and write the following image types:</p>
 483 <table class="docutils field-list" frame="void" rules="none">
 484 <col class="field-name" />
 485 <col class="field-body" />
 486 <tbody valign="top">
 487 <tr class="field-odd field"><th class="field-name">Read:</th><td class="field-body"><code class="docutils literal"><span class="pre">gray8_image_t</span></code>, <code class="docutils literal"><span class="pre">rgb8_image_t</span></code>, <code class="docutils literal"><span class="pre">cmyk8_image_t</span></code></td>
 488 </tr>
 489 <tr class="field-even field"><th class="field-name">Write:</th><td class="field-body"><code class="docutils literal"><span class="pre">gray8_image_t</span></code>, <code class="docutils literal"><span class="pre">rgb8_image_t</span></code>, <code class="docutils literal"><span class="pre">cmyk8_image_t</span></code></td>
 490 </tr>
 491 </tbody>
 492 </table>
 493 <p>Reading YCbCr or YCCK images is possible but might result in inaccuracies since
 494 both color spaces aren&#8217;t available yet for gil.
 495 For now these color space are read as rgb images.
 496 This is subject to change soon.</p>
 497 </div>
 498 <div class="section" id="png">
 499 <h4>PNG</h4>
 500 <p>For a general overview of the PNG image file format go to the
 501 following <a class="reference external" href="http://en.wikipedia.org/wiki/Portable_Network_Graphics">PNG_Wiki</a>.</p>
 502 <p>This png extension is based on the libpng, which can be found
 503 here, <a class="reference external" href="http://libpng.org/pub/png/libpng.html">PNG_Lib</a>.</p>
 504 <p>All versions starting from 1.5.x are supported.</p>
 505 <p>The user has to make sure this library is properly installed.
 506 I strongly recommend the user to build the library yourself.
 507 It could potentially save you a lot of trouble.</p>
 508 <p>Currently the code is able to read and write the following image types:</p>
 509 <table class="docutils field-list" frame="void" rules="none">
 510 <col class="field-name" />
 511 <col class="field-body" />
 512 <tbody valign="top">
 513 <tr class="field-odd field"><th class="field-name">Read:</th><td class="field-body">gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8, rgb16, rgba8, rgba16</td>
 514 </tr>
 515 <tr class="field-even field"><th class="field-name">Write:</th><td class="field-body">gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8, rgb16, rgba8, rgba16</td>
 516 </tr>
 517 </tbody>
 518 </table>
 519 <p>For reading gray_alpha images the user has to compile application with <code class="docutils literal"><span class="pre">BOOST_GIL_IO_ENABLE_GRAY_ALPHA</span></code>
 520 macro  defined. This color space is defined in the toolbox by using <code class="docutils literal"><span class="pre">gray_alpha.hpp</span></code>.</p>
 521 </div>
 522 <div class="section" id="pnm">
 523 <h4>PNM</h4>
 524 <p>For a general overview of the PNM image file format go to the
 525 following <a class="reference external" href="http://en.wikipedia.org/wiki/Portable_anymap">PNM_Wiki</a>. No external library is needed for the pnm format.</p>
 526 <p>The extension can read images in both flavours of the formats, ASCII and binary,
 527 that is types from P1 through P6; can write only binary formats.</p>
 528 <p>Currently the code is able to read and write the following image types:</p>
 529 <table class="docutils field-list" frame="void" rules="none">
 530 <col class="field-name" />
 531 <col class="field-body" />
 532 <tbody valign="top">
 533 <tr class="field-odd field"><th class="field-name">Read:</th><td class="field-body">gray1, gray8, rgb8</td>
 534 </tr>
 535 <tr class="field-even field"><th class="field-name">Write:</th><td class="field-body">gray1, gray8, rgb8</td>
 536 </tr>
 537 </tbody>
 538 </table>
 539 <p>When reading a mono text image the data is read as a gray8 image.</p>
 540 </div>
 541 <div class="section" id="raw">
 542 <h4>RAW</h4>
 543 <p>For a general overview see <a class="reference external" href="http://en.wikipedia.org/wiki/Raw_image_format">RAW_Wiki</a>.</p>
 544 <p>Currently the extension is only able to read rgb8 images.</p>
 545 </div>
 546 <div class="section" id="targa">
 547 <h4>TARGA</h4>
 548 <p>For a general overview of the BMP image file format go to the
 549 following <a class="reference external" href="http://en.wikipedia.org/wiki/Truevision_TGA">TARGA_Wiki</a>.</p>
 550 <p>Currently the code is able to read and write the following image types:</p>
 551 <table class="docutils field-list" frame="void" rules="none">
 552 <col class="field-name" />
 553 <col class="field-body" />
 554 <tbody valign="top">
 555 <tr class="field-odd field"><th class="field-name">Read:</th><td class="field-body">rgb8_image_t and rgba8_image_t</td>
 556 </tr>
 557 <tr class="field-even field"><th class="field-name">Write:</th><td class="field-body">rgb8_image_t and rgba8_image_t</td>
 558 </tr>
 559 </tbody>
 560 </table>
 561 <p>The lack of having an indexed image type in gil restricts the current
 562 interface to only write out non-indexed images.
 563 This is subject to change soon.</p>
 564 </div>
 565 <div class="section" id="tiff">
 566 <h4>TIFF</h4>
 567 <p>For a general overview of the TIFF image file format go to the
 568 following <a class="reference external" href="http://en.wikipedia.org/wiki/Tagged_Image_File_Format">TIFF_Wiki</a>.</p>
 569 <p>This tiff extension is based on the libtiff, which can be found, <a class="reference external" href="http://www.remotesensing.org/libtiff/">TIFF_Lib</a>.</p>
 570 <p>All versions starting from 3.9.x are supported.</p>
 571 <p>The user has to make sure this library is properly installed. I strongly
 572 recommend the user to build the library yourself. It could potentially
 573 save you a lot of trouble.</p>
 574 <p>TIFF images can virtually encode all kinds of channel sizes representing
 575 various color spaces. Even planar images are possible.
 576 For instance, <code class="docutils literal"><span class="pre">rbg323</span></code> or <code class="docutils literal"><span class="pre">gray7</span></code>. The channels also can have specific
 577 formats, like integer values or floating point values.</p>
 578 <p>For a complete set of options please consult the following websites:</p>
 579 <ul class="simple">
 580 <li><a class="reference external" href="http://www.awaresystems.be/imaging/tiff/tifftags/baseline.html">TIFF_Base_Tags</a></li>
 581 <li><a class="reference external" href="http://www.awaresystems.be/imaging/tiff/tifftags/extension.html">TIFF_Extension_Tags</a></li>
 582 </ul>
 583 <p>The author of this extension is not claiming all tiff formats are supported.
 584 This extension is likely to be a moving target adding new features with each
 585 new milestone. Here is an incomplete lists:</p>
 586 <ul class="simple">
 587 <li>Multi-page TIFF - read only</li>
 588 <li>Strip TIFF - read and write support</li>
 589 <li>Tiled TIFF - read and write support with user defined tiled sizes</li>
 590 <li>Bit images TIFF - fully supported, like <code class="docutils literal"><span class="pre">gray1_image_t</span></code> (minisblack)</li>
 591 <li>Planar TIFF - fully supported</li>
 592 <li>Floating-point TIFF - fully supported</li>
 593 <li>Palette TIFF - supported but no indexed image type is available as of now</li>
 594 </ul>
 595 <p>This gil extension uses two different test image suites to test read and
 596 write capabilities. See <code class="docutils literal"><span class="pre">test_image</span></code> folder.
 597 It&#8217;s advisable to use ImageMagick test viewer to display images.</p>
 598 </div>
 599 </div>
 600 <div class="section" id="extending-gil-io-with-new-formats">
 601 <h3>Extending GIL::IO with new Formats</h3>
 602 <p>Extending the gil::io with new formats is meant to be simple and
 603 straightforward. Before adding I would recommend to have a look at existing
 604 implementations and then trying to follow a couple of guidelines:</p>
 605 <ul>
 606 <li><dl class="first docutils">
 607 <dt>Create the following files for your new xxx format</dt>
 608 <dd><ul class="first last simple">
 609 <li><code class="docutils literal"><span class="pre">xxx_read.hpp</span></code> - Only includes read code</li>
 610 <li><code class="docutils literal"><span class="pre">xxx_write.hpp</span></code> - Only includes write code</li>
 611 <li><code class="docutils literal"><span class="pre">xxx_all.hpp</span></code> - includes xxx_read.hpp and xxx_write.hpp</li>
 612 </ul>
 613 </dd>
 614 </dl>
 615 </li>
 616 <li><p class="first">Add the code to the <code class="docutils literal"><span class="pre">boost::gil::detail</span></code> namespace</p>
 617 </li>
 618 <li><p class="first">Create a tag type for the new format. Like this:</p>
 619 <div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="nl">xxx_tag</span> <span class="p">:</span> <span class="n">format_tag</span> <span class="p">{};</span>
 620 </pre></div>
 621 </div>
 622 </li>
 623 <li><p class="first">Create the image_read_info for the new format. It contains all the
 624 information that are necessary to read an image. It should be filled
 625 and returned by the <code class="docutils literal"><span class="pre">get_info</span></code> member of the reader class. See below:</p>
 626 <div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o">&lt;&gt;</span> <span class="k">struct</span> <span class="n">image_read_info</span><span class="o">&lt;</span> <span class="n">xxx_tag</span> <span class="o">&gt;</span> <span class="p">{};</span>
 627 </pre></div>
 628 </div>
 629 </li>
 630 <li><p class="first">Create the image_write_info for the new format. It contains all the
 631 information that are necessary to write an image:</p>
 632 <div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o">&lt;&gt;</span> <span class="k">struct</span> <span class="n">image_write_info</span><span class="o">&lt;</span> <span class="n">xxx_tag</span> <span class="o">&gt;</span> <span class="p">{};</span>
 633 </pre></div>
 634 </div>
 635 </li>
 636 <li><p class="first">Use the following reader skeleton as a start:</p>
 637 <div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o">&lt;</span> <span class="k">typename</span> <span class="n">Device</span>
 638         <span class="p">,</span> <span class="k">typename</span> <span class="n">ConversionPolicy</span>
 639         <span class="o">&gt;</span>
 640 <span class="k">class</span> <span class="nc">reader</span><span class="o">&lt;</span> <span class="n">Device</span>
 641             <span class="p">,</span> <span class="n">xxx_tag</span>
 642             <span class="p">,</span> <span class="n">ConversionPolicy</span>
 643             <span class="o">&gt;</span>
 644             <span class="o">:</span> <span class="k">public</span> <span class="n">reader_base</span><span class="o">&lt;</span> <span class="n">xxx_tag</span>
 645                                 <span class="p">,</span> <span class="n">ConversionPolicy</span>
 646                                 <span class="o">&gt;</span>
 647 <span class="p">{</span>
 648 <span class="k">private</span><span class="o">:</span>
 649
 650     <span class="k">typedef</span> <span class="k">typename</span> <span class="n">ConversionPolicy</span><span class="o">::</span><span class="n">color_converter_type</span> <span class="n">cc_t</span><span class="p">;</span>
 651
 652 <span class="k">public</span><span class="o">:</span>
 653
 654     <span class="n">reader</span><span class="p">(</span> <span class="n">Device</span><span class="o">&amp;</span> <span class="n">device</span> <span class="p">)</span>
 655     <span class="o">:</span> <span class="n">_io_dev</span><span class="p">(</span> <span class="n">device</span> <span class="p">)</span>
 656     <span class="p">{}</span>
 657
 658     <span class="n">reader</span><span class="p">(</span> <span class="n">Device</span><span class="o">&amp;</span>     <span class="n">device</span>
 659           <span class="p">,</span> <span class="k">const</span> <span class="n">cc_t</span><span class="o">&amp;</span> <span class="n">cc</span>
 660           <span class="p">)</span>
 661     <span class="o">:</span> <span class="n">_io_dev</span><span class="p">(</span> <span class="n">device</span> <span class="p">)</span>
 662     <span class="p">,</span> <span class="n">reader_base</span><span class="o">&lt;</span> <span class="n">xxx_tag</span>
 663                  <span class="p">,</span> <span class="n">ConversionPolicy</span>
 664                  <span class="o">&gt;</span><span class="p">(</span> <span class="n">cc</span> <span class="p">)</span>
 665     <span class="p">{}</span>
 666
 667     <span class="n">image_read_info</span><span class="o">&lt;</span> <span class="n">xxx_tag</span> <span class="o">&gt;</span> <span class="n">get_info</span><span class="p">()</span>
 668     <span class="p">{</span>
 669         <span class="c1">// your implementation here</span>
 670     <span class="p">}</span>
 671
 672     <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>
 673     <span class="kt">void</span> <span class="n">apply</span><span class="p">(</span> <span class="k">const</span> <span class="n">View</span><span class="o">&amp;</span> <span class="n">dst_view</span> <span class="p">)</span>
 674     <span class="p">{</span>
 675         <span class="c1">// your implementation here</span>
 676     <span class="p">}</span>
 677 <span class="p">};</span>
 678 </pre></div>
 679 </div>
 680 </li>
 681 <li><p class="first">The writer skeleton:</p>
 682 <div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o">&lt;</span> <span class="k">typename</span> <span class="n">Device</span> <span class="o">&gt;</span>
 683 <span class="k">class</span> <span class="nc">writer</span><span class="o">&lt;</span> <span class="n">Device</span>
 684             <span class="p">,</span> <span class="n">xxx_tag</span>
 685             <span class="o">&gt;</span>
 686 <span class="p">{</span>
 687 <span class="k">public</span><span class="o">:</span>
 688
 689     <span class="n">writer</span><span class="p">(</span> <span class="n">Device</span> <span class="o">&amp;</span> <span class="n">file</span> <span class="p">)</span>
 690     <span class="o">:</span> <span class="n">out</span><span class="p">(</span><span class="n">file</span><span class="p">)</span>
 691     <span class="p">{}</span>
 692
 693     <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>
 694     <span class="kt">void</span> <span class="n">apply</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>
 695     <span class="p">{</span>
 696         <span class="c1">// your implementation here</span>
 697     <span class="p">}</span>
 698
 699     <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>
 700     <span class="kt">void</span> <span class="n">apply</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>
 701               <span class="p">,</span> <span class="k">const</span> <span class="n">image_write_info</span><span class="o">&lt;</span> <span class="n">xxx_tag</span> <span class="o">&gt;&amp;</span> <span class="n">info</span> <span class="p">)</span>
 702     <span class="p">{</span>
 703         <span class="c1">// your implementation here</span>
 704     <span class="p">}</span>
 705 <span class="p">};</span>
 706 </pre></div>
 707 </div>
 708 </li>
 709 </ul>
 710 </div>
 711 </div>
 712 <div class="section" id="running-gil-io-tests">
 713 <h2>Running gil::io tests</h2>
 714 <p>gil::io comes with a large suite of test cases which reads and writes various
 715 file formats. It uses some test image suites which can be found online or
 716 which can be demanded from me by sending me an email.</p>
 717 <p>There are some test images created by me in the test folder.
 718 To enable unit tests which make use of them set the following compiler options
 719 <code class="docutils literal"><span class="pre">BOOST_GIL_IO_TEST_ALLOW_READING_IMAGES</span></code> and
 720 <code class="docutils literal"><span class="pre">BOOST_GIL_IO_TEST_ALLOW_WRITING_IMAGES</span></code>.</p>
 721 <p>The following list provides all links to the image suites the compiler symbol
 722 to enable the tests:</p>
 723 <table class="docutils field-list" frame="void" rules="none">
 724 <col class="field-name" />
 725 <col class="field-body" />
 726 <tbody valign="top">
 727 <tr class="field-odd field"><th class="field-name">BMP:</th><td class="field-body"><a class="reference external" href="http://entropymine.com/jason/bmpsuite/">BMP_TEST_FILES</a>                 &#8211; BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES</td>
 728 </tr>
 729 <tr class="field-even field"><th class="field-name">PNG:</th><td class="field-body"><a class="reference external" href="http://www.schaik.com/pngsuite/pngsuite.html">PNG_TEST_FILES</a>                 &#8211; BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES</td>
 730 </tr>
 731 <tr class="field-odd field"><th class="field-name">PNM:</th><td class="field-body">request files from me           &#8211; BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES</td>
 732 </tr>
 733 <tr class="field-even field"><th class="field-name">TARGA:</th><td class="field-body"><a class="reference external" href="http://www.fileformat.info/format/tga/sample/index.htm">TARGA_TEST_FILES</a>               &#8211; BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES</td>
 734 </tr>
 735 <tr class="field-odd field"><th class="field-name">TIFF:</th><td class="field-body"><a class="reference external" href="http://www.remotesensing.org/libtiff/images.html">TIFF_LIB_TIFF_TEST_FILES</a>       &#8211; BOOST_GIL_IO_USE_TIFF_LIBTIFF_TEST_SUITE_IMAGES</td>
 736 </tr>
 737 <tr class="field-even field"><th class="field-name">TIFF:</th><td class="field-body"><a class="reference external" href="ftp://ftp.graphicsmagick.org/pub/tiff-samples/tiff-sample-images-be.tar.gz">TIFF_GRAPHICSMAGICK_TEST_FILES</a> &#8211; BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES</td>
 738 </tr>
 739 </tbody>
 740 </table>
 741 </div>
 742 </div>
 743
 744
 745     <div class="navbar" style="text-align:right;">
 746
 747
 748       <a class="prev" title="Affine region detectors" href="image_processing/affine-region-detectors.html"><img src="_static/prev.png" alt="prev"/></a>
 749       <a class="next" title="ToolBox extension" href="toolbox.html"><img src="_static/next.png" alt="next"/></a>
 750
 751     </div>
 752     </div>
 753     <div class="footer" role="contentinfo">
 754       Last updated on 2019-12-10 00:12:10.
 755       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
 756     </div>
 757   </body>
 758 </html>