## VipsForeign

VipsForeign — load and save images in a variety of formats

## Stability Level

Stable, unless otherwise indicated

## Functions

void * | vips_foreign_map ()
const char * | vips_foreign_find_load ()
const char * | vips_foreign_find_load_buffer ()
const char * | vips_foreign_find_load_source ()
VipsForeignFlags | vips_foreign_flags ()
gboolean | vips_foreign_is_a ()
gboolean | vips_foreign_is_a_buffer ()
gboolean | vips_foreign_is_a_source ()
void | vips_foreign_load_invalidate ()
const char * | vips_foreign_find_save ()
gchar ** | vips_foreign_get_suffixes ()
const char * | vips_foreign_find_save_buffer ()
const char * | vips_foreign_find_save_target ()
int | vips_vipsload ()
int | vips_vipssave ()
int | vips_openslideload ()
int | vips_jpegload ()
int | vips_jpegload_buffer ()
int | vips_jpegsave_target ()
int | vips_jpegsave ()
int | vips_jpegsave_buffer ()
int | vips_jpegsave_mime ()
int | vips_webpload_source ()
int | vips_webpload ()
int | vips_webpload_buffer ()
int | vips_webpsave_target ()
int | vips_webpsave ()
int | vips_webpsave_buffer ()
int | vips_webpsave_mime ()
int | vips_tiffload ()
int | vips_tiffload_buffer ()
int | vips_tiffload_source ()
int | vips_tiffsave ()
int | vips_tiffsave_buffer ()
int | vips_openexrload ()
int | vips_fitsload ()
int | vips_fitssave ()
int | vips_analyzeload ()
int | vips_rawload ()
int | vips_rawsave ()
int | vips_rawsave_fd ()
int | vips_csvload ()
int | vips_csvsave ()
int | vips_matrixload ()
int | vips_matrixsave ()
int | vips_matrixprint ()
int | vips_magickload ()
int | vips_magickload_buffer ()
int | vips_magicksave ()
int | vips_magicksave_buffer ()
int | vips_pngload_source ()
int | vips_pngload ()
int | vips_pngload_buffer ()
int | vips_pngsave_target ()
int | vips_pngsave ()
int | vips_pngsave_buffer ()
int | vips_ppmload ()
int | vips_ppmsave ()
int | vips_matload ()
int | vips_radload_source ()
int | vips_radload ()
int | vips_radload_buffer ()
int | vips_radsave ()
int | vips_radsave_buffer ()
int | vips_radsave_target ()
int | vips_pdfload ()
int | vips_pdfload_buffer ()
int | vips_svgload ()
int | vips_svgload_buffer ()
int | vips_gifload ()
int | vips_gifload_buffer ()
int | vips_heifload ()
int | vips_heifload_buffer ()
int | vips_heifsave ()
int | vips_heifsave_buffer ()
int | vips_niftiload ()
int | vips_niftisave ()
int | vips_dzsave ()

## Properties

VipsAccess | access | Read / Write
gboolean | disc | Read / Write
gboolean | fail | Read / Write
VipsForeignFlags | flags | Read / Write
gboolean | memory | Read / Write
VipsImage * | out | Read / Write
gboolean | sequential | Read / Write
VipsArrayDouble * | background | Read / Write
VipsImage * | in | Read / Write
gint | page-height | Read / Write
gboolean | strip | Read / Write

## Types and Values

enum | VipsForeignFlags
enum | VipsSaveable
enum | VipsForeignWebpPreset
enum | VipsForeignTiffCompression
enum | VipsForeignTiffPredictor
enum | VipsForeignTiffResunit
enum | VipsForeignPngFilter
enum | VipsForeignDzLayout
enum | VipsForeignDzDepth
enum | VipsForeignDzContainer
enum | VipsForeignHeifCompression

## Object Hierarchy

        GObject
        ╰── VipsObject
            ╰── VipsOperation
                ╰── VipsForeign
                    ├── VipsForeignLoad
                    ╰── VipsForeignSave

## Includes

    #include <vips/vips.h>

## 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 buffer (see `vips_foreign_find_load_buffer()`), or which could be used to save an image to a certain file type (see `vips_foreign_find_save()` and `vips_foreign_find_save_buffer()`). You can then run these operations using `vips_call()` and friends to perform the load or save.

vips_image_write_to_file() and `vips_image_new_from_file()` and friends use these functions to automate file load and save.

You can also invoke the operations directly, for example:

    1
    2
    3

    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, WebP, SVG, PDF, GIF and VIPS. It also includes import filters which can load with libMagick and with OpenSlide.

#### Writing a new loader

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

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

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.

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90

    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 )
    {
    }

#### Writing a new saver

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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69

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

## Functions

### 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()`.

#### Parameters

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]

### vips_foreign_find_load ()

    const char *
    vips_foreign_find_load (const char *filename);

Searches for an operation you could use to load `filename` . Any trailing options on `filename` are stripped and ignored.

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

#### Parameters

filename | file to find a loader for |

#### Returns

the name of an operation on success, `NULL` on error

### vips_foreign_find_load_buffer ()

    const char *
    vips_foreign_find_load_buffer (const void *data,
                                   size_t size);

Searches for an operation you could use to load a memory buffer. To see the range of buffer loaders supported by your vips, try something like:

vips -l | grep load_buffer

See also: `vips_image_new_from_buffer()`.

#### Parameters

data | start of memory buffer. | [array length=size][element-type guint8][transfer none]
size | number of bytes in `data` . | [type gsize]

#### Returns

the name of an operation on success, `NULL` on error.

[transfer none]

### vips_foreign_find_load_source ()

    const char *
    vips_foreign_find_load_source (VipsSource *source);

Searches for an operation you could use to load a source. To see the range of source loaders supported by your vips, try something like:

vips -l | grep load_source

See also: `vips_image_new_from_source()`.

#### Parameters

source | source to load from |

#### Returns

the name of an operation on success, `NULL` on error.

[transfer none]

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

#### Parameters

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

#### Parameters

loader | name of loader to use for test |
filename | file to test |

#### Returns

`TRUE` if `filename` can be loaded by `loader` .

### vips_foreign_is_a_buffer ()

    gboolean
    vips_foreign_is_a_buffer (const char *loader,
                              const void *data,
                              size_t size);

Return `TRUE` if `data` can be loaded by `loader` . `loader` is something like "tiffload_buffer" or "VipsForeignLoadTiffBuffer".

#### Parameters

loader | name of loader to use for test |
data | pointer to the buffer to test. | [array length=size][element-type guint8]
size | size of the buffer to test. | [type gsize]

