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

Functions
Image Import/Export Facilities

## Functions

template<...>
void | exportImage (...)
| Write an image to a file.
template<...>
void | exportImageAlpha (...)
| Write the image and its alpha channel to a file.
template<...>
void | importImage (...)
| Read an image from a file.
template<...>
void | importImageAlpha (...)
| Read the image specified by the given ImageImportInfo object including its alpha channel.

## Detailed Description

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

## Function Documentation

## ◆ importImage()

template<...>

void importImage | ( |  | ... | ) |

Read an image from a file.

If the first parameter is 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 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);
}
vigra::ImageImportInfo
Argument object for the function importImage().
Definition imageinfo.hxx:391
vigra::MultiArrayView
Base class for, and view to, MultiArray.
Definition multi_array.hxx:705
vigra::MultiArray
Main MultiArray class containing the memory management.
Definition multi_array.hxx:2483
vigra::importImage
void importImage(...)
Read an image from a file.
vigra

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)
}
vigra::Accessor
vigra::ImageIterator
Standard 2D random access iterator for images that store the data in a linear array.
Definition imageiterator.hxx:851
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));
...
}
vigra::BRGBImage
BasicImage< RGBValue< UInt8 > > BRGBImage
Definition stdimage.hxx:164
vigra::BImage
BasicImage< UInt8 > BImage
Definition stdimage.hxx:62

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.

## ◆ exportImage()

template<...>

void exportImage | ( |  | ... | ) |

Write an image to a file.

The file can be specified either by a file name or by a 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);
}
vigra::ImageExportInfo
Argument object for the function exportImage().
Definition imageinfo.hxx:134
vigra::exportImage
void exportImage(...)
Write an image to a file.

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.

## ◆ importImageAlpha()

template<...>

void importImageAlpha | ( |  | ... | ) |

Read the image specified by the given 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);
}
vigra::importImageAlpha
void importImageAlpha(...)
Read the image specified by the given ImageImportInfo object including its alpha channel.

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);
...
}
vigra::UInt8
detail::SelectIntegerType< 8, detail::UnsignedIntTypes >::type UInt8
8-bit unsigned int
Definition sized_int.hxx:179

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.

## ◆ exportImageAlpha()

template<...>

void 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)
}
vigra::exportImageAlpha
void exportImageAlpha(...)
Write the image and its alpha channel to a file.

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);
}
vigra::BasicImage::accessor
Accessor accessor()
Definition basicimage.hxx:1066
vigra::BasicImage::lowerRight
traverser lowerRight()
Definition basicimage.hxx:936
vigra::BasicImage::upperLeft
traverser upperLeft()
Definition basicimage.hxx:925

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