next up previous contents
Next: 3.3 Examples Up: 3. The VIPS image Previous: 3.1 Image descriptors   Contents

3.2 Opening and closing

Descriptors are created with im_open(). This takes a file name and a string representing the mode with which the descriptor is to be opened:

IMAGE *im_open( const char *filename, 
  const char *mode )

The possible values for mode are:

"r"
The file is opened read-only. If you open a non-VIPS image, or a VIPS image written on a machine with a different byte ordering, im_open() will automatically convert it to native VIPS format. If the underlying file does not support random access (JPEG, for example), the entire file will be converted in memory.

VIPS can read images in TIFF, JPEG, PPM/PGM/PBM, PNG and VIPS format, all in both big- and little-endian varieties. You can control the details of the conversion with extra characters embedded in the filename. For example:

fred = im_open( "fred.tif:2", "r" );

will read page 2 of a multi-page TIFF. See the man pages for details.

If VIPS has been built with libMagick, it can also read any of the 80 or so libMagick-supported image file formats.

"w"
An IMAGE descriptor is created which, when written to, will write pixels to disc in the specified file.

VIPS looks at the filename suffix to determine the save format. If there is no suffix, or the filename ends in ".v", the image is written in VIPS native format.

If the filename ends in ".tif" or ".tiff", the image is written with im_vips2tiff(). If the filename ends in ".jpg", ".jpeg" or ".jpe", the image is written with im_vips2jpg(). If the filename ends with ".pbm", ".pgm" or ".ppm", the image is written using im_vips2ppm(). If the filename ends with ".png", the image is written using im_vips2png(). Case is not considered when testing the suffix.

If you want to control the details of the conversion to the disc format (such as setting the Q factor for a JPEG, for example), you embed extra control characters in the filename. For example:

fred = im_open( "fred.jpg:95", "w" );

writes to fred will write a JPEG with Q 95. Again, see the man pages for the conversion functions for details.

"t"
As the "w" mode, but pels written to the descriptor will be saved in a temporary memory buffer.

"p"
This creates a special partial image. Partial images are used to join VIPS operations together, see §3.8.

"rw"
As the "r" mode, but the image is mapped into the caller's address space read-write. This mode is only provided for the use of paintbox-style applications which need to directly modify an image. Most programs should use the "w" mode for image output.

If an error occurs opening the image, im_open() calls im_error() with a string describing the cause of the error and returns NULL. im_error() has type

void im_error( const char *domain,
  const char *format, ... )

The first argument is a string giving the name of the thing that raised the error (just "im_open", for example). The format and subsequent arguments work exactly as printf(). It formats the message and appends the string formed to the error log. You can get a pointer to the error text with im_error_buffer().

const char *im_error_buffer()

Applications may display this string to give users feedback about the cause of the error. The VIPS exit function, error_exit(), prints im_error_buffer() to stderr and terminates the program with an error code of 1.

void error_exit( const char *format, 
  ... )

There are other functions for handling errors: see the man page for im_error().

If the file name given to im_open() ends with ".v", VIPS looks in the same directory as the image for a file with the same name but with the extension ".desc". If present, this file is read in and a pointer to the data put in the Hist field of the descriptor. See the notes on im_updatehist() in §3.3.

Descriptors are closed with im_close(). It has type:

int im_close( IMAGE *im )

im_close() returns 0 on success and non-zero on error. If the descriptor represents a disc file which has been written to and whose name ends in ".v", VIPS writes the Hist field of the image descriptor to a file in the same directory whose name ends in ".desc".


next up previous contents
Next: 3.3 Examples Up: 3. The VIPS image Previous: 3.1 Image descriptors   Contents
John Cupitt 2004-11-02