#### Returns

`TRUE` if `data` can be loaded by `loader` .

### vips_foreign_is_a_source ()

    gboolean
    vips_foreign_is_a_source (const char *loader,
                              VipsSource *source);

Return `TRUE` if `source` can be loaded by `loader` . `loader` is something like "tiffload_source" or "VipsForeignLoadTiffSource".

#### Parameters

loader | name of loader to use for test |
source | source to test |

#### Returns

`TRUE` if `data` can be loaded by `source` .

### vips_foreign_load_invalidate ()

    void
    vips_foreign_load_invalidate (VipsImage *image);

Loaders can call this on the image they are making if they see a read error from the load library. It signals "invalidate" on the load operation and will cause it to be dropped from cache.

If we know a file will cause a read error, we don't want to cache the failing operation, we want to make sure the image will really be opened again if our caller tries again. For example, a broken file might be replaced by a working one.

[method]

#### Parameters

image | image to invalidate |

### vips_foreign_find_save ()

    const char *
    vips_foreign_find_save (const char *filename);

Searches for an operation you could use to write to `filename` . Any trailing options on `filename` are stripped and ignored.

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

#### Parameters

filename | name to find a saver for |

#### Returns

the name of an operation on success, `NULL` on error

### vips_foreign_get_suffixes ()

    gchar **
    vips_foreign_get_suffixes (void);

Get a `NULL`-terminated array listing all the supported suffixes.

This is not the same as all the supported file types, since libvips detects image format for load by testing the first few bytes.

Use `vips_foreign_find_load()` to detect type for a specific file.

Free the return result with `g_strfreev()`.

[method]

#### Returns

all supported file extensions, as a `NULL`-terminated array.

[transfer full]

### vips_foreign_find_save_buffer ()

    const char *
    vips_foreign_find_save_buffer (const char *suffix);

Searches for an operation you could use to write to a buffer in `suffix` format.

See also: `vips_image_write_to_buffer()`.

#### Parameters

suffix | name to find a saver for |

#### Returns

the name of an operation on success, `NULL` on error

### vips_foreign_find_save_target ()

    const char *
    vips_foreign_find_save_target (const char *suffix);

Searches for an operation you could use to write to a target in `suffix` format.

See also: `vips_image_write_to_buffer()`.

#### Parameters

suffix | format to find a saver for |

#### Returns

the name of an operation on success, `NULL` on error

### vips_vipsload ()

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

Read in a vips image.

See also: `vips_vipssave()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_vipssave ()

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

Write `in` to `filename` in VIPS format.

See also: `vips_vipsload()`.

[method]

#### Parameters

in | image to save |
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:

- `level` : `gint`, load this level

- `associated` : `gchararray`, load this associated image

- `attach_associated` : `gboolean`, attach all associated images as metadata

- `autocrop` : `gboolean`, crop to image bounds

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

To facilitate zooming, virtual slide formats include multiple scaled-down versions of the high-resolution image. These are typically called "levels". By default, `vips_openslideload()` reads the highest-resolution level (level 0). Set `level` to the level 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.

If you set `attach_associated` , then all associated images are attached as metadata items. Use `vips_image_get_image()` on `out` to retrieve them. Images are attached as "openslide-associated-XXXXX", where XXXXX is the name of the associated image.

The output of this operator is always RGBA.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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` : `gint`, shrink by this much on load

- `fail` : `gboolean`, fail on errors

- `autorotate` : `gboolean`, rotate image upright during load

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 errors. This can be useful for detecting truncated files, for example. Normally reading these produces a warning, but no fatal error.

Setting `autorotate` to `TRUE` will make the loader interpret the orientation tag and automatically rotate the image appropriately during load.

If `autorotate` is `FALSE`, the metadata field VIPS_META_ORIENTATION is set to the value of the orientation tag. Applications may read and interpret this field as they wish later in processing. See `vips_autorot()`. Save operations will use VIPS_META_ORIENTATION, if present, to set the orientation of output images.

Example:

    1
    2
    3
    4

    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. 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, IPTC as VIPS_META_IPTC_NAME, and XMP as VIPS_META_XMP_NAME.

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 string-valued field "jpeg-chroma-subsample" gives the chroma subsample in standard notation. 4:4:4 means no subsample, 4:2:0 means YCbCr with Cb and Cr subsampled horizontally and vertically, 4:4:4:4 means a CMYK image with no subsampling.

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

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

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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,
                          ...);

Optional arguments:

- `shrink` : `gint`, shrink by this much on load

- `fail` : `gboolean`, fail on errors

- `autorotate` : `gboolean`, use exif Orientation tag to rotate the image during load

Read a JPEG-formatted memory block into a VIPS image. Exactly as `vips_jpegload()`, but read from a memory buffer.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_jpegload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_jpegsave_target ()

    int
    vips_jpegsave_target (VipsImage *in,
                          VipsTarget *target,
                          ...);

Optional arguments:

- `Q` : `gint`, quality factor

- `profile` : filename of ICC profile to attach

- `optimize_coding` : `gboolean`, compute optimal Huffman coding tables

- `interlace` : `gboolean`, write an interlaced (progressive) jpeg

- `strip` : `gboolean`, remove all metadata from image

- `no_subsample` : `gboolean`, disable chroma subsampling

- `trellis_quant` : `gboolean`, apply trellis quantisation to each 8x8 block

- `overshoot_deringing` : `gboolean`, overshoot samples with extreme values

- `optimize_scans` : `gboolean`, split DCT coefficients into separate scans

- `quant_table` : `gint`, quantization table index

As `vips_jpegsave()`, but save to a target.

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

[method]

#### Parameters

in | image to save |
target | save image to this target |
... | `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` : `gint`, quality factor

- `profile` : filename of ICC profile to attach

- `optimize_coding` : `gboolean`, compute optimal Huffman coding tables

- `interlace` : `gboolean`, write an interlaced (progressive) jpeg

- `strip` : `gboolean`, remove all metadata from image

- `no_subsample` : `gboolean`, disable chroma subsampling

- `trellis_quant` : `gboolean`, apply trellis quantisation to each 8x8 block

- `overshoot_deringing` : `gboolean`, overshoot samples with extreme values

- `optimize_scans` : `gboolean`, split DCT coefficients into separate scans

- `quant_table` : `gint`, quantization table index

Write a VIPS image to a file as JPEG.

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

Use `profile` to give the name of a profile to be embedded in the JPEG. This does not affect the pixels which are written, just the way they are tagged. See `vips_profile_load()` for details on profile naming.

