VipsForeignSave

VipsForeignSave — load and save images in a variety of formats

Stability Level

Stable, unless otherwise indicated

Functions

Properties

VipsAccess access Read / Write
gboolean disc Read / Write
VipsForeignFlags flags Read / Write
VipsImage * out Read / Write
gboolean sequential Read / Write
VipsArrayDouble * background Read / Write
VipsImage * in Read / Write
gboolean strip Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── VipsObject
        ╰── VipsOperation
            ├── VipsForeign
               ├── VipsForeignLoad
               ╰── VipsForeignSave
            ╰── 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:

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

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 (void *data,
                               size_t size);

Searches for an operation you could use to load a memory 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

 

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_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_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_openslideload ()

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

Optional arguments:

level : load this level associated : load this associated image autocrop : 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.

The output of this operator is always RGBA.

See also: vips_image_new_from_file().

Parameters

filename

file to load

 

out

decompressed image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_jpegload ()

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

Optional arguments:

shrink : shrink by this much on load fail : fail on warnings autorotate : use exif Orientation tag to rotate the image 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 warnings. 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 EXIF Orientation field and automatically rotate the image appropriately during load. After rotation, the Orientation tag will be removed to prevent accidental double-rotation.

Using autorotate can be much slower than doing the rotate later in processing. See vips_autorot().

Example:

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

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

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

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

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

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

See also: vips_jpegload_buffer(), vips_image_new_from_file().

Parameters

filename

file to load

 

out

decompressed image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_jpegload_buffer ()

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

Optional arguments:

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

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

See also: vips_jpegload().

Parameters

buf

memory area to load

 

len

size of memory area

 

out

image to write

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_jpegsave ()

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

Optional arguments:

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

Write a VIPS image to a file as JPEG.

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

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

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

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

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

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

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

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

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

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

See also: vips_jpegsave_buffer(), vips_image_write_to_file().

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 : JPEG quality factor profile : attach this ICC profile optimize_coding : compute optimal Huffman coding tables interlace : write an interlaced (progressive) jpeg strip : remove all metadata from image no -subsample: disable chroma subsampling

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

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

See also: vips_jpegsave(), vips_image_write_to_file().

Parameters

in

image to save

 

buf

return output buffer here

 

len

return output length here

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_jpegsave_mime ()

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

Optional arguments:

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

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

See also: vips_jpegsave(), vips_image_write_to_file().

Parameters

in

image to save

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_webpload ()

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

Optional arguments:

Read a webp file into a VIPS image.

See also:

Parameters

filename

file to load

 

out

decompressed image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_webpload_buffer ()

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

See also:

Parameters

buf

memory area to load

 

len

size of memory area

 

out

image to write

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_webpsave ()

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

Optional arguments:

Q : quality factor

See also:

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 : JPEG quality factor

See also:

Parameters

in

image to save

 

buf

return output buffer here

 

len

return output length here

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_webpsave_mime ()

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

Optional arguments:

Q : quality factor

See also:

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 : int, load this page

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

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

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

See also: vips_image_new_from_file().

Parameters

filename

file to load

 

out

decompressed image

 

...

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 : load this page

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

See also: vips_tiffload().

Parameters

buf

memory area to load

 

len

size of memory area

 

out

image to write

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_tiffsave ()

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

Optional arguments:

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

Write a VIPS image to a file as TIFF.

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

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

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

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

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

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

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

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

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

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

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

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

If in has a field called VIPS_META_XMP_NAME ("xmp-data") it is written to the tiff image.

See also: vips_tiffload(), vips_image_write_to_file().

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

 

...

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

 

...

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

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

 

...

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 : offset in bytes from start of file

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

out will be a 8-bit uchar image with bands image bands, so bands can be thought of as meaning "number of bytes per pixel". Use functions like vips_copy() to set the exact band format, number of bands, byte ordering and so on.

See also: vips_image_new_from_file().

Parameters

filename

file to load

 

out

output image

 

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

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

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

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

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

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

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

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

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

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

See also: vips_image_new_from_file().

Parameters

filename

file to load

 

out

output image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_csvsave ()

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

Optional arguments:

separator : separator string

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

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

See also: vips_image_write_to_file().

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 line of matrix data, with numbers again separated by any mixture of spaces, commas, tabs and quotation marks ("). The numbers may be floating-point, and must use '.' as a decimal separator.

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

See also: vips_csvload().

Parameters

filename

file to load

 

out

output image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_matrixsave ()

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

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

See also: vips_matrixload().

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

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:

all_frames : gboolean, load all frames in sequence 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.

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

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

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_pngload ()

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

Optional arguments:

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

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

See also: vips_image_new_from_file().

Parameters

filename

file to load

 

out

decompressed image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_pngload_buffer ()

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

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

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

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

See also: vips_pngload().

Parameters

buf

memory area to load

 

len

size of memory area

 

out

image to write

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_pngsave ()

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

Optional arguments:

compression : compression level interlace : interlace image profile : ICC profile to embed filter : VipsForeignPngFilter row filter flag(s)

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. You can use the special string "none" to mean "don't attach a profile".

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.

See also: vips_image_new_from_file().

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 : compression level interlace : interlace image profile : ICC profile to embed filter : libpng row filter flag(s)

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

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

See also: vips_pngsave(), vips_image_write_to_file().

Parameters

in

image to save

 

buf

return output buffer here

 

len

return output length here

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_ppmload ()

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

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

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

See also: vips_image_new_from_file().

Parameters

filename

file to load

 

out

output image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_ppmsave ()

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

Optional arguments:

ascii : save as ASCII rather than binary 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().

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

 

...

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

 

...

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

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:

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

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.

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

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

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

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

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

See also: vips_tiffsave().

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_RGB_CMYK

1, 3 or 4 bands (eg. JPEG)

 

VIPS_SAVEABLE_ANY

any number of bands (eg. TIFF)

 

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

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

   

enum VipsForeignDzDepth

How many pyramid layers to create.

Members

VIPS_FOREIGN_DZ_DEPTH_1PIXEL

create layers down to 1x1 pixel

 

VIPS_FOREIGN_DZ_DEPTH_1TILE

create layers down to 1x1 tile

 

VIPS_FOREIGN_DZ_DEPTH_1

only create a single layer

 

VIPS_FOREIGN_DZ_DEPTH_LAST

   

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_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 “flags” property

  “flags”                    VipsForeignFlags

Flags for this file.

Flags: Read / Write


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 “strip” property

  “strip”                    gboolean

Strip all metadata from image.

Flags: Read / Write

Default value: FALSE

See Also

image