| .TH IM_OPEN 3 "30 October 1992" |
| .SH NAME |
| im_open, im_open_local, im_open_local_array \- open VIPS |
| image descriptor(s) |
| .SH SYNOPSIS |
| #include <vips/vips.h> |
| |
| IMAGE *im_open( const char *filename, const char *mode ) |
| |
| 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 ) |
| |
| .SH DESCRIPTION |
| .B im_open(3) |
| examines the mode string, and creates an appropriate VIPS IMAGE descriptor. |
| |
| .B "r" |
| opens the named file for reading. If the file is not in the native VIPS format |
| for your machine, |
| .B 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 |
| .B im_tiff2vips(3), |
| .B im_jpeg2vips(3), |
| .B im_png2vips(3), |
| .B im_magick2vips(3), |
| and |
| .B im_ppm2vips(3). |
| |
| .B im_open(3) |
| can read files in most formats. |
| |
| .B "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 |
| .B im_vips2tiff(3), |
| .B im_vips2jpeg(3), |
| .B im_vips2png(3) |
| and |
| .B im_vips2ppm(3) |
| for details on all of the options available. |
| |
| .B "t" |
| creates a temporary memory buffer image. |
| |
| .B "p" |
| creates a "glue" descriptor you can use to join two image processing |
| operations together. |
| |
| .B "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. |
| |
| .B 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. |
| |
| .B im_open_local(3) |
| is handy for saving you from adding many |
| .B im_close(3) |
| calls to |
| escape points. Example: find the total of an array of images. |
| |
| #include <vips/vips.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. |
| |
| .B im_open_local(3) |
| returns NULL on error, or if its first parameter is NULL. |
| |
| .B 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]). |
| |
| .SH RETURN VALUE |
| The function returns the image descriptor on success and NULL on error. |
| .SH SEE ALSO |
| im_close(3), im_vips2tiff(3), im_vips2jpeg(3), im_vips2ppm(3), |
| im_tiff2vips(3), im_jpeg2vips(3), im_ppm2vips(3). |
| .SH COPYRIGHT |
| K. Martinez, 1992. |
| .SH AUTHOR |
| K. Martinez. |