## VipsFormat

VipsFormat — load and save in a variety of formats

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    enum                VipsFormatFlags;
                        VipsFormat;
                        VipsFormatClass;
    void *              vips_format_map                     (VipsSListMap2Fn fn,
                                                             void *a,
                                                             void *b);
    VipsFormatClass *   vips_format_for_file                (const char *filename);
    VipsFormatClass *   vips_format_for_name                (const char *filename);
    VipsFormatFlags     vips_format_get_flags               (VipsFormatClass *format,
                                                             const char *filename);
    int                 vips_format_read                    (const char *filename,
                                                             VipsImage *out);
    int                 vips_format_write                   (VipsImage *in,
                                                             const char *filename);
    int                 im_jpeg2vips                        (const char *filename,
                                                             VipsImage *out);
    int                 im_bufjpeg2vips                     (void *buf,
                                                             size_t len,
                                                             VipsImage *out,
                                                             gboolean header_only);
    int                 im_vips2jpeg                        (VipsImage *in,
                                                             const char *filename);
    int                 im_vips2mimejpeg                    (VipsImage *in,
                                                             int qfac);
    int                 im_vips2bufjpeg                     (VipsImage *in,
                                                             VipsImage *out,
                                                             int qfac,
                                                             char **obuf,
                                                             int *olen);
    int                 im_tiff2vips                        (const char *filename,
                                                             VipsImage *out);
    int                 im_vips2tiff                        (VipsImage *in,
                                                             const char *filename);
    int                 im_tile_cache                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int tile_width,
                                                             int tile_height,
                                                             int max_tiles);
    int                 im_magick2vips                      (const char *filename,
                                                             VipsImage *out);
    int                 im_exr2vips                         (const char *filename,
                                                             VipsImage *out);
    int                 im_ppm2vips                         (const char *filename,
                                                             VipsImage *out);
    int                 im_vips2ppm                         (VipsImage *in,
                                                             const char *filename);
    int                 im_analyze2vips                     (const char *filename,
                                                             VipsImage *out);
    int                 im_csv2vips                         (const char *filename,
                                                             VipsImage *out);
    int                 im_vips2csv                         (VipsImage *in,
                                                             const char *filename);
    int                 im_png2vips                         (const char *filename,
                                                             VipsImage *out);
    int                 im_vips2png                         (VipsImage *in,
                                                             const char *filename);
    int                 im_vips2bufpng                      (VipsImage *in,
                                                             VipsImage *out,
                                                             int compression,
                                                             int interlace,
                                                             char **obuf,
                                                             size_t *olen);
    int                 im_raw2vips                         (const char *filename,
                                                             VipsImage *out,
                                                             int width,
                                                             int height,
                                                             int bpp,
                                                             int offset);
    int                 im_vips2raw                         (VipsImage *in,
                                                             int fd);
    int                 im_mat2vips                         (const char *filename,
                                                             VipsImage *out);
    int                 im_rad2vips                         (const char *filename,
                                                             VipsImage *out);
    int                 im_vips2rad                         (VipsImage *in,
                                                             const char *filename);
    int                 im_fits2vips                        (const char *filename,
                                                             VipsImage *out);
    int                 im_vips2fits                        (VipsImage *in,
                                                             const char *filename);

## Object Hierarchy

      GObject
       +----VipsObject
             +----VipsFormat

## Description

VIPS has a simple system for representing image load and save operations in a generic way. You can ask for a loader for a certain file or select a saver based on a filename. Once you have found a format, you can use it to load a file of that type, save an image to a file of that type, query files for their type and fields, and ask for supported features. You can also call the converters directly, if you like.

If you define a new format, support for it automatically appears in all VIPS user-interfaces. It will also be transparently supported by `im_open()`.

VIPS comes with VipsFormat for TIFF, JPEG, PNG, Analyze, PPM, OpenEXR, CSV, Matlab, Radiance, RAW, VIPS and one that wraps libMagick.

## Details

