Reading An Image

Probably the most common case to read a tiff image can be done as follows:

std::string filename( "image.tif" );
rgb8_image_t img;
read_image( filename, img, tiff_tag() );

The code would be same for all other image formats. The only thing that needs to change is the tag type ( tiff_tag ) in the read_image call. The read_image() expects the supplied image type to be compatible with the image stored in the file. If the user doesn’t know what format an image has she can use read_and_convert_image(). Another important fact is that read_image() will allocate the appropriate memory needed for the read operation. There are read_view or read_and_convert_view counterparts, if the memory is already allocated.

Sometimes the user only wants to read a sub-part of an image, then the above call would look as follows:

read_image( filename
          , img
          , image_read_settings< tiff_tag >( point_t( 0, 0 ), point_t( 50, 50 ) )
          );

The image_read_settings class will provide the user with image format independent reading setting but can also serves as a pointer for format dependent settings. Please see the specific image format sections [link gil.io.using_io.supported_image_formats Supported Image Formats] for more details.

Writing An Image

Besides reading the information also writing is the second part of this Boost.GIL extension. Writing is a lot simpler than reading since an existing image view contains all the information.

For instance writing an image can be done as follows:

std::string filename( "image.tif" );
rgb8_image_t img( 640, 480 );

// write data into image

write_view( filename
          , view( img )
          , tiff_tag()
          );

The interface is similar to reading an image. To add image format specific parameter the user can use image_write_info class. For instance, a user can specify the JPEG quality when writing like this:

std::string filename( "image.jpg" );
rgb8_image_t img( 640, 480 );

// write data into image

write_view( filename
          , view( img )
          , image_write_info< jpeg_tag >( 95 )
          );

The above example will write an image where the jpeg quality is set to 95 percent.

Reading And Writing In-Memory Buffers

Reading and writing in-memory buffers are supported as well. See as follows:

// 1. Read an image.
ifstream in( "test.tif", ios::binary );

rgb8_image_t img;
read_image( in, img, tiff_tag() );

// 2. Write image to in-memory buffer.
stringstream out_buffer( ios_base::out | ios_base::binary );

rgb8_image_t src;
write_view( out_buffer, view( src ), tiff_tag() );

// 3. Copy in-memory buffer to another.
stringstream in_buffer( ios_base::in | ios_base::binary );
in_buffer << out_buffer.rdbuf();

// 4. Read in-memory buffer to gil image
rgb8_image_t dst;
read_image( in_buffer, dst, tag_t() );

// 5. Write out image.
string filename( "out.tif" );
ofstream out( filename.c_str(), ios_base::binary );
write_view( out, view( dst ), tiff_tag() );

In case the user is using his own stream classes he has to make sure it has the common interface read, write, seek, close, etc. Interface.

General Overview

The tutorial pointed out some use cases for reading and writing images in various image formats. This section will provide a more thorough overview.

The next sections will introduce the Read and Write interface. But it might be worth pointing out that by using some advanced metaprogramming techniques the interface is rather small and hopefully easy to understand.

Besides the general interface the user also has the ability to interface directly with the underlying image format. For that each reader or writer provides access to the so-called backend.

For instance:

typedef bmp_tag tag_t;

typedef get_reader_backend< const std::string
                          , tag_t
                          >::type backend_t;

backend_t backend = read_image_info( bmp_filename
                                   , tag_t()
                                   );

BOOST_CHECK_EQUAL( backend._info._width , 127 );
BOOST_CHECK_EQUAL( backend._info._height, 64 );

Of course, the typedef can be removed when using c++11’s auto feature.

Read Interface

As the Tutorial demonstrated there are a few ways to read images. Here is an enumeration of all read functions with a short description:

• read_image - read into a gil image with no conversion. Memory is allocated.

• read_view - read into a gil view with no conversion.

• read_and_convert_image - read and convert into a gil image. Memory is allocated.

• read_and_convert_view - read and convert into a gil view.

• read_image_info - read the image header.

Conversion in this context is necessary if the source (file) has an incompatible color space with the destination (gil image type). If that’s the case the user has to use the xxx_and_convert_xxx variants.

All functions take the filename or a device as the first parameter. The filename can be anything from a C-string, std::string, std::wstring to std::filesystem and boost::filesystem path. The availability of the std::filesystem is detected automatically, unless BOOST_GIL_IO_USE_BOOST_FILESYSTEM macro is defined that forces preference of the Boost.Filesystem. Devices could be a FILE*, std::ifstream, and TIFF* for TIFF images.

The second parameter is either an image or view type depending on the read_xxx function. The third and last parameter is either an instance of the image_read_settings<FormatTag> or just the FormatTag. The settings can be various depending on the format which is being read. But the all share settings for reading a partial image area. The first point describes the top left image coordinate whereas the second are the dimensions in x and y directions.

Here an example of setting up partial read:

read_image( filename
          , img
          , image_read_settings< tiff_tag >( point_t( 0, 0 ), point_t( 50, 50 ) )
          );

