Image Import/Export Facilities

Classes
class	ImageExportInfo
	Argument object for the function exportImage(). More...
class	ImageImportInfo
	Argument object for the function importImage(). More...

Functions
template<... >
void	exportImage (...)
	Write an image to a file. More...
template<... >
void	exportImageAlpha (...)
	Write the image and its alpha channel to a file. More...
std::string	impexListExtensions ()
	List the file extension VIGRA understands. More...
std::string	impexListFormats ()
	List the image formats VIGRA can read and write. More...
template<... >
void	importImage (...)
	Read an image from a file. More...
template<... >
void	importImageAlpha (...)
	Read the image specified by the given vigra::ImageImportInfo object including its alpha channel. More...
bool	isImage (char const *filename)
	Test whether a file is an image format known to VIGRA. More...

Detailed Description

supports GIF, TIFF, JPEG, BMP, EXR, HDR, PNM (PBM, PGM, PPM), PNG, SunRaster, KHOROS-VIFF formats

Function Documentation

std::string vigra::impexListFormats

(

)

List the image formats VIGRA can read and write.

This is useful for creating error messages if VIGRA encounters an image format it doesn't recognize.

Usage:

#include <vigra/imageinfo.hxx>
Namespace: vigra

std::cout << "supported formats: " << vigra::impexListFormats() << std::endl;

Examples:

boundarytensor.cxx, convert.cxx, dissolve.cxx, edge.cxx, graph_agglomerative_clustering.cxx, imageImportInfo_tutorial.cxx, imageIO_tutorial.cxx, invert.cxx, invert_explicitly.cxx, invert_tutorial.cxx, mirror_tutorial.cxx, profile.cxx, pyramid.cxx, resize.cxx, smooth.cxx, smooth_convolve.cxx, smooth_explicitly.cxx, subimage.cxx, subimage_tutorial.cxx, total_variation.cxx, transpose_image_tutorial.cxx, and watershed.cxx.

std::string vigra::impexListExtensions

(

)

List the file extension VIGRA understands.

This is useful for creating file dialogs that only list image files VIGRA can actually import.

Usage:

#include <vigra/imageinfo.hxx>
Namespace: vigra

std::cout << "supported extensions: " << vigra::impexListExtensions() << std::endl;

bool vigra::isImage

(

char const *

filename

)

Test whether a file is an image format known to VIGRA.

This checks the first few bytes of the file and compares them with the "magic strings" of each recognized image format.

Usage:

#include <vigra/imageinfo.hxx>
Namespace: vigra

std::cout << "is image: " << vigra::isImage("foo.bmp") << std::endl;

void vigra::importImage

(

...

)

Read an image from a file.

If the first parameter is vigra::ImageImportInfo, this function assumes that the destination image has already the appropriate shape. If the first parameter is a string, the destination must be a vigra::MultiArray reference, which will be reshaped automatically.

If the input image has only a single band, but the destination has multiple bands (e.g. is an RGB image), all bands will receive the same data. When a multi-band file is read into a single-band destination array, only the first band is read. Any other mismatch between the number of bands in input and output is an error and will throw a precondition exception.

Declarations

pass 2D array views:

namespace vigra {
    // read the data into an array view of appropriate size
    template <class T, class S>
    void
    importImage(ImageImportInfo const & import_info,
                MultiArrayView<2, T, S> image);

    // resize the given array and then read the data
    template <class T, class A>
    void
    importImage(char const * filename,
                MultiArray<2, T, A> & image);

    template <class T, class A>
    void
    importImage(std::string const & filename,
                MultiArray<2, T, A> & image);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class ImageIterator, class Accessor>
    void
    importImage(const ImageImportInfo& importInfo,
                ImageIterator imageIterator, Accessor imageAccessor)
}

Use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class ImageIterator, class Accessor>
    void
    importImage(const ImageImportInfo& importInfo,
                const pair<ImageIterator, Accessor>& image)
}

Usage:

#include <vigra/impex.hxx>
Namespace: vigra

ImageImportInfo info("myimage.gif");