If no profile is specified and the VIPS header contains an ICC profile named VIPS_META_ICC_NAME, the profile from the VIPS header will be attached.

If `optimize_coding` is set, the Huffman tables are optimized. 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, IPTC 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.

If `trellis_quant` is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0), apply trellis quantisation to each 8x8 block. Reduces file size but increases compression time.

If `overshoot_deringing` is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0), apply overshooting to samples with extreme values for example 0 and 255 for 8-bit. Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears on a white background.

If `optimize_scans` is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0), split the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time.

If `quant_table` is set and the version of libjpeg supports it (e.g. mozjpeg >= 3.0) it selects the quantization table to use:

- 0 — Tables from JPEG Annex K (vips and libjpeg default)

- 1 — Flat table

- 2 — Table tuned for MSSIM on Kodak image set

- 3 — Table from ImageMagick by N. Robidoux (current mozjpeg default)

- 4 — Table tuned for PSNR-HVS-M on Kodak image set

- 5 — Table from Relevance of Human Vision to JPEG-DCT Compression (1992)

- 6 — Table from DCTune Perceptual Optimization of Compressed Dental X-Rays (1997)

- 7 — Table from A Visual Detection Model for DCT Coefficient Quantization (1993)

- 8 — Table from An Improved Detection Model for DCT Coefficient Quantization (1993)

Quantization table 0 is the default in vips and libjpeg(-turbo), but it tends to favor detail over color accuracy, producting colored patches and stripes as well as heavy banding in flat areas at high compression ratios. Quantization table 2 is a good candidate to try if the default quantization table produces banding or color shifts and is well suited for hires images. Quantization table 3 is the default in mozjpeg and has been tuned to produce good results at the default quality setting; banding at high compression. Quantization table 4 is the most accurate at the cost of compression ratio. Tables 5-7 are based on older research papers, but generally achieve worse compression ratios and/or quality than 2 or 4.

For maximum compression with mozjpeg, a useful set of options is `strip, optimize-coding, interlace, optimize-scans, trellis-quant, quant_table=3`.

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

EXIF data is constructed from VIPS_META_EXIF_NAME, then modified with any other related tags on the image before being written to the file. VIPS_META_RESOLUTION_UNIT is used to set the EXIF resolution unit. VIPS_META_ORIENTATION is used to set the EXIF orientation tag.

IPTC as VIPS_META_IPTC_NAME and XMP as VIPS_META_XMP_NAME are coded and attached.

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

[method]

#### Parameters

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` : `gint`, quality factor

- `profile` : filename of ICC profile to attach

- `optimize_coding` : `gboolean`, compute optimal Huffman coding tables

- `interlace` : `gboolean`, write an interlaced (progressive) jpeg

- `strip` : `gboolean`, remove all metadata from image

- `no_subsample` : `gboolean`, disable chroma subsampling

- `trellis_quant` : `gboolean`, apply trellis quantisation to each 8x8 block

- `overshoot_deringing` : `gboolean`, overshoot samples with extreme values

- `optimize_scans` : `gboolean`, split DCT coefficients into separate scans

- `quant_table` : `gint`, quantization table index

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

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [array length=len][element-type guint8]
len | return output length here. | [type gsize]
... | `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` : `gint`, quality factor

- `profile` : filename of ICC profile to attach

- `optimize_coding` : `gboolean`, compute optimal Huffman coding tables

- `interlace` : `gboolean`, write an interlaced (progressive) jpeg

- `strip` : `gboolean`, remove all metadata from image

- `no_subsample` : `gboolean`, disable chroma subsampling

- `trellis_quant` : `gboolean`, apply trellis quantisation to each 8x8 block

- `overshoot_deringing` : `gboolean`, overshoot samples with extreme values

- `optimize_scans` : `gboolean`, split DCT coefficients into separate scans

- `quant_table` : `gint`, quantization table index

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

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

[method]

#### Parameters

in | image to save |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_webpload_source ()

    int
    vips_webpload_source (VipsSource *source,
                          VipsImage **out,
                          ...);

Optional arguments:

- `page` : `gint`, page (frame) to read

- `n` : `gint`, load this many pages

- `scale` : `gdouble`, scale by this much on load

Exactly as `vips_webpload()`, but read from a source.

See also: `vips_webpload()`

#### Parameters

source | source to load from |
out | image to write. | [out]
... | `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:

- `page` : `gint`, page (frame) to read

- `n` : `gint`, load this many pages

- `scale` : `gdouble`, scale by this much on load

Read a WebP file into a VIPS image.

Use `page` to select a page to render, numbering from zero.

Use `n` to select the number of pages to render. The default is 1. Pages are rendered in a vertical column, with each individual page aligned to the left. Set to -1 to mean "until the end of the document". Use `vips_grid()` to change page layout.

Use `scale` to specify a scale-on-load factor. For example, 2.0 to double the size on load.

The loader supports ICC, EXIF and XMP metadata.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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,
                          ...);

Optional arguments:

- `page` : `gint`, page (frame) to read

- `n` : `gint`, load this many pages

- `scale` : `gdouble`, scale by this much on load