Each format supports reading just the header information, using read_image_info. Please refer to the format specific sections under 3.3. A basic example follows:

image_read_info< tiff_t > info = read_image_info( filename
                                                , tiff_t()
                                                );

GIL also comes with a dynamic image extension. In the context of GIL.IO a user can define an any_image type based on several image types. The IO extension would then pick the matching image type to the current image file. The following example shows this feature:

any_image< gray8_image_t
         , gray16_image_t
         , rgb8_image_t
         , rgba8_image_t
         > runtime_image;

read_image( filename
          , runtime_image
          , tiff_tag()
          );

During the review it became clear that there is a need to read big images scanline by scanline. To support such use case a scanline_reader is implemented for all supported image formats. The scanline_read_iterators will then allow to traverse through the image. The following code sample shows the usage:

typedef tiff_tag tag_t;

typedef scanline_reader< typename get_read_device< const char*
                                                 , tag_t
                                                 >::type
                        , tag_t
                        > reader_t;

reader_t reader = make_scanline_reader( "C:/boost/libs/gil/test/extension/io/images/tiff/test.tif", tag_t() );

typedef rgba8_image_t image_t;

image_t dst( reader._info._width, reader._info._height );
fill_pixels( view(dst), image_t::value_type() );

typedef reader_t::iterator_t iterator_t;

iterator_t it  = reader.begin();
iterator_t end = reader.end();

for( int row = 0; it != end; ++it, ++row )
{
    copy_pixels( interleaved_view( reader._info._width
                                    , 1
                                    , ( image_t::view_t::x_iterator ) *it
                                    , reader._scanline_length
                                    )
                , subimage_view( view( dst )
                                , 0
                                , row
                                , reader._info._width
                                , 1
                                )
                );
}

There are many ways to traverse an image but for as of now only by scanline is supported.

Write Interface

There is only one function for writing out images, write_view. Similar to reading the first parameter is either a filename or a device. The filename can be anything from a C-string, std::string, std::wstring to std::filesystem and boost::filesystem path. The availability of the std::filesystem is detected automatically, unless BOOST_GIL_IO_USE_BOOST_FILESYSTEM macro is defined that forces preference of the Boost.Filesystem. Devices could be FILE*, std::ifstream, and TIFF* for TIFF images.

The second parameter is an view object to image being written. The third and last parameter is either a tag or an image_write_info<FormatTag> object containing more settings. One example for instance is the JPEG quality. Refer to the format specific sections under 3.3. to have a list of all the possible settings.

Writing an any_image<…> is supported. See the following example:

any_image< gray8_image_t
         , gray16_image_t
         , rgb8_image_t
         , rgba8_image_t
         > runtime_image;

// fill any_image

write_view( filename
          , view( runtime_image )
          , tiff_tag()
          );

Compiler Symbols

The following table gives an overview of all supported compiler symbols that can be set by the user:

Supported Image Formats

Extending GIL::IO with new Formats

Extending the gil::io with new formats is meant to be simple and straightforward. Before adding I would recommend to have a look at existing implementations and then trying to follow a couple of guidelines:

• Create the following files for your new xxx format

  • xxx_read.hpp - Only includes read code

  • xxx_write.hpp - Only includes write code

  • xxx_all.hpp - includes xxx_read.hpp and xxx_write.hpp

• Add the code to the boost::gil::detail namespace

• Create a tag type for the new format. Like this:

  struct xxx_tag : format_tag {};
  

• Create the image_read_info for the new format. It contains all the information that are necessary to read an image. It should be filled and returned by the get_info member of the reader class. See below:

  template<> struct image_read_info< xxx_tag > {};
  

• Create the image_write_info for the new format. It contains all the information that are necessary to write an image:

  template<> struct image_write_info< xxx_tag > {};
  

• Use the following reader skeleton as a start:

  template< typename Device
          , typename ConversionPolicy
          >
  class reader< Device
              , xxx_tag
              , ConversionPolicy
              >
              : public reader_base< xxx_tag
                                  , ConversionPolicy
                                  >
  {
  private:
  
      typedef typename ConversionPolicy::color_converter_type cc_t;
  
  public:
  
      reader( Device& device )
      : _io_dev( device )
      {}
  
      reader( Device&     device
            , const cc_t& cc
            )
      : _io_dev( device )
      , reader_base< xxx_tag
                   , ConversionPolicy
                   >( cc )
      {}
  
      image_read_info< xxx_tag > get_info()
      {
          // your implementation here
      }
  
      template< typename View >
      void apply( const View& dst_view )
      {
          // your implementation here
      }
  };
  

• The writer skeleton:

  template< typename Device >
  class writer< Device
              , xxx_tag
              >
  {
  public:
  
      writer( Device & file )
      : out(file)
      {}
  
      template<typename View>
      void apply( const View& view )
      {
          // your implementation here
      }
  
      template<typename View>
      void apply( const View&                        view
                , const image_write_info< xxx_tag >& info )
      {
          // your implementation here
      }
  };