if (info.isGrayscale())
{
    // create byte image of appropriate size
    MultiArray<2, unsigned char> image(info.width(), info.height());

    importImage(info, image);
    ...
}
else
{
    // create byte RGB image of appropriate size
    MultiArray<2, RGBValue<unsigned char> > image(info.width(), info.height());

    importImage(info, image);
    ...
}

When the type of input image is already known, this can be shortened:

// create empty float image
MultiArray<2, float> image;

// resize image and read the data
importImage("myimage.png", image);

show deprecated examples

ImageImportInfo info("myimage.gif");

if (info.isGrayscale())
{
    // create byte image of appropriate size
    BImage image(info.width(), info.height());

    importImage(info, destImage(image));
    ...
}
else
{
    // create byte RGB image of appropriate size
    BRGBImage image(info.width(), info.height());

    importImage(info, destImage(image));
    ...
}

Preconditions

• The image file must be readable.
• The required support library must be installed (if the table doesn't specify an external library, VIGRA supports the format natively).
• The file type must be one of the following:

Type	Extension	Name	Support Library
BMP	bmp	Microsoft Windows bitmap image file
EXR	exr	OpenEXR high dynamic range image format	libopenexr
GIF	gif	CompuServe graphics interchange format, 8-bit color
HDR	hdr	Radiance RGBE high dynamic range image format
JPEG	jpg, jpeg	Joint Photographic Experts Group JFIF format, 24-bit color	libjpeg
PBM	pbm	Portable bitmap format (black and white)
PGM	pgm	Portable graymap format (gray scale)
PNG	png	Portable Network Graphic	libpng
PNM	pnm	Portable anymap
PPM	ppm	Portable pixmap format (color)
SUN	ras	SUN Rasterfile
TIFF	tif, tiff	Tagged Image File Format	libtiff
VIFF	xv	Khoros Visualization image file

Examples:

boundarytensor.cxx, composite.cxx, convert.cxx, dissolve.cxx, edge.cxx, graph_agglomerative_clustering.cxx, imageIO_tutorial.cxx, invert.cxx, invert_explicitly.cxx, invert_tutorial.cxx, mirror_tutorial.cxx, profile.cxx, pyramid.cxx, smooth.cxx, smooth_convolve.cxx, smooth_explicitly.cxx, subimage.cxx, subimage_tutorial.cxx, total_variation.cxx, transpose_image_tutorial.cxx, and watershed.cxx.

void vigra::exportImage

(

...

)

Write an image to a file.

The file can be specified either by a file name or by a vigra::ImageExportInfo object. In the latter case, you have much more control about how the file is written. By default, the file format to be created is guessed from the filename extension. This can be overridden by an explicit file type in the ImageExportInfo object. If the file format supports compression (e.g. JPEG and TIFF), default compression parameters are used which can be overridden by the ImageExportInfo object.

If the file format to be created supports the pixel type of the source image, this pixel type will be kept in the file (e.g. float can be stored by TIFF without conversion) unless the ImageExportInfo object explicitly requests a different storage type. If the array's pixel type is not supported by the file format, the pixel values are transformed to the range 0..255 and converted to unsigned char, unless another mapping is explicitly requested by the ImageExportInfo object.

Currently, the following file formats are supported. The pixel types given in brackets are those that are written without conversion:

• BMP: Microsoft Windows bitmap image file (pixel types: UINT8 as gray and RGB);
• GIF: CompuServe graphics interchange format, 8-bit color (pixel types: UINT8 as gray and RGB);
• JPEG: Joint Photographic Experts Group JFIF format, compressed 24-bit color (pixel types: UINT8 as gray and RGB), only available if libjpeg is installed;
• PNG: Portable Network Graphic (pixel types: UINT8 and UINT16 with up to 4 channels), only available if libpng is installed;
• PBM: Portable bitmap format (black and white);
• PGM: Portable graymap format (pixel types: UINT8, INT16, INT32 as gray scale);
• PNM: Portable anymap (pixel types: UINT8, INT16, INT32 as gray and RGB);
• PPM: Portable pixmap format (pixel types: UINT8, INT16, INT32 as RGB);
• SUN: SUN Rasterfile (pixel types: UINT8 as gray and RGB);
• TIFF: Tagged Image File Format (pixel types: UINT8, INT16, INT32, FLOAT, DOUBLE with up to 4 channels), only available if libtiff is installed;
• VIFF: Khoros Visualization image file (pixel types: UINT8, INT16, INT32, FLOAT, DOUBLE with arbitrary many channels);

Declarations

pass 2D array views:

namespace vigra {
    template <class T, class S>
    void
    exportImage(MultiArrayView<2, T, S> const & image,
                ImageExportInfo const & export_info);

    template <class T, class S>
    void
    exportImage(MultiArrayView<2, T, S> const & image,
                char const * filename);

    template <class T, class S>
    void
    exportImage(MultiArrayView<2, T, S> const & image,
                std::string const & filename);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class ImageIterator, class ImageAccessor>
    void
    exportImage(ImageIterator imageUpperLeft, ImageIterator imageLowerRight, ImageAccessor imageAccessor,
                const ImageExportInfo& exportInfo)
}

Use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class ImageIterator, class ImageAccessor>
    void exportImage(ImageIterator imageUpperLeft, ImageIterator imageLowerRight, ImageAccessor imageAccessor,
                     const ImageExportInfo& exportInfo)
}

