vigra - Image Import/Export Facilities

[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

| 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, 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, 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, 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.

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany | html generated using doxygen and Python vigra 1.10.0 (Mon Nov 18 2013)