## VipsForeign

VipsForeign — load and save images in a variety of formats

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

                        VipsForeign;
                        VipsForeignClass;
    void *              vips_foreign_map                    (const char *base,
                                                             VipsSListMap2Fn fn,
                                                             void *a,
                                                             void *b);
    enum                VipsForeignFlags;
                        VipsForeignLoad;
                        VipsForeignLoadClass;
    const char *        vips_foreign_find_load              (const char *filename);
    const char *        vips_foreign_find_load_options      (const char *filename);
    VipsForeignFlags    vips_foreign_flags                  (const char *loader,
                                                             const char *filename);
    gboolean            vips_foreign_is_a                   (const char *loader,
                                                             const char *filename);
    enum                VipsSaveable;
                        VipsForeignSave;
                        VipsForeignSaveClass;
    const char *        vips_foreign_find_save              (const char *filename);
    const char *        vips_foreign_find_save_options      (const char *filename);
    int                 vips_foreign_load                   (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_foreign_save                   (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_foreign_load_options           (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_foreign_save_options           (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_openslideload                  (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_jpegload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_jpegload_buffer                (void *buf,
                                                             size_t len,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_jpegsave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_jpegsave_buffer                (VipsImage *in,
                                                             void **buf,
                                                             size_t *len,
                                                             ...);
    int                 vips_jpegsave_mime                  (VipsImage *in,
                                                             ...);
    int                 vips_webpload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_webpload_buffer                (void *buf,
                                                             size_t len,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_webpsave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_webpsave_buffer                (VipsImage *in,
                                                             void **buf,
                                                             size_t *len,
                                                             ...);
    int                 vips_webpsave_mime                  (VipsImage *in,
                                                             ...);
    enum                VipsForeignTiffCompression;
    enum                VipsForeignTiffPredictor;
    enum                VipsForeignTiffResunit;
    int                 vips_tiffload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_tiffsave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_openexrload                    (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_fitsload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_fitssave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_analyzeload                    (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_rawload                        (const char *filename,
                                                             VipsImage **out,
                                                             int width,
                                                             int height,
                                                             int bands,
                                                             ...);
    int                 vips_rawsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_rawsave_fd                     (VipsImage *in,
                                                             int fd,
                                                             ...);
    int                 vips_csvload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_csvsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_matrixload                     (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_matrixsave                     (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_matrixprint                    (VipsImage *in,
                                                             ...);
    int                 vips_magickload                     (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_pngload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_pngload_buffer                 (void *buf,
                                                             size_t len,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_pngsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_pngsave_buffer                 (VipsImage *in,
                                                             void **buf,
                                                             size_t *len,
                                                             ...);
    int                 vips_ppmload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_ppmsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    int                 vips_matload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_radload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_radsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);
    enum                VipsForeignDzLayout;
    enum                VipsForeignDzDepth;
    int                 vips_dzsave                         (VipsImage *in,
                                                             const char *basename,
                                                             ...);

## Object Hierarchy

      GObject
       +----VipsObject
             +----VipsOperation
                   +----VipsForeign
                         +----VipsForeignLoad
                         +----VipsForeignSave

      GObject
       +----VipsObject
             +----VipsOperation
                   +----VipsForeign
                         +----VipsForeignLoad

      GObject
       +----VipsObject
             +----VipsOperation
                   +----VipsForeign
                         +----VipsForeignSave

## Properties

      "access"                   VipsAccess            : Read / Write
      "disc"                     gboolean              : Read / Write
      "flags"                    VipsForeignFlags      : Read / Write
      "out"                      VipsImage*            : Read / Write
      "sequential"               gboolean              : Read / Write
      "in"                       VipsImage*            : Read / Write
      "strip"                    gboolean              : Read / Write

## Description

This set of operations load and save images in a variety of formats.

The operations share a base class that offers a simple way to search for a subclass of VipsForeign which can load a certain file (see `vips_foreign_find_load()`) or which could be used to save an image to a certain file type (see `vips_foreign_find_save()`). You can then run these operations using `vips_call()` and friends to perform the load or save.

A pair of convenience functions, `vips_foreign_load()` and `vips_foreign_save()`, automate the process, loading an image from a file or saving an image to a file. These functions let you give load or save options as name - value pairs in the C argument list. You can use `vips_foreign_load_options()` and `vips_foreign_save_options()` to include options in the file name.

For example:

    vips_foreign_save (my_image, "frank.tiff",
        "compression", VIPS_FOREIGN_TIFF_COMPRESSION_JPEG,
        NULL);

Will save an image to the file "frank.tiff" in TIFF format (selected by the file name extension) with JPEG compression.

    vips_foreign_save_options (my_image, "frank.tiff[compression=jpeg]");

Is the same thing, but with the option in the filename.

You can also invoke the operations directly, for example:

    vips_tiffsave (my_image, "frank.anything",
        "compression", VIPS_FOREIGN_TIFF_COMPRESSION_JPEG,
        NULL);

To add support for a new file format to vips, simply define a new subclass of VipsForeignLoad or VipsForeignSave.

If you define a new operation which is a subclass of VipsForeign, support for it automatically appears in all VIPS user-interfaces. It will also be transparently supported by `vips_image_new_from_file()` and friends.

VIPS comes with VipsForeign for TIFF, JPEG, PNG, Analyze, PPM, OpenEXR, CSV, Matlab, Radiance, RAW, FITS and VIPS. It also includes import filters which can load with libMagick and with OpenSlide.

## Details

### VipsForeign

    typedef struct _VipsForeign VipsForeign;

### VipsForeignClass

    typedef struct {
    	VipsOperationClass parent_class;

    	/* Loop over formats in this order, default 0. We need this because
    	 * some formats can be read by several loaders (eg. tiff can be read
    	 * by the libMagick loader as well as by the tiff loader), and we want
    	 * to make sure the better loader comes first.
    	 */
    	int priority;

    	/* Null-terminated list of recommended suffixes, eg. ".tif", ".tiff".
    	 * This can be used by both load and save, so it's in the base class.
    	 */
    	const char **suffs;
    } VipsForeignClass;

The suffix list is used to select a format to save a file in, and to pick a loader if you don't define `is_a()`.

You should also define `nickname` and `description` in VipsObject.

### vips_foreign_map ()

    void *              vips_foreign_map                    (const char *base,
                                                             VipsSListMap2Fn fn,
                                                             void *a,
                                                             void *b);

Apply a function to every VipsForeignClass that VIPS knows about. Foreigns are presented to the function in priority order.

Like all VIPS map functions, if `fn` returns `NULL`, iteration continues. If it returns non-`NULL`, iteration terminates and that value is returned. The map function returns `NULL` if all calls return `NULL`.

See also: `vips_slist_map()`.

`base` : | base class to search below (eg. "VipsForeignLoad")
`fn` : | function to apply to each VipsForeignClass. [scope call]
`a` : | user data
`b` : | user data
Returns : | the result of iteration. [transfer none]

### enum VipsForeignFlags

    typedef enum {
    	VIPS_FOREIGN_NONE = 0,		/* No flags set */
    	VIPS_FOREIGN_PARTIAL = 1, /* Lazy read OK (eg. tiled tiff) */
    	VIPS_FOREIGN_BIGENDIAN = 2, /* Most-significant byte first */
    	VIPS_FOREIGN_SEQUENTIAL = 4, /* Top-to-bottom lazy read OK */
    	VIPS_FOREIGN_ALL = 7		/* All flags set */
    } VipsForeignFlags;

Some hints about the image loader.

`VIPS_FOREIGN_PARTIAL` means that the image can be read directly from the file without needing to be unpacked to a temporary image first.

`VIPS_FOREIGN_SEQUENTIAL` means that the loader supports lazy reading, but only top-to-bottom (sequential) access. Formats like PNG can read sets of scanlines, for example, but only in order.

If neither PARTIAL or SEQUENTIAL is set, the loader only supports whole image read. Setting both PARTIAL and SEQUENTIAL is an error.

`VIPS_FOREIGN_BIGENDIAN` means that image pixels are most-significant byte first. Depending on the native byte order of the host machine, you may need to swap bytes. See `vips_copy()`.

`VIPS_FOREIGN_NONE` | no flags set
`VIPS_FOREIGN_PARTIAL` | the image may be read lazilly
`VIPS_FOREIGN_BIGENDIAN` | image pixels are most-significant byte first
`VIPS_FOREIGN_SEQUENTIAL` | top-to-bottom lazy reading
`VIPS_FOREIGN_ALL` |

### VipsForeignLoad

    typedef struct {
    	/* The image we generate. This must be set by ->header().
    	 */
    	VipsImage *out;

    	/* The behind-the-scenes real image we decompress to. This can be a
    	 * disc foreign or a memory buffer. This must be set by ->load().
    	 */
    	VipsImage *real;

    	/* Set this to tag the operation as nocache.
    	 */
    	gboolean nocache;
    } VipsForeignLoad;

``header()`` must set at least the header fields of `out`. ``laod()``, if defined, must load the pixels to `real`.

### VipsForeignLoadClass

    typedef struct {
    	VipsForeignClass parent_class;

    	/* Is a file in this format.
    	 *
    	 * This function should return %TRUE if the file contains an image of
    	 * this type. If you don't define this function, #VipsForeignLoad
    	 * will use @suffs instead.
    	 */
    	gboolean (*is_a)( const char * );

    	/* Get the flags from a filename.
    	 *
    	 * This function should examine the file and return a set
    	 * of flags. If you don't define it, vips will default to 0 (no flags
    	 * set).
    	 *
    	 * This operation is necessary for vips7 compatibility.
    	 */
    	VipsForeignFlags (*get_flags_filename)( const char * );

    	/* Get the flags for this load operation. Images can be loaded from
    	 * (for example) memory areas rather than files, so you can't just use
    	 * @get_flags_filename().
    	 */
    	VipsForeignFlags (*get_flags)( VipsForeignLoad * );

    	/* Do the minimum read we can.
    	 *
    	 * Set the header fields in @out from @filename. If you can read the
    	 * whole image as well with no performance cost (as with vipsload),
    	 * or if your loader does not support reading only the header, read
    	 * the entire image in this method and leave @load() NULL.
    	 *
    	 * @header() needs to set the dhint on the image .. otherwise you get
    	 * the default SMALLTILE.
    	 *
    	 * Return 0 for success, -1 for error, setting
    	 * vips_error().
    	 */
    	int (*header)( VipsForeignLoad * );

    	/* Read the whole image into @real. The pixels will get copied to @out
    	 * later.
    	 *
    	 * You can omit this method if you define a @header() method which
    	 * loads the whole file.
    	 *
    	 * Return 0 for success, -1 for error, setting
    	 * vips_error().
    	 */
    	int (*load)( VipsForeignLoad * );
    } VipsForeignLoadClass;

Add a new loader to VIPS by subclassing VipsForeignLoad. Subclasses need to implement at least ``header()``.

As a complete example, here's the code for the PNG loader, minus the actual calls to libpng.

    typedef struct _VipsForeignLoadPng {
    	VipsForeignLoad parent_object;

    	char *filename;
    } VipsForeignLoadPng;

    typedef VipsForeignLoadClass VipsForeignLoadPngClass;

    G_DEFINE_TYPE( VipsForeignLoadPng, vips_foreign_load_png,
    	VIPS_TYPE_FOREIGN_LOAD );

    static VipsForeignFlags
    vips_foreign_load_png_get_flags_filename( const char *filename )
    {
    	VipsForeignFlags flags;

    	flags = 0;
    	if( vips__png_isinterlaced( filename ) )
    		flags = VIPS_FOREIGN_PARTIAL;
    	else
    		flags = VIPS_FOREIGN_SEQUENTIAL;

    	return( flags );
    }

    static VipsForeignFlags
    vips_foreign_load_png_get_flags( VipsForeignLoad *load )
    {
    	VipsForeignLoadPng *png = (VipsForeignLoadPng *) load;

    	return( vips_foreign_load_png_get_flags_filename( png->filename ) );
    }

    static int
    vips_foreign_load_png_header( VipsForeignLoad *load )
    {
    	VipsForeignLoadPng *png = (VipsForeignLoadPng *) load;

    	if( vips__png_header( png->filename, load->out ) )
    		return( -1 );

    	return( 0 );
    }

    static int
    vips_foreign_load_png_load( VipsForeignLoad *load )
    {
    	VipsForeignLoadPng *png = (VipsForeignLoadPng *) load;

    	if( vips__png_read( png->filename, load->real ) )
    		return( -1 );

    	return( 0 );
    }

    static void
    vips_foreign_load_png_class_init( VipsForeignLoadPngClass *class )
    {
    	GObjectClass *gobject_class = G_OBJECT_CLASS( class );
    	VipsObjectClass *object_class = (VipsObjectClass *) class;
    	VipsForeignClass *foreign_class = (VipsForeignClass *) class;
    	VipsForeignLoadClass *load_class = (VipsForeignLoadClass *) class;

    	gobject_class->set_property = vips_object_set_property;
    	gobject_class->get_property = vips_object_get_property;

    	object_class->nickname = "pngload";
    	object_class->description = _( "load png from file" );

    	foreign_class->suffs = vips__png_suffs;

    	load_class->is_a = vips__png_ispng;
    	load_class->get_flags_filename =
    		vips_foreign_load_png_get_flags_filename;
    	load_class->get_flags = vips_foreign_load_png_get_flags;
    	load_class->header = vips_foreign_load_png_header;
    	load_class->load = vips_foreign_load_png_load;

    	VIPS_ARG_STRING( class, "filename", 1,
    		_( "Filename" ),
    		_( "Filename to load from" ),
    		VIPS_ARGUMENT_REQUIRED_INPUT,
    		G_STRUCT_OFFSET( VipsForeignLoadPng, filename ),
    		NULL );
    }

    static void
    vips_foreign_load_png_init( VipsForeignLoadPng *png )
    {
    }

### vips_foreign_find_load ()

    const char *        vips_foreign_find_load              (const char *filename);

Searches for an operation you could use to load `filename`.

See also: `vips_foreign_read()`.

`filename` : | file to find a loader for
Returns : | the name of an operation on success, `NULL` on error

### vips_foreign_find_load_options ()

    const char *        vips_foreign_find_load_options      (const char *filename);

Searches for an operation you could use to load `filename`.

Arguments to the loader may be embedded in the filename using the usual syntax.

See also: `vips_foreign_load()`.

`filename` : | file to find a loader for
Returns : | 0 on success, -1 on error

### vips_foreign_flags ()

    VipsForeignFlags    vips_foreign_flags                  (const char *loader,
                                                             const char *filename);

Return the flags for `filename` using `loader`. `loader` is something like "tiffload" or "VipsForeignLoadTiff".

`loader` : | name of loader to use for test
`filename` : | file to test
Returns : | the flags for `filename`.

### vips_foreign_is_a ()

    gboolean            vips_foreign_is_a                   (const char *loader,
                                                             const char *filename);

Return `TRUE` if `filename` can be loaded by `loader`. `loader` is something like "tiffload" or "VipsForeignLoadTiff".

`loader` : | name of loader to use for test
`filename` : | file to test
Returns : | `TRUE` if `filename` can be loaded by `loader`.

### enum VipsSaveable

    typedef enum {
    	VIPS_SAVEABLE_MONO,
    	VIPS_SAVEABLE_RGB,
    	VIPS_SAVEABLE_RGBA,
    	VIPS_SAVEABLE_RGB_CMYK,
    	VIPS_SAVEABLE_ANY,
    	VIPS_SAVEABLE_LAST
    } VipsSaveable;

See also: VipsForeignSave.

`VIPS_SAVEABLE_MONO` | 1 band (eg. CSV)
`VIPS_SAVEABLE_RGB` | 1 or 3 bands (eg. PPM)
`VIPS_SAVEABLE_RGBA` | 1, 2, 3 or 4 bands (eg. PNG)
`VIPS_SAVEABLE_RGB_CMYK` | 1, 3 or 4 bands (eg. JPEG)
`VIPS_SAVEABLE_ANY` | any number of bands (eg. TIFF)
`VIPS_SAVEABLE_LAST` |

### VipsForeignSave

    typedef struct {
    	/* The image we are to save, as supplied by our caller.
    	 */
    	VipsImage *in;

    	/* @in converted to a saveable format (eg. 8-bit RGB) according to the
    	 * instructions you give in the class fields below.
    	 *
    	 * This is the image you should actually write to the output.
    	 */
    	VipsImage *ready;
    } VipsForeignSave;

### VipsForeignSaveClass

    typedef struct {
    	VipsForeignClass parent_class;

    	/* How this format treats bands.
    	 *
    	 * @saveable describes the bands that your saver can handle. For
    	 * example, PPM images can have 1 or 3 bands (mono or RGB), so it
    	 * uses #VIPS_SAVEABLE_RGB.
    	 */
    	VipsSaveable saveable;

    	/* How this format treats band formats.
    	 *
    	 * @format_table describes the band formats that your saver can
    	 * handle. For each of the 10 #VipsBandFormat values, the array
    	 * should give the format your saver will accept.
    	 */
    	VipsBandFormat *format_table;

    	/* The set of coding types this format can save. For example, jpeg can
    	 * only save NONE, so has NONE TRUE and RAD and LABQ FALSE.
    	 *
    	 * Default NONE TRUE, RAD and LABQ FALSE.
    	 */
    	gboolean coding[VIPS_CODING_LAST];
    } VipsForeignSaveClass;

Call your saver in the class' ``build()`` method after chaining up. The prepared image should be ready for you to save in `ready`.

As a complete example, here's the code for the CSV saver, minus the calls to the actual save routines.

    typedef struct _VipsForeignSaveCsv {
    	VipsForeignSave parent_object;

    	char *filename;
    	const char *separator;
    } VipsForeignSaveCsv;

    typedef VipsForeignSaveClass VipsForeignSaveCsvClass;

    G_DEFINE_TYPE( VipsForeignSaveCsv, vips_foreign_save_csv,
    	VIPS_TYPE_FOREIGN_SAVE );

    static int
    vips_foreign_save_csv_build( VipsObject *object )
    {
    	VipsForeignSave *save = (VipsForeignSave *) object;
    	VipsForeignSaveCsv *csv = (VipsForeignSaveCsv *) object;

    	if( VIPS_OBJECT_CLASS( vips_foreign_save_csv_parent_class )->
    		build( object ) )
    		return( -1 );

    	if( vips__csv_write( save->ready, csv->filename, csv->separator ) )
    		return( -1 );

    	return( 0 );
    }

    static void
    vips_foreign_save_csv_class_init( VipsForeignSaveCsvClass *class )
    {
    	GObjectClass *gobject_class = G_OBJECT_CLASS( class );
    	VipsObjectClass *object_class = (VipsObjectClass *) class;
    	VipsForeignClass *foreign_class = (VipsForeignClass *) class;
    	VipsForeignSaveClass *save_class = (VipsForeignSaveClass *) class;

    	gobject_class->set_property = vips_object_set_property;
    	gobject_class->get_property = vips_object_get_property;

    	object_class->nickname = "csvsave";
    	object_class->description = _( "save image to csv file" );
    	object_class->build = vips_foreign_save_csv_build;

    	foreign_class->suffs = vips__foreign_csv_suffs;

    	save_class->saveable = VIPS_SAVEABLE_MONO;
    	// no need to define ->format_table, we don't want the input
    	// cast for us

    	VIPS_ARG_STRING( class, "filename", 1,
    		_( "Filename" ),
    		_( "Filename to save to" ),
    		VIPS_ARGUMENT_REQUIRED_INPUT,
    		G_STRUCT_OFFSET( VipsForeignSaveCsv, filename ),
    		NULL );

    	VIPS_ARG_STRING( class, "separator", 13,
    		_( "Separator" ),
    		_( "Separator characters" ),
    		VIPS_ARGUMENT_OPTIONAL_INPUT,
    		G_STRUCT_OFFSET( VipsForeignSaveCsv, separator ),
    		"\t" );
    }

    static void
    vips_foreign_save_csv_init( VipsForeignSaveCsv *csv )
    {
    	csv->separator = g_strdup( "\t" );
    }

### vips_foreign_find_save ()

    const char *        vips_foreign_find_save              (const char *filename);

Searches for an operation you could use to write to `filename`.

`filename` may not contain embedded options. See `vips_foreign_find_save_options()` if your filename may have options in.

See also: `vips_foreign_write()`.

`filename` : | name to find a saver for
Returns : | the name of an operation on success, `NULL` on error

### vips_foreign_find_save_options ()

    const char *        vips_foreign_find_save_options      (const char *filename);

Searches for an operation you could use to write to `filename`.

`filename` may contain embedded options. See `vips_foreign_find_save()` if your filename does not options in.

See also: `vips_foreign_write()`.

`filename` : | name to find a saver for
Returns : | 0 on success, -1 on error

### vips_foreign_load ()

    int                 vips_foreign_load                   (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Loads `filename` into `out` using the loader recommended by `vips_foreign_find_load()`.

See also: `vips_foreign_save()`, `vips_foreign_load_options()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### vips_foreign_save ()

    int                 vips_foreign_save                   (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Saves `in` to `filename` using the saver recommended by `vips_foreign_find_save()`. Options are not in `filename` but must be given as a NULL-terminated list of name-value pairs.

See also: `vips_foreign_load()`.

`in` : | image to write
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### vips_foreign_load_options ()

    int                 vips_foreign_load_options           (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Loads `filename` into `out` using the loader recommended by `vips_foreign_find_load()`.

Arguments to the loader may be embedded in the filename using the usual syntax. They may also be given as a set of NULL-terminated optional arguments.

See also: `vips_foreign_load()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### vips_foreign_save_options ()

    int                 vips_foreign_save_options           (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Saves `in` to `filename` using the saver recommended by `vips_foreign_find_save()`.

Arguments to the saver may be embedded in the filename using the usual syntax. They may also be given as a set of NULL-terminated optional arguments.

See also: `vips_foreign_save()`.

`in` : | image to write
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### vips_openslideload ()

    int                 vips_openslideload                  (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

`layer`: load this layer `associated`: load this associated image

Read a virtual slide supported by the OpenSlide library into a VIPS image. OpenSlide supports images in Aperio, Hamamatsu VMS, Hamamatsu VMU, MIRAX, and Trestle formats.

To facilitate zooming, virtual slide formats include multiple scaled-down versions of the high-resolution image. These are typically called "levels", though OpenSlide and `im_openslide2vips()` call them "layers". By default, `vips_openslideload()` reads the highest-resolution layer (layer 0). Set `layer` to the layer number you want.

In addition to the slide image itself, virtual slide formats sometimes include additional images, such as a scan of the slide's barcode. OpenSlide calls these "associated images". To read an associated image, set `associated` to the image's name. A slide's associated images are listed in the "slide-associated-images" metadata item.

The output of this operator is in pre-multipled ARGB format. Use `im_argb2rgba()` to decode to png-style RGBA.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_jpegload ()

    int                 vips_jpegload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

`shrink`: shrink by this much on load `fail`: fail on warnings

Read a JPEG file into a VIPS image. It can read most 8-bit JPEG images, including CMYK and YCbCr.

`shrink` means shrink by this integer factor during load. Possible values are 1, 2, 4 and 8. Shrinking during read is very much faster than decompressing the whole image and then shrinking later.

Setting `fail` to true makes the JPEG reader fail on any warnings. This can be useful for detecting truncated files, for example. Normally reading these produces a warning, but no fatal error.

Example:

    vips_jpegload( "fred.jpg", &out,
    	"shrink", 8,
    	"fail", TRUE,
    	NULL );

Any embedded ICC profiles are ignored: you always just get the RGB from the file. Instead, the embedded profile will be attached to the image as `VIPS_META_ICC_NAME` ("icc-profile-data"). You need to use something like `vips_icc_import()` to get CIE values from the file.

EXIF metadata is attached as `VIPS_META_EXIF_NAME` ("exif-data"), IPCT as `VIPS_META_IPCT_NAME` ("ipct-data"), and XMP as VIPS_META_XMP_NAME ("xmp-data").

The int metadata item "jpeg-multiscan" is set to the result of `jpeg_has_multiple_scans()`. Interlaced jpeg images need a large amount of memory to load, so this field gives callers a chance to handle these images differently.

The EXIF thumbnail, if present, is attached to the image as "jpeg-thumbnail-data". See `vips_image_get_blob()`.

This function only reads the image header and does not decompress any pixel data. Decompression only occurs when pixels are accessed by some other function.

See also: `vips_jpegload_buffer()`, `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_jpegload_buffer ()

    int                 vips_jpegload_buffer                (void *buf,
                                                             size_t len,
                                                             VipsImage **out,
                                                             ...);

Read a JPEG-formatted memory block into a VIPS image. It can read most 8-bit JPEG images, including CMYK and YCbCr.

This function is handy for processing JPEG image thumbnails.

Caution: on return only the header will have been read, the pixel data is not decompressed until the first pixel is read. Therefore you must not free `buf` until you have read pixel data from `out`.

See also: `vips_jpegload()`.

`buf` : | memory area to load
`len` : | size of memory area
`out` : | image to write
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_jpegsave ()

    int                 vips_jpegsave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Optional arguments:

`Q`: quality factor `profile`: attach this ICC profile `optimize_coding`: compute optimal Huffman coding tables `interlace`: write an interlaced (progressive) jpeg `strip`: remove all metadata from image `no`-subsample: disable chroma subsampling

Write a VIPS image to a file as JPEG.

Use `Q` to set the JPEG compression factor. Default 75.

Use `profile` to give the filename of a profile to be embedded in the JPEG. This does not affect the pixels which are written, just the way they are tagged. You can use the special string "none" to mean "don't attach a profile".

If no profile is specified and the VIPS header contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the profile from the VIPS header will be attached.

The image is automatically converted to RGB, Monochrome or CMYK before saving.

EXIF data is constructed from `VIPS_META_EXIF_NAME` ("exif-data"), then modified with any other related tags on the image before being written to the file.

IPCT as `VIPS_META_IPCT_NAME` ("ipct-data") and XMP as VIPS_META_XMP_NAME ("xmp-data") are coded and attached.

If `optimize_coding` is set, the Huffman tables are optimised. This is sllightly slower and produces slightly smaller files.

If `interlace` is set, the jpeg files will be interlaced (progressive jpeg, in jpg parlance). These files may be better for display over a slow network conection, but need much more memory to encode and decode.

If `strip` is set, no EXIF data, IPCT data, ICC profile or XMP metadata is written into the output file.

If `no`-subsample is set, chrominance subsampling is disabled. This will improve quality at the cost of larger file size. Useful for high Q factors.

See also: `vips_jpegsave_buffer()`, `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_jpegsave_buffer ()

    int                 vips_jpegsave_buffer                (VipsImage *in,
                                                             void **buf,
                                                             size_t *len,
                                                             ...);

Optional arguments:

`Q`: JPEG quality factor `profile`: attach this ICC profile `optimize_coding`: compute optimal Huffman coding tables `interlace`: write an interlaced (progressive) jpeg `strip`: remove all metadata from image `no`-subsample: disable chroma subsampling

As `vips_jpegsave()`, but save to a memory buffer.

The address of the buffer is returned in `obuf`, the length of the buffer in `olen`. You are responsible for freeing the buffer with `g_free()` when you are done with it.

See also: `vips_jpegsave()`, `vips_image_write_to_file()`.

`in` : | image to save
`buf` : | return output buffer here
`len` : | return output length here
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_jpegsave_mime ()

    int                 vips_jpegsave_mime                  (VipsImage *in,
                                                             ...);

Optional arguments:

`Q`: JPEG quality factor `profile`: attach this ICC profile `optimize_coding`: compute optimal Huffman coding tables `strip`: remove all metadata from image `no`-subsample: disable chroma subsampling

As `vips_jpegsave()`, but save as a mime jpeg on stdout.

See also: `vips_jpegsave()`, `vips_image_write_to_file()`.

`in` : | image to save
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_webpload ()

    int                 vips_webpload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

Read a webp file into a VIPS image.

See also:

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_webpload_buffer ()

    int                 vips_webpload_buffer                (void *buf,
                                                             size_t len,
                                                             VipsImage **out,
                                                             ...);

See also:

`buf` : | memory area to load
`len` : | size of memory area
`out` : | image to write
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_webpsave ()

    int                 vips_webpsave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Optional arguments:

`Q`: quality factor

See also:

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_webpsave_buffer ()

    int                 vips_webpsave_buffer                (VipsImage *in,
                                                             void **buf,
                                                             size_t *len,
                                                             ...);

Optional arguments:

`Q`: JPEG quality factor

See also:

`in` : | image to save
`buf` : | return output buffer here
`len` : | return output length here
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_webpsave_mime ()

    int                 vips_webpsave_mime                  (VipsImage *in,
                                                             ...);

Optional arguments:

`Q`: quality factor

See also:

`in` : | image to save
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### enum VipsForeignTiffCompression

    typedef enum {
    	VIPS_FOREIGN_TIFF_COMPRESSION_NONE,
    	VIPS_FOREIGN_TIFF_COMPRESSION_JPEG,
    	VIPS_FOREIGN_TIFF_COMPRESSION_DEFLATE,
    	VIPS_FOREIGN_TIFF_COMPRESSION_PACKBITS,
    	VIPS_FOREIGN_TIFF_COMPRESSION_CCITTFAX4,
    	VIPS_FOREIGN_TIFF_COMPRESSION_LZW,
    	VIPS_FOREIGN_TIFF_COMPRESSION_LAST
    } VipsForeignTiffCompression;

The compression types supported by the tiff writer.

Use `Q` to set the jpeg compression level, default 75.

Use `prediction` to set the lzw or deflate prediction, default none.

`VIPS_FOREIGN_TIFF_COMPRESSION_NONE` | no compression
`VIPS_FOREIGN_TIFF_COMPRESSION_JPEG` | jpeg compression
`VIPS_FOREIGN_TIFF_COMPRESSION_DEFLATE` | deflate (zip) compression
`VIPS_FOREIGN_TIFF_COMPRESSION_PACKBITS` | packbits compression
`VIPS_FOREIGN_TIFF_COMPRESSION_CCITTFAX4` | fax4 compression
`VIPS_FOREIGN_TIFF_COMPRESSION_LZW` | LZW compression
`VIPS_FOREIGN_TIFF_COMPRESSION_LAST` |

### enum VipsForeignTiffPredictor

    typedef enum {
    	VIPS_FOREIGN_TIFF_PREDICTOR_NONE = 1,
    	VIPS_FOREIGN_TIFF_PREDICTOR_HORIZONTAL = 2,
    	VIPS_FOREIGN_TIFF_PREDICTOR_FLOAT = 3,
    	VIPS_FOREIGN_TIFF_PREDICTOR_LAST
    } VipsForeignTiffPredictor;

The predictor can help deflate and lzw compression. The values are fixed by the tiff library.

`VIPS_FOREIGN_TIFF_PREDICTOR_NONE` | no prediction
`VIPS_FOREIGN_TIFF_PREDICTOR_HORIZONTAL` | horizontal differencing
`VIPS_FOREIGN_TIFF_PREDICTOR_FLOAT` | float predictor
`VIPS_FOREIGN_TIFF_PREDICTOR_LAST` |

### enum VipsForeignTiffResunit

    typedef enum {
    	VIPS_FOREIGN_TIFF_RESUNIT_CM,
    	VIPS_FOREIGN_TIFF_RESUNIT_INCH,
    	VIPS_FOREIGN_TIFF_RESUNIT_LAST
    } VipsForeignTiffResunit;

Use inches or centimeters as the resolution unit for a tiff file.

`VIPS_FOREIGN_TIFF_RESUNIT_CM` | use centimeters
`VIPS_FOREIGN_TIFF_RESUNIT_INCH` | use inches
`VIPS_FOREIGN_TIFF_RESUNIT_LAST` |

### vips_tiffload ()

    int                 vips_tiffload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

`page`: load this page

Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader, with extensions for tiled images, multipage images, LAB colour space, pyramidal images and JPEG compression. including CMYK and YCbCr.

`page` means load this page from the file. By default the first page (page 0) is read.

Any ICC profile is read and attached to the VIPS image.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_tiffsave ()

    int                 vips_tiffsave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Optional arguments:

`compression`; use this compression scheme `Q`: quality factor `predictor`; compress with this prediction `profile`: attach this ICC profile `tile`; set `TRUE` to write a tiled tiff `tile_width`; set tile size `tile_height`; set tile size `pyramid`; set `TRUE` to write an image pyramid `squash`; squash 8-bit images down to 1 bit `resunit`; convert resolution to pixels per inch or cm during write `xres`; horizontal resolution in pixels/mm `yres`; vertical resolution in pixels/mm `bigtiff`; write a BigTiff file

Write a VIPS image to a file as TIFF.

Use `compression` to set the tiff compression. Currently jpeg, packbits, fax4, lzw, none and deflate are supported. The default is no compression. JPEG compression is a good lossy compressor for photographs, packbits is good for 1-bit images, and deflate is the best lossless compression TIFF can do. LZW has patent problems and is no longer recommended.

Use `Q` to set the JPEG compression factor. Default 75.

Use `predictor` to set the predictor for lzw and deflate compression.

Predictor is not set by default. There are three predictor values recognised at the moment (2007, July): 1 is no prediction, 2 is a horizontal differencing and 3 is a floating point predictor. Refer to the libtiff specifications for further discussion of various predictors. In short, predictor helps to better compress image, especially in case of digital photos or scanned images and bit depths > 8. Try it to find whether it works for your images.

Use `profile` to give the filename of a profile to be embedded in the TIFF. This does not affect the pixels which are written, just the way they are tagged. You can use the special string "none" to mean "don't attach a profile".

If no profile is specified and the VIPS header contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the profile from the VIPS header will be attached.

Set `tile` to TRUE to write a tiled tiff. By default tiff are written in strips. Use `tile_width` and `tile_height` to set the tile size. The defaiult is 128 by 128.

Set `pyramid` to write the image as a set of images, one per page, of decreasing size.

Set `squash` to make 8-bit uchar images write as 1-bit TIFFs with zero pixels written as 0 and non-zero as 1.

Use `resunit` to override the default resolution unit. The default resolution unit is taken from the header field "resolution-unit" (VIPS_META_RESOLUTION_UNIT in C). If this field is not set, then VIPS defaults to cm.

Use `xres` and `yres` to override the default horizontal and vertical resolutions. By default these values are taken from the VIPS image header. libvips resolution is always in pixels per millimetre.

Set `bigtiff` to attempt to write a bigtiff. Bigtiff is a variant of the TIFF format that allows more than 4GB in a file.

See also: `vips_tiffload()`, `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_openexrload ()

    int                 vips_openexrload                    (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Read a OpenEXR file into a VIPS image.

The reader can handle scanline and tiled OpenEXR images. It can't handle OpenEXR colour management, image attributes, many pixel formats, anything other than RGBA.

This reader uses the rather limited OpenEXR C API. It should really be redone in C++.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_fitsload ()

    int                 vips_fitsload                       (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Read a FITS image file into a VIPS image.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_fitssave ()

    int                 vips_fitssave                       (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Write a VIPS image to a file as FITS.

See also: `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_analyzeload ()

    int                 vips_analyzeload                    (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Load an Analyze 6.0 file. If `filename` is "fred.img", this will look for an image header called "fred.hdr" and pixel data in "fred.img". You can also load "fred" or "fred.hdr".

Images are loaded lazilly and byte-swapped, if necessary. The Analyze metadata is read and attached.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_rawload ()

    int                 vips_rawload                        (const char *filename,
                                                             VipsImage **out,
                                                             int width,
                                                             int height,
                                                             int bands,
                                                             ...);

Optional arguments:

`width`: width of image in pixels `height`: height of image in pixels `bands`: number of image bands `offset`: offset in bytes from start of file

This operation mmaps the file, setting `out` so that access to that image will read from the file.

Use functions like `vips_copy()` to set the pixel type, byte ordering and so on.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_rawsave ()

    int                 vips_rawsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Writes the pixels in `in` to the file `filename` with no header or other metadata.

See also: `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_rawsave_fd ()

    int                 vips_rawsave_fd                     (VipsImage *in,
                                                             int fd,
                                                             ...);

Writes the pixels in `in` to the `fd` with no header or other metadata. Handy for implementing other savers.

See also: `vips_rawsave()`.

`in` : | image to save
`fd` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_csvload ()

    int                 vips_csvload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

`skip`: skip this many lines at start of file `lines`: read this many lines from file `whitespace`: set of whitespace characters `separator`: set of separator characters

Load a CSV (comma-separated values) file. The output image is always 1 band (monochrome), VIPS_FORMAT_DOUBLE.

Items in lines can be either floating point numbers in the C locale, or strings enclosed in double-quotes ("), or empty. You can use a backslash (\) within the quotes to escape special characters, such as quote marks.

The reader is deliberately rather fussy: it will fail if there are any short lines, or if the file is too short. It will ignore lines that are too long.

`skip` sets the number of lines to skip at the start of the file. Default zero.

`lines` sets the number of lines to read from the file. Default -1, meaning read all lines to end of file.

`whitespace` sets the skippable whitespace characters. Default space. Whitespace characters are always run together.

`separator` sets the characters that separate fields. Default ;,tab. Separators are never run together.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_csvsave ()

    int                 vips_csvsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Optional arguments:

`separator`: separator string

Writes the pixels in `in` to the `filename` as CSV (comma-separated values). The image is written one line of text per scanline. Complex numbers are written as "(real,imaginary)" and will need extra parsing I guess. Only the first band is written.

`separator` gives the string to use to separate numbers in the output. The default is "\\t" (tab).

See also: `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_matrixload ()

    int                 vips_matrixload                     (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Reads a matrix from a file.

Matrix files have a simple format that's supposed to be easy to create with a text editor or a spreadsheet.

The first line has four numbers for width, height, scale and offset (scale and offset may be omitted, in which case they default to 1.0 and 0.0). Scale must be non-zero. Width and height must be positive integers. The numbers are separated by any mixture of spaces, commas, tabs and quotation marks ("). The scale and offset fields may be floating-point, and must use '.' as a decimal separator.

Subsequent lines each hold one line of matrix data, with numbers again separated by any mixture of spaces, commas, tabs and quotation marks ("). The numbers may be floating-point, and must use '.' as a decimal separator.

Extra characters at the ends of lines or at the end of the file are ignored.

See also: `vips_csvload()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_matrixsave ()

    int                 vips_matrixsave                     (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Write `in` to `filename` in matrix format. See `vips_matrixload()` for a description of the format.

See also: `vips_matrixload()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_matrixprint ()

    int                 vips_matrixprint                    (VipsImage *in,
                                                             ...);

Print `in` to `stdout` in matrix format. See `vips_matrixload()` for a description of the format.

See also: `vips_matrixload()`.

`in` : | image to print
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_magickload ()

    int                 vips_magickload                     (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

`all_frames`: load all frames in sequence

Read in an image using libMagick, the ImageMagick library. This library can read more than 80 file formats, including SVG, BMP, EPS, DICOM and many others. The reader can handle any ImageMagick image, including the float and double formats. It will work with any quantum size, including HDR. Any metadata attached to the libMagick image is copied on to the VIPS image.

The reader should also work with most versions of GraphicsMagick. See the "--with-magickpackage" configure option.

Normally it will only load the first image in a many-image sequence (such as a GIF). Set `all_frames` to true to read the whole image sequence.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_pngload ()

    int                 vips_pngload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Optional arguments:

Read a PNG file into a VIPS image. It can read all png images, including 8- and 16-bit images, 1 and 3 channel, with and without an alpha channel.

Any ICC profile is read and attached to the VIPS image.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | decompressed image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_pngload_buffer ()

    int                 vips_pngload_buffer                 (void *buf,
                                                             size_t len,
                                                             VipsImage **out,
                                                             ...);

Read a PNG-formatted memory block into a VIPS image. It can read all png images, including 8- and 16-bit images, 1 and 3 channel, with and without an alpha channel.

Any ICC profile is read and attached to the VIPS image.

Caution: on return only the header will have been read, the pixel data is not decompressed until the first pixel is read. Therefore you must not free `buf` until you have read pixel data from `out`.

See also: `vips_pngload()`.

`buf` : | memory area to load
`len` : | size of memory area
`out` : | image to write
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_pngsave ()

    int                 vips_pngsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Optional arguments:

`compression`: compression level `interlace`: interlace image

Write a VIPS image to a file as PNG.

`compression` means compress with this much effort (0 - 9). Default 6.

Set `interlace` to `TRUE` to interlace the image with ADAM7 interlacing. Beware than an interlaced PNG can be up to 7 times slower to write than a non-interlaced image.

If the VIPS header contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the profile from the VIPS header will be attached.

The image is automatically converted to RGB, RGBA, Monochrome or Mono + alpha before saving. Images with more than one byte per band element are saved as 16-bit PNG, others are saved as 8-bit PNG.

See also: `vips_image_new_from_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_pngsave_buffer ()

    int                 vips_pngsave_buffer                 (VipsImage *in,
                                                             void **buf,
                                                             size_t *len,
                                                             ...);

Optional arguments:

`compression`: compression level `interlace`: interlace image

As `vips_pngsave()`, but save to a memory buffer.

The address of the buffer is returned in `obuf`, the length of the buffer in `olen`. You are responsible for freeing the buffer with `g_free()` when you are done with it.

See also: `vips_pngsave()`, `vips_image_write_to_file()`.

`in` : | image to save
`buf` : | return output buffer here
`len` : | return output length here
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_ppmload ()

    int                 vips_ppmload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Read a PPM/PBM/PGM/PFM file into a VIPS image.

It can read 1, 8, 16 and 32 bit images, colour or monochrome, stored in binary or in ASCII. One bit images become 8 bit VIPS images, with 0 and 255 for 0 and 1.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_ppmsave ()

    int                 vips_ppmsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Optional arguments:

`ascii`: save as ASCII rather than binary

Write a VIPS image to a file as PPM. It can write 8, 16 or 32 bit unsigned integer images, float images, colour or monochrome, stored as binary or ASCII. Integer images of more than 8 bits can only be stored in ASCII.

When writing float (PFM) images the scale factor is set from the "pfm-scale" metadata.

Set `ascii` to `TRUE` to write as human-readable ASCII. Normally data is written in binary.

The storage format is indicated by a filename extension. Use one of .pbm, .pgm, .ppm, .pfm.

See also: `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_matload ()

    int                 vips_matload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Read a Matlab save file into a VIPS image.

This operation searches the save file for the first array variable with between 1 and 3 dimensions and loads it as an image. It will not handle complex images. It does not handle sparse matrices.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_radload ()

    int                 vips_radload                        (const char *filename,
                                                             VipsImage **out,
                                                             ...);

Read a Radiance (HDR) file into a VIPS image.

Radiance files are read as VIPS_CODING_RAD. They have one byte for each of red, green and blue, and one byte of shared exponent. Some operations (like `vips_extract_area()`) can work directly with images in this format, but mmany (all the arithmetic operations, for example) will not. Unpack VIPS_CODING_RAD images to 3 band float with `im_rad2float()` if you want to do arithmetic on them.

This operation ignores some header fields, like VIEW and DATE. It will not rotate/flip as the FORMAT string asks.

Sections of this reader from Greg Ward and Radiance with kind permission.

See also: `vips_image_new_from_file()`.

`filename` : | file to load
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### vips_radsave ()

    int                 vips_radsave                        (VipsImage *in,
                                                             const char *filename,
                                                             ...);

Write a VIPS image in Radiance (HDR) format.

Sections of this reader from Greg Ward and Radiance with kind permission.

See also: `vips_image_write_file()`.

`in` : | image to save
`filename` : | file to write to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

### enum VipsForeignDzLayout

    typedef enum {
    	VIPS_FOREIGN_DZ_LAYOUT_DZ,
    	VIPS_FOREIGN_DZ_LAYOUT_ZOOMIFY,
    	VIPS_FOREIGN_DZ_LAYOUT_GOOGLE,
    	VIPS_FOREIGN_DZ_LAYOUT_LAST
    } VipsForeignDzLayout;

What directory layout and metadata standard to use.

`VIPS_FOREIGN_DZ_LAYOUT_DZ` | use DeepZoom directory layout
`VIPS_FOREIGN_DZ_LAYOUT_ZOOMIFY` | use Zoomify directory layout
`VIPS_FOREIGN_DZ_LAYOUT_GOOGLE` | use Google maps directory layout
`VIPS_FOREIGN_DZ_LAYOUT_LAST` |

### enum VipsForeignDzDepth

    typedef enum {
    	VIPS_FOREIGN_DZ_DEPTH_1PIXEL,
    	VIPS_FOREIGN_DZ_DEPTH_1TILE,
    	VIPS_FOREIGN_DZ_DEPTH_1,
    	VIPS_FOREIGN_DZ_DEPTH_LAST
    } VipsForeignDzDepth;

How many pyramid layers to create.

`VIPS_FOREIGN_DZ_DEPTH_1PIXEL` | create layers down to 1x1 pixel
`VIPS_FOREIGN_DZ_DEPTH_1TILE` | create layers down to 1x1 tile
`VIPS_FOREIGN_DZ_DEPTH_1` | only create a single layer
`VIPS_FOREIGN_DZ_DEPTH_LAST` |

### vips_dzsave ()

    int                 vips_dzsave                         (VipsImage *in,
                                                             const char *basename,
                                                             ...);

Optional arguments:

`layout`; directory layout convention `suffix`: suffix for tile tiles `overlap`; set tile overlap `tile_size`; set tile size `background`: background colour `depth`: how deep to make the pyramid `centre`: centre the tiles `angle`: rotate the image by this much

Save an image as a set of tiles at various resolutions. By default dzsave uses DeepZoom layout -- use `layout` to pick other conventions.

In DeepZoom layout a directory called "`basename_files`" is created to hold the tiles, and an XML file called "`basename.dzi`" is written with the image metadata,

In Zoomify and Google layout, a directory called `basename` is created to hold the tile structure.

You can set `suffix` to something like ".jpg[Q=85]" to control the tile write options.

In Google layout mode, edge tiles are expanded to `tile_size` by `tile_size` pixels. Normally they are filled with white, but you can set another colour with `background`. Images are usually placed at the top-left of the tile, but you can have them centred by turning on `centre`.

You can set the size and overlap of tiles with `tile_size` and `overlap`. They default to the correct settings for the selected `layout`.

Use `depth` to control how low the pyramid goes. This defaults to the correct setting for the `layout` you select.

See also: `vips_tiffsave()`.

`in` : | image to save
`basename` : | basename to save to
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error.

## Property Details

### The `"access"` property

      "access"                   VipsAccess            : Read / Write

Required access pattern for this file.

Default value: VIPS_ACCESS_RANDOM

### The `"disc"` property

      "disc"                     gboolean              : Read / Write

Open to disc.

Default value: TRUE

### The `"flags"` property

      "flags"                    VipsForeignFlags      : Read / Write

Flags for this file.

### The `"out"` property

      "out"                      VipsImage*            : Read / Write

Output image.

### The `"sequential"` property

      "sequential"               gboolean              : Read / Write

Sequential read only.

Default value: FALSE

### The `"in"` property

      "in"                       VipsImage*            : Read / Write

Image to save.

### The `"strip"` property

      "strip"                    gboolean              : Read / Write

Strip all metadata from image.

Default value: FALSE

## See Also

image