Read a WebP-formatted memory block into a VIPS image. Exactly as `vips_webpload()`, but read from a memory buffer.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_webpload()`

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_webpsave_target ()

    int
    vips_webpsave_target (VipsImage *in,
                          VipsTarget *target,
                          ...);

Optional arguments:

- `Q` : `gint`, quality factor

- `lossless` : `gboolean`, enables lossless compression

- `preset` : VipsForeignWebpPreset, choose lossy compression preset

- `smart_subsample` : `gboolean`, enables high quality chroma subsampling

- `near_lossless` : `gboolean`, preprocess in lossless mode (controlled by Q)

- `alpha_q` : `gint`, set alpha quality in lossless mode

- `reduction_effort` : `gint`, level of CPU effort to reduce file size

- `min_size` : `gboolean`, minimise size

- `kmin` : `gint`, minimum number of frames between keyframes

- `kmax` : `gint`, maximum number of frames between keyframes

- `strip` : `gboolean`, remove all metadata from image

As `vips_webpsave()`, but save to a target.

See also: `vips_webpsave()`.

[method]

#### Parameters

in | image to save |
target | save image to this target |
... | `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` : `gint`, quality factor

- `lossless` : `gboolean`, enables lossless compression

- `preset` : VipsForeignWebpPreset, choose lossy compression preset

- `smart_subsample` : `gboolean`, enables high quality chroma subsampling

- `near_lossless` : `gboolean`, preprocess in lossless mode (controlled by Q)

- `alpha_q` : `gint`, set alpha quality in lossless mode

- `reduction_effort` : `gint`, level of CPU effort to reduce file size

- `min_size` : `gboolean`, minimise size

- `kmin` : `gint`, minimum number of frames between keyframes

- `kmax` : `gint`, maximum number of frames between keyframes

- `strip` : `gboolean`, remove all metadata from image

Write an image to a file in WebP format.

By default, images are saved in lossy format, with `Q` giving the WebP quality factor. It has the range 0 - 100, with the default 75.

Use `preset` to hint the image type to the lossy compressor. The default is VIPS_FOREIGN_WEBP_PRESET_DEFAULT.

Set `smart_subsample` to enable high quality chroma subsampling.

Use `alpha_q` to set the quality for the alpha channel in lossy mode. It has the range 1 - 100, with the default 100.

Use `reduction_effort` to control how much CPU time to spend attempting to reduce file size. A higher value means more effort and therefore CPU time should be spent. It has the range 0-6 and a default value of 4.

Set `lossless` to use lossless compression, or combine `near_lossless` with `Q` 80, 60, 40 or 20 to apply increasing amounts of preprocessing which improves the near-lossless compression ratio by up to 50%.

For animated webp output, `min_size` will try to optimize for minimum size.

For animated webp output, `kmax` sets the maximum number of frames between keyframes. Setting 0 means only keyframes. `kmin` sets the minimum number of frames between frames. Setting 0 means no keyframes. By default, keyframes are disabled.

Use the metadata items `loop` and `delay` to set the number of loops for the animation and the frame delays.

The writer will attach ICC, EXIF and XMP metadata, unless `strip` is set to `TRUE`.

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

[method]

#### Parameters

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` : `gint`, quality factor

- `lossless` : `gboolean`, enables lossless compression

- `preset` : VipsForeignWebpPreset, choose lossy compression preset

- `smart_subsample` : `gboolean`, enables high quality chroma subsampling

- `near_lossless` : `gboolean`, preprocess in lossless mode (controlled by Q)

- `alpha_q` : `gint`, set alpha quality in lossless mode

- `reduction_effort` : `gint`, level of CPU effort to reduce file size

- `min_size` : `gboolean`, minimise size

- `kmin` : `gint`, minimum number of frames between keyframes

- `kmax` : `gint`, maximum number of frames between keyframes

- `strip` : `gboolean`, remove all metadata from image

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

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

See also: `vips_webpsave()`.

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [out][array length=len][element-type guint8]
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` : `gint`, quality factor

- `lossless` : `gboolean`, enables lossless compression

- `preset` : VipsForeignWebpPreset, choose lossy compression preset

- `smart_subsample` : `gboolean`, enables high quality chroma subsampling

- `near_lossless` : `gboolean`, preprocess in lossless mode (controlled by Q)

- `alpha_q` : `gint`, set alpha quality in lossless mode

- `reduction_effort` : `gint`, level of CPU effort to reduce file size

- `min_size` : `gboolean`, minimise size

- `kmin` : `gint`, minimum number of frames between keyframes

- `kmax` : `gint`, maximum number of frames between keyframes

- `strip` : `gboolean`, remove all metadata from image

As `vips_webpsave()`, but save as a mime webp on stdout.

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

[method]

#### Parameters

in | image to save |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_tiffload ()

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

Optional arguments:

- `page` : `gint`, load this page

- `n` : `gint`, load this many pages

- `autorotate` : `gboolean`, use orientation tag to rotate the image during load

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.

`n` means load this many pages. By default a single page is read. All the pages must have the same dimensions, and they are loaded as a tall, thin "toilet roll" image. The VIPS_META_PAGE_HEIGHT metadata tag gives the height in pixels of each page. Use -1 to load all pages.

Setting `autorotate` to `TRUE` will make the loader interpret the orientation tag and automatically rotate the image appropriately during load.

If `autorotate` is `FALSE`, the metadata field VIPS_META_ORIENTATION is set to the value of the orientation tag. Applications may read and interpret this field as they wish later in processing. See `vips_autorot()`. Save operations will use VIPS_META_ORIENTATION, if present, to set the orientation of output images.

Any ICC profile is read and attached to the VIPS image as VIPS_META_ICC_NAME. Any XMP metadata is read and attached to the image as VIPS_META_XMP_NAME. Any IPTC is attached as VIPS_META_IPTC_NAME. The image description is attached as VIPS_META_IMAGEDESCRIPTION. Data in the photoshop tag is attached as VIPS_META_PHOTOSHOP_NAME.

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

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_tiffload_buffer ()

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

Optional arguments:

- `page` : `gint`, load this page

- `n` : `gint`, load this many pages

- `autorotate` : `gboolean`, use orientation tag to rotate the image during load

Read a TIFF-formatted memory block into a VIPS image. Exactly as `vips_tiffload()`, but read from a memory source.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_tiffload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_tiffload_source ()

    int
    vips_tiffload_source (VipsSource *source,
                          VipsImage **out,
                          ...);

Optional arguments:

- `page` : `gint`, load this page

- `n` : `gint`, load this many pages

- `autorotate` : `gboolean`, use orientation tag to rotate the image during load

Exactly as `vips_tiffload()`, but read from a source.

See also: `vips_tiffload()`.

#### Parameters

source | source to load |
out | image to write. | [out]
... | `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 VipsForeignTiffCompression

- `Q` : `gint` quality factor

- `predictor` : use this VipsForeignTiffPredictor

- `profile` : `gchararray`, filename of ICC profile to attach

- `tile` : `gboolean`, set `TRUE` to write a tiled tiff

- `tile_width` : `gint` for tile size

- `tile_height` : `gint` for tile size

- `pyramid` : `gboolean`, write an image pyramid

- `squash` : `gboolean`, squash 8-bit images down to 1 bit

- `miniswhite` : `gboolean`, write 1-bit images as MINISWHITE

- `resunit` : VipsForeignTiffResunit for resolution unit

- `xres` : `gdouble` horizontal resolution in pixels/mm

- `yres` : `gdouble` vertical resolution in pixels/mm

- `bigtiff` : `gboolean`, write a BigTiff file

- `properties` : `gboolean`, set `TRUE` to write an IMAGEDESCRIPTION tag

- `region_shrink` : VipsRegionShrink How to shrink each 2x2 region.

- `level` : `gint`, Zstd compression level

- `lossless` : `gboolean`, WebP losssless mode

Write a VIPS image to a file as TIFF.

