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 named is opened read-only and an IMAGE descriptor is returned with all the fields filled in.

If you open a non-VIPS image, or a VIPS image written on a machine with a different byte ordering, im_open() will use one of the conversion functions (eg. see the man page for im_tiff2vips()) to make the image readable. For big images this can require a large amount of RAM -- you might be better off allocating a disc file and calling the conversion function yourself..

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" );

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

"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 below.

"w"
An IMAGE descriptor is created which, when written to, will write pels 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.

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

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

The arguments to im_errormsg() works 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_errorstring().

const char *im_errorstring()

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

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

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, setting im_errorstring(). 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 2003-07-21