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_vipsload_source ()
int vips_vipssave ()
int vips_vipssave_target ()
int vips_openslideload ()
int vips_openslideload_source ()
int vips_jpegload ()
int vips_jpegload_buffer ()
int vips_jpegload_source ()
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_tiffsave_target ()
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_csvload_source ()
int vips_csvsave ()
int vips_csvsave_target ()
int vips_matrixload ()
int vips_matrixload_source ()
int vips_matrixsave ()
int vips_matrixsave_target ()
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_ppmload_source ()
int vips_ppmsave ()
int vips_ppmsave_target ()
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_pdfload_source ()
int vips_svgload ()
int vips_svgload_buffer ()
int vips_svgload_string ()
int vips_svgload_source ()
int vips_gifload ()
int vips_gifload_buffer ()
int vips_gifload_source ()
int vips_gifsave ()
int vips_gifsave_buffer ()
int vips_gifsave_target ()
int vips_heifload ()
int vips_heifload_buffer ()
int vips_heifload_source ()
int vips_heifsave ()
int vips_heifsave_buffer ()
int vips_heifsave_target ()
int vips_niftiload ()
int vips_niftiload_source ()
int vips_niftisave ()
int vips_jp2kload ()
int vips_jp2kload_buffer ()
int vips_jp2kload_source ()
int vips_jp2ksave ()
int vips_jp2ksave_buffer ()
int vips_jp2ksave_target ()
int vips_jxlload_source ()
int vips_jxlload_buffer ()
int vips_jxlload ()
int vips_jxlsave ()
int vips_jxlsave_buffer ()
int vips_jxlsave_target ()
int vips_dzsave ()
int vips_dzsave_buffer ()
int vips_dzsave_target ()

Properties

VipsAccess access Read / Write
gboolean disc Read / Write
gboolean fail Read / Write
VipsFailOn fail-on Read / Write
VipsForeignFlags flags Read / Write
gboolean memory Read / Write
VipsImage * out Read / Write
gboolean revalidate Read / Write
gboolean sequential Read / Write
VipsArrayDouble * background Read / Write
VipsImage * in Read / Write
VipsForeignKeep keep Read / Write
int page-height Read / Write
char * profile Read / Write
gboolean strip Read / Write

Object Hierarchy

    GEnum
    ├── VipsFailOn
    ├── VipsForeignDzContainer
    ├── VipsForeignDzDepth
    ├── VipsForeignDzLayout
    ├── VipsForeignHeifCompression
    ├── VipsForeignHeifEncoder
    ├── VipsForeignJpegSubsample
    ├── VipsForeignPpmFormat
    ├── VipsForeignSubsample
    ├── VipsForeignTiffCompression
    ├── VipsForeignTiffPredictor
    ├── VipsForeignTiffResunit
    ├── VipsForeignWebpPreset
    ╰── VipsSaveable
    GFlags
    ├── VipsForeignFlags
    ├── VipsForeignKeep
    ╰── VipsForeignPngFilter
    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.

Load and save

You can load and save from and to files, memory areas, and the libvips IO abstractions, VipsSource and VipsTarget.

Use vips_foreign_find_load(), vips_foreign_find_load_buffer() and vips_foreign_find_load_source() to find a loader for an object. Use vips_foreign_find_save(), vips_foreign_find_save_buffer() and vips_foreign_find_save_target() to find a saver for a format. 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);


Image metadata

All loaders attach all image metadata as libvips properties on load.

You can change metadata with vips_image_set_int() and friends.

During save, you can use keep to specify which metadata to retain, defaults to all, see VipsForeignKeep. Setting profile will automatically keep the ICC profile.


Many page images

By default, libvips will only load the first page of many page or animated images. Use page and n to set the start page and the number of pages to load. Set n to -1 to load all pages.

Many page images are loaded as a tall, thin strip of pages.

Use vips_image_get_page_height() and vips_image_get_n_pages() to find the page height and number of pages of a loaded image.

Use page_height to set the page height for image save.


Alpha save

Not all image formats support alpha. If you try to save an image with an alpha channel to a format that does not support it, the alpha will be automatically flattened out. Use background (default 0) to set the colour that alpha should be flattened against.


Adding new formats

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.

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.

