IM_OPEN(3)

NAME
im_open, im_open_local, im_open_local_array, im_open_header - open VIPS image descriptor(s)

SYNOPSIS
#include <vips/vips.h> IMAGE *im_open( const char *filename, const char *mode ) IMAGE *im_open_header( const char *filename ) IMAGE *im_open_local( IMAGE *im, const char *filename, const char *mode ) int im_open_local_array( IMAGE *im,
  IMAGE **out, int n, const char *filename, const char *mode )

DESCRIPTION
im_open(3) examines the mode string, and creates an appropriate VIPS IMAGE descriptor. See `VIPS Library Programmers' Guide,' for an introduction to IMAGE input and output. r opens the named file for reading. If the file is not in the native VIPS format for your machine, im_open(3) automatically converts the file for you in memory. For some large files (eg. TIFF) this may not be what you want: you should call the appropriate converter yourself, and arrange for the conversion to take place on disc. See im_tiff2vips(3), im_jpeg2vips(3), im_png2vips(3), im_magick2vips(3), and im_ppm2vips(3). im_open(3) can read files in most formats. w opens the named file for writing. It looks at the file name suffix to determine the type to write -- for example:
  im_open( "fred.tif", "w" ) will write in TIFF format. You can pass parameters to the conversion functions encoded in the filename string. For example:
  im_open( "fred.tif:deflate", "w" ) will write a deflate (ZIP) compressed TIFF file. See the man pages for im_vips2tiff(3), im_vips2jpeg(3), im_vips2png(3) and im_vips2ppm(3) for details on all of the options available. t creates a temporary memory buffer image. p creates a "glue" descriptor you can use to join two image processing operations together. rw opens the named file for reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications. im_open_header(3) opens just the header of the image file. You can test all fields (such as Xsize or Ysize), but you can't read any image data. This is (usually) faster than im_open(). im_open_local(3) is a convenience function which opens an image descriptor as im_open(3), but makes it local to im, that is, when im is closed, the descriptor created by im_open_local(3) will be closed too. im_open_local(3) is handy for saving you from adding many im_close(3) calls to escape points. Example: find the total of an array of images.
  #include <vips/vips.h>
  #include <vips/region.h>
  int
  total( IMAGE **in, int nin, IMAGE *out )
  {
    int i;
    IMAGE *t1, *t2;
    if( nin <= 0 ) {
      im_errormsg( "total: nin should be > 0" );
      return( -1 );
    }
    else if( nin == 1 )
      return( im_copy( *in, out ) );
    else
      for( t1 = *in, i = 1; i < nin; i++ ) {
        if( i + 1 == nin )
      t2 = out;
    else if( !(t2 = im_open_local( out, "t2", "p" )) )
          return( -1 );
        if( im_add( t1, in[i], t2 ) )
          return( -1 );
        t1 = t2;
      }
    return( 0 );
  } This function will create many intermediate images, but does not need to close them. Any which are created will be closed automatically when out is closed by our caller. im_open_local(3) returns NULL on error, or if its first parameter is NULL. im_open_local_array(3) will open an array of images, failing if any of the opens fail. It's handy if you need a number of images for intermediates. Example:
  IMAGE *t[6];
  if( im_open_local_array( out, t, 6, "mytemps", "p" ) )
    return( -1 ); opens 6 temp images (t[0] to t[5]).

RETURN VALUE
The function returns the image descriptor on success and NULL on error.

SEE ALSO
im_close(3), im_vips2tiff(3), im_vips2jpeg(3), im_vips2ppm(3), im_tiff2vips(3), im_jpeg2vips(3), im_ppm2vips(3), `VIPS Library Programmers' Guide,' in accompanying documentation.

COPYRIGHT
K. Martinez, 1992.

AUTHOR
K. Martinez.