libs/gil/io/doc/io.qbk

   1 [library Boost.GIL.IO
   2         [quickbook 1.3]
   3     [authors [Henning, Christian] ]
   4     [copyright 2013 Christian Henning]
   5     [purpose
   6         An generic, user-friendly interface for reading and writing different image formats.
   7     ]
   8     [id gil.io]
   9     [dirname gil/extension/io_new]
  10     [license
  11         Distributed under the Boost Software License, Version 1.0.
  12         (See accompanying file LICENSE_1_0.txt or copy at
  13         [@http://www.boost.org/LICENSE_1_0.txt])
  14     ]
  15 ]
  16
  17 [/ Links ]
  18 [def _BMP_Wiki_            [@http://en.wikipedia.org/wiki/BMP_file_format]]
  19 [def _JPEG_Wiki_           [@http://en.wikipedia.org/wiki/JPEG]]
  20 [def _JPEG_lib_            [@http://www.ijg.org/]]
  21 [def _PNG_Wiki_            [@http://en.wikipedia.org/wiki/Portable_Network_Graphics]]
  22 [def _PNG_Lib_             [@http://libpng.org/pub/png/libpng.html]]
  23 [def _PNM_Wiki_            [@http://en.wikipedia.org/wiki/Portable_anymap]]
  24 [def _RAW_Wiki_            [@http://en.wikipedia.org/wiki/Raw_image_format]]
  25 [def _TARGA_Wiki           [@http://en.wikipedia.org/wiki/Truevision_TGA]]
  26 [def _RAW_lib_             [@http://www.libraw.org/]]
  27 [def _RAW_Wiki_            [@http://en.wikipedia.org/wiki/Raw_image_format]]
  28 [def _TIFF_Wiki_           [@http://en.wikipedia.org/wiki/Tagged_Image_File_Format]]
  29 [def _TIFF_Lib_            [@http://www.remotesensing.org/libtiff/]]
  30 [def _TIFF_Base_Tags_      [@http://www.awaresystems.be/imaging/tiff/tifftags/baseline.html]]
  31 [def _TIFF_Extension_Tags_ [@http://www.awaresystems.be/imaging/tiff/tifftags/extension.html]]
  32
  33 [def _BMP_TEST_FILES                    [@http://entropymine.com/jason/bmpsuite/]]
  34 [def _PNG_TEST_FILES                    [@http://www.schaik.com/pngsuite/pngsuite.html]]
  35 [def _TARGA_TEST_FILES                  [@http://www.fileformat.info/format/tga/sample/index.htm]]
  36 [def _TIFF_LIB_TIFF_TEST_FILES          [@http://www.remotesensing.org/libtiff/images.html]]
  37 [def _TIFF_GRAPHICSMAGICK_TEST_FILES    [@ftp://ftp.graphicsmagick.org/pub/tiff-samples/tiff-sample-images-be.tar.gz]]
  38
  39 [section Overview]
  40 This extension to boost::gil provides an easy to use interface for reading and writing
  41 various image formats. It also includes a framework for adding new formats.
  42
  43 Please see section 3.3 for all supported image formats. A basic tutorial is provided
  44 in section [link gil.io.tutorial Tutorial]. Also, this extension requires Boost version 1.42 and up. Furthermore the gil
  45 extension Toolbox is used.
  46
  47 For adding new image formats please refer to section [link gil.io.using_io.extending_gil__io_with_new_formats Extending GIL::IO with new Formats].
  48 [h2 Supported Platforms]
  49 All platforms supported by boost which have a decent C++ compiler. Depending on the
  50 image format one or more of the following image libraries might be needed:
  51
  52 * libtiff
  53 * libjpeg
  54 * libpng
  55 * libraw
  56 * zlib
  57
  58 The library is designed to support as many formats as required by the user.
  59 For instance, if the user only needs bmp support none of the above mentioned
  60 dependencies are required.
  61
  62 There are more details available in this documentation on the image format dependencies.
  63 Please see section [link gil.io.using_io.supported_image_formats Supported Image Formats].
  64 [endsect]
  65
  66 [section Tutorial]
  67 Thanks to modern C++ programming techniques the interface for this library
  68 is rather small and easy to use. In this tutorial I'll give you a short walk-around
  69 on how to use this boost::gil extension. For more details please refer to section 3.
  70
  71 Since this is an extension to boost::gil I expect the user to have some very basic
  72 understanding of the gil ( generic image library ). Please see here for the help.
  73
  74 [h2 Header Files]
  75 The header files to be included all have the same format. For instance, tiff_all.hpp will
  76 allow to read and write. Whereas, tiff_read.hpp only allows for reading. If the user only
  77 wants to write jpeg's include jpeg_write.hpp. All formats provide these three types of header files:
  78
  79 * xxx_all.hpp
  80 * xxx_read.hpp
  81 * xxx_write.hpp
  82
  83 xxx stands for image format.
  84
  85 [h2 Reading An Image]
  86 Probably the most common case to read a tiff image can be done as follows:
  87
  88     std::string filename( "image.tif" );
  89     rgb8_image_t img;
  90     read_image( filename, img, tiff_tag() );
  91
  92 The code would be same for all other image formats. The only thing that needs to
  93 change is the tag type ( tiff_tag ) in the read_image call.
  94 The read_image() expects the supplied image type to be compatible with the
  95 image stored in the file. If the user doesn't know what format an image has he/she
  96 can use read_and_convert_image().
  97 Another important fact is that read_image() will allocate the appropriate
  98 memory needed for the read operation. There are read_view or read_and_convert_view
  99 counterparts, if the memory is already allocated.
 100
 101 Sometimes the user only wants to read a sub-part of an image, then the above call
 102 would look as follows:
 103
 104     read_image( filename
 105               , img
 106               , image_read_settings< tiff_tag >( point_t( 0, 0 ), point_t( 50, 50 ) )
 107               );
 108
 109 The image_read_settings class will provide the user with image format independent
 110 reading setting but can also serves as a pointer for format dependent settings. Please
 111 see the specific image format sections [link gil.io.using_io.supported_image_formats Supported Image Formats] for more details.
 112
 113 [h2 Writing An Image]
 114 Besides reading the information also writing is the second part of this boost::gil extension.
 115 Writing is a lot simpler than reading since an existing image view contains all the information.
 116 For instance writing an image can be done as follows:
 117
 118     std::string filename( "image.tif" );
 119     rgb8_image_t img( 640, 480 );
 120
 121     // write data into image
 122
 123     write_view( filename
 124               , view( img )
 125               , tiff_tag()
 126               );
 127
 128
 129 The interface is similar to reading an image. To add image format specific parameter the user can use
 130 image_write_info class. For instance, a user can specify the jpeg quality when writing like this:
 131
 132     std::string filename( "image.jpg" );
 133     rgb8_image_t img( 640, 480 );
 134
 135     // write data into image
 136
 137     write_view( filename
 138               , view( img )
 139               , image_write_info< jpeg_tag >( 95 )
 140               );
 141
 142
 143 The above example will write an image where the jpeg quality is set to 95 percent.
 144
 145 [h2 Reading And Writing In-Memory Buffers]
 146 Reading and writing in-memory buffers are supported as well. See as follows:
 147
 148     // 1. Read an image.
 149     ifstream in( "test.tif", ios::binary );
 150
 151     rgb8_image_t img;
 152     read_image( in, img, tiff_tag() );
 153
 154     // 2. Write image to in-memory buffer.
 155     stringstream out_buffer( ios_base::out | ios_base::binary );
 156
 157     rgb8_image_t src;
 158     write_view( out_buffer, view( src ), tiff_tag() );
 159
 160     // 3. Copy in-memory buffer to another.
 161     stringstream in_buffer( ios_base::in | ios_base::binary );
 162     in_buffer << out_buffer.rdbuf();
 163
 164     // 4. Read in-memory buffer to gil image
 165     rgb8_image_t dst;
 166     read_image( in_buffer, dst, tag_t() );
 167
 168     // 5. Write out image.
 169     string filename( "out.tif" );
 170     ofstream out( filename.c_str(), ios_base::binary );
 171     write_view( out, view( dst ), tiff_tag() );
 172
 173 In case the user is using his own stream classes he has to make sure it has the common interface read,
 174 write, seek, close, etc. Interface.
 175
 176 [endsect]
 177
 178 [section:using_io Using IO]
 179 [h2 General Overview]
 180 The tutorial pointed out some use cases for reading and writing images in various image formats. This section will provide a more thorough overview.
 181
 182 The next sections will introduce the Read and Write interface. But it might be worth poiting out that by using some advanced metaprogramming techniques
 183 the interface is rather small and hopefully easy to understand.
 184
 185 Besides the general interface the user also has the ability to interface directly with the underlying image format. For that each reader or writer
 186 provides access to the so-called backend. For instance:
 187
 188     typedef get_reader_backend< const std::string
 189                               , tag_t
 190                               >::type backend_t;
 191
 192     backend_t backend = read_image_info( bmp_filename
 193                                        , tag_t()
 194                                        );
 195
 196     BOOST_CHECK_EQUAL( backend._info._width , 127 );
 197     BOOST_CHECK_EQUAL( backend._info._height, 64 );
 198
 199 Of course, the typedef can be removed when using c++11's auto feature.
 200
 201 [h2 Read Interface]
 202 As the Tutorial demonstrated there are a few ways to read images. Here is an enumeration of
 203 all read functions with a short description:
 204
 205     * read_image - read into a gil image with no conversion. Memory is allocated.
 206     * read_view  - read into a gil view with no conversion.
 207     * read_and_convert_image - read and convert into a gil image. Memory is allocated.
 208     * read_and_convert_view  - read and convert into a gil view.
 209     * read_image_info - read the image header.
 210
 211 Conversion in this context is necessary if the source ( file ) has an incompatible color space
 212 with the destination ( gil image type ). If that's the case the user has to use the xxx_and_convert_xxx
 213 variants.
 214
 215 All functions take the filename or a device as the first parameter. The filename can be anything from
 216 a c string, std::string, std::wstring, and a boost::filesystem path. When using the path object the
 217 user needs to define the ADD_FS_PATH_SUPPORT compiler symbol to include the boost::filesystem
 218 dependency. Devices could be a FILE*, std::ifstream, and a TIFF* for TIFF images.
 219
 220 The second parameter is either an image or view type depending on the read_xxx function.
 221 The third and last parameter is either an instance of the image_read_settings<FormatTag> or just the
 222 FormatTag. The settings can be various depending on the format which is being read. But the all
 223 share settings for reading a partial image area. The first point describes the top left image
 224 coordinate whereas the second are the dimensions in x and y directions. Here an example of
 225 setting up partial read.
 226
 227     read_image( filename
 228               , img
 229               , image_read_settings< tiff_tag >( point_t( 0, 0 ), point_t( 50, 50 ) )
 230               );
 231
 232 Each format supports reading just the header information, using read_image_info(). Please
 233 refer to the format specific sections under 3.3. A basic example follows:
 234
 235     image_read_info< tiff_t > info = read_image_info( filename
 236                                                     , tiff_t()
 237                                                     );
 238
 239 GIL also comes with a dynamic image extension. In the context of GIL.IO a user can define an any_image type based
 240 on several image types. The IO extension would then pick the matching image type to the current image file.
 241 The following example shows this feature:
 242
 243     typedef mpl::vector< gray8_image_t
 244                        , gray16_image_t
 245                        , rgb8_image_t
 246                        , rgba_image_t
 247                        > my_img_types;
 248
 249     any_image< my_img_types > runtime_image;
 250
 251     read_image( filename
 252               , runtime_image
 253               , tiff_tag()
 254               );
 255
 256
 257 During the review it became clear that there is a need to read big images scanline by scanline. To support such use case
 258 a scanline_reader is implemented for all supported image formats. The scanline_read_iterators will then allow to traverse
 259 through the image. The following code sample shows the usage:
 260
 261     typedef tiff_tag tag_t;
 262
 263     typedef scanline_reader< typename get_read_device< const char*
 264                                                      , tag_t
 265                                                      >::type
 266                             , tag_t
 267                             > reader_t;
 268
 269     reader_t reader = make_scanline_reader( "C:/boost/libs/gil/io/test_images/tiff/test.tif", tag_t() );
 270
 271     typedef rgba8_image_t image_t;
 272
 273     image_t dst( reader._info._width, reader._info._height );
 274     fill_pixels( view(dst), image_t::value_type() );
 275
 276     typedef reader_t::iterator_t iterator_t;
 277
 278     iterator_t it  = reader.begin();
 279     iterator_t end = reader.end();
 280
 281     for( int row = 0; it != end; ++it, ++row )
 282     {
 283         copy_pixels( interleaved_view( reader._info._width
 284                                         , 1
 285                                         , ( image_t::view_t::x_iterator ) *it
 286                                         , reader._scanline_length
 287                                         )
 288                     , subimage_view( view( dst )
 289                                     , 0
 290                                     , row
 291                                     , reader._info._width
 292                                     , 1
 293                                     )
 294                     );
 295     }
 296
 297 There are many ways to travese an image but for as of now only by scanline is supported.
 298
 299
 300 [h2 Write Interface]
 301 There is only one function for writing out images, write_view. Similar to reading the first parameter is either
 302 a filename or a device. The filename can be anything from a c string, std::string, std::wstring, and a
 303 boost::filesystem path. When using the path object the user needs to define the ADD_FS_PATH_SUPPORT compiler symbol
 304 to include the boost::filesystem dependency. Devices could be a FILE*, std::ifstream, and a TIFF* for TIFF images.
 305
 306 The second parameter is an view object to image being written. The third and last parameter is either a tag or
 307 an image_write_info< FormatTag > object containing more settings. One example for instance is the jpeg quality.
 308 Refer to the format specific sections under 3.3. to have a list of all the possible settings.
 309
 310 Writing an any_image<...> is supported. See the following example:
 311
 312     typedef mpl::vector< gray8_image_t
 313                        , gray16_image_t
 314                        , rgb8_image_t
 315                        , rgba_image_t
 316                        > my_img_types;
 317
 318
 319     any_image< my_img_types > runtime_image;
 320
 321     // fill any_image
 322
 323     write_view( filename
 324               , view( runtime_image )
 325               , tiff_tag()
 326               );
 327
 328 [h2 Compiler Symbols]
 329
 330 The following table gives an overview of all supported compiler symbols that can be set by the user:
 331
 332 [table Compiler Symbols
 333     [[Symbol]                                                   [Description]]
 334     [[BOOST_GIL_IO_ENABLE_GRAY_ALPHA]                           [Enable the color space "gray_alpha".]]
 335     [[BOOST_GIL_IO_ADD_FS_PATH_SUPPORT]                         [Enable boost::filesystem 3.0 library.]]
 336     [[BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED]                [Use libpng in floating point mode. This symbol is incompatible with BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED.]]
 337     [[BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED]                   [Use libpng in integer mode. This symbol is incompatible with BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED.]]
 338     [[BOOST_GIL_IO_PNG_DITHERING_SUPPORTED]                     [Look up "dithering" in libpng manual for explanation.]]
 339     [[BOOST_GIL_IO_PNG_1_4_OR_LOWER]                            [Allow compiling with libpng 1.4 or lower.]]
 340     [[BOOST_GIL_EXTENSION_IO_JPEG_C_LIB_COMPILED_AS_CPLUSPLUS]  [libjpeg is compiled as c++ lib.]]
 341     [[BOOST_GIL_EXTENSION_IO_PNG_C_LIB_COMPILED_AS_CPLUSPLUS]   [libpng is compiled as c++ lib.]]
 342     [[BOOST_GIL_EXTENSION_IO_TIFF_C_LIB_COMPILED_AS_CPLUSPLUS]  [libtiff is compiled as c++ lib.]]
 343     [[BOOST_GIL_EXTENSION_IO_ZLIB_C_LIB_COMPILED_AS_CPLUSPLUS]  [zlib is compiled as c++ lib.]]
 344     [[BOOST_GIL_IO_TEST_ALLOW_READING_IMAGES]                   [Allow basic test images to be read from local hard drive. The paths can be set in paths.hpp]]
 345     [[BOOST_GIL_IO_TEST_ALLOW_WRITING_IMAGES]                   [Allow images to be written to the local hard drive. The paths can be set in paths.hpp]]
 346     [[BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES]                   [Run tests using the bmp test images suite. See _BMP_TEST_FILES]]
 347     [[BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES]                   [Run tests using the png test images suite. See _PNG_TEST_FILES]]
 348     [[BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES]                   [Run tests using the pnm test images suite. Send me an email for accessing the files.]]
 349     [[BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES]      [Run tests using the targa file format test images suite. See _TARGA_TEST_FILES]]
 350     [[BOOST_GIL_IO_USE_TIFF_LIBTIFF_TEST_SUITE_IMAGES]          [Run tests using the targa file format test images suite. See _TIFF_LIB_TIFF_TEST_FILES]]
 351     [[BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES]   [Run tests using the targa file format test images suite. See _TIFF_GRAPHICSMAGICK_TEST_FILES]]
 352
 353 ]
 354
 355 [h2 Supported Image Formats]
 356 [h3 BMP]
 357 For a general overview of the BMP image file format go to the following _BMP_Wiki_.
 358
 359 Please note, the code has not been tested on X Windows System variations
 360 of the BMP format which are usually referred to XBM and XPM formats.
 361
 362 Here, only the MS Windows and OS/2 format is relevant.
 363
 364 Currently the code is able to read and write the following image types:
 365
 366 Read: gray1_image_t, gray4_image_t, gray8_image_t, rgb8_image_t and, rgba8_image_t
 367 Write: rgb8_image_t and, rgba8_image_t
 368
 369 The lack of having an indexed image type in gil restricts the current interface to only
 370 write out non-indexed images. This is subject to change soon.
 371
 372 [h3 JPEG]
 373 For a general overview of the JPEG image file format go to the following _JPEG_Wiki_.
 374
 375 This jpeg extension is based on the libjpeg library which can be found here, _JPEG_Lib_.
 376
 377 All versions starting from 8x are supported.
 378
 379 The user has to make sure this library is properly installed. I strongly recommend the user
 380 to build the library yourself. It could potentially save you a lot of trouble.
 381
 382 Currently the code is able to read and write the following image types:
 383
 384 Read: gray8_image_t, rgb8_image_t, cmyk8_image_t
 385 Write: gray8_image_t, rgb8_image_t, cmyk8_image_t
 386
 387 Reading YCbCr or YCCK images is possible but might result in inaccuracies since both color spaces
 388 aren't available yet for gil. For now these color space are read as rgb images.
 389 This is subject to change soon.
 390
 391 [h3 PNG]
 392 For a general overview of the PNG image file format go to the following _PNG_Wiki_.
 393
 394 This png extension is based on the libpng, which can be found here, _PNG_Lib.
 395
 396 All versions starting from 1.5.x are supported.
 397
 398 The user has to make sure this library is properly installed. I strongly recommend the user
 399 to build the library yourself. It could potentially save you a lot of trouble.
 400
 401 Currently the code is able to read and write the following image types:
 402
 403 Read: gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8, rgb16, rgba8, rgba16
 404 Write: gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8, rgb16, rgba8, rgba16
 405
 406 For reading gray_alpha images the user has to enable the ENABLE_GRAY_ALPHA compiler switch. This color
 407 space is defined in the toolbox by using gray_alpha.hpp.
 408
 409 [h3 PNM]
 410 For a general overview of the PNM image file format go to the following _PNM_Wiki_.
 411
 412 No external library is needed for the pnm format. Both ascii and binary formats are supported.
 413
 414 Currently the code is able to read and write the following image types:
 415
 416 Read: gray1, gray8, rgb8
 417 Write: gray1, gray8, rgb8
 418
 419 When reading a mono text image the data is read as a gray8 image.
 420
 421 [h3 RAW]
 422 For a general overview see _RAW_Wiki.
 423
 424 Currently the extension is only able to read rgb8 images.
 425
 426 [h3 TARGA]
 427 For a general overview of the BMP image file format go to the following _TARGA_Wiki_.
 428
 429 Currently the code is able to read and write the following image types:
 430
 431 Read: rgb8_image_t and rgba8_image_t
 432 Write: rgb8_image_t and rgba8_image_t
 433
 434 The lack of having an indexed image type in gil restricts the current interface to only
 435 write out non-indexed images. This is subject to change soon.
 436
 437 [h3 TIFF]
 438 For a general overview of the TIFF image file format go to the following _TIFF_Wiki_.
 439
 440 This tiff extension is based on the libtiff, which can be found, _TIFF_Lib_.
 441
 442 All versions starting from 3.9.x are supported.
 443
 444 The user has to make sure this library is properly installed. I strongly recommend the user
 445 to build the library yourself. It could potentially save you a lot of trouble.
 446
 447 TIFF images can virtually encode all kinds of channel sizes representing various color spaces. Even
 448 planar images are possible. For instance, rbg323 or gray7. The channels also can have specific formats, like
 449 integer values or floating point values. For a complete set of options please consult the following websites:
 450
 451 * _TIFF_Base_Tags_
 452 * _TIFF_Extension_Tags_
 453
 454 The author of this extension is not claiming all tiff formats are supported. This extension is
 455 likely to be a moving target adding new features with each new milestone. Here is an incomplete lists:
 456
 457 * Multi-page tiffs - read only
 458 * Strip tiffs - read and write support
 459 * Tiled tiffs - read and write support with user defined tiled sizes
 460 * bit images tiffs - fully supported, like gray1_image_t ( minisblack )
 461 * planar tiffs - fully supported
 462 * floating point tiffs - fully supported
 463 * palette tiffs - supported but no indexed image type is available as of now
 464
 465 This gil extension uses two different test image suites to test read and write capabilities. See test_image folder.
 466 It's advisable to use ImageMagick's test viewer to display images.
 467
 468
 469 [h2 Extending GIL::IO with new Formats]
 470 Extending the gil::io with new formats is meant to be simple and straightforward. Before adding I would
 471 recommend to have a look at existing implementations and then trying to follow a couple of guidelines:
 472
 473 * Create the following files for your new xxx format
 474         * xxx_read.hpp // Only includes read code
 475         * xxx_write.hpp // Only includes write code
 476         * xxx_all.hpp // includes xxx_read.hpp and xxx_write.hpp
 477 * Add the code to the boost::gil::detail namespace
 478 * Create a tag type for the new format. Like this:
 479   ``
 480                 struct xxx_tag : format_tag {};
 481   ``
 482
 483 * Create the image_read_info for the new format. It contains all the information that are
 484   necessary to read an image. It should be filled and returned by the get_info() member of
 485   the reader class. See below.
 486   ``
 487           template<> struct image_read_info< xxx_tag > {};
 488   ``
 489
 490 * Create the image_write_info for the new format. It contains all the information that are
 491   necessary to write an image.
 492   ``
 493           template<> struct image_write_info< xxx_tag > {};
 494   ``
 495
 496 * Use the following reader skeleton as a start:
 497   ``
 498     template< typename Device
 499             , typename ConversionPolicy
 500             >
 501     class reader< Device
 502                 , xxx_tag
 503                 , ConversionPolicy
 504                 >
 505                 : public reader_base< xxx_tag
 506                                     , ConversionPolicy
 507                                     >
 508     {
 509     private:
 510
 511         typedef typename ConversionPolicy::color_converter_type cc_t;
 512
 513     public:
 514
 515         reader( Device& device )
 516         : _io_dev( device )
 517         {}
 518
 519         reader( Device&     device
 520               , const cc_t& cc
 521               )
 522         : _io_dev( device )
 523         , reader_base< xxx_tag
 524                      , ConversionPolicy
 525                      >( cc )
 526         {}
 527
 528         image_read_info< xxx_tag > get_info()
 529         {
 530             // your implementation here
 531         }
 532
 533         template< typename View >
 534         void apply( const View& dst_view )
 535         {
 536             // your implementation here
 537         }
 538     };
 539   ``
 540
 541 * The writer skeleton:
 542   ``
 543     template< typename Device >
 544     class writer< Device
 545                 , xxx_tag
 546                 >
 547     {
 548     public:
 549
 550         writer( Device & file )
 551         : out(file)
 552         {}
 553
 554         template<typename View>
 555         void apply( const View& view )
 556         {
 557             // your implementation here
 558         }
 559
 560         template<typename View>
 561         void apply( const View&                        view
 562                   , const image_write_info< xxx_tag >& info )
 563         {
 564             // your implementation here
 565         }
 566     };
 567   ``
 568
 569 [endsect]
 570
 571 [section Running gil::io tests]
 572 gil::io comes with a large suite of test cases which reads and writes various file formats. It uses some test image suites which can be found online or which can be demanded from me by sending me an email.
 573
 574 There are some test images created by me in the test folder. To enable unit tests which make use of them set the following compiler options BOOST_GIL_IO_TEST_ALLOW_READING_IMAGES and BOOST_GIL_IO_TEST_ALLOW_WRITING_IMAGES.
 575
 576 The following list provides all links to the image suites the compiler symbol to enable the tests:
 577
 578 * BMP:   _BMP_TEST_FILES                 -- BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES
 579 * PNG:   _PNG_TEST_FILES                 -- BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES
 580 * PNM:   request files from me           -- BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES
 581 * TARGA: _TARGA_TEST_FILES               -- BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES
 582 * TIFF:  _TIFF_LIB_TIFF_TEST_FILES       -- BOOST_GIL_IO_USE_TIFF_LIBTIFF_TEST_SUITE_IMAGES
 583 * TIFF   _TIFF_GRAPHICSMAGICK_TEST_FILES -- BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES
 584
 585 [endsect]