Usage:

#include <vigra/impex.hxx>
Namespace: vigra

MultiArray<2, RGBValue<unsigned char> > image(width, height);
...

// write as JPEG image, using compression quality 80
exportImage(image,
            ImageExportInfo("my-image.jpg").setCompression("80"));

// Force it to a particular pixel type.  The pixel type must be supported by the
// desired image file format, otherwise an \ref vigra::PreconditionViolation
// exception will be thrown.
exportImage(image,
            ImageExportInfo("my-INT16-image.tif").setPixelType("INT16"));

show deprecated examples

BRGBImage image(width, height);
...

// write as JPEG image, using compression quality 80
exportImage(srcImageRange(image),
            ImageExportInfo("my-image.jpg").setCompression("80"));

// Force it to a particular pixel type.  The pixel type must be supported by the
// desired image file format, otherwise an \ref vigra::PreconditionViolation
// exception will be thrown.
exportImage(srcImageRange(image),
            ImageExportInfo("my-INT16-image.tif").setPixelType("INT16"));

Preconditions

• The image file must be writable and
• the file type must be one of the supported file types.

Examples:

boundarytensor.cxx, composite.cxx, convert.cxx, dissolve.cxx, edge.cxx, graph_agglomerative_clustering.cxx, imageExportInfo_tutorial.cxx, imageIO_tutorial.cxx, invert.cxx, invert_explicitly.cxx, invert_tutorial.cxx, mirror_tutorial.cxx, palette.cxx, profile.cxx, pyramid.cxx, smooth.cxx, smooth_convolve.cxx, smooth_explicitly.cxx, subimage.cxx, subimage_tutorial.cxx, total_variation.cxx, transpose_image_tutorial.cxx, voronoi.cxx, and watershed.cxx.

void vigra::importImageAlpha

(

...

)

Read the image specified by the given vigra::ImageImportInfo object including its alpha channel.

See importImage() for more information.

Declarations

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2>
    void
    importImageAlpha(ImageImportInfo const & import_info,
                     MultiArrayView<2, T1, S1> image,
                     MultiArrayView<2, T2, S2> alpha);
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class ImageIterator, class ImageAccessor,
              class AlphaIterator, class AlphaAccessor>
    void
    importImageAlpha(const ImageImportInfo& importInfo,
                     ImageIterator imageIterator, ImageAccessor imageAccessor,
                     AlphaIterator alphaIterator, AlphaAccessor alphaAccessor)
}

Use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class ImageIterator, class ImageAccessor,
              class AlphaIterator, class AlphaAccessor>
    void
    importImageAlpha(const ImageImportInfo& importInfo,
                     const pair<ImageIterator, ImageAccessor>& image,
                     const pair<AlphaIterator, AlphaAccessor>& alpha)
}

Usage:

#include <vigra/impexalpha.hxx>
Namespace: vigra

typedef UInt8 value_t;
ImageImportInfo info("zorro.tif");

if (info.isGrayscale())
{
    MultiArray<2, value_t> alpha(info.shape());
    MultiArray<2, value_t> image(info.shape());

    importImageAlpha(info, image, alpha);
    ...
}
else
{
    MultiArray<2, value_t>            alpha(info.shape());
    MultiArray<2, RGBValue<value_t> > image(info.shape());

    importImageAlpha(info, image, alpha);
    ...
}