If `in` has the VIPS_META_PAGE_HEIGHT metadata item, this is assumed to be a "toilet roll" image. It will be written as series of pages, each VIPS_META_PAGE_HEIGHT pixels high.

Use `compression` to set the tiff compression. Currently jpeg, packbits, fax4, lzw, none, deflate, webp and zstd 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.

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

User `level` to set the ZSTD compression level. Use `lossless` to set WEBP lossless mode on. Use `Q` to set the WEBP compression level.

Use `predictor` to set the predictor for lzw and deflate compression. It defaults to VIPS_FOREIGN_TIFF_PREDICTOR_HORIZONTAL, meaning horizontal differencing. Please refer to the libtiff specifications for further discussion of various predictors.

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. See `vips_profile_load()` for details on profile naming.

If no profile is specified and the VIPS header contains an ICC profile named VIPS_META_ICC_NAME, 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. Use `region_shrink` to set how images will be shrunk: by default each 2x2 block is just averaged, but you can set MODE or MEDIAN as well.

Set `squash` to make 8-bit uchar images write as 1-bit TIFFs. Values >128 are written as white, values <=128 as black. Normally vips will write MINISBLACK TIFFs where black is a 0 bit, but if you set `miniswhite` , it will use 0 for a white bit. Many pre-press applications only work with images which use this sense. `miniswhite` only affects one-bit images, it does nothing for greyscale images.

Set `squash` to squash 3-band float CIELAB images down to 8-bit CIELAB.

Use `resunit` to override the default resolution unit. The default resolution unit is taken from the header field VIPS_META_RESOLUTION_UNIT. 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.

Set `properties` to write all vips metadata to the IMAGEDESCRIPTION tag as xml. If `properties` is not set, the value of VIPS_META_IMAGEDESCRIPTION is used instead.

The value of VIPS_META_XMP_NAME is written to the XMP tag. VIPS_META_ORIENTATION (if set) is used to set the value of the orientation tag. VIPS_META_IPTC (if set) is used to set the value of the IPTC tag. VIPS_META_PHOTOSHOP_NAME (if set) is used to set the value of the PHOTOSHOP tag.

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

[method]

#### Parameters

in | image to save |
filename | file to write to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_tiffsave_buffer ()

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

Optional arguments:

- `compression` : use this VipsForeignTiffCompression

- `Q` : `gint` quality factor

- `predictor` : use this VipsForeignTiffPredictor

- `profile` : `gchararray`, filename of ICC profile to attach

- `tile` : `gboolean`, set `TRUE` to write a tiled tiff

- `tile_width` : `gint` for tile size

- `tile_height` : `gint` for tile size

- `pyramid` : `gboolean`, write an image pyramid

- `squash` : `gboolean`, squash 8-bit images down to 1 bit

- `miniswhite` : `gboolean`, write 1-bit images as MINISWHITE

- `resunit` : VipsForeignTiffResunit for resolution unit

- `xres` : `gdouble` horizontal resolution in pixels/mm

- `yres` : `gdouble` vertical resolution in pixels/mm

- `bigtiff` : `gboolean`, write a BigTiff file

- `properties` : `gboolean`, set `TRUE` to write an IMAGEDESCRIPTION tag

- `region_shrink` : VipsRegionShrink How to shrink each 2x2 region.

- `level` : `gint`, Zstd compression level

- `lossless` : `gboolean`, WebP losssless mode

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

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

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

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [array length=len][element-type guint8]
len | return output length here. | [type gsize]
... | `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()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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.

This operation can read images with up to three dimensions. Any higher dimensions must be empty.

It can read 8, 16 and 32-bit integer images, signed and unsigned, float and double.

FITS metadata is attached with the "fits-" prefix.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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 in FITS format.

See also: `vips_image_write_to_file()`.

[method]

#### Parameters

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

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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:

- `offset` : `guint64`, offset in bytes from start of file

- `format` : VipsBandFormat, set image format

- `interpretation` : VipsInterpretation, set image interpretation

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

By default, it assumes uchar pixels. Use `format` to select something else.

The image will be tagged as VIPS_INTERPRETATION_MULTIBAND. Use `interpretation` to select something else.

Use `vips_byteswap()` to reverse the byte ordering if necessary.

See also: `vips_image_new_from_file()`, `vips_copy()`, `vips_byteswap()`.

#### Parameters

filename | file to load |
out | output image. | [out]
width | width of image in pixels |
height | height of image in pixels |
bands | number of image bands |
... | `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_to_file()`.

[method]

#### Parameters

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

[method]

#### Parameters

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

- `fail` : `gboolean`, fail on errors

Load a CSV (comma-separated values) file. The output image is always 1 band (monochrome), VIPS_FORMAT_DOUBLE. Use `vips_bandfold()` to turn RGBRGBRGB mono images into colour iamges.

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.

Setting `fail` to `TRUE` makes the reader fail on any errors.

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

#### Parameters

filename | file to load |
out | output image. | [out]
... | `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_to_file()`.

[method]

#### Parameters

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 row 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()`.

#### Parameters

filename | file to load |
out | output image. | [out]
... | `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()`.

[method]

#### Parameters

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

[method]

#### Parameters

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:

- `page` : `gint`, load from this page

- `n` : `gint`, load this many pages

- `density` : string, canvas resolution for rendering vector formats like SVG

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.

The file format is usually guessed from the filename suffix, or sniffed from the file contents.

Normally it will only load the first image in a many-image sequence (such as a GIF or a PDF). Use `page` and `n` to set the start page and number of pages to load. Set `n` to -1 to load all pages from `page` onwards.

`density` is "WxH" in DPI, e.g. "600x300" or "600" (default is "72x72"). See the density docs on the imagemagick website.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_magickload_buffer ()

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

Optional arguments:

- `page` : `gint`, load from this page

- `n` : `gint`, load this many pages

- `density` : string, canvas resolution for rendering vector formats like SVG

Read an image memory block using libMagick into a VIPS image. Exactly as `vips_magickload()`, but read from a memory source.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_magickload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area |
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_magicksave ()

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

Optional arguments:

- `quality` : `gint`, quality factor

- `format` : `gchararray`, format to save as

- `optimize_gif_frames` : `gboolean`, apply GIF frames optimization

- `optimize_gif_transparency` : `gboolean`, apply GIF transparency optimization

Write an image using libMagick.

Use `quality` to set the quality factor. Default 0.

Use `format` to explicitly set the save format, for example, "BMP". Otherwise the format is guessed from the filename suffix.

If `optimize_gif_frames` is set, GIF frames are cropped to the smallest size while preserving the results of the GIF animation. This takes some time for computation but saves some time on encoding and produces smaller files in some cases.