### enum VipsFormatFlags

    typedef enum {
    	VIPS_FORMAT_NONE = 0,		/* No flags set */
    	VIPS_FORMAT_PARTIAL = 1, /* Lazy read OK (eg. tiled tiff) */
    	VIPS_FORMAT_BIGENDIAN = 2 /* Most-significant byte first */
    } VipsFormatFlags;

Some hints about the image loader.

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

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

`VIPS_FORMAT_NONE` | no flags set
`VIPS_FORMAT_PARTIAL` | the image may be read lazilly
`VIPS_FORMAT_BIGENDIAN` | image pixels are most-significant byte first

### VipsFormat

    typedef struct _VipsFormat VipsFormat;

Actually, we never make `VipsFormat` objects, we just use virtual methods on the class object. It is defined as:

    typedef struct _VipsFormatClass {
      VipsObjectClass parent_class;

      gboolean (*is_a)( const char *filename );
      int (*header)( const char *filename, IMAGE *out );
      int (*load)( const char *filename, IMAGE *out );
      int (*save)( IMAGE *in, const char *filename );
      VipsFormatFlags (*get_flags)( const char *filename );
      int priority;
      const char **suffs;
    } VipsFormatClass;

Add a new format to VIPS by subclassing VipsFormat. Subclasses need to implement at least `load()` or `save()`.

These members are:

- `is_a()` This function should return `TRUE` if the file contains an image of this type. If you don't define this function, VIPS will use the list of suffixes you supply instead.

- `header()` This function should load the image header, but not load any pixel data. If you don't define it, VIPS will use your `load()` method instead. Return 0 for success, -1 for error, setting `im_error()`.

- `load()` This function should load the image, or perhaps use `im_generate()` to attach something to load sections of the image on demand. Users can embed load options in the filename, see (for example) `im_jpeg2vips()`. If you don't define this method, you can still define `save()` and have a save-only format. Return 0 for success, -1 for error, setting `im_error()`.

- `save()` This function should save the image to the file. Users can embed save options in the filename, see (for example) `im_vips2tiff()`. If you don't define this method, you can still define `load()` and have a load-only format. Return 0 for success, -1 for error, setting `im_error()`.

- `get_flags()` This function should return a hint about the properties of this loader on this file. If you don't define it, users will always see '0', or no flags.

- `priority` Where this format should fit in this list of supported formats. 0 is a sensible value for most formats. Set a negative value if you want to be lower on the list, positive to move up.

- `suffs` A `NULL`-terminated list of possible file name suffixes, for example:

      static const char *tiff_suffs[] = { ".tif", ".tiff", NULL };

  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.

At the command-line, use:

    vips --list classes | grep Format

To see a list of all the supported formats.

For example, the TIFF format is defined like this:

    typedef VipsFormat VipsFormatTiff;
    typedef VipsFormatClass VipsFormatTiffClass;

    static void
    vips_format_tiff_class_init( VipsFormatTiffClass *class )
    {
    	VipsObjectClass *object_class = (VipsObjectClass *) class;
    	VipsFormatClass *format_class = (VipsFormatClass *) class;

    	object_class->nickname = "tiff";
    	object_class->description = _( "TIFF" );

    	format_class->is_a = istiff;
    	format_class->header = tiff2vips_header;
    	format_class->load = im_tiff2vips;
    	format_class->save = im_vips2tiff;
    	format_class->get_flags = tiff_flags;
    	format_class->suffs = tiff_suffs;
    }

    static void
    vips_format_tiff_init( VipsFormatTiff *object )
    {
    }

    G_DEFINE_TYPE( VipsFormatTiff, vips_format_tiff, VIPS_TYPE_FORMAT );

Then call `vips_format_tiff_get_type()` somewhere in your init code to link the format into VIPS (though of course the tiff format is linked in for you already).

