Image file I/O

      #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
Gan_ImageFormat enumerated type:

      /* 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.