If `optimize_gif_transparency` is set, pixels that don't change the image through animation are made transparent. This takes some time for computation but saves some time on encoding and produces smaller files in some cases.

See also: `vips_magicksave_buffer()`, `vips_magickload()`.

[method]

#### Parameters

in | image to save |
filename | file to write to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_magicksave_buffer ()

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

Optional arguments:

- `quality` : `gint`, quality factor

- `format` : `gchararray`, format to save as

- `optimize_gif_frames` : `gboolean`, apply GIF frames optimization

- `optimize_gif_transparency` : `gboolean`, apply GIF transparency optimization

As `vips_magicksave()`, 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_magicksave()`, `vips_image_write_to_file()`.

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [array length=len][element-type guint8]
len | return output length here. | [type gsize]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_pngload_source ()

    int
    vips_pngload_source (VipsSource *source,
                         VipsImage **out,
                         ...);

Exactly as `vips_pngload()`, but read from a source.

See also: `vips_pngload()`.

#### Parameters

source | source to load from |
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_pngload ()

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

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. It also supports XMP metadata.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `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,
                         ...);

Exactly as `vips_pngload()`, but read from a PNG-formatted memory block.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_pngload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_pngsave_target ()

    int
    vips_pngsave_target (VipsImage *in,
                         VipsTarget *target,
                         ...);

Optional arguments:

- `compression` : compression level

- `interlace` : interlace image

- `profile` : ICC profile to embed

- `filter` : libpng row filter flag(s)

- `palette` : enable quantisation to 8bpp palette

- `colours` : max number of palette colours for quantisation

- `Q` : quality for 8bpp quantisation (does not exceed `colours` )

- `dither` : amount of dithering for 8bpp quantization

As `vips_pngsave()`, but save to a target.

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

[method]

#### Parameters

in | image to save |
target | save image to this target |
... | `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` : `gint`, compression level

- `interlace` : `gboolean`, interlace image

- `profile` : `gchararray`, ICC profile to embed

- `filter` : VipsForeignPngFilter row filter flag(s)

- `palette` : `gboolean`, enable quantisation to 8bpp palette

- `colours` : `gint`, max number of palette colours for quantisation

- `Q` : `gint`, quality for 8bpp quantisation (does not exceed `colours` )

- `dither` : `gdouble`, amount of dithering for 8bpp quantization

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.

Use `profile` to give the filename of a profile to be embedded in the PNG. This does not affect the pixels which are written, just the way they are tagged. See `vips_profile_load()` for details on profile naming.

If `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.

Use `filter` to specify one or more filters (instead of adaptive filtering), see VipsForeignPngFilter.

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.

Set `palette` to `TRUE` to enable quantisation to an 8-bit per pixel palette image with alpha transparency support. If `colours` is given, it limits the maximum number of palette entries. Similar to JPEG the quality can also be be changed with the `Q` parameter which further reduces the palette size and `dither` controls the amount of Floyd-Steinberg dithering. This feature requires libvips to be compiled with libimagequant.

XMP metadata is written to the XMP chunk. PNG comments are written to separate text chunks.

See also: `vips_image_new_from_file()`.

[method]

#### Parameters

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` : `gint`, compression level

- `interlace` : `gboolean`, interlace image

- `profile` : `gchararray`, ICC profile to embed

- `filter` : VipsForeignPngFilter row filter flag(s)

- `palette` : `gboolean`, enable quantisation to 8bpp palette

- `colours` : `gint`, max number of palette colours for quantisation

- `Q` : `gint`, quality for 8bpp quantisation (does not exceed `colours` )

- `dither` : `gdouble`, amount of dithering for 8bpp quantization

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

The address of the buffer is returned in `buf` , the length of the buffer in `len` . 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()`.

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [array length=len][element-type guint8]
len | return output length here. | [type gsize]
... | `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()`.

#### Parameters

filename | file to load |
out | output image. | [out]
... | `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

- `squash` : squash 8-bit images down to one bit

Write a VIPS image to a file as PPM. It can write 1, 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.

Set `squash` to `TRUE` to squash 8-bit images down to one bit. The saver does no dithering, that's up to you.

See also: `vips_image_write_to_file()`.

[method]

#### Parameters

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

#### Parameters

filename | file to load |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_radload_source ()

    int
    vips_radload_source (VipsSource *source,
                         VipsImage **out,
                         ...);

Exactly as `vips_radload()`, but read from a source.

See also: `vips_radload()`.

#### Parameters

