#include <gandalf/image/io/image_io.h>
Currently Gandalf supports six image file formats: PNG, PBM, PGM, PPM, TIFF
and JPEG. These are described by the
/* image file formats supported by Gandalf */
typedef enum
{
GAN_PNG_FORMAT, /**< PNG image format */
GAN_PBM_FORMAT, /**< Portable bitmap image format */
GAN_PGM_FORMAT, /**< Portable greymap image format */
GAN_PPM_FORMAT, /**< Portable pixmap image format */
GAN_TIFF_FORMAT, /**< TIFF image format */
GAN_JPEG_FORMAT, /**< JPEG image format */
GAN_UNKNOWN_FORMAT /**< Unknown Image Format */
} Gan_ImageFileFormat;
PBM, PGM and PPM are very simple formats, for boolean, grey-level and
RGB colour image formats respectively, and the code to implement I/O in those
formats is built into Gandalf, although currently only binary file formats
are supported. PNG, TIFF and JPEG formats are considerably
more complex, and require specific libraries to be installed.
The Gandalf configure script detects the presence of the PNG,
TIFF and JPEG libraries, and only compiles
in the I/O code for those formats when the relevant libraries
are detected on the host system.
The image_io.h header file contains declaration of the basic image I/O functions. To read a image from a PNG image file, for instance, you can use the code
Gan_Image *pImage;
/* read the image from a file in PNG format */
pImage = gan_image_read ( "image1.png", GAN_PNG_FORMAT, NULL );
The first argument is the file name, the second the file format (Gandalf
doesn't currently support automatic file format determination via magic
numbers. Who wants to volunteer?). The last argument is either a pointer
to an already created image structure or NULL, as here. In the latter
case the image is created inside the gan_image_read() function
and returned.
To write an RGB unsigned character image to a PNG file you could write
Gan_Image *pRGBImage;
/* ... create and fill RGB unsigned character image ... */
/* output the image to a file in PNG format */
gan_image_write ( "image1.png", GAN_PNG_FORMAT, pRGBImage, 0.0 );
We recommend that where possible you should use the PNG format. It is the
most flexible of the formats supported by Gandalf, allowing alpha channels
to be stored with the image, and also supporting binary images. PPM images
are restricted to unsigned character type (GAN_UCHAR), while
PGM format supports unsigned character and binary (GAN_BOOL) type.
However the binary support in PGM files is very inefficient, storing
one byte per pixel, so again PNG is the better format.