show deprecated examples

typedef UInt8 value_t;
ImageImportInfo info("zorro.tif");

if (info.isGrayscale())
{
    BasicImage<value_t> alpha(info.size());
    BasicImage<value_t> image(info.size());

    importImageAlpha(info,
                     image.upperLeft(), image.accessor(),
                     alpha.upperLeft(), alpha.accessor());
    ...
}
else
{
    BasicImage<value_t> alpha(info.size());
    BasicImage<vigra::RGBValue<value_t> > image(info.size());

    importImageAlpha(info,
                     image.upperLeft(), image.accessor(),
                     alpha.upperLeft(), alpha.accessor());
    ...
}

Preconditions

• The same preconditions hold as for importImage(), however the only image formats that support alpha channels are
  • TIFF and
  • PNG. In particular, JPEG does not support alpha channels.
• The alpha channel always is scalar-valued, i.e. comprises a single band.

void vigra::exportImageAlpha

(

...

)

Write the image and its alpha channel to a file.

See exportImage() for more information.

Declarations

pass 2D array views:

namespace vigra {
    template <class T1, class S1,
              class T2, class S2>
    void
    exportImageAlpha(MultiArrayView<2, T1, S1> const & image,
                     MultiArrayView<2, T2, S2> const & alpha,
                     ImageExportInfo const & export_info);

    template <class T1, class S1,
              class T2, class S2>
    void
    exportImageAlpha(MultiArrayView<2, T1, S1> const & image,
                     MultiArrayView<2, T2, S2> const & alpha,
                     char const * filename)

    template <class T1, class S1,
              class T2, class S2>
    void
    exportImageAlpha(MultiArrayView<2, T1, S1> const & image,
                     MultiArrayView<2, T2, S2> const & alpha,
                     std::string const & filename)
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class ImageIterator, class ImageAccessor,
              class AlphaIterator, class AlphaAccessor>
    void
    exportImageAlpha(ImageIterator imageUpperLeft, ImageIterator imageLowerRight, ImageAccessor imageAccessor,
                     AlphaIterator alphaUpperLeft, AlphaAccessor alphaAccessor,
                     const ImageExportInfo& exportInfo)
}

Use argument objects in conjunction with Argument Object Factories :

namespace vigra {
template <class ImageIterator, class ImageAccessor,
          class AlphaIterator, class AlphaAccessor>
void
exportImageAlpha(const triple<ImageIterator, ImageIterator, ImageAccessor>& image,
                 const pair<AlphaIterator, AlphaAccessor>& alpha,
                 const ImageExportInfo& exportInfo)
}

Usage:

#include <vigra/impexalpha.hxx>
Namespace: vigra

 typedef UInt8 value_t;

 MultiArray<2, value_t>            alpha(width, height);
 MultiArray<2, RGBValue<value_t> > image(width, height);

... // do some image processing

 // specify the output filename 
 exportImageAlpha(image, alpha, "zorro.tif");
 
 // use a ImageExportInfo if you need more control over the export
 exportImageAlpha(image, alpha, ImageExportInfo("zorro.tif").setPixelType("FLOAT"));

show deprecated examples

typedef UInt8 value_t;
ImageExportInfo info("zorro.tif");

if (info.isGrayscale())
{
    BasicImage<value_t> alpha;
    BasicImage<value_t> image;

    ...

    exportImageAlpha(image.upperLeft(), image.lowerRight(), image.accessor(),
                     alpha.upperLeft(), alpha.accessor(),
                     info);
}
else
{
    BasicImage<value_t> alpha;
    BasicImage<vigra::RGBValue<value_t> > image;

    ...

    exportImageAlpha(image.upperLeft(), image.lowerRight(), image.accessor(),
                     alpha.upperLeft(), alpha.accessor(),
                     info);
}

Preconditions

• The same preconditions hold as for exportImage(), however the only image formats that support alpha channels are
  • TIFF and
  • PNG. In particular, JPEG does not support alpha channels.
• The alpha channel always is scalar-valued, i.e. comprises a single band.