[nullable]


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

Returns

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

[transfer full][array]


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.

[nullable]


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.

[nullable]


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

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

Exactly as vips_vipsload(), but read from a source.

Parameters

source

source to load from

 

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

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

As vips_vipssave(), but save to a 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_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

  • rgb : gboolean, output RGB (not RGBA) pixels

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.

By default, the output of this operator is RGBA. Set rgb to enable RGB output.

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

int
vips_openslideload_source (VipsSource *source,
                           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

  • rgb : gboolean, output RGB (not RGBA) pixels

Exactly as vips_openslideload(), but read from a source.

Parameters

source

source to load from

 

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_on : VipsFailOn, types of read error to fail on

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

Use fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, VIPS_FAIL_ON_NONE.

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_on", VIPS_FAIL_ON_TRUNCATED,
    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_on : VipsFailOn, types of read error to fail on

  • 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_jpegload_source ()

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

Optional arguments:

  • shrink : gint, shrink by this much on load

  • fail_on : VipsFailOn, types of read error to fail on

  • 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 source.

See also: vips_jpegload().

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

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

Optional arguments:

  • Q : gint, quality factor

  • optimize_coding : gboolean, compute optimal Huffman coding tables

  • interlace : gboolean, write an interlaced (progressive) jpeg

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • 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

  • restart_interval : gint, restart interval in mcu

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

  • optimize_coding : gboolean, compute optimal Huffman coding tables

  • interlace : gboolean, write an interlaced (progressive) jpeg

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • 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

  • restart_interval : gint, restart interval in mcu

Write a VIPS image to a file as JPEG.

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

If optimize_coding is set, the Huffman tables are optimized. This is slightly 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 connection, but need much more memory to encode and decode.

Chroma subsampling is normally automatically disabled for Q >= 90. You can force the subsampling mode with subsample_mode .

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, producing 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.

By default, the output stream won't have restart markers. If a non-zero restart_interval is specified, a restart marker will be added after each specified number of MCU blocks. This makes the stream more recoverable if there are transmission errors, but also allows for some decoders to read part of the JPEG without decoding the whole stream.

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

  • optimize_coding : gboolean, compute optimal Huffman coding tables

  • interlace : gboolean, write an interlaced (progressive) jpeg

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • 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

  • restart_interval : gint, restart interval in mcu

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

  • optimize_coding : gboolean, compute optimal Huffman coding tables

  • interlace : gboolean, write an interlaced (progressive) jpeg

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • 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

  • restart_interval : gint, restart interval in mcu

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. Animated webp images don't support shrink-on-load, so a further resize may be necessary.

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

  • effort : gint, level of CPU effort to reduce file size

  • min_size : gboolean, minimise size

  • mixed : gboolean, allow both lossy and lossless encoding

  • kmin : gint, minimum number of frames between keyframes

  • kmax : gint, maximum number of frames between keyframes

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

  • effort : gint, level of CPU effort to reduce file size

  • min_size : gboolean, minimise size

  • mixed : gboolean, allow both lossy and lossless encoding

  • kmin : gint, minimum number of frames between keyframes

  • kmax : gint, maximum number of frames between keyframes

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

For animated webp output, mixed tries to improve the file size by mixing both lossy and lossless encoding.

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

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

  • effort : gint, level of CPU effort to reduce file size

  • min_size : gboolean, minimise size

  • mixed : gboolean, allow both lossy and lossless encoding

  • kmin : gint, minimum number of frames between keyframes

  • kmax : gint, maximum number of frames between keyframes

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

  • effort : gint, level of CPU effort to reduce file size

  • min_size : gboolean, minimise size

  • mixed : gboolean, allow both lossy and lossless encoding

  • kmin : gint, minimum number of frames between keyframes

  • kmax : gint, maximum number of frames between keyframes

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

  • subifd : gint, select this subifd index

Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader, with extensions for tiled images, multipage images, XYZ and 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.

If autorotate is TRUE, the image will be rotated upright during load and no metadata attached. This can be very slow.

If subifd is -1 (the default), the main image is selected for each page. If it is 0 or greater and there is a SUBIFD tag, the indexed SUBIFD is selected. This can be used to read lower resolution layers from bioformats-style image pyramids.

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

  • subifd : gint, select this subifd index

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

  • subifd : gint, select this subifd index

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

  • 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

  • bitdepth : int, change bit depth to 1,2, or 4 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 lossless mode

  • depth : VipsForeignDzDepth how deep to make the pyramid

  • subifd : gboolean write pyr layers as sub-ifds

  • premultiply : gboolean write premultiplied alpha

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.

XYZ images are automatically saved as libtiff LOGLUV with SGILOG compression. Float LAB images are saved as float CIELAB. Set bitdepth to save as 8-bit CIELAB.

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, deflate and zstd compression. It defaults to VIPS_FOREIGN_TIFF_PREDICTOR_HORIZONTAL, meaning horizontal differencing. Please refer to the libtiff specifications for further discussion of various predictors.

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.

By default, the pyramid stops when the image is small enough to fit in one tile. Use depth to stop when the image fits in one pixel, or to only write a single layer.

Set bitdepth to save 8-bit uchar images as 1, 2 or 4-bit TIFFs. In case of depth 1: 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. In case of depth 2: The same holds but values < 64 are written as black. For 64 <= values < 128 they are written as dark grey, for 128 <= values < 192 they are written as light gray and values above are written as white. In case miniswhite is set to true this behavior is inverted. In case of depth 4: values < 16 are written as black, and so on for the lighter shades. In case miniswhite is set to true this behavior is inverted.

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.

By default, pyramid layers are saved as consecutive pages. Set subifd to save pyramid layers as sub-directories of the main image. Setting this option can improve compatibility with formats like OME.

Set premultiply to save with premultiplied alpha. Some programs, such as InDesign, will only work with premultiplied alpha.

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

  • 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

  • bitdepth : int, set write bit depth to 1, 2, 4 or 8

  • 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 lossless mode

  • depth : VipsForeignDzDepth how deep to make the pyramid

  • subifd : gboolean write pyr layers as sub-ifds

  • premultiply : gboolean write premultiplied alpha

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

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

Optional arguments:

  • compression : use this VipsForeignTiffCompression

  • Q : gint quality factor

  • predictor : use this VipsForeignTiffPredictor

  • 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

  • bitdepth : int, set write bit depth to 1, 2, 4 or 8

  • 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 lossless mode

  • depth : VipsForeignDzDepth how deep to make the pyramid

  • subifd : gboolean write pyr layers as sub-ifds

  • premultiply : gboolean write premultiplied alpha

As vips_tiffsave(), but save to a target.

See also: vips_tiffsave(), 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_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:

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_on : VipsFailOn, types of read error to fail on

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

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.

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.

Use fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, VIPS_FAIL_ON_NONE.

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

int
vips_csvload_source (VipsSource *source,
                     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_on : VipsFailOn, types of read error to fail on

Exactly as vips_csvload(), but read from a source.

See also: vips_csvload().

Parameters

source

source 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_csvsave_target ()

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

Optional arguments:

  • separator : separator string

As vips_csvsave(), but save to a target.

See also: vips_csvsave().

[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_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_matrixload().

Parameters

filename

file to load

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_matrixload_source ()

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

Exactly as vips_matrixload(), but read from a source.

See also: vips_matrixload().

Parameters

source

source 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_matrixsave_target ()

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

As vips_matrixsave(), but save to a target.

See also: vips_matrixsave().

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

  • bitdepth : gint, number of bits per pixel

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.

bitdepth specifies the number of bits per pixel. The image will be quantized and dithered if the value is within the valid range (1 to 8).

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

  • bitdepth : gint, number of bits per pixel

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

Optional arguments:

  • fail_on : VipsFailOn, types of read error to fail on

  • unlimited : gboolean, Remove all denial of service limits

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

Optional arguments:

  • fail_on : VipsFailOn, types of read error to fail on

  • unlimited : gboolean, remove all denial of service limits

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.

Use fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, VIPS_FAIL_ON_NONE.

By default, the PNG loader limits the number of text and data chunks to block some denial of service attacks. Set unlimited to disable these limits.

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

Optional arguments:

  • fail_on : VipsFailOn, types of read error to fail on

  • unlimited : gboolean, Remove all denial of service limits

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

  • filter : libpng row filter flag(s)

  • palette : enable quantisation to 8bpp palette

  • Q : quality for 8bpp quantisation

  • dither : amount of dithering for 8bpp quantization

  • bitdepth : gint, set write bit depth to 1, 2, 4, 8 or 16

  • effort : gint, quantisation CPU effort

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

  • filter : VipsForeignPngFilter row filter flag(s)

  • palette : gboolean, enable quantisation to 8bpp palette

  • Q : gint, quality for 8bpp quantisation

  • dither : gdouble, amount of dithering for 8bpp quantization

  • bitdepth : gint, set write bit depth to 1, 2, 4, 8 or 16

  • effort : gint, quantisation CPU effort

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 filter to specify one or more filters, defaults to none, 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 palette mode for RGB or RGBA images. A palette will be computed with enough space for bitdepth (1, 2, 4 or 8) bits. Use Q to set the optimisation effort, dither to set the degree of Floyd-Steinberg dithering and effort to control the CPU effort (1 is the fastest, 10 is the slowest, 7 is the default). This feature requires libvips to be compiled with libimagequant.

The default bitdepth is either 8 or 16 depending on the interpretation. You can also set bitdepth for mono and mono + alpha images, and the image will be quantized.

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

  • filter : VipsForeignPngFilter row filter flag(s)

  • palette : gboolean, enable quantisation to 8bpp palette

  • Q : gint, quality for 8bpp quantisation

  • dither : gdouble, amount of dithering for 8bpp quantization

  • bitdepth : gint, set write bit depth to 1, 2, 4, 8 or 16

  • effort : gint, quantisation CPU effort

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

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

Exactly as vips_ppmload(), but read from a source.

See also: vips_ppmload().

Parameters

source

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

  • format : VipsForeignPpmFormat, format to save in

  • ascii : gboolean, save as ASCII rather than binary

  • bitdepth : gint, bitdepth to save at

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 bitdepth to 1 to write a one-bit image.

format defaults to the sub-type for this filename suffix.

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

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

Optional arguments:

  • format : VipsForeignPpmFormat, format to save in

  • ascii : gboolean, save as ASCII rather than binary

  • bitdepth : gint, bitdepth to save at

As vips_ppmsave(), but save to a target.

See also: vips_ppmsave().

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

  • password : gchararray background colour

Render a PDF file into a VIPS image.

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. Additionally, you can scale by setting scale . If you set both, they combine.

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

Use password to supply a decryption password.

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

int
vips_pdfload_source (VipsSource *source,
                     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

Exactly as vips_pdfload(), but read from a source.

See also: vips_pdfload()

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

int
vips_svgload_string (const char *str,
                     VipsImage **out,
                     ...);

Optional arguments:

  • dpi : gdouble, render at this DPI

  • scale : gdouble, scale render by this factor

  • unlimited : gboolean, allow SVGs of any size

Exactly as vips_svgload(), but read from a string. This function takes a copy of the string.

See also: vips_svgload().

Parameters

str

string to load

 

out

image to write.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_svgload_source ()

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

Exactly as vips_svgload(), but read from a source.

See also: vips_svgload().

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

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

Optional arguments:

  • page : gint, page (frame) to read

  • n : gint, load this many pages

  • fail_on : VipsFailOn, types of read error to fail on

Read a GIF file into a libvips 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. Set to -1 to mean "until the end of the document". Use vips_grid() to change page layout.

Use fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, VIPS_FAIL_ON_NONE.

The output image is RGBA for GIFs containing transparent elements, RGB otherwise.

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

  • fail_on : VipsFailOn, types of read error to fail on

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

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

Optional arguments:

  • page : gint, page (frame) to read

  • n : gint, load this many pages

  • fail_on : VipsFailOn, types of read error to fail on

Exactly as vips_gifload(), but read from a source.

See also: vips_gifload().

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

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

Optional arguments:

  • dither : gdouble, quantisation dithering level

  • effort : gint, quantisation CPU effort

  • bitdepth : gint, number of bits per pixel

  • interframe_maxerror : gdouble, maximum inter-frame error for transparency

  • reuse : gboolean, reuse palette from input

  • interlace : gboolean, write an interlaced (progressive) GIF

  • interpalette_maxerror : gdouble, maximum inter-palette error for palette reusage

Write to a file in GIF format.

Use dither to set the degree of Floyd-Steinberg dithering and effort to control the CPU effort (1 is the fastest, 10 is the slowest, 7 is the default).

Use bitdepth (from 1 to 8, default 8) to control the number of colours in the palette. The first entry in the palette is always reserved for transparency. For example, a bitdepth of 4 will allow the output to contain up to 15 colours.

Use interframe_maxerror to set the threshold below which pixels are considered equal. Pixels which don't change from frame to frame can be made transparent, improving the compression rate. Default 0.

Use interpalette_maxerror to set the threshold below which the previously generated palette will be reused.

If reuse is TRUE, the GIF will be saved with a single global palette taken from the metadata in in , and no new palette optimisation will be done.

If interlace is TRUE, the GIF file will be interlaced (progressive GIF). These files may be better for display over a slow network connection, but need more memory to encode.

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

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

Optional arguments:

  • dither : gdouble, quantisation dithering level

  • effort : gint, quantisation CPU effort

  • bitdepth : gint, number of bits per pixel

  • interframe_maxerror : gdouble, maximum inter-frame error for transparency

  • reuse : gboolean, reuse palette from input

  • interlace : gboolean, write an interlaced (progressive) GIF

  • interpalette_maxerror : gdouble, maximum inter-palette error for palette reusage

As vips_gifsave(), 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_gifsave(), 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_gifsave_target ()

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

Optional arguments:

  • dither : gdouble, quantisation dithering level

  • effort : gint, quantisation CPU effort

  • bitdepth : gint, number of bits per pixel

  • interframe_maxerror : gdouble, maximum inter-frame error for transparency

  • reuse : gboolean, reuse palette from input

  • interlace : gboolean, write an interlaced (progressive) GIF

  • interpalette_maxerror : gdouble, maximum inter-palette error for palette reusage

As vips_gifsave(), but save to a target.

See also: vips_gifsave(), 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_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

  • unlimited : gboolean, remove all denial of service limits

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.

By default, input image dimensions are limited to 16384x16384. If unlimited is TRUE, this increases to the maximum of 65535x65535.

The bitdepth of the heic image is recorded in the metadata item heif-bitdepth.

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

  • unlimited : gboolean, remove all denial of service limits

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

int
vips_heifload_source (VipsSource *source,
                      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

  • unlimited : gboolean, remove all denial of service limits

Exactly as vips_heifload(), but read from a source.

See also: vips_heifload().

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

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

Optional arguments:

  • Q : gint, quality factor

  • bitdepth : gint, set write bit depth to 8, 10, or 12 bits

  • lossless : gboolean, enable lossless encoding

  • compression : VipsForeignHeifCompression, write with this compression

  • effort : gint, encoding effort

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • encoder : VipsForeignHeifEncoder, select encoder to use

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 compression format e.g. HEVC, AVC, AV1 to use. It defaults to AV1 if the target filename ends with ".avif", otherwise HEVC.

Use effort to control the CPU effort spent improving compression. This is currently only applicable to AV1 encoders. Defaults to 4, 0 is fastest, 9 is slowest.

Chroma subsampling is normally automatically disabled for Q >= 90. You can force the subsampling mode with subsample_mode .

Use bitdepth to set the bitdepth of the output file. HEIC supports at least 8, 10 and 12 bits; other codecs may support more or fewer options.

Use encoder to set the encode library to use, e.g. aom, SVT-AV1, rav1e etc.

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

  • bitdepth : gint, set write bit depth to 8, 10, or 12 bits

  • lossless : gboolean, enable lossless encoding

  • compression : VipsForeignHeifCompression, write with this compression

  • effort : gint, encoding effort

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • encoder : VipsForeignHeifEncoder, select encoder to use

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

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

Optional arguments:

  • Q : gint, quality factor

  • bitdepth : gint, set write bit depth to 8, 10, or 12 bits

  • lossless : gboolean, enable lossless encoding

  • compression : VipsForeignHeifCompression, write with this compression

  • effort : gint, encoding effort

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

  • encoder : VipsForeignHeifEncoder, select encoder to use

As vips_heifsave(), but save to a target.

See also: vips_heifsave(), 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_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_niftiload_source ()

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

Exactly as vips_niftiload(), but read from a source.

Parameters

source

source to load from

 

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

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

Optional arguments:

  • page : gint, load this page

  • fail_on : VipsFailOn, types of read error to fail on

Read a JPEG2000 image. The loader supports 8, 16 and 32-bit int pixel values, signed and unsigned. It supports greyscale, RGB, YCC, CMYK and multispectral colour spaces. It will read any ICC profile on the image.

It will only load images where all channels have the same format.

Use page to set the page to load, where page 0 is the base resolution image and higher-numbered pages are x2 reductions. Use the metadata item "n-pages" to find the number of pyramid layers.

Use fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, VIPS_FAIL_ON_NONE.

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

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

Optional arguments:

  • page : gint, load this page

  • fail_on : VipsFailOn, types of read error to fail on

Exactly as vips_jp2kload(), but read from a buffer.

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

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

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

Optional arguments:

  • page : gint, load this page

  • fail_on : VipsFailOn, types of read error to fail on

Exactly as vips_jp2kload(), but read from a source.

Parameters

source

source to load from

 

out

decompressed image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_jp2ksave ()

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

Optional arguments:

  • Q : gint, quality factor

  • lossless : gboolean, enables lossless compression

  • tile_width : gint for tile size

  • tile_height : gint for tile size

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

Write a VIPS image to a file in JPEG2000 format. The saver supports 8, 16 and 32-bit int pixel values, signed and unsigned. It supports greyscale, RGB, CMYK and multispectral images.

Use Q to set the compression quality factor. The default value produces file with approximately the same size as regular JPEG Q 75.

Set lossless to enable lossless compression.

Use tile_width and tile_height to set the tile size. The default is 512.

Chroma subsampling is normally disabled for compatibility. Set subsample_mode to auto to enable chroma subsample for Q < 90. Subsample mode uses YCC rather than RGB colourspace, and many jpeg2000 decoders do not support this.

This operation always writes a pyramid.

See also: vips_image_write_to_file(), vips_jp2kload().

[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_jp2ksave_buffer ()

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

Optional arguments:

  • Q : gint, quality factor

  • lossless : gboolean, enables lossless compression

  • tile_width : gint for tile size

  • tile_height : gint for tile size

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

As vips_jp2ksave(), but save to a target.

See also: vips_jp2ksave(), vips_image_write_to_target().

[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_jp2ksave_target ()

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

Optional arguments:

  • Q : gint, quality factor

  • lossless : gboolean, enables lossless compression

  • tile_width : gint for tile size

  • tile_height : gint for tile size

  • subsample_mode : VipsForeignSubsample, chroma subsampling mode

As vips_jp2ksave(), but save to a target.

See also: vips_jp2ksave(), 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_jxlload_source ()

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

Exactly as vips_jxlload(), but read from a source.

Parameters

source

source to load from

 

out

decompressed image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_jxlload_buffer ()

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

Exactly as vips_jxlload(), but read from a buffer.

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

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

Read a JPEG-XL image.

The JPEG-XL loader and saver are experimental features and may change in future libvips versions.

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

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

Optional arguments:

  • tier : gint, decode speed tier

  • distance : gdouble, maximum encoding error

  • effort : gint, encoding effort

  • lossless : gboolean, enables lossless compression

  • Q : gint, quality setting

Write a VIPS image to a file in JPEG-XL format.

The JPEG-XL loader and saver are experimental features and may change in future libvips versions.

tier sets the overall decode speed the encoder will target. Minimum is 0 (highest quality), and maximum is 4 (lowest quality). Default is 0.

distance sets the target maximum encoding error. Minimum is 0 (highest quality), and maximum is 15 (lowest quality). Default is 1.0 (visually lossless).

As a convenience, you can also use Q to set distance . Q uses approximately the same scale as regular JPEG.

Set lossless to enable lossless compression.

[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_jxlsave_buffer ()

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

Optional arguments:

  • tier : gint, decode speed tier

  • distance : gdouble, maximum encoding error

  • effort : gint, encoding effort

  • lossless : gboolean, enables lossless compression

  • Q : gint, quality setting

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

See also: vips_jxlsave(), vips_image_write_to_target().

[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_jxlsave_target ()

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

Optional arguments:

  • tier : gint, decode speed tier

  • distance : gdouble, maximum encoding error

  • effort : gint, encoding effort

  • lossless : gboolean, enables lossless compression

  • Q : gint, quality setting

As vips_jxlsave(), but save to a target.

See also: vips_jxlsave(), 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_dzsave ()

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

Optional arguments:

  • basename : gchar base part of name

  • layout : VipsForeignDzLayout directory layout convention

  • suffix : gchar suffix for 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

  • 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

  • id : gchar id for IIIF properties

  • Q : gint, quality factor

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 image we are creating. The default value is set from name .

By default, tiles are written as JPEGs. Use Q set set the JPEG quality factor.

You can set suffix to something like ".png[bitdepth=4]" to write tiles in another format.

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.

By default, all tiles are stripped since usually you do not want a copy of all metadata in every tile. Set keep if you 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.

In IIIF layout, you can set the base of the id property in info.json with id . The default is https://example.com/iiif.

Use layout VIPS_FOREIGN_DZ_LAYOUT_IIIF3 for IIIF v3 layout.

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.


vips_dzsave_buffer ()

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

Optional arguments:

  • basename : gchar base part of name

  • layout : VipsForeignDzLayout directory layout convention

  • suffix : gchar suffix for 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

  • 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

  • id : gchar id for IIIF properties

  • Q : gint, quality factor

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

Output is always in a zip container. Use basename to set the name of the directory that the zip will create when unzipped.

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_dzsave(), 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_dzsave_target ()

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

Optional arguments:

  • basename : gchar base part of name

  • layout : VipsForeignDzLayout directory layout convention

  • suffix : gchar suffix for 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

  • 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

  • id : gchar id for IIIF properties

  • Q : gint, quality factor

As vips_dzsave(), but save to a target.

See also: vips_dzsave(), 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.

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 VipsFailOn

How sensitive loaders are to errors, from never stop (very insensitive), to stop on the smallest warning (very sensitive).

Each one implies the ones before it, so VIPS_FAIL_ON_ERROR implies VIPS_FAIL_ON_TRUNCATED.

Members

VIPS_FAIL_ON_NONE

never stop

 

VIPS_FAIL_ON_TRUNCATED

stop on image truncated, nothing else

 

VIPS_FAIL_ON_ERROR

stop on serious error or truncation

 

VIPS_FAIL_ON_WARNING

stop on anything, even warnings

 

VIPS_FAIL_ON_LAST

   

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 VipsForeignKeep

Which metadata to retain.

Members

VIPS_FOREIGN_KEEP_NONE

don't attach metadata

 

VIPS_FOREIGN_KEEP_EXIF

keep Exif metadata

 

VIPS_FOREIGN_KEEP_XMP

keep XMP metadata

 

VIPS_FOREIGN_KEEP_IPTC

keep IPTC metadata

 

VIPS_FOREIGN_KEEP_ICC

keep ICC metadata

 

VIPS_FOREIGN_KEEP_OTHER

keep other metadata (e.g. PNG comments and some TIFF tags)

 

VIPS_FOREIGN_KEEP_ALL

keep all metadata

 

enum VipsForeignSubsample

Set subsampling mode.

Members

VIPS_FOREIGN_SUBSAMPLE_AUTO

prevent subsampling when quality >= 90

 

VIPS_FOREIGN_SUBSAMPLE_ON

always perform subsampling

 

VIPS_FOREIGN_SUBSAMPLE_OFF

never perform subsampling

 

VIPS_FOREIGN_SUBSAMPLE_LAST

   

enum VipsForeignJpegSubsample

VipsForeignJpegSubsample is deprecated and should not be used in newly-written code.

use VipsForeignSubsample

Set jpeg subsampling mode.

Members

VIPS_FOREIGN_JPEG_SUBSAMPLE_AUTO

default preset

 

VIPS_FOREIGN_JPEG_SUBSAMPLE_ON

always perform subsampling

 

VIPS_FOREIGN_JPEG_SUBSAMPLE_OFF

never perform subsampling

 

VIPS_FOREIGN_JPEG_SUBSAMPLE_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 predictor to set the lzw or deflate prediction, default horizontal.

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_JP2K

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

The netpbm file format to save as.

VIPS_FOREIGN_PPM_FORMAT_PBM images are single bit.

VIPS_FOREIGN_PPM_FORMAT_PGM images are 8, 16, or 32-bits, one band.

VIPS_FOREIGN_PPM_FORMAT_PPM images are 8, 16, or 32-bits, three bands.

VIPS_FOREIGN_PPM_FORMAT_PFM images are 32-bit float pixels.

VIPS_FOREIGN_PPM_FORMAT_PNM images are anymap images -- the image format is used to pick the saver.

Members

VIPS_FOREIGN_PPM_FORMAT_PBM

portable bitmap

 

VIPS_FOREIGN_PPM_FORMAT_PGM

portable greymap

 

VIPS_FOREIGN_PPM_FORMAT_PPM

portable pixmap

 

VIPS_FOREIGN_PPM_FORMAT_PFM

portable float map

 

VIPS_FOREIGN_PPM_FORMAT_PNM

portable anymap

 

VIPS_FOREIGN_PPM_FORMAT_LAST

   

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 v2 directory layout

 

VIPS_FOREIGN_DZ_LAYOUT_IIIF3

use IIIF v3 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

   

enum VipsForeignHeifEncoder

The selected encoder to use. If libheif hasn't been compiled with the selected encoder, we will fallback to the default encoder for the compression format.

Members

VIPS_FOREIGN_HEIF_ENCODER_AUTO

auto

 

VIPS_FOREIGN_HEIF_ENCODER_AOM

aom

 

VIPS_FOREIGN_HEIF_ENCODER_RAV1E

RAV1E

 

VIPS_FOREIGN_HEIF_ENCODER_SVT

SVT-AV1

 

VIPS_FOREIGN_HEIF_ENCODER_X265

x265

 

VIPS_FOREIGN_HEIF_ENCODER_LAST

   

Property Details

The “access” property

  “access”                   VipsAccess

Required access pattern for this file.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: VIPS_ACCESS_RANDOM


The “disc” property

  “disc”                     gboolean

Open to disc.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: TRUE


The “fail” property

  “fail”                     gboolean

Fail on first warning.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: FALSE


The “fail-on” property

  “fail-on”                  VipsFailOn

Error level to fail on.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: VIPS_FAIL_ON_NONE


The “flags” property

  “flags”                    VipsForeignFlags

Flags for this file.

Owner: VipsForeignLoad

Flags: Read / Write


The “memory” property

  “memory”                   gboolean

Force open via memory.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: FALSE


The “out” property

  “out”                      VipsImage *

Output image.

Owner: VipsForeignLoad

Flags: Read / Write


The “revalidate” property

  “revalidate”               gboolean

Don't use a cached result for this operation.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: FALSE


The “sequential” property

  “sequential”               gboolean

Sequential read only.

Owner: VipsForeignLoad

Flags: Read / Write

Default value: FALSE


The “background” property

  “background”               VipsArrayDouble *

Background value.

Owner: VipsForeignSave

Flags: Read / Write


The “in” property

  “in”                       VipsImage *

Image to save.

Owner: VipsForeignSave

Flags: Read / Write


The “keep” property

  “keep”                     VipsForeignKeep

Which metadata to retain.

Owner: VipsForeignSave

Flags: Read / Write

Default value: VIPS_FOREIGN_KEEP_EXIF | VIPS_FOREIGN_KEEP_XMP | VIPS_FOREIGN_KEEP_IPTC | VIPS_FOREIGN_KEEP_ICC | VIPS_FOREIGN_KEEP_OTHER


The “page-height” property

  “page-height”              int

Set page height for multipage save.

Owner: VipsForeignSave

Flags: Read / Write

Allowed values: [0,10000000]

Default value: 0


The “profile” property

  “profile”                  char *

Filename of ICC profile to embed.

Owner: VipsForeignSave

Flags: Read / Write

Default value: NULL


The “strip” property

  “strip”                    gboolean

Strip all metadata from image.

Owner: VipsForeignSave

Flags: Read / Write

Default value: FALSE

See Also

image