### VipsFormatClass

    typedef struct {
    	VipsObjectClass parent_class;

    	/* Is a file in this format.
    	 */
    	gboolean (*is_a)( const char * );

    	/* Read just the header into the VipsImage.
    	 */
    	int (*header)( const char *, VipsImage * );

    	/* Load the whole image.
    	 */
    	int (*load)( const char *, VipsImage * );

    	/* Write the VipsImage to the file in this format.
    	 */
    	int (*save)( VipsImage *, const char * );

    	/* Get the flags for this file in this format.
    	 */
    	VipsFormatFlags (*get_flags)( const char * );

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

    	/* Null-terminated list of allowed suffixes, eg. ".tif", ".tiff".
    	 */
    	const char **suffs;
    } VipsFormatClass;

### vips_format_map ()

    void *              vips_format_map                     (VipsSListMap2Fn fn,
                                                             void *a,
                                                             void *b);

Apply a function to every `VipsFormatClass` that VIPS knows about. Formats 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: `im_slist_map()`.

`fn` : | function to apply to each VipsFormatClass
`a` : | user data
`b` : | user data
Returns : | the result of iteration

### vips_format_for_file ()

    VipsFormatClass *   vips_format_for_file                (const char *filename);

Searches for a format you could use to load a file.

See also: `vips_format_read()`, `vips_format_for_name()`.

`filename` : | file to find a format for
Returns : | a format on success, `NULL` on error

### vips_format_for_name ()

    VipsFormatClass *   vips_format_for_name                (const char *filename);

Searches for a format you could use to save a file.

See also: `vips_format_write()`, `vips_format_for_file()`.

`filename` : | name to find a format for
Returns : | a format on success, `NULL` on error

### vips_format_get_flags ()

    VipsFormatFlags     vips_format_get_flags               (VipsFormatClass *format,
                                                             const char *filename);

Get a set of flags for this file.

`format` : | format to test
`filename` : | file to test
Returns : | flags for this format and file

### vips_format_read ()

    int                 vips_format_read                    (const char *filename,
                                                             VipsImage *out);

Searches for a format for this file, then loads the file into `out`.

See also: `vips_format_write()`.

`filename` : | file to load
`out` : | write the file to this image
Returns : | 0 on success, -1 on error

### vips_format_write ()

    int                 vips_format_write                   (VipsImage *in,
                                                             const char *filename);

Searches for a format for this name, then saves `im` to it.

See also: `vips_format_read()`.

`in` : | image to write
`filename` : | file to write to
Returns : | 0 on success, -1 on error

### im_jpeg2vips ()

    int                 im_jpeg2vips                        (const char *filename,
                                                             VipsImage *out);

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

You can embed options in the filename. They have the form:

    filename.jpg:shrink-factor,fail

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

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

Example:

    im_jpeg2vips( "fred.jpg:8" out );
    im_jpeg2vips( "fred.jpg:,fail" out );

The first example will shrink by a factor of 8 during load. The second will fail with an error if there are any problems loading the file.

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 metadata. You need to use something like `im_icc_import()` to get CIE values from the file. Any EXIF data is also attached as VIPS metadata.

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

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

See also: VipsFormat, `im_vips2jpeg()`.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_bufjpeg2vips ()

    int                 im_bufjpeg2vips                     (void *buf,
                                                             size_t len,
                                                             VipsImage *out,
                                                             gboolean header_only);

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

This function is handy for processing JPEG image thumbnails.

See also: VipsFormat, `im_jpeg2vips()`.

`buf` : | memory area to load
`len` : | size of memory area
`out` : | image to write
`header_only` : | set to just read the header
Returns : | 0 on success, -1 on error.

### im_vips2jpeg ()

    int                 im_vips2jpeg                        (VipsImage *in,
                                                             const char *filename);

Write a VIPS image to a file as JPEG.

You can embed options in the filename. They have the form:

    filename.jpg:compression,profile

- compression Compress with this quality factor. Default 75.

- profile Attach this ICC profile. For example, "fred.jpg:,/home/john/srgb.icc" will embed the profile stored in the file "/home/john/srgb.icc" in the JPEG image. This does not affect the pixels which are written, just the way they are tagged. You can use the special string "none" to mean "don't attach a profile".

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

