![]() |
Home | Libraries | People | FAQ | More |
Thanks to modern C++ programming techniques the interface for this library is rather small and easy to use. In this tutorial I'll give you a short walk-around on how to use this boost::gil extension. For more details please refer to section 3.
Since this is an extension to boost::gil I expect the user to have some very basic understanding of the gil ( generic image library ). Please see here for the help.
The header files to be included all have the same format. For instance, tiff_all.hpp will allow to read and write. Whereas, tiff_read.hpp only allows for reading. If the user only wants to write jpeg's include jpeg_write.hpp. All formats provide these three types of header files:
xxx stands for image format.
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 he/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 Supported Image Formats for more details.
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 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.