Man Linux: Main Page and Category List

NAME

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

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 )

DESCRIPTION

       im_open(3)  examines  the  mode string, and creates an appropriate VIPS
       IMAGE descriptor.

       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_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>

         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).

COPYRIGHT

       K. Martinez, 1992.

AUTHOR

       K. Martinez.

                                30 October 1992                     IM_OPEN(3)