7 This extension to boost::gil provides an easy to use interface for reading and
8 writing various image formats. It also includes a framework for adding
11 Please see section 3.3 for all supported image formats. A basic tutorial is
12 provided in section [link gil.io.tutorial Tutorial].
13 Also, this extension requires Boost version 1.42 and up.
14 Furthermore the GIL extension Toolbox is used.
16 For adding new image formats please refer to section
17 [link gil.io.using_io.extending_gil__io_with_new_formats Extending GIL::IO with new Formats].
22 All platforms supported by Boost which have a decent C++ compiler.
23 Depending on the image format one or more of the following image
24 libraries might be needed:
32 The library is designed to support as many formats as required by the user.
33 For instance, if the user only needs bmp support none of the above mentioned
34 dependencies are required.
36 There are more details available in this documentation on the image format
37 dependencies. Please see section
38 [link gil.io.using_io.supported_image_formats Supported Image Formats].
43 Thanks to modern C++ programming techniques the interface for this library
44 is rather small and easy to use. In this tutorial I'll give you a short
45 walk-around on how to use this boost::gil extension.
46 For more details please refer to section 3.
48 For each supported IO format a single top-level header file is provided.
49 For instance, include `boost/gil/extension/io/tiff.hpp` to be able
50 to read or write TIFF files.
55 Probably the most common case to read a tiff image can be done as follows::
57 std::string filename( "image.tif" );
59 read_image( filename, img, tiff_tag() );
61 The code would be same for all other image formats. The only thing that needs
62 to change is the tag type ( tiff_tag ) in the read_image call.
63 The read_image() expects the supplied image type to be compatible with the
64 image stored in the file. If the user doesn't know what format an image has she
65 can use read_and_convert_image().
66 Another important fact is that read_image() will allocate the appropriate
67 memory needed for the read operation. There are ``read_view`` or
68 ``read_and_convert_view`` counterparts, if the memory is already allocated.
70 Sometimes the user only wants to read a sub-part of an image,
71 then the above call would look as follows::
75 , image_read_settings< tiff_tag >( point_t( 0, 0 ), point_t( 50, 50 ) )
78 The image_read_settings class will provide the user with image format
79 independent reading setting but can also serves as a pointer for format
81 Please see the specific image format sections
82 [link gil.io.using_io.supported_image_formats Supported Image Formats]
88 Besides reading the information also writing is the second part of this
89 Boost.GIL extension. Writing is a lot simpler than reading since an existing
90 image view contains all the information.
92 For instance writing an image can be done as follows::
94 std::string filename( "image.tif" );
95 rgb8_image_t img( 640, 480 );
97 // write data into image
105 The interface is similar to reading an image. To add image format specific
106 parameter the user can use ``image_write_info`` class.
107 For instance, a user can specify the JPEG quality when writing like this::
109 std::string filename( "image.jpg" );
110 rgb8_image_t img( 640, 480 );
112 // write data into image
116 , image_write_info< jpeg_tag >( 95 )
120 The above example will write an image where the jpeg quality is
123 Reading And Writing In-Memory Buffers
124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126 Reading and writing in-memory buffers are supported as well. See as follows::
129 ifstream in( "test.tif", ios::binary );
132 read_image( in, img, tiff_tag() );
134 // 2. Write image to in-memory buffer.
135 stringstream out_buffer( ios_base::out | ios_base::binary );
138 write_view( out_buffer, view( src ), tiff_tag() );
140 // 3. Copy in-memory buffer to another.
141 stringstream in_buffer( ios_base::in | ios_base::binary );
142 in_buffer << out_buffer.rdbuf();
144 // 4. Read in-memory buffer to gil image
146 read_image( in_buffer, dst, tag_t() );
148 // 5. Write out image.
149 string filename( "out.tif" );
150 ofstream out( filename.c_str(), ios_base::binary );
151 write_view( out, view( dst ), tiff_tag() );
153 In case the user is using his own stream classes he has to make sure it
154 has the common interface read, write, seek, close, etc. Interface.
162 The tutorial pointed out some use cases for reading and writing images in
163 various image formats. This section will provide a more thorough overview.
165 The next sections will introduce the Read and Write interface. But it might be
166 worth pointing out that by using some advanced metaprogramming techniques the
167 interface is rather small and hopefully easy to understand.
169 Besides the general interface the user also has the ability to interface
170 directly with the underlying image format. For that each reader or writer
171 provides access to the so-called backend.
175 typedef get_reader_backend< const std::string
179 backend_t backend = read_image_info( bmp_filename
183 BOOST_CHECK_EQUAL( backend._info._width , 127 );
184 BOOST_CHECK_EQUAL( backend._info._height, 64 );
186 Of course, the typedef can be removed when using c++11's auto feature.
191 As the Tutorial demonstrated there are a few ways to read images.
192 Here is an enumeration of all read functions with a short description:
194 * ``read_image`` - read into a gil image with no conversion.
196 * ``read_view`` - read into a gil view with no conversion.
197 * ``read_and_convert_image`` - read and convert into a gil image.
199 * ``read_and_convert_view`` - read and convert into a gil view.
200 * ``read_image_info`` - read the image header.
202 Conversion in this context is necessary if the source (file) has an
203 incompatible color space with the destination (gil image type).
204 If that's the case the user has to use the xxx_and_convert_xxx variants.
206 All functions take the filename or a device as the first parameter.
207 The filename can be anything from a C-string, ``std::string``,
208 ``std::wstring`` and ``boost::filesystem`` path. When using the path
209 object the user needs to define the ADD_FS_PATH_SUPPORT compiler symbol to
210 include the boost::filesystem dependency.
211 Devices could be a ``FILE*``, ``std::ifstream``, and ``TIFF*`` for TIFF images.
213 The second parameter is either an image or view type depending on the
214 ``read_xxx`` function.
215 The third and last parameter is either an instance of the
216 ``image_read_settings<FormatTag>`` or just the ``FormatTag``.
217 The settings can be various depending on the format which is being read.
218 But the all share settings for reading a partial image area.
219 The first point describes the top left image coordinate whereas the second
220 are the dimensions in x and y directions.
222 Here an example of setting up partial read::
226 , image_read_settings< tiff_tag >( point_t( 0, 0 ), point_t( 50, 50 ) )
229 Each format supports reading just the header information,
230 using ``read_image_info``. Please refer to the format specific sections
231 under 3.3. A basic example follows::
233 image_read_info< tiff_t > info = read_image_info( filename
237 GIL also comes with a dynamic image extension.
238 In the context of GIL.IO a user can define an ``any_image`` type based on
239 several image types. The IO extension would then pick the matching image type
240 to the current image file.
241 The following example shows this feature::
243 typedef mpl::vector< gray8_image_t
249 any_image< my_img_types > runtime_image;
256 During the review it became clear that there is a need to read big images
257 scanline by scanline. To support such use case a ``scanline_reader`` is
258 implemented for all supported image formats.
259 The ``scanline_read_iterators`` will then allow to traverse through the image.
260 The following code sample shows the usage::
262 typedef tiff_tag tag_t;
264 typedef scanline_reader< typename get_read_device< const char*
270 reader_t reader = make_scanline_reader( "C:/boost/libs/gil/test/extension/io/images/tiff/test.tif", tag_t() );
272 typedef rgba8_image_t image_t;
274 image_t dst( reader._info._width, reader._info._height );
275 fill_pixels( view(dst), image_t::value_type() );
277 typedef reader_t::iterator_t iterator_t;
279 iterator_t it = reader.begin();
280 iterator_t end = reader.end();
282 for( int row = 0; it != end; ++it, ++row )
284 copy_pixels( interleaved_view( reader._info._width
286 , ( image_t::view_t::x_iterator ) *it
287 , reader._scanline_length
289 , subimage_view( view( dst )
292 , reader._info._width
298 There are many ways to traverse an image but for as of now only by
299 scanline is supported.
305 There is only one function for writing out images, write_view.
306 Similar to reading the first parameter is either a filename or a device.
307 The filename can be anything from a C-string, ``std::string``,
308 ``std::wstring``, and ``boost::filesystem`` path. When using the path object
309 the user needs to define the ``ADD_FS_PATH_SUPPORT`` compiler symbol to
310 include the ``boost::filesystem`` dependency.
311 Devices could be ``FILE*``, ``std::ifstream``, and ``TIFF*`` for TIFF images.
313 The second parameter is an view object to image being written.
314 The third and last parameter is either a tag or an
315 ``image_write_info<FormatTag>`` object containing more settings.
316 One example for instance is the JPEG quality.
317 Refer to the format specific sections under 3.3. to have a list of all
318 the possible settings.
320 Writing an any_image<...> is supported. See the following example::
322 typedef mpl::vector< gray8_image_t
329 any_image< my_img_types > runtime_image;
334 , view( runtime_image )
341 The following table gives an overview of all supported compiler symbols
342 that can be set by the user:
344 .. comment [table Compiler Symbols
346 ======================================================== ========================================================
348 ======================================================== ========================================================
349 BOOST_GIL_IO_ENABLE_GRAY_ALPHA Enable the color space "gray_alpha".
350 BOOST_GIL_IO_ADD_FS_PATH_SUPPORT Enable boost::filesystem 3.0 library.
351 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.
352 BOOST_GIL_IO_PNG_FIXED_POINT_SUPPORTED Use libpng in integer mode. This symbol is incompatible with BOOST_GIL_IO_PNG_FLOATING_POINT_SUPPORTED.
353 BOOST_GIL_IO_PNG_DITHERING_SUPPORTED Look up "dithering" in libpng manual for explanation.
354 BOOST_GIL_IO_PNG_1_4_OR_LOWER Allow compiling with libpng 1.4 or lower.
355 BOOST_GIL_EXTENSION_IO_JPEG_C_LIB_COMPILED_AS_CPLUSPLUS libjpeg is compiled as c++ lib.
356 BOOST_GIL_EXTENSION_IO_PNG_C_LIB_COMPILED_AS_CPLUSPLUS libpng is compiled as c++ lib.
357 BOOST_GIL_EXTENSION_IO_TIFF_C_LIB_COMPILED_AS_CPLUSPLUS libtiff is compiled as c++ lib.
358 BOOST_GIL_EXTENSION_IO_ZLIB_C_LIB_COMPILED_AS_CPLUSPLUS zlib is compiled as c++ lib.
359 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
360 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
361 BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES Run tests using the bmp test images suite. See _BMP_TEST_FILES
362 BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES Run tests using the png test images suite. See _PNG_TEST_FILES
363 BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES Run tests using the pnm test images suite. Send me an email for accessing the files.
364 BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES Run tests using the targa file format test images suite. See _TARGA_TEST_FILES
365 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
366 BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES Run tests using the targa file format test images suite. See _TIFF_GRAPHICSMAGICK_TEST_FILES
367 ======================================================== ========================================================
369 Supported Image Formats
370 ~~~~~~~~~~~~~~~~~~~~~~~
375 For a general overview of the BMP image file format go to the
378 Please note, the code has not been tested on X Windows System variations
379 of the BMP format which are usually referred to XBM and XPM formats.
381 Here, only the MS Windows and OS/2 format is relevant.
383 Currently the code is able to read and write the following image types:
385 :Read: ``gray1_image_t``, ``gray4_image_t``, ``gray8_image_t``, ``rgb8_image_t`` and, ``rgba8_image_t``
386 :Write: ``rgb8_image_t`` and, ``rgba8_image_t``
388 The lack of having an indexed image type in gil restricts the current
389 interface to only write out non-indexed images.
390 This is subject to change soon.
395 For a general overview of the JPEG image file format go to the
396 following JPEG_Wiki_.
398 This jpeg extension is based on the libjpeg library which can be
399 found here, JPEG_Lib_.
401 All versions starting from 8x are supported.
403 The user has to make sure this library is properly installed.
404 I strongly recommend the user to build the library yourself.
405 It could potentially save you a lot of trouble.
407 Currently the code is able to read and write the following image types:
409 :Read: ``gray8_image_t``, ``rgb8_image_t``, ``cmyk8_image_t``
410 :Write: ``gray8_image_t``, ``rgb8_image_t``, ``cmyk8_image_t``
412 Reading YCbCr or YCCK images is possible but might result in inaccuracies since
413 both color spaces aren't available yet for gil.
414 For now these color space are read as rgb images.
415 This is subject to change soon.
420 For a general overview of the PNG image file format go to the
423 This png extension is based on the libpng, which can be found
426 All versions starting from 1.5.x are supported.
428 The user has to make sure this library is properly installed.
429 I strongly recommend the user to build the library yourself.
430 It could potentially save you a lot of trouble.
432 Currently the code is able to read and write the following image types:
434 :Read: gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8, rgb16, rgba8, rgba16
435 :Write: gray1, gray2, gray4, gray8, gray16, gray_alpha_8, gray_alpha_16, rgb8, rgb16, rgba8, rgba16
437 For reading gray_alpha images the user has to compile application with ``BOOST_GIL_IO_ENABLE_GRAY_ALPHA``
438 macro defined. This color space is defined in the toolbox by using ``gray_alpha.hpp``.
443 For a general overview of the PNM image file format go to the
444 following PNM_Wiki_. No external library is needed for the pnm format.
446 The extension can read images in both flavours of the formats, ASCII and binary,
447 that is types from P1 through P6; can write only binary formats.
449 Currently the code is able to read and write the following image types:
451 :Read: gray1, gray8, rgb8
452 :Write: gray1, gray8, rgb8
454 When reading a mono text image the data is read as a gray8 image.
459 For a general overview see RAW_Wiki_.
461 Currently the extension is only able to read rgb8 images.
466 For a general overview of the BMP image file format go to the
467 following TARGA_Wiki_.
469 Currently the code is able to read and write the following image types:
471 :Read: rgb8_image_t and rgba8_image_t
472 :Write: rgb8_image_t and rgba8_image_t
474 The lack of having an indexed image type in gil restricts the current
475 interface to only write out non-indexed images.
476 This is subject to change soon.
481 For a general overview of the TIFF image file format go to the
482 following TIFF_Wiki_.
484 This tiff extension is based on the libtiff, which can be found, TIFF_Lib_.
486 All versions starting from 3.9.x are supported.
488 The user has to make sure this library is properly installed. I strongly
489 recommend the user to build the library yourself. It could potentially
490 save you a lot of trouble.
492 TIFF images can virtually encode all kinds of channel sizes representing
493 various color spaces. Even planar images are possible.
494 For instance, ``rbg323`` or ``gray7``. The channels also can have specific
495 formats, like integer values or floating point values.
497 For a complete set of options please consult the following websites:
500 * TIFF_Extension_Tags_
502 The author of this extension is not claiming all tiff formats are supported.
503 This extension is likely to be a moving target adding new features with each
504 new milestone. Here is an incomplete lists:
506 * Multi-page TIFF - read only
507 * Strip TIFF - read and write support
508 * Tiled TIFF - read and write support with user defined tiled sizes
509 * Bit images TIFF - fully supported, like ``gray1_image_t`` (minisblack)
510 * Planar TIFF - fully supported
511 * Floating-point TIFF - fully supported
512 * Palette TIFF - supported but no indexed image type is available as of now
514 This gil extension uses two different test image suites to test read and
515 write capabilities. See ``test_image`` folder.
516 It's advisable to use ImageMagick test viewer to display images.
519 Extending GIL::IO with new Formats
520 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
522 Extending the gil::io with new formats is meant to be simple and
523 straightforward. Before adding I would recommend to have a look at existing
524 implementations and then trying to follow a couple of guidelines:
526 * Create the following files for your new xxx format
527 * ``xxx_read.hpp`` - Only includes read code
528 * ``xxx_write.hpp`` - Only includes write code
529 * ``xxx_all.hpp`` - includes xxx_read.hpp and xxx_write.hpp
530 * Add the code to the ``boost::gil::detail`` namespace
531 * Create a tag type for the new format. Like this::
533 struct xxx_tag : format_tag {};
535 * Create the image_read_info for the new format. It contains all the
536 information that are necessary to read an image. It should be filled
537 and returned by the ``get_info`` member of the reader class. See below::
539 template<> struct image_read_info< xxx_tag > {};
541 * Create the image_write_info for the new format. It contains all the
542 information that are necessary to write an image::
544 template<> struct image_write_info< xxx_tag > {};
546 * Use the following reader skeleton as a start::
548 template< typename Device
549 , typename ConversionPolicy
555 : public reader_base< xxx_tag
561 typedef typename ConversionPolicy::color_converter_type cc_t;
565 reader( Device& device )
569 reader( Device& device
573 , reader_base< xxx_tag
578 image_read_info< xxx_tag > get_info()
580 // your implementation here
583 template< typename View >
584 void apply( const View& dst_view )
586 // your implementation here
590 * The writer skeleton::
592 template< typename Device >
599 writer( Device & file )
603 template<typename View>
604 void apply( const View& view )
606 // your implementation here
609 template<typename View>
610 void apply( const View& view
611 , const image_write_info< xxx_tag >& info )
613 // your implementation here
617 Running gil::io tests
618 ---------------------
620 gil::io comes with a large suite of test cases which reads and writes various
621 file formats. It uses some test image suites which can be found online or
622 which can be demanded from me by sending me an email.
624 There are some test images created by me in the test folder.
625 To enable unit tests which make use of them set the following compiler options
626 ``BOOST_GIL_IO_TEST_ALLOW_READING_IMAGES`` and
627 ``BOOST_GIL_IO_TEST_ALLOW_WRITING_IMAGES``.
629 The following list provides all links to the image suites the compiler symbol
632 :BMP: BMP_TEST_FILES_ -- BOOST_GIL_IO_USE_BMP_TEST_SUITE_IMAGES
633 :PNG: PNG_TEST_FILES_ -- BOOST_GIL_IO_USE_PNG_TEST_SUITE_IMAGES
634 :PNM: request files from me -- BOOST_GIL_IO_USE_PNM_TEST_SUITE_IMAGES
635 :TARGA: TARGA_TEST_FILES_ -- BOOST_GIL_IO_USE_TARGA_FILEFORMAT_TEST_SUITE_IMAGES
636 :TIFF: TIFF_LIB_TIFF_TEST_FILES_ -- BOOST_GIL_IO_USE_TIFF_LIBTIFF_TEST_SUITE_IMAGES
637 :TIFF: TIFF_GRAPHICSMAGICK_TEST_FILES_ -- BOOST_GIL_IO_USE_TIFF_GRAPHICSMAGICK_TEST_SUITE_IMAGES
640 .. _BMP_Wiki: http://en.wikipedia.org/wiki/BMP_file_format
641 .. _JPEG_Wiki: http://en.wikipedia.org/wiki/JPEG
642 .. _JPEG_lib: http://www.ijg.org/
643 .. _PNG_Wiki: http://en.wikipedia.org/wiki/Portable_Network_Graphics
644 .. _PNG_Lib: http://libpng.org/pub/png/libpng.html
645 .. _PNM_Wiki: http://en.wikipedia.org/wiki/Portable_anymap
646 .. _RAW_Wiki: http://en.wikipedia.org/wiki/Raw_image_format
647 .. _TARGA_Wiki: http://en.wikipedia.org/wiki/Truevision_TGA
648 .. _RAW_lib: http://www.libraw.org/
649 .. _RAW_Wiki: http://en.wikipedia.org/wiki/Raw_image_format
650 .. _TIFF_Wiki: http://en.wikipedia.org/wiki/Tagged_Image_File_Format
651 .. _TIFF_Lib: http://www.remotesensing.org/libtiff/
652 .. _TIFF_Base_Tags: http://www.awaresystems.be/imaging/tiff/tifftags/baseline.html
653 .. _TIFF_Extension_Tags: http://www.awaresystems.be/imaging/tiff/tifftags/extension.html
654 .. _BMP_TEST_FILES: http://entropymine.com/jason/bmpsuite/
655 .. _PNG_TEST_FILES: http://www.schaik.com/pngsuite/pngsuite.html
656 .. _TARGA_TEST_FILES: http://www.fileformat.info/format/tga/sample/index.htm
657 .. _TIFF_LIB_TIFF_TEST_FILES: http://www.remotesensing.org/libtiff/images.html
658 .. _TIFF_GRAPHICSMAGICK_TEST_FILES: ftp://ftp.graphicsmagick.org/pub/tiff-samples/tiff-sample-images-be.tar.gz