The image is automatically converted to RGB, Monochrome or CMYK before saving. Any metadata attached to the image is saved as EXIF, if possible.

Example:

    im_vips2jpeg( in, "fred.jpg:99,none" );

Will write "fred.jpg" at high-quality with no ICC profile.

See also: VipsFormat, `im_jpeg2vips()`.

`in` : | image to save
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

### im_vips2mimejpeg ()

    int                 im_vips2mimejpeg                    (VipsImage *in,
                                                             int qfac);

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

See also: VipsFormat, `im_vips2jpeg()`.

`in` : | image to save
`qfac` : | JPEG quality factor
Returns : | 0 on success, -1 on error.

### im_vips2bufjpeg ()

    int                 im_vips2bufjpeg                     (VipsImage *in,
                                                             VipsImage *out,
                                                             int qfac,
                                                             char **obuf,
                                                             int *olen);

As `im_vips2jpeg()`, but save as a memory buffer. The memory is allocated local to `out` (that is, when `out` is closed the memory will be released, pass `NULL` to release yourself).

The address of the buffer is returned in `obuf`, the length of the buffer in `olen`. `olen` should really be a size_t rather than an int :-(

See also: VipsFormat, `im_vips2jpeg()`.

`in` : | image to save
`out` : | allocate output buffer local to this
`qfac` : | JPEG quality factor
`obuf` : | return output buffer here
`olen` : | return output length here
Returns : | 0 on success, -1 on error.

### im_tiff2vips ()

    int                 im_tiff2vips                        (const char *filename,
                                                             VipsImage *out);

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.

You can embed a page number in the filename. For example:

    im_tiff2vips( "fred.tif:23", out );

Will read page 23. By default, the operation reads the first page.

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

See also: VipsFormat, `im_vips2tiff()`.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_vips2tiff ()

    int                 im_vips2tiff                        (VipsImage *in,
                                                             const char *filename);

Write a VIPS image to a file as TIFF.

You can embed options in the filename. They have the form:

    filename.tif:compression,layout,multi-res,format,resolution,icc, bigtiff

- compression should be one of "none" (no compression), "jpeg" (JPEG compression), "deflate" (ZIP compression), "packbits" (TIFF packbits compression), "ccittfax4" (CCITT Group 4 fax encoding), "lzw" (Lempel-Ziv compression).

  "jpeg" compression can be followed by a ":" character and a JPEG quality level; "lzw" and "deflate" can be followed by a ":" and predictor value. The default compression type is "none", the default JPEG quality factor is 75.

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

  JPEG compression is a good lossy compressor for photographs, packbits is good for 1-bit images, and deflate is the best lossless compression TIFF can do. LZW has patent problems and is no longer recommended.

- layout should be "strip" (strip layout) or "tile" (tiled layout).

  "tile" layout can be followed by a ":" character and the horizontal and vertical tile size, separated by a "x" character. The default layout is "strip", and the default tile size is 128 by 128 pixels.

- multi-res should be "flat" (single image) or "pyramid" (many images arranged in a pyramid). The default multi-res mode is "flat".

- format shoiuld be "manybit" (don't bit-reduce images) or "onebit" (one band 8 bit images are saved as 1 bit). The default format is "multibit".

- resolution should be "res_cm" (output resolution unit is pixels per centimetre) or "res_inch" (output resolution unit is pixels per inch). The default resolution unit is taken from the header field "resolution-unit" (IM_META_RESOLUTION_UNIT in C). If this field is not set, then VIPS defaults to cm.

  The unit can optionally be followed by a ":" character and the horizontal and vertical resolution, separated by a "x" character. You can have a single number with no "x" and set the horizontal and vertical resolutions together.

- icc Attach this ICC profile. This does not affect the pixels which are written, just the way they are tagged.

- bigtiff Set this to 8 to enable bigtiff output. Bigtiff is a variant of the TIFF format that allows more than 4GB in a file.

Example:

    im_vips2jpeg( in, "fred.tif:jpeg,tile,pyramid" );

Will write "fred.tif" as a tiled jpeg-compressed pyramid.

    im_vips2jpeg( in, "fred.tif:packbits,tile,,onebit" );

Writes a tiled one bit TIFF image (provided fred.v is a one band 8 bit image) compressed with packbits.

See also: VipsFormat, `im_tiff2vips()`.

`in` : | image to save
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

### im_tile_cache ()

    int                 im_tile_cache                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int tile_width,
                                                             int tile_height,
                                                             int max_tiles);

This operation behaves rather like `im_copy()` between images `in` and `out`, except that it keeps a cache of computed pixels. This cache is made of up to `max_tiles` tiles (a value of -1 for means any number of tiles), and each tile is of size `tile_width` by `tile_height` pixels. Each cache tile is made with a single call to `im_prepare()`.

This is a lower-level operation than `im_cache()` since it does no subdivision. It is suitable for caching the output of operations like `im_exr2vips()` on tiled images.

See also: `im_cache()`.

`in` : | input image
`out` : | output image
`tile_width` : | tile width
`tile_height` : | tile height
`max_tiles` : | maximum number of tiles to cache
Returns : | 0 on success, -1 on error.

### im_magick2vips ()

    int                 im_magick2vips                      (const char *filename,
                                                             VipsImage *out);

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 also: VipsFormat.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_exr2vips ()

    int                 im_exr2vips                         (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: VipsFormat.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_ppm2vips ()

    int                 im_ppm2vips                         (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.

PFM images have the scale factor attached as "pfm-scale".

See also: VipsFormat, `im_vips2ppm()`, `im_meta_get_double()`

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_vips2ppm ()

    int                 im_vips2ppm                         (VipsImage *in,
                                                             const char *filename);

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

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

The storage format is indicated by a filename extension, for example:

    im_vips2ppm( im, "fred.ppm:ascii" )

will write to "fred.ppm" in ascii format. The default is binary.

See also: VipsFormat, `im_ppm2vips()`, `im_meta_set_double()`.

`in` : | image to save
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

### im_analyze2vips ()

    int                 im_analyze2vips                     (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: VipsFormat, `im_meta_get()`, `im_grid()`.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_csv2vips ()

    int                 im_csv2vips                         (const char *filename,
                                                             VipsImage *out);

Load a CSV (comma-separated values) file. The output image is always 1 band (monochrome), `IM_BANDFMT_DOUBLE`. 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.

Read options can be embedded in the filename. The options can be given in any order and are:

- skip:lines-to-skip The number of lines to skip at the start of the file. Default zero.

- line:lines-to-read The number of lines to read from the file. Default -1, meaning read to end of file.

- whi:whitespace-characters The skippable whitespace characters. Default space and double quotes ("). Whitespace characters are always run together.

- sep:separator-characters The characters that separate fields. Default ;,tab. Separators are never run together.

For example:

    im_csv2vips( "fred.csv:skip:58,sep:\,,line:3", out );

Will read three lines starting at line 59, with comma as the only allowed separator. Note that the ',' has to be escaped with a backslash.

See also: VipsFormat, `im_vips2csv()`, `im_read_dmask()`, `im_ppm2vips()`.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_vips2csv ()

    int                 im_vips2csv                         (VipsImage *in,
                                                             const char *filename);

Save a CSV (comma-separated values) file. The image is written one line of text per scanline. Complex numbers are written as "(real,imaginary)" and will need extra parsing I guess. The image must have a single band.

Write options can be embedded in the filename. The options can be given in any order and are:

- sep:separator-string The string to use to separate numbers in the output. The default is "\\t" (tab).

For example:

    im_csv2vips( in, "fred.csv:sep:\t" );

Will write to fred.csv, separating numbers with tab characters.

See also: VipsFormat, `im_csv2vips()`, `im_write_dmask()`, `im_vips2ppm()`.

`in` : | image to save
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

### im_png2vips ()

    int                 im_png2vips                         (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.

There is no support for embedded ICC profiles.

See also: VipsFormat, `im_vips2png()`.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_vips2png ()

    int                 im_vips2png                         (VipsImage *in,
                                                             const char *filename);

Write a VIPS image to a file as PNG.

You can embed options in the filename. They have the form:

    filename.png:compression,interlace

- compression Compress with this much effort (0 - 9). Default 6.

- interlace 0 means don't interlace (the default), 1 selects ADAM7 interlacing. Beware than an interlaced PNG can be up to 7 times slower to write than a non-interlaced image.

There is no support for attaching ICC profiles to PNG images.

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.

Example:

    im_vips2png( in, "fred.png:0,1" );

Will write "fred.png" with no compression and with ADAM7 interlacing.

See also: VipsFormat, `im_png2vips()`.

`in` : | image to save
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

### im_vips2bufpng ()

    int                 im_vips2bufpng                      (VipsImage *in,
                                                             VipsImage *out,
                                                             int compression,
                                                             int interlace,
                                                             char **obuf,
                                                             size_t *olen);

As `im_vips2png()`, but save as a memory buffer. The memory is allocated local to `out` (that is, when `out` is closed the memory will be released, pass `NULL` to release yourself).

The address of the buffer is returned in `obuf`, the length of the buffer in `olen`.

See also: VipsFormat, `im_vips2png()`.

`in` : | image to save
`out` : | allocate output buffer local to this
`compression` : | compress with this much effort
`interlace` : | 0 means don't interlace, 1 selects ADAM7 interlacing
`obuf` : | return output buffer here
`olen` : | return output length here
Returns : | 0 on success, -1 on error.

### im_raw2vips ()

    int                 im_raw2vips                         (const char *filename,
                                                             VipsImage *out,
                                                             int width,
                                                             int height,
                                                             int bpp,
                                                             int offset);

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

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

See also: VipsFormat, `im_vips2raw()`.

`filename` : | file to read
`out` : | image to write to
`width` : | image width in pixels
`height` : | image height in pixels
`bpp` : | bytes per pixel
`offset` : | skip this many bytes at the start of the file
Returns : | 0 on success, -1 on error.

### im_vips2raw ()

    int                 im_vips2raw                         (VipsImage *in,
                                                             int fd);

Writes the pixels in `in` to the file descriptor. It's handy for writing writers for other formats.

See also: VipsFormat, `im_raw2vips()`.

`in` : | image to save
`fd` : | file descriptor to write to
Returns : | 0 on success, -1 on error.

### im_mat2vips ()

    int                 im_mat2vips                         (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: VipsFormat.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_rad2vips ()

    int                 im_rad2vips                         (const char *filename,
                                                             VipsImage *out);

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

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

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

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

See also: VipsFormat, `im_rad2float()`, `im_vips2rad()`.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_vips2rad ()

    int                 im_vips2rad                         (VipsImage *in,
                                                             const char *filename);

Write a VIPS image in Radiance (HDR) format.

This operation needs an IM_CODING_RAD image, or a three-band float image.

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

See also: VipsFormat, `im_float2rad()`, `im_rad2vips()`.

`in` : | image to save
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

### im_fits2vips ()

    int                 im_fits2vips                        (const char *filename,
                                                             VipsImage *out);

Read a FITS image file into a VIPS image.

See also: `im_vips2fits()`, VipsFormat.

`filename` : | file to load
`out` : | image to write to
Returns : | 0 on success, -1 on error.

### im_vips2fits ()

    int                 im_vips2fits                        (VipsImage *in,
                                                             const char *filename);

Write `in` to `filename` in FITS format.

See also: `im_fits2vips()`, VipsFormat.

`in` : | image to write
`filename` : | file to write to
Returns : | 0 on success, -1 on error.

## See Also

image