[boost] [gil] new io extension

Subject: [boost] [gil] new io extension
From: Christian Henning (chhenning_at_[hidden])
Date: 2008-09-23 13:56:29

Hi there, I've been busy working on the next version of gil's IO
extension. The last iteration was very slow to compile especially when
reading or writing tiff images. This and other problems have been
fixed. As a result compilation is a lot faster but also a lot more
tiff formats can now be read or written.

Please grab the latest from:

http://gil-contributions.googlecode.com/svn/trunk/gil_2/boost/gil/extension/io_new

This download is a little bigger than to usual since there are test
images included.

Please see my original announcement below for documentation. The goal
of this extension is to substitute the original io lib which is part
of gil, and though shipped with boost. To do this a review is probably
needed. I'll work on a proper documentation as the next step. Can
anyone tell me where to find a tutorial for creating quickdoc?

There is one problem I cannot fix and would like to ask the experts on
this list. Please read the readme.txt in libs\gil\io_new\unit_test
which explains the scenario. This problem has something to do with
erroneously choosing the wrong functions by the compiler. The
enable_if metafunction doesn't work correctly here.

As usual any feedback is welcome.

Thanks,
Christian

-------------------------------------------------------

Hi there, over the past few months I have been working on a new
version of gil's io extension. In this release I've added support for:

* more image formats, most importantly bit_aligned images ( like 1bit images ),
* reading of subimages like one row at a time for huge images,
* reading image information, only.
* having a unified interface for all sorts of devices, subimages, and
converter objects.

So far, png, jpeg, and tiff images are supported. In the not so
distant future there will be bmp and pnm images added.

You can grab the current version via subversion from:

https://gil-contributions.googlecode.com/svn/trunk/gil_2/boost/gil/extension/io_new

If desired I can supply a zip file to the vault.

The images libraries can be grabbed from:

ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz ( www.ijg.org isn't
responding )
http://www.libpng.org/pub/png/libpng.html
http://www.libtiff.org/

It's highly advised to built your own version of the image lib you
need. I installed the GNU's binaries for Windows, but unfortunately, I
only had problems with them.

The library is still header-only. When using boost::filesystem's
paths, of course, you add a dependency to the filesystem lib.

The Read Interface
------------------------

Reading an image can be done in multiple ways depending on what your
need is. Like the old io lib there are 4 different ways of reading
images. As there are:

* read_image: Read image, the right amount of memory will be allocated
beforehand. The supplied image type needs to be compatible with actual
image file.

* read_view: Read image, the image's memory must be already allocated.
 The supplied image type needs to be compatible with actual image
file.

* read_and_convert_image: Same as read_image, but the user can specify
an color converter.

* read_and_convert_view: Same as read_view, but the user can specify
an color converter.

There is a new function for reading image information. Since every
image format has it's own set of tags, the library defines seperate
image_read_info<format_tag> structures. Please see, for instance, the
jpeg_tags.hpp header.

As for the function parameters the following sections in the same order.

1. String for file name ( std::string, std::wstring, char*,
boost::filesystem::path ) OR devices ( FILE*, TIFF*, std::ifstream )

2. Image or view type

3. Optional: Subimage definition ( top_left corner + dimensions )

4. Optional: Color converter. This parameter is only valid for
converting functions. The default parameter is gil's
default_color_converter

5. Format Tag.

Reading the image information only takes parameter 1 and 5.

Here are some examples for reading images:

#include <boost/gil/extension/io_new/jpeg_read.hpp>

// Read image information
std::string filename( "..\\test_images\\jpg\\found online\\test.jpg" );
image_read_info< jpeg_tag > info = read_image_info( filename, tag_t() );

// Read image
FILE* file = fopen( filename.c_str(), "rb" );
rgb8_image_t img;
read_image( file, img, tag_t() );

// Read image
ifstream in( filename.c_str(), ios::in | ios::binary );
rgb8_image_t img( 136, 98 );
read_view( in, view( img ), tag_t() );

// Read and convert image, use gil's default converter.
rgb8_image_t img;
read_and_convert_image( filename, img, tag_t() );

// Read a 10x10 subimage, starting from the top_left corner.
rgb8_image_t img;
read_image( filename, img, point_t( 0,0 ), point_t( 10, 10 ), tag_t() );

I have created some header files to support the old read interface. For example:

#include <boost/gil/extension/io_new/jpeg_io_old.hpp>

std::string filename( "..\\test_images\\jpg\\found online\\test.jpg" );
rgb8_image_t img( 136, 98 );
jpeg_read_view( filename, view( img ) );

The Write Interface
---------------------------
The write interface is a much simpler than the read interface. Here,
we only have write_view as the entry point. As for parameters the
following sections are supported:

1. String for file name ( std::string, std::wstring, char*,
boost::filesystem::path ) or devices ( FILE*, TIFF*, std::ofstream )

2. View type

3. Optional: image_write_info< FormatTag >

4. Format type

The image_write_info<...> structure defines a format specific
properties which can be used when writing an image. A good example is
jpeg's image quality value.

Examples:

#include <boost/gil/extension/io_new/tiff_write.hpp>

// Write image
string filename( "..\\test\\tiff\\test1.tif" );
gray8_image_t img( 320, 240 );
write_view( filename, view( img ), tiff_tag() );

// Write image
string filename( "..\\test\\tiff\\test2.tif" );
TIFF* file = TIFFOpen( filename.c_str(), "w" );
rgb8_image_t img( 320, 240 );
write_view( file, view( img ), tag_t() );

I have created some header files to support the old write interface.
For example:

#include <boost/gil/extension/io_new/tiff_io_old.hpp>

string filename( "..\\test\\tiff\\test3.tif" );
gray8_image_t img( 320, 240 );
tiff_write_view( filename, view( img ) );

The primary goal of this new version is to eventually replace the old
io library which is part of boost's distribution. Do I need to apply
for a review? I'm not sure how to go from here.

I know there is still some work to do before a possible review.
Documentation is lacking and support for dynamic image needs to be
added. But what I want for now is to get some feedback on design and
implementation.

I would like to thank Lubomir Bourdev and Andreas Pokorny for their
most valueable input.

Thanks,
Christian