source | source to load from |
out | output image. | [out]
... | `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 `vips_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()`.

#### Parameters

filename | file to load |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_radload_buffer ()

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

Exactly as `vips_radload()`, but read from a HDR-formatted memory block.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_radload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `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_to_file()`.

[method]

#### Parameters

in | image to save |
filename | file to write to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_radsave_buffer ()

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

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

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

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

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [array length=len][element-type guint8]
len | return output length here. | [type gsize]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_radsave_target ()

    int
    vips_radsave_target (VipsImage *in,
                         VipsTarget *target,
                         ...);

As `vips_radsave()`, but save to a target.

See also: `vips_radsave()`.

[method]

#### Parameters

in | image to save |
target | save image to this target |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_pdfload ()

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

Optional arguments:

- `page` : `gint`, load this page, numbered from zero

- `n` : `gint`, load this many pages

- `dpi` : `gdouble`, render at this DPI

- `scale` : `gdouble`, scale render by this factor

- `background` : VipsArrayDouble background colour

Render a PDF file into a VIPS image. Rendering uses the libpoppler library and should be fast.

The output image is always RGBA --- CMYK PDFs will be converted. If you need CMYK bitmaps, you should use `vips_magickload()` instead.

Use `page` to select a page to render, numbering from zero.

Use `n` to select the number of pages to render. The default is 1. Pages are rendered in a vertical column, with each individual page aligned to the left. Set to -1 to mean "until the end of the document". Use `vips_grid()` to change page layout.

Use `dpi` to set the rendering resolution. The default is 72. Alternatively, you can scale the rendering from the default 1 point == 1 pixel by setting `scale` .

Use `background` to set the background RGBA colour. The default is 255 (solid white), use eg. 0 for a transparent background.

The operation fills a number of header fields with metadata, for example "pdf-author". They may be useful.

This function only reads the image header and does not render any pixel data. Rendering occurs when pixels are accessed.

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

#### Parameters

filename | file to load |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_pdfload_buffer ()

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

Optional arguments:

- `page` : `gint`, load this page, numbered from zero

- `n` : `gint`, load this many pages

- `dpi` : `gdouble`, render at this DPI

- `scale` : `gdouble`, scale render by this factor

- `background` : VipsArrayDouble background colour

Read a PDF-formatted memory buffer into a VIPS image. Exactly as `vips_pdfload()`, but read from memory.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_pdfload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_svgload ()

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

Optional arguments:

- `dpi` : `gdouble`, render at this DPI

- `scale` : `gdouble`, scale render by this factor

- `unlimited` : `gboolean`, allow SVGs of any size

Render a SVG file into a VIPS image. Rendering uses the librsvg library and should be fast.

Use `dpi` to set the rendering resolution. The default is 72. You can also scale the rendering by `scale` .

This function only reads the image header and does not render any pixel data. Rendering occurs when pixels are accessed.

SVGs larger than 10MB are normally blocked for security. Set `unlimited` to allow SVGs of any size.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_svgload_buffer ()

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

Optional arguments:

- `dpi` : `gdouble`, render at this DPI

- `scale` : `gdouble`, scale render by this factor

- `unlimited` : `gboolean`, allow SVGs of any size

Read a SVG-formatted memory block into a VIPS image. Exactly as `vips_svgload()`, but read from a memory buffer.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_svgload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_gifload ()

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

Optional arguments:

- `page` : `gint`, page (frame) to read

- `n` : `gint`, load this many pages

Read a GIF file into a VIPS image.

Use `page` to select a page to render, numbering from zero.

Use `n` to select the number of pages to render. The default is 1. Pages are rendered in a vertical column, with each individual page aligned to the left. Set to -1 to mean "until the end of the document". Use `vips_grid()` to change page layout.

The whole GIF is rendered into memory on header access. The output image will be 1, 2, 3 or 4 bands depending on what the reader finds in the file.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_gifload_buffer ()

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

Optional arguments:

- `page` : `gint`, page (frame) to read

- `n` : `gint`, load this many pages

Read a GIF-formatted memory block into a VIPS image. Exactly as `vips_gifload()`, but read from a memory buffer.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_gifload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_heifload ()

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

Optional arguments:

- `page` : `gint`, page (top-level image number) to read

- `n` : `gint`, load this many pages

- `thumbnail` : `gboolean`, fetch thumbnail instead of image

- `autorotate` : `gboolean`, rotate image upright during load

Read a HEIF image file into a VIPS image.

Use `page` to select a page to render, numbering from zero. If neither `n` nor `page` are set, `page` defaults to the primary page, otherwise to 0.

Use `n` to select the number of pages to render. The default is 1. Pages are rendered in a vertical column. Set to -1 to mean "until the end of the document". Use `vips_grid()` to reorganise pages.

HEIF images have a primary image. The metadata item `heif-primary` gives the page number of the primary.

If `thumbnail` is `TRUE`, then fetch a stored thumbnail rather than the image.

Setting `autorotate` to `TRUE` will make the loader interpret the orientation tag and automatically rotate the image appropriately during load.

If `autorotate` is `FALSE`, the metadata field VIPS_META_ORIENTATION is set to the value of the orientation tag. Applications may read and interpret this field as they wish later in processing. See `vips_autorot()`. Save operations will use VIPS_META_ORIENTATION, if present, to set the orientation of output images.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_heifload_buffer ()

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

Optional arguments:

- `page` : `gint`, page (top-level image number) to read

- `n` : `gint`, load this many pages

- `thumbnail` : `gboolean`, fetch thumbnail instead of image

- `autorotate` : `gboolean`, rotate image upright during load

Read a HEIF image file into a VIPS image. Exactly as `vips_heifload()`, but read from a memory buffer.

You must not free the buffer while `out` is active. The “postclose” signal on `out` is a good place to free.

See also: `vips_heifload()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | image to write. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_heifsave ()

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

Optional arguments:

- `Q` : `gint`, quality factor

- `lossless` : `gboolean`, enable lossless encoding

- `compression` : VipsForeignHeifCompression, write with this compression

Write a VIPS image to a file in HEIF format.

Use `Q` to set the compression factor. Default 50, which seems to be roughly what the iphone uses. Q 30 gives about the same quality as JPEG Q 75.

Set `lossless` `TRUE` to switch to lossless compression.

Use `compression` to set the encoder e.g. HEVC, AVC, AV1

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

[method]

#### Parameters

in | image to save |
filename | file to write to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_heifsave_buffer ()

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

Optional arguments:

- `Q` : `gint`, quality factor

- `lossless` : `gboolean`, enable lossless encoding

- `compression` : VipsForeignHeifCompression, write with this compression

As `vips_heifsave()`, 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_heifsave()`, `vips_image_write_to_file()`.

[method]

#### Parameters

in | image to save |
buf | return output buffer here. | [array length=len][element-type guint8]
len | return output length here. | [type gsize]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_niftiload ()

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

Read a NIFTI image file into a VIPS image.

NIFTI metadata is attached with the "nifti-" prefix.

See also: `vips_image_new_from_file()`.

#### Parameters

filename | file to load |
out | decompressed image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_niftisave ()

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

Write a VIPS image to a file in NIFTI format.

Use the various NIFTI suffixes to pick the nifti save format.

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

[method]

#### Parameters

in | image to save |
filename | file to write to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_dzsave ()

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

Optional arguments:

- `basename` : `gchar`, base part of name

- `layout` : VipsForeignDzLayout directory layout convention

- `suffix` : suffix for tile tiles

- `overlap` : `gint` set tile overlap

- `tile_size` : `gint` set tile size

- `background` : VipsArrayDouble background colour

- `depth` : VipsForeignDzDepth how deep to make the pyramid

- `centre` : `gboolean` centre the tiles

- `angle` : VipsAngle rotate the image by this much

- `container` : VipsForeignDzContainer set container type

- `properties` : `gboolean` write a properties file

- `compression` : `gint` zip deflate compression level

- `region_shrink` : VipsRegionShrink how to shrink each 2x2 region

- `skip_blanks` : `gint` skip tiles which are nearly equal to the background

- `no_strip` : `gboolean` don't strip tiles

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

vips_dzsave() creates a directory called `name` to hold the tiles. If `name` ends `.zip`, `vips_dzsave()` will create a zip file called `name` to hold the tiles. You can use `container` to force zip file output.

Use `basename` to set the name of the directory tree we are creating. The default value is set from `name` .

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` . The deepzoom defaults produce 256x256 jpeg files for centre tiles, the most efficient size.

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

