libs/gil/io/doc/html/gil/io/using_io.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Using IO</title>
   5 <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.GIL.IO">
   8 <link rel="up" href="../../index.html" title="Chapter&#160;1.&#160;Boost.GIL.IO">
   9 <link rel="prev" href="tutorial.html" title="Tutorial">
  10 <link rel="next" href="running_gil__io_tests.html" title="Running gil::io tests">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="tutorial.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="running_gil__io_tests.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section gil_io_using_io">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="gil.io.using_io"></a><a class="link" href="using_io.html" title="Using IO">Using IO</a>
  28 </h2></div></div></div>
  29 <h3>
  30 <a name="gil.io.using_io.h0"></a>
  31       <span class="phrase"><a name="gil.io.using_io.general_overview"></a></span><a class="link" href="using_io.html#gil.io.using_io.general_overview">General
  32       Overview</a>
  33     </h3>
  34 <p>
  35       The tutorial pointed out some use cases for reading and writing images in various
  36       image formats. This section will provide a more thorough overview.
  37     </p>
  38 <p>
  39       The next sections will introduce the Read and Write interface. But it might
  40       be worth poiting out that by using some advanced metaprogramming techniques
  41       the interface is rather small and hopefully easy to understand.
  42     </p>
  43 <p>
  44       Besides the general interface the user also has the ability to interface directly
  45       with the underlying image format. For that each reader or writer provides access
  46       to the so-called backend. For instance:
  47     </p>
  48 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">get_reader_backend</span><span class="special">&lt;</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span>
  49                           <span class="special">,</span> <span class="identifier">tag_t</span>
  50                           <span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">backend_t</span><span class="special">;</span>
  51
  52 <span class="identifier">backend_t</span> <span class="identifier">backend</span> <span class="special">=</span> <span class="identifier">read_image_info</span><span class="special">(</span> <span class="identifier">bmp_filename</span>
  53                                    <span class="special">,</span> <span class="identifier">tag_t</span><span class="special">()</span>
  54                                    <span class="special">);</span>
  55
  56 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span> <span class="identifier">backend</span><span class="special">.</span><span class="identifier">_info</span><span class="special">.</span><span class="identifier">_width</span> <span class="special">,</span> <span class="number">127</span> <span class="special">);</span>
  57 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span> <span class="identifier">backend</span><span class="special">.</span><span class="identifier">_info</span><span class="special">.</span><span class="identifier">_height</span><span class="special">,</span> <span class="number">64</span> <span class="special">);</span>
  58 </pre>
  59 <p>
  60       Of course, the typedef can be removed when using c++11's auto feature.
  61     </p>
  62 <h3>
  63 <a name="gil.io.using_io.h1"></a>
  64       <span class="phrase"><a name="gil.io.using_io.read_interface"></a></span><a class="link" href="using_io.html#gil.io.using_io.read_interface">Read
  65       Interface</a>
  66     </h3>
  67 <p>
  68       As the Tutorial demonstrated there are a few ways to read images. Here is an
  69       enumeration of all read functions with a short description:
  70     </p>
  71 <pre class="programlisting"><span class="special">*</span> <span class="identifier">read_image</span> <span class="special">-</span> <span class="identifier">read</span> <span class="identifier">into</span> <span class="identifier">a</span> <span class="identifier">gil</span> <span class="identifier">image</span> <span class="identifier">with</span> <span class="identifier">no</span> <span class="identifier">conversion</span><span class="special">.</span> <span class="identifier">Memory</span> <span class="identifier">is</span> <span class="identifier">allocated</span><span class="special">.</span>
  72 <span class="special">*</span> <span class="identifier">read_view</span>  <span class="special">-</span> <span class="identifier">read</span> <span class="identifier">into</span> <span class="identifier">a</span> <span class="identifier">gil</span> <span class="identifier">view</span> <span class="identifier">with</span> <span class="identifier">no</span> <span class="identifier">conversion</span><span class="special">.</span>
  73 <span class="special">*</span> <span class="identifier">read_and_convert_image</span> <span class="special">-</span> <span class="identifier">read</span> <span class="keyword">and</span> <span class="identifier">convert</span> <span class="identifier">into</span> <span class="identifier">a</span> <span class="identifier">gil</span> <span class="identifier">image</span><span class="special">.</span> <span class="identifier">Memory</span> <span class="identifier">is</span> <span class="identifier">allocated</span><span class="special">.</span>
  74 <span class="special">*</span> <span class="identifier">read_and_convert_view</span>  <span class="special">-</span> <span class="identifier">read</span> <span class="keyword">and</span> <span class="identifier">convert</span> <span class="identifier">into</span> <span class="identifier">a</span> <span class="identifier">gil</span> <span class="identifier">view</span><span class="special">.</span>
  75 <span class="special">*</span> <span class="identifier">read_image_info</span> <span class="special">-</span> <span class="identifier">read</span> <span class="identifier">the</span> <span class="identifier">image</span> <span class="identifier">header</span><span class="special">.</span>
  76 </pre>
  77 <p>
  78       Conversion in this context is necessary if the source ( file ) has an incompatible
  79       color space with the destination ( gil image type ). If that's the case the
  80       user has to use the xxx_and_convert_xxx variants.
  81     </p>
  82 <p>
  83       All functions take the filename or a device as the first parameter. The filename
  84       can be anything from a c string, std::string, std::wstring, and a boost::filesystem
  85       path. When using the path object the user needs to define the ADD_FS_PATH_SUPPORT
  86       compiler symbol to include the boost::filesystem dependency. Devices could
  87       be a FILE*, std::ifstream, and a TIFF* for TIFF images.
  88     </p>
  89 <p>
  90       The second parameter is either an image or view type depending on the read_xxx
  91       function. The third and last parameter is either an instance of the image_read_settings&lt;FormatTag&gt;
  92       or just the FormatTag. The settings can be various depending on the format
  93       which is being read. But the all share settings for reading a partial image
  94       area. The first point describes the top left image coordinate whereas the second
  95       are the dimensions in x and y directions. Here an example of setting up partial
  96       read.
  97     </p>
  98 <pre class="programlisting"><span class="identifier">read_image</span><span class="special">(</span> <span class="identifier">filename</span>
  99           <span class="special">,</span> <span class="identifier">img</span>
 100           <span class="special">,</span> <span class="identifier">image_read_settings</span><span class="special">&lt;</span> <span class="identifier">tiff_tag</span> <span class="special">&gt;(</span> <span class="identifier">point_t</span><span class="special">(</span> <span class="number">0</span><span class="special">,</span> <span class="number">0</span> <span class="special">),</span> <span class="identifier">point_t</span><span class="special">(</span> <span class="number">50</span><span class="special">,</span> <span class="number">50</span> <span class="special">)</span> <span class="special">)</span>
 101           <span class="special">);</span>
 102 </pre>
 103 <p>
 104       Each format supports reading just the header information, using read_image_info().
 105       Please refer to the format specific sections under 3.3. A basic example follows:
 106     </p>
 107 <pre class="programlisting"><span class="identifier">image_read_info</span><span class="special">&lt;</span> <span class="identifier">tiff_t</span> <span class="special">&gt;</span> <span class="identifier">info</span> <span class="special">=</span> <span class="identifier">read_image_info</span><span class="special">(</span> <span class="identifier">filename</span>
 108                                                 <span class="special">,</span> <span class="identifier">tiff_t</span><span class="special">()</span>
 109                                                 <span class="special">);</span>
 110 </pre>
 111 <p>
 112       GIL also comes with a dynamic image extension. In the context of GIL.IO a user
 113       can define an any_image type based on several image types. The IO extension
 114       would then pick the matching image type to the current image file. The following
 115       example shows this feature:
 116     </p>
 117 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="identifier">gray8_image_t</span>
 118                    <span class="special">,</span> <span class="identifier">gray16_image_t</span>
 119                    <span class="special">,</span> <span class="identifier">rgb8_image_t</span>
 120                    <span class="special">,</span> <span class="identifier">rgba_image_t</span>
 121                    <span class="special">&gt;</span> <span class="identifier">my_img_types</span><span class="special">;</span>
 122
 123 <span class="identifier">any_image</span><span class="special">&lt;</span> <span class="identifier">my_img_types</span> <span class="special">&gt;</span> <span class="identifier">runtime_image</span><span class="special">;</span>
 124
 125 <span class="identifier">read_image</span><span class="special">(</span> <span class="identifier">filename</span>
 126           <span class="special">,</span> <span class="identifier">runtime_image</span>
 127           <span class="special">,</span> <span class="identifier">tiff_tag</span><span class="special">()</span>
 128           <span class="special">);</span>
 129 </pre>
 130 <p>
 131       During the review it became clear that there is a need to read big images scanline
 132       by scanline. To support such use case a scanline_reader is implemented for
 133       all supported image formats. The scanline_read_iterators will then allow to
 134       traverse through the image. The following code sample shows the usage:
 135     </p>
 136 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">tiff_tag</span> <span class="identifier">tag_t</span><span class="special">;</span>
 137
 138 <span class="keyword">typedef</span> <span class="identifier">scanline_reader</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">get_read_device</span><span class="special">&lt;</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span>
 139                                                  <span class="special">,</span> <span class="identifier">tag_t</span>
 140                                                  <span class="special">&gt;::</span><span class="identifier">type</span>
 141                         <span class="special">,</span> <span class="identifier">tag_t</span>
 142                         <span class="special">&gt;</span> <span class="identifier">reader_t</span><span class="special">;</span>
 143
 144 <span class="identifier">reader_t</span> <span class="identifier">reader</span> <span class="special">=</span> <span class="identifier">make_scanline_reader</span><span class="special">(</span> <span class="string">"C:/boost/libs/gil/io/test_images/tiff/test.tif"</span><span class="special">,</span> <span class="identifier">tag_t</span><span class="special">()</span> <span class="special">);</span>
 145
 146 <span class="keyword">typedef</span> <span class="identifier">rgba8_image_t</span> <span class="identifier">image_t</span><span class="special">;</span>
 147
 148 <span class="identifier">image_t</span> <span class="identifier">dst</span><span class="special">(</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">_info</span><span class="special">.</span><span class="identifier">_width</span><span class="special">,</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">_info</span><span class="special">.</span><span class="identifier">_height</span> <span class="special">);</span>
 149 <span class="identifier">fill_pixels</span><span class="special">(</span> <span class="identifier">view</span><span class="special">(</span><span class="identifier">dst</span><span class="special">),</span> <span class="identifier">image_t</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">()</span> <span class="special">);</span>
 150
 151 <span class="keyword">typedef</span> <span class="identifier">reader_t</span><span class="special">::</span><span class="identifier">iterator_t</span> <span class="identifier">iterator_t</span><span class="special">;</span>
 152
 153 <span class="identifier">iterator_t</span> <span class="identifier">it</span>  <span class="special">=</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
 154 <span class="identifier">iterator_t</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>
 155
 156 <span class="keyword">for</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">row</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">,</span> <span class="special">++</span><span class="identifier">row</span> <span class="special">)</span>
 157 <span class="special">{</span>
 158     <span class="identifier">copy_pixels</span><span class="special">(</span> <span class="identifier">interleaved_view</span><span class="special">(</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">_info</span><span class="special">.</span><span class="identifier">_width</span>
 159                                     <span class="special">,</span> <span class="number">1</span>
 160                                     <span class="special">,</span> <span class="special">(</span> <span class="identifier">image_t</span><span class="special">::</span><span class="identifier">view_t</span><span class="special">::</span><span class="identifier">x_iterator</span> <span class="special">)</span> <span class="special">*</span><span class="identifier">it</span>
 161                                     <span class="special">,</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">_scanline_length</span>
 162                                     <span class="special">)</span>
 163                 <span class="special">,</span> <span class="identifier">subimage_view</span><span class="special">(</span> <span class="identifier">view</span><span class="special">(</span> <span class="identifier">dst</span> <span class="special">)</span>
 164                                 <span class="special">,</span> <span class="number">0</span>
 165                                 <span class="special">,</span> <span class="identifier">row</span>
 166                                 <span class="special">,</span> <span class="identifier">reader</span><span class="special">.</span><span class="identifier">_info</span><span class="special">.</span><span class="identifier">_width</span>
 167                                 <span class="special">,</span> <span class="number">1</span>
 168                                 <span class="special">)</span>
 169                 <span class="special">);</span>
 170 <span class="special">}</span>
 171 </pre>
 172 <p>
 173       There are many ways to travese an image but for as of now only by scanline
 174       is supported.
 175     </p>
 176 <h3>
 177 <a name="gil.io.using_io.h2"></a>
 178       <span class="phrase"><a name="gil.io.using_io.write_interface"></a></span><a class="link" href="using_io.html#gil.io.using_io.write_interface">Write
 179       Interface</a>
 180     </h3>
 181 <p>
 182       There is only one function for writing out images, write_view. Similar to reading
 183       the first parameter is either a filename or a device. The filename can be anything
 184       from a c string, std::string, std::wstring, and a boost::filesystem path. When
 185       using the path object the user needs to define the ADD_FS_PATH_SUPPORT compiler
 186       symbol to include the boost::filesystem dependency. Devices could be a FILE*,
 187       std::ifstream, and a TIFF* for TIFF images.
 188     </p>
 189 <p>
 190       The second parameter is an view object to image being written. The third and
 191       last parameter is either a tag or an image_write_info&lt; FormatTag &gt; object
 192       containing more settings. One example for instance is the jpeg quality. Refer
 193       to the format specific sections under 3.3. to have a list of all the possible
 194       settings.
 195     </p>
 196 <p>
 197       Writing an any_image&lt;...&gt; is supported. See the following example:
 198     </p>
 199 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="identifier">gray8_image_t</span>
 200                    <span class="special">,</span> <span class="identifier">gray16_image_t</span>
 201                    <span class="special">,</span> <span class="identifier">rgb8_image_t</span>
 202                    <span class="special">,</span> <span class="identifier">rgba_image_t</span>
 203                    <span class="special">&gt;</span> <span class="identifier">my_img_types</span><span class="special">;</span>
 204
 205
 206 <span class="identifier">any_image</span><span class="special">&lt;</span> <span class="identifier">my_img_types</span> <span class="special">&gt;</span> <span class="identifier">runtime_image</span><span class="special">;</span>
 207
 208 <span class="comment">// fill any_image </span>
 209
 210 <span class="identifier">write_view</span><span class="special">(</span> <span class="identifier">filename</span>
 211           <span class="special">,</span> <span class="identifier">view</span><span class="special">(</span> <span class="identifier">runtime_image</span> <span class="special">)</span>
 212           <span class="special">,</span> <span class="identifier">tiff_tag</span><span class="special">()</span>
 213           <span class="special">);</span>
 214 </pre>
 215 <h3>
 216 <a name="gil.io.using_io.h3"></a>
 217       <span class="phrase"><a name="gil.io.using_io.compiler_symbols"></a></span><a class="link" href="using_io.html#gil.io.using_io.compiler_symbols">Compiler
 218       Symbols</a>
 219     </h3>
 220 <p>
 221       The following table gives an overview of all supported compiler symbols that
 222       can be set by the user:
 223     </p>
 224 <div class="table">
 225 <a name="gil.io.using_io.t0"></a><p class="title"><b>Table&#160;1.1.&#160;Compiler Symbols</b></p>
 226 <div class="table-contents"><table class="table" summary="Compiler Symbols">
 227 <colgroup>
 228 <col>
 229 <col>
 230 </colgroup>
 231 <thead><tr>
 232 <th>
 233               <p>
 234                 Symbol
 235               </p>
 236             </th>
 237 <th>
 238               <p>
 239                 Description
 240               </p>
 241             </th>
 242 </tr></thead>
 243 <tbody>
 244 <tr>
 245 <td>
 246               <p>
 247                 BOOST_GIL_IO_ENABLE_GRAY_ALPHA
 248               </p>
 249             </td>
 250 <td>
 251               <p>
 252                 Enable the color space "gray_alpha".
 253               </p>
 254             </td>
 255 </tr>
 256 <tr>
 257 <td>
 258               <p>
 259                 BOOST_GIL_IO_ADD_FS_PATH_SUPPORT
 260               </p>
 261             </td>
 262 <td>
 263               <p>
 264                 Enable boost::filesystem 3.0 library.
 265               </p>
 266             </td>
 267 </tr>
 268 <tr>
 269 <td>
 270               <p>
 271                 BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED
 272               </p>
 273             </td>
 274 <td>
 275               <p>
 276                 Use libpng in floating point mode. This symbol is incompatible with
 277                 BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED.
 278               </p>
 279             </td>
 280 </tr>
 281 <tr>
 282 <td>
 283               <p>
 284                 BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED
 285               </p>
 286             </td>
 287 <td>
 288               <p>
 289                 Use libpng in integer mode. This symbol is incompatible with BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED.
 290               </p>
 291             </td>
 292 </tr>
 293 <tr>
 294 <td>
 295               <p>
 296                 BOOST_GIL_EXTENSION_IO_JPEG_C_LIB_COMPILED_AS_CPLUSPLUS
 297               </p>
 298             </td>
 299 <td>
 300               <p>
 301                 libjpeg is compiled as c++ lib.
 302               </p>
 303             </td>
 304 </tr>
 305 <tr>
 306 <td>
 307               <p>
 308                 BOOST_GIL_EXTENSION_IO_PNG_C_LIB_COMPILED_AS_CPLUSPLUS
 309               </p>
 310             </td>
 311 <td>
 312               <p>
 313                 libpng is compiled as c++ lib.
 314               </p>
 315             </td>
 316 </tr>
 317 <tr>
 318 <td>
 319               <p>
 320                 BOOST_GIL_EXTENSION_IO_RAW_C_LIB_COMPILED_AS_CPLUSPLUS
 321               </p>
 322             </td>
 323 <td>
 324               <p>
 325                 libraw is compiled as c++ lib.
 326               </p>
 327             </td>
 328 </tr>
 329 <tr>
 330 <td>
 331               <p>
 332                 BOOST_GIL_EXTENSION_IO_TIFF_C_LIB_COMPILED_AS_CPLUSPLUS
 333               </p>
 334             </td>
 335 <td>
 336               <p>
 337                 libtiff is compiled as c++ lib.
 338               </p>
 339             </td>
 340 </tr>
 341 <tr>
 342 <td>
 343               <p>
 344                 BOOST_GIL_IO_TEST_ALLOW_READING_IMAGES
 345               </p>
 346             </td>
 347 <td>
 348               <p>
 349                 Allow basic test images to be read from local hard drive. The paths
 350                 can be set in paths.hpp
 351               </p>
 352             </td>
 353 </tr>
 354 <tr>
 355 <td>
 356               <p>
 357                 BOOST_GIL_IO_TEST_ALLOW_WRITING_IMAGES
 358               </p>
 359             </td>
 360 <td>
 361               <p>
 362                 Allow images to be written to the local hard drive. The paths can
 363                 be set in paths.hpp
 364               </p>
 365             </td>
 366 </tr>
 367 <tr>
 368 <td>
 369               <p>
 370                 BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES
 371               </p>
 372             </td>
 373 <td>
 374               <p>
 375                 Run tests using the bmp test images suite. See <a href="http://entropymine.com/jason/bmpsuite/" target="_top">http://entropymine.com/jason/bmpsuite/</a>
 376               </p>
 377             </td>
 378 </tr>
 379 <tr>
 380 <td>
 381               <p>
 382                 BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES
 383               </p>
 384             </td>
 385 <td>
 386               <p>
 387                 Run tests using the png test images suite. See <a href="http://www.schaik.com/pngsuite/pngsuite.html" target="_top">http://www.schaik.com/pngsuite/pngsuite.html</a>
 388               </p>
 389             </td>
 390 </tr>
 391 <tr>
 392 <td>
 393               <p>
 394                 BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES
 395               </p>
 396             </td>
 397 <td>
 398               <p>
 399                 Run tests using the pnm test images suite. Send me an email for accessing
 400                 the files.
 401               </p>
 402             </td>
 403 </tr>
 404 <tr>
 405 <td>
 406               <p>
 407                 BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES
 408               </p>
 409             </td>
 410 <td>
 411               <p>
 412                 Run tests using the targa file format test images suite. See <a href="http://www.fileformat.info/format/tga/sample/index.htm" target="_top">http://www.fileformat.info/format/tga/sample/index.htm</a>
 413               </p>
 414             </td>
 415 </tr>
 416 <tr>
 417 <td>
 418               <p>
 419                 BOOST_GIL_IO_USE_TIFF_LIBTIFF_TEST_SUITE_IMAGES
 420               </p>
 421             </td>
 422 <td>
 423               <p>
 424                 Run tests using the targa file format test images suite. See <a href="http://www.remotesensing.org/libtiff/images.html" target="_top">http://www.remotesensing.org/libtiff/images.html</a>
 425               </p>
 426             </td>
 427 </tr>
 428 <tr>
 429 <td>
 430               <p>
 431                 BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES
 432               </p>
 433             </td>
 434 <td>
 435               <p>
 436                 Run tests using the targa file format test images suite. See <a href="ftp://ftp.graphicsmagick.org/pub/tiff-samples/tiff-sample-images-be.tar.gz" target="_top">ftp://ftp.graphicsmagick.org/pub/tiff-samples/tiff-sample-images-be.tar.gz</a>
 437               </p>
 438             </td>
 439 </tr>
 440 </tbody>
 441 </table></div>
 442 </div>
 443 <br class="table-break"><h3>
 444 <a name="gil.io.using_io.h4"></a>
 445       <span class="phrase"><a name="gil.io.using_io.supported_image_formats"></a></span><a class="link" href="using_io.html#gil.io.using_io.supported_image_formats">Supported
 446       Image Formats</a>
 447     </h3>
 448 <h4>
 449 <a name="gil.io.using_io.h5"></a>
 450       <span class="phrase"><a name="gil.io.using_io.bmp"></a></span><a class="link" href="using_io.html#gil.io.using_io.bmp">BMP</a>
 451     </h4>
 452 <p>
 453       For a general overview of the BMP image file format go to the following <a href="http://en.wikipedia.org/wiki/BMP_file_format" target="_top">http://en.wikipedia.org/wiki/BMP_file_format</a>.
 454     </p>
 455 <p>
 456       Please note, the code has not been tested on X Windows System variations of
 457       the BMP format which are usually referred to XBM and XPM formats.
 458     </p>
 459 <p>
 460       Here, only the MS Windows and OS/2 format is relevant.
 461     </p>
 462 <p>
 463       Currently the code is able to read and write the following image types:
 464     </p>
 465 <p>
 466       Read: gray1_image_t, gray4_image_t, gray8_image_t, rgb8_image_t and, rgba8_image_t
 467       Write: rgb8_image_t and, rgba8_image_t
 468     </p>
 469 <p>
 470       The lack of having an indexed image type in gil restricts the current interface
 471       to only write out non-indexed images. This is subject to change soon.
 472     </p>
 473 <h4>
 474 <a name="gil.io.using_io.h6"></a>
 475       <span class="phrase"><a name="gil.io.using_io.jpeg"></a></span><a class="link" href="using_io.html#gil.io.using_io.jpeg">JPEG</a>
 476     </h4>
 477 <p>
 478       For a general overview of the JPEG image file format go to the following <a href="http://en.wikipedia.org/wiki/JPEG" target="_top">http://en.wikipedia.org/wiki/JPEG</a>.
 479     </p>
 480 <p>
 481       This jpeg extension is based on the libjpeg library which can be found here,
 482       <span class="underline">JPEG_Lib</span>.
 483     </p>
 484 <p>
 485       The user has to make sure this library is properly installed. I strongly recommend
 486       the user to build the library yourself. It could potentially save you a lot
 487       of trouble.
 488     </p>
 489 <p>
 490       Currently the code is able to read and write the following image types:
 491     </p>
 492 <p>
 493       Read: gray8_image_t, rgb8_image_t, cmyk8_image_t Write: gray8_image_t, rgb8_image_t,
 494       cmyk8_image_t
 495     </p>
 496 <p>
 497       Reading YCbCr or YCCK images is possible but might result in inaccuracies since
 498       both color spaces aren't available yet for gil. For now these color space are
 499       read as rgb images. This is subject to change soon.
 500     </p>
 501 <h4>
 502 <a name="gil.io.using_io.h7"></a>
 503       <span class="phrase"><a name="gil.io.using_io.png"></a></span><a class="link" href="using_io.html#gil.io.using_io.png">PNG</a>
 504     </h4>
 505 <p>
 506       For a general overview of the PNG image file format go to the following <a href="http://en.wikipedia.org/wiki/Portable_Network_Graphics" target="_top">http://en.wikipedia.org/wiki/Portable_Network_Graphics</a>.
 507     </p>
 508 <p>
 509       This png extension is based on the libpng, which can be found here, _PNG_Lib.
 510     </p>
 511 <p>
 512       The user has to make sure this library is properly installed. I strongly recommend
 513       the user to build the library yourself. It could potentially save you a lot
 514       of trouble.
 515     </p>
 516 <p>
 517       Currently the code is able to read and write the following image types:
 518     </p>
 519 <p>
 520       Read: gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8,
 521       rgb16, rgba8, rgba16 Write: gray1, gray2, gray4, gray8, gray16, gray_alpha_8,
 522       gray_alpha_16, rgb8, rgb16, rgba8, rgba16
 523     </p>
 524 <p>
 525       For reading gray_alpha images the user has to enable the ENABLE_GRAY_ALPHA
 526       compiler switch. This color space is defined in the toolbox by using gray_alpha.hpp.
 527     </p>
 528 <h4>
 529 <a name="gil.io.using_io.h8"></a>
 530       <span class="phrase"><a name="gil.io.using_io.pnm"></a></span><a class="link" href="using_io.html#gil.io.using_io.pnm">PNM</a>
 531     </h4>
 532 <p>
 533       For a general overview of the PNM image file format go to the following <a href="http://en.wikipedia.org/wiki/Portable_anymap" target="_top">http://en.wikipedia.org/wiki/Portable_anymap</a>.
 534     </p>
 535 <p>
 536       No external library is needed for the pnm format. Both ascii and binary formats
 537       are supported.
 538     </p>
 539 <p>
 540       Currently the code is able to read and write the following image types:
 541     </p>
 542 <p>
 543       Read: gray1, gray8, rgb8 Write: gray1, gray8, rgb8
 544     </p>
 545 <p>
 546       When reading a mono text image the data is read as a gray8 image.
 547     </p>
 548 <h4>
 549 <a name="gil.io.using_io.h9"></a>
 550       <span class="phrase"><a name="gil.io.using_io.raw"></a></span><a class="link" href="using_io.html#gil.io.using_io.raw">RAW</a>
 551     </h4>
 552 <p>
 553       For a general overview see _RAW_Wiki.
 554     </p>
 555 <p>
 556       Currently the extension is only able to read rgb8 images.
 557     </p>
 558 <h4>
 559 <a name="gil.io.using_io.h10"></a>
 560       <span class="phrase"><a name="gil.io.using_io.targa"></a></span><a class="link" href="using_io.html#gil.io.using_io.targa">TARGA</a>
 561     </h4>
 562 <p>
 563       For a general overview of the BMP image file format go to the following <span class="underline">TARGA_Wiki</span>.
 564     </p>
 565 <p>
 566       Currently the code is able to read and write the following image types:
 567     </p>
 568 <p>
 569       Read: rgb8_image_t and rgba8_image_t Write: rgb8_image_t and rgba8_image_t
 570     </p>
 571 <p>
 572       The lack of having an indexed image type in gil restricts the current interface
 573       to only write out non-indexed images. This is subject to change soon.
 574     </p>
 575 <h4>
 576 <a name="gil.io.using_io.h11"></a>
 577       <span class="phrase"><a name="gil.io.using_io.tiff"></a></span><a class="link" href="using_io.html#gil.io.using_io.tiff">TIFF</a>
 578     </h4>
 579 <p>
 580       For a general overview of the TIFF image file format go to the following <a href="http://en.wikipedia.org/wiki/Tagged_Image_File_Format" target="_top">http://en.wikipedia.org/wiki/Tagged_Image_File_Format</a>.
 581     </p>
 582 <p>
 583       This tiff extension is based on the libtiff, which can be found, <a href="http://www.remotesensing.org/libtiff/" target="_top">http://www.remotesensing.org/libtiff/</a>.
 584     </p>
 585 <p>
 586       The user has to make sure this library is properly installed. I strongly recommend
 587       the user to build the library yourself. It could potentially save you a lot
 588       of trouble.
 589     </p>
 590 <p>
 591       TIFF images can virtually encode all kinds of channel sizes representing various
 592       color spaces. Even planar images are possible. For instance, rbg323 or gray7.
 593       The channels also can have specific formats, like integer values or floating
 594       point values. For a complete set of options please consult the following websites:
 595     </p>
 596 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 597 <li class="listitem">
 598           <a href="http://www.awaresystems.be/imaging/tiff/tifftags/baseline.html" target="_top">http://www.awaresystems.be/imaging/tiff/tifftags/baseline.html</a>
 599         </li>
 600 <li class="listitem">
 601           <a href="http://www.awaresystems.be/imaging/tiff/tifftags/extension.html" target="_top">http://www.awaresystems.be/imaging/tiff/tifftags/extension.html</a>
 602         </li>
 603 </ul></div>
 604 <p>
 605       The author of this extension is not claiming all tiff formats are supported.
 606       This extension is likely to be a moving target adding new features with each
 607       new milestone. Here is an incomplete lists:
 608     </p>
 609 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 610 <li class="listitem">
 611           Multi-page tiffs - read only
 612         </li>
 613 <li class="listitem">
 614           Strip tiffs - read and write support
 615         </li>
 616 <li class="listitem">
 617           Tiled tiffs - read and write support with user defined tiled sizes
 618         </li>
 619 <li class="listitem">
 620           bit images tiffs - fully supported, like gray1_image_t ( minisblack )
 621         </li>
 622 <li class="listitem">
 623           planar tiffs - fully supported
 624         </li>
 625 <li class="listitem">
 626           floating point tiffs - fully supported
 627         </li>
 628 <li class="listitem">
 629           palette tiffs - supported but no indexed image type is available as of
 630           now
 631         </li>
 632 </ul></div>
 633 <p>
 634       This gil extension uses two different test image suites to test read and write
 635       capabilities. See test_image folder. It's advisable to use ImageMagick's test
 636       viewer to display images.
 637     </p>
 638 <h3>
 639 <a name="gil.io.using_io.h12"></a>
 640       <span class="phrase"><a name="gil.io.using_io.extending_gil__io_with_new_formats"></a></span><a class="link" href="using_io.html#gil.io.using_io.extending_gil__io_with_new_formats">Extending
 641       GIL::IO with new Formats</a>
 642     </h3>
 643 <p>
 644       Extending the gil::io with new formats is meant to be simple and straightforward.
 645       Before adding I would recommend to have a look at existing implementations
 646       and then trying to follow a couple of guidelines:
 647     </p>
 648 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 649 <li class="listitem">
 650           Create the following files for your new xxx format
 651           <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
 652 <li class="listitem">
 653                 xxx_read.hpp // Only includes read code
 654               </li>
 655 <li class="listitem">
 656                 xxx_write.hpp // Only includes write code
 657               </li>
 658 <li class="listitem">
 659                 xxx_all.hpp // includes xxx_read.hpp and xxx_write.hpp
 660               </li>
 661 </ul></div>
 662         </li>
 663 <li class="listitem">
 664           Add the code to the boost::gil::detail namespace
 665         </li>
 666 <li class="listitem">
 667           Create a tag type for the new format. Like this:
 668 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">xxx_tag</span> <span class="special">:</span> <span class="identifier">format_tag</span> <span class="special">{};</span>
 669 </pre>
 670         </li>
 671 <li class="listitem">
 672           Create the image_read_info for the new format. It contains all the information
 673           that are necessary to read an image. It should be filled and returned by
 674           the get_info() member of the reader class. See below.
 675 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;&gt;</span> <span class="keyword">struct</span> <span class="identifier">image_read_info</span><span class="special">&lt;</span> <span class="identifier">xxx_tag</span> <span class="special">&gt;</span> <span class="special">{};</span>
 676 </pre>
 677         </li>
 678 <li class="listitem">
 679           Create the image_write_info for the new format. It contains all the information
 680           that are necessary to write an image.
 681 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;&gt;</span> <span class="keyword">struct</span> <span class="identifier">image_write_info</span><span class="special">&lt;</span> <span class="identifier">xxx_tag</span> <span class="special">&gt;</span> <span class="special">{};</span>
 682 </pre>
 683         </li>
 684 <li class="listitem">
 685           Use the following reader skeleton as a start:
 686 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">Device</span>
 687         <span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">ConversionPolicy</span>
 688         <span class="special">&gt;</span>
 689 <span class="keyword">class</span> <span class="identifier">reader</span><span class="special">&lt;</span> <span class="identifier">Device</span>
 690             <span class="special">,</span> <span class="identifier">xxx_tag</span>
 691             <span class="special">,</span> <span class="identifier">ConversionPolicy</span>
 692             <span class="special">&gt;</span>
 693             <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">reader_base</span><span class="special">&lt;</span> <span class="identifier">xxx_tag</span>
 694                                 <span class="special">,</span> <span class="identifier">ConversionPolicy</span>
 695                                 <span class="special">&gt;</span>
 696 <span class="special">{</span>
 697 <span class="keyword">private</span><span class="special">:</span>
 698
 699     <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">ConversionPolicy</span><span class="special">::</span><span class="identifier">color_converter_type</span> <span class="identifier">cc_t</span><span class="special">;</span>
 700
 701 <span class="keyword">public</span><span class="special">:</span>
 702
 703     <span class="identifier">reader</span><span class="special">(</span> <span class="identifier">Device</span><span class="special">&amp;</span> <span class="identifier">device</span> <span class="special">)</span>
 704     <span class="special">:</span> <span class="identifier">_io_dev</span><span class="special">(</span> <span class="identifier">device</span> <span class="special">)</span>
 705     <span class="special">{}</span>
 706
 707     <span class="identifier">reader</span><span class="special">(</span> <span class="identifier">Device</span><span class="special">&amp;</span>     <span class="identifier">device</span>
 708           <span class="special">,</span> <span class="keyword">const</span> <span class="identifier">cc_t</span><span class="special">&amp;</span> <span class="identifier">cc</span>
 709           <span class="special">)</span>
 710     <span class="special">:</span> <span class="identifier">_io_dev</span><span class="special">(</span> <span class="identifier">device</span> <span class="special">)</span>
 711     <span class="special">,</span> <span class="identifier">reader_base</span><span class="special">&lt;</span> <span class="identifier">xxx_tag</span>
 712                  <span class="special">,</span> <span class="identifier">ConversionPolicy</span>
 713                  <span class="special">&gt;(</span> <span class="identifier">cc</span> <span class="special">)</span>
 714     <span class="special">{}</span>
 715
 716     <span class="identifier">image_read_info</span><span class="special">&lt;</span> <span class="identifier">xxx_tag</span> <span class="special">&gt;</span> <span class="identifier">get_info</span><span class="special">()</span>
 717     <span class="special">{</span>
 718         <span class="comment">// your implementation here</span>
 719     <span class="special">}</span>
 720
 721     <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">View</span> <span class="special">&gt;</span>
 722     <span class="keyword">void</span> <span class="identifier">apply</span><span class="special">(</span> <span class="keyword">const</span> <span class="identifier">View</span><span class="special">&amp;</span> <span class="identifier">dst_view</span> <span class="special">)</span>
 723     <span class="special">{</span>
 724         <span class="comment">// your implementation here</span>
 725     <span class="special">}</span>
 726 <span class="special">};</span>
 727 </pre>
 728         </li>
 729 <li class="listitem">
 730           The writer skeleton:
 731 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">Device</span> <span class="special">&gt;</span>
 732 <span class="keyword">class</span> <span class="identifier">writer</span><span class="special">&lt;</span> <span class="identifier">Device</span>
 733             <span class="special">,</span> <span class="identifier">xxx_tag</span>
 734             <span class="special">&gt;</span>
 735 <span class="special">{</span>
 736 <span class="keyword">public</span><span class="special">:</span>
 737
 738     <span class="identifier">writer</span><span class="special">(</span> <span class="identifier">Device</span> <span class="special">&amp;</span> <span class="identifier">file</span> <span class="special">)</span>
 739     <span class="special">:</span> <span class="identifier">out</span><span class="special">(</span><span class="identifier">file</span><span class="special">)</span>
 740     <span class="special">{}</span>
 741
 742     <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">View</span><span class="special">&gt;</span>
 743     <span class="keyword">void</span> <span class="identifier">apply</span><span class="special">(</span> <span class="keyword">const</span> <span class="identifier">View</span><span class="special">&amp;</span> <span class="identifier">view</span> <span class="special">)</span>
 744     <span class="special">{</span>
 745         <span class="comment">// your implementation here</span>
 746     <span class="special">}</span>
 747
 748     <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">View</span><span class="special">&gt;</span>
 749     <span class="keyword">void</span> <span class="identifier">apply</span><span class="special">(</span> <span class="keyword">const</span> <span class="identifier">View</span><span class="special">&amp;</span>                        <span class="identifier">view</span>
 750               <span class="special">,</span> <span class="keyword">const</span> <span class="identifier">image_write_info</span><span class="special">&lt;</span> <span class="identifier">xxx_tag</span> <span class="special">&gt;&amp;</span> <span class="identifier">info</span> <span class="special">)</span>
 751     <span class="special">{</span>
 752         <span class="comment">// your implementation here</span>
 753     <span class="special">}</span>
 754 <span class="special">};</span>
 755 </pre>
 756         </li>
 757 </ul></div>
 758 </div>
 759 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 760 <td align="left"></td>
 761 <td align="right"><div class="copyright-footer">Copyright &#169; 2013 Christian Henning<p>
 762         Distributed under the Boost Software License, Version 1.0. (See accompanying
 763         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 764       </p>
 765 </div></td>
 766 </tr></table>
 767 <hr>
 768 <div class="spirit-nav">
 769 <a accesskey="p" href="tutorial.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="running_gil__io_tests.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 770 </div>
 771 </body>
 772 </html>