You can rotate the image during write with the `angle` argument. However, this will only work for images which support random access, like openslide, and not for things like JPEG. You'll need to rotate those images yourself with `vips_rot()`. Note that the `autorotate` option to the loader may do what you need.

If `properties` is `TRUE`, `vips_dzsave()` will write a file called `vips-properties.xml` to the output directory. This file lists all of the metadata attached to `in` in an obvious manner. It can be useful for viewing programs which wish to use fields from source files loaded via `vips_openslideload()`.

By default, all tiles are stripped, since very few people want a copy of the metadata on every tile. Set `no_strip` if you really want to keep metadata.

If `container` is set to `zip`, you can set a compression level from -1 (use zlib default), 0 (store, compression disabled) to 9 (max compression). If no value is given, the default is to store files without compression.

You can use `region_shrink` to control the method for shrinking each 2x2 region. This defaults to using the average of the 4 input pixels but you can also use the median in cases where you want to preserve the range of values.

If you set `skip_blanks` to a value greater than or equal to zero, tiles which are all within that many pixel values to the background are skipped. This can save a lot of space for some image types. This option defaults to 5 in Google layout mode, -1 otherwise.

See also: `vips_tiffsave()`.

[method]

#### Parameters

in | image to save |
name | name to save to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

## Types and Values

### enum 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()`.

#### Members

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

### enum VipsSaveable

See also: VipsForeignSave.

#### Members

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_RGBA_ONLY | 3 or 4 bands (eg. WEBP) |
VIPS_SAVEABLE_RGB_CMYK | 1, 3 or 4 bands (eg. JPEG) |
VIPS_SAVEABLE_ANY | any number of bands (eg. TIFF) |
VIPS_SAVEABLE_LAST |  |

### enum VipsForeignWebpPreset

Tune lossy encoder settings for different image types.

#### Members

VIPS_FOREIGN_WEBP_PRESET_DEFAULT | default preset |
VIPS_FOREIGN_WEBP_PRESET_PICTURE | digital picture, like portrait, inner shot |
VIPS_FOREIGN_WEBP_PRESET_PHOTO | outdoor photograph, with natural lighting |
VIPS_FOREIGN_WEBP_PRESET_DRAWING | hand or line drawing, with high-contrast details |
VIPS_FOREIGN_WEBP_PRESET_ICON | small-sized colorful images |
VIPS_FOREIGN_WEBP_PRESET_TEXT | text-like |
VIPS_FOREIGN_WEBP_PRESET_LAST |  |

### enum 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.

Use `lossless` to set WEBP lossless compression.

Use `level` to set webp and zstd compression level.

#### Members

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_WEBP | WEBP compression |
VIPS_FOREIGN_TIFF_COMPRESSION_ZSTD | ZSTD compression |
VIPS_FOREIGN_TIFF_COMPRESSION_LAST |  |

### enum VipsForeignTiffPredictor

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

#### Members

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

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

#### Members

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

### enum VipsForeignPngFilter

http://www.w3.org/TR/PNG-Filters.html The values mirror those of png.h in libpng.

#### Members

VIPS_FOREIGN_PNG_FILTER_NONE | no filtering |
VIPS_FOREIGN_PNG_FILTER_SUB | difference to the left |
VIPS_FOREIGN_PNG_FILTER_UP | difference up |
VIPS_FOREIGN_PNG_FILTER_AVG | average of left and up |
VIPS_FOREIGN_PNG_FILTER_PAETH | pick best neighbor predictor automatically |
VIPS_FOREIGN_PNG_FILTER_ALL | adaptive |

### enum VipsForeignDzLayout

What directory layout and metadata standard to use.

#### Members

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_IIIF | use IIIF directory layout |
VIPS_FOREIGN_DZ_LAYOUT_LAST |  |

### enum VipsForeignDzDepth

How many pyramid layers to create.

#### Members

VIPS_FOREIGN_DZ_DEPTH_ONEPIXEL | create layers down to 1x1 pixel |
VIPS_FOREIGN_DZ_DEPTH_ONETILE | create layers down to 1x1 tile |
VIPS_FOREIGN_DZ_DEPTH_ONE | only create a single layer |
VIPS_FOREIGN_DZ_DEPTH_LAST |  |

### enum VipsForeignDzContainer

How many pyramid layers to create.

#### Members

VIPS_FOREIGN_DZ_CONTAINER_FS | write tiles to the filesystem |
VIPS_FOREIGN_DZ_CONTAINER_ZIP | write tiles to a zip file |
VIPS_FOREIGN_DZ_CONTAINER_SZI | write to a szi file |
VIPS_FOREIGN_DZ_CONTAINER_LAST |  |

### enum VipsForeignHeifCompression

The compression format to use inside a HEIF container.

This is assumed to use the same numbering as `heif_compression_format`.

#### Members

VIPS_FOREIGN_HEIF_COMPRESSION_HEVC | x265 |
VIPS_FOREIGN_HEIF_COMPRESSION_AVC | x264 |
VIPS_FOREIGN_HEIF_COMPRESSION_JPEG | jpeg |
VIPS_FOREIGN_HEIF_COMPRESSION_AV1 | aom |
VIPS_FOREIGN_HEIF_COMPRESSION_LAST |  |

## Property Details

### The `“access”` property

      “access”                   VipsAccess

Required access pattern for this file.

Flags: Read / Write

Default value: VIPS_ACCESS_RANDOM

### The `“disc”` property

      “disc”                     gboolean

Open to disc.

Flags: Read / Write

Default value: TRUE

### The `“fail”` property

      “fail”                     gboolean

Fail on first error.

Flags: Read / Write

Default value: FALSE

### The `“flags”` property

      “flags”                    VipsForeignFlags

Flags for this file.

Flags: Read / Write

### The `“memory”` property

      “memory”                   gboolean

Force open via memory.

Flags: Read / Write

Default value: FALSE

### The `“out”` property

      “out”                      VipsImage *

Output image.

Flags: Read / Write

### The `“sequential”` property

      “sequential”               gboolean

Sequential read only.

Flags: Read / Write

Default value: FALSE

### The `“background”` property

      “background”               VipsArrayDouble *

Background value.

Flags: Read / Write

### The `“in”` property

      “in”                       VipsImage *

Image to save.

Flags: Read / Write

### The `“page-height”` property

      “page-height”              gint

Set page height for multipage save.

Flags: Read / Write

Allowed values: [0,10000000]

Default value: 0

### The `“strip”` property

      “strip”                    gboolean

Strip all metadata from image.

Flags: Read / Write

Default value: FALSE

## See Also

image