Load and save

You can load and save from and to files, memory areas, and the libvips IOabstractions,VipsSource andVipsTarget.

Usevips_foreign_find_load(),vips_foreign_find_load_buffer() andvips_foreign_find_load_source() to find a loader for an object. Usevips_foreign_find_save(),vips_foreign_find_save_buffer() andvips_foreign_find_save_target() to find a saver for a format. You can thenrun these operations usingvips_call() and friends to perform the load orsave.

vips_image_write_to_file() andvips_image_new_from_file() and friends usethese functions to automate file load and save.

You can also invoke the operations directly, for example:

123

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 withvips_image_set_int() and friends.

During save, you can usekeep to specify which metadata to retain,defaults to all, seeVipsForeignKeep. Settingprofile willautomatically keep the ICC profile.

Many page images

By default, libvips will only load the first page of many page or animatedimages. Usepage andn to set the start page and the number of pages toload. Setn to -1 to load all pages.

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

Usevips_image_get_page_height() andvips_image_get_n_pages() to find thepage height and number of pages of a loaded image.

Usepage_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 analpha channel to a format that does not support it, the alpha will beautomatically flattened out. Usebackground (default 0) to set the colourthat alpha should be flattened against.

Adding new formats

To add support for a new file format to vips, simply define a new subclassofVipsForeignLoad orVipsForeignSave.

If you define a new operation which is a subclass ofVipsForeign, supportfor it automatically appears in all VIPS user-interfaces. It will also betransparently supported byvips_image_new_from_file() and friends.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990

typedefstruct_VipsForeignLoadPng{VipsForeignLoadparent_object;char*filename;}VipsForeignLoadPng;typedefVipsForeignLoadClassVipsForeignLoadPngClass;G_DEFINE_TYPE(VipsForeignLoadPng,vips_foreign_load_png,VIPS_TYPE_FOREIGN_LOAD);staticVipsForeignFlagsvips_foreign_load_png_get_flags_filename(constchar*filename){VipsForeignFlagsflags;flags=0;if(vips__png_isinterlaced(filename))flags=VIPS_FOREIGN_PARTIAL;elseflags=VIPS_FOREIGN_SEQUENTIAL;returnflags;}staticVipsForeignFlagsvips_foreign_load_png_get_flags(VipsForeignLoad*load){VipsForeignLoadPng*png=(VipsForeignLoadPng*)load;returnvips_foreign_load_png_get_flags_filename(png->filename);}staticintvips_foreign_load_png_header(VipsForeignLoad*load){VipsForeignLoadPng*png=(VipsForeignLoadPng*)load;if(vips__png_header(png->filename,load->out))return-1;return0;}staticintvips_foreign_load_png_load(VipsForeignLoad*load){VipsForeignLoadPng*png=(VipsForeignLoadPng*)load;if(vips__png_read(png->filename,load->real))return-1;return0;}staticvoidvips_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);}staticvoidvips_foreign_load_png_init(VipsForeignLoadPng*png){}

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869

typedefstruct_VipsForeignSaveCsv{VipsForeignSaveparent_object;char*filename;constchar*separator;}VipsForeignSaveCsv;typedefVipsForeignSaveClassVipsForeignSaveCsvClass;G_DEFINE_TYPE(VipsForeignSaveCsv,vips_foreign_save_csv,VIPS_TYPE_FOREIGN_SAVE);staticintvips_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;return0;}staticvoidvips_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 usVIPS_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");}staticvoidvips_foreign_save_csv_init(VipsForeignSaveCsv*csv){csv->separator=g_strdup("\t");}

vips_foreign_map ()

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

Apply a function to everyVipsForeignClass that VIPS knows about. Foreignsare presented to the function in priority order.

Like all VIPS map functions, iffn returnsNULL, iteration continues. Ifit returns non-NULL, iteration terminates and that value is returned. Themap function returnsNULL if all calls returnNULL.

See also:vips_slist_map().

vips_foreign_find_load ()

constchar *vips_foreign_find_load (constchar *filename);

Searches for an operation you could use to loadfilename. Any trailingoptions onfilename are stripped and ignored.

See also:vips_foreign_find_load_buffer(),vips_image_new_from_file().

vips_foreign_find_load_buffer ()

constchar *vips_foreign_find_load_buffer (constvoid *data,size_t size);

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

vips -l | grep load_buffer

See also:vips_image_new_from_buffer().

vips_foreign_find_load_source ()

constchar *vips_foreign_find_load_source (VipsSource *source);

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

vips -l | grep load_source

See also:vips_image_new_from_source().

vips_foreign_flags ()

VipsForeignFlagsvips_foreign_flags (constchar *loader,constchar *filename);

Return the flags forfilename usingloader.loader is something like "tiffload" or "VipsForeignLoadTiff".

vips_foreign_is_a ()

gbooleanvips_foreign_is_a (constchar *loader,constchar *filename);

ReturnTRUE iffilename can be loaded byloader.loader is somethinglike "tiffload" or "VipsForeignLoadTiff".

vips_foreign_is_a_buffer ()

gbooleanvips_foreign_is_a_buffer (constchar *loader,constvoid *data,size_t size);

ReturnTRUE ifdata can be loaded byloader.loader is somethinglike "tiffload_buffer" or "VipsForeignLoadTiffBuffer".

vips_foreign_is_a_source ()

gbooleanvips_foreign_is_a_source (constchar *loader,VipsSource *source);

ReturnTRUE ifsource can be loaded byloader.loader is somethinglike "tiffload_source" or "VipsForeignLoadTiffSource".

vips_foreign_load_invalidate ()

voidvips_foreign_load_invalidate (VipsImage *image);

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

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

[method]

vips_foreign_find_save ()

constchar *vips_foreign_find_save (constchar *filename);

Searches for an operation you could use to write tofilename.Any trailing options onfilename are stripped and ignored.

See also:vips_foreign_find_save_buffer(),vips_image_write_to_file().

vips_foreign_get_suffixes ()

gchar **vips_foreign_get_suffixes (void);

Get aNULL-terminated array listing all the supported suffixes.

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

Usevips_foreign_find_load() to detect type for a specific file.

Free the return result withg_strfreev().

vips_foreign_find_save_buffer ()

constchar *vips_foreign_find_save_buffer (constchar *suffix);

Searches for an operation you could use to write to a buffer insuffixformat.

See also:vips_image_write_to_buffer().

vips_foreign_find_save_target ()

constchar *vips_foreign_find_save_target (constchar *suffix);

Searches for an operation you could use to write to a target insuffixformat.

See also:vips_image_write_to_buffer().

vips_vipsload ()

intvips_vipsload (constchar *filename,VipsImage **out,...);

Read in a vips image.

See also:vips_vipssave().

vips_vipsload_source ()

intvips_vipsload_source (VipsSource *source,VipsImage **out,...);

Exactly asvips_vipsload(), but read from a source.

vips_vipssave ()

intvips_vipssave (VipsImage *in,constchar *filename,...);

Writein tofilename in VIPS format.

See also:vips_vipsload().

[method]

vips_vipssave_target ()

intvips_vipssave_target (VipsImage *in,VipsTarget *target,...);

Asvips_vipssave(), but save to a target.

[method]

vips_openslideload ()

intvips_openslideload (constchar *filename,VipsImage **out,...);

Optional arguments:

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-downversions of the high-resolution image. These are typically called"levels". By default,vips_openslideload() reads the highest-resolutionlevel (level 0). Setlevel to the level number you want.

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

If you setattach_associated, then all associated images are attached asmetadata items. Usevips_image_get_image() onout to retrieve them. Imagesare attached as "openslide-associated-XXXXX", where XXXXX is the name of theassociated image.

By default, the output of this operator is RGBA. Setrgb to enable RGBoutput.

See also:vips_image_new_from_file().

vips_openslideload_source ()

intvips_openslideload_source (VipsSource *source,VipsImage **out,...);

Optional arguments:

Exactly asvips_openslideload(), but read from a source.

vips_jpegload ()

intvips_jpegload (constchar *filename,VipsImage **out,...);

Optional arguments:

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 valuesare 1, 2, 4 and 8. Shrinking during read is very much faster thandecompressing the whole image and then shrinking later.

Usefail_on to set the type of error that will cause load to fail. Bydefault, loaders are permissive, that is,VIPS_FAIL_ON_NONE.

Settingautorotate toTRUE will make the loader interpret theorientation tag and automatically rotate the image appropriately duringload.

Ifautorotate isFALSE, the metadata fieldVIPS_META_ORIENTATION is setto the value of the orientation tag. Applications may read and interpretthis fieldas they wish later in processing. Seevips_autorot(). Saveoperations will useVIPS_META_ORIENTATION, if present, to set theorientation of output images.

Example:

1234

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 fromthe file. Instead, the embedded profile will be attached to the image asVIPS_META_ICC_NAME. You need to use something likevips_icc_import() to get CIE values from the file.

EXIF metadata is attached asVIPS_META_EXIF_NAME, IPTC asVIPS_META_IPTC_NAME, and XMP asVIPS_META_XMP_NAME.

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

The string-valued field "jpeg-chroma-subsample" gives the chroma subsamplein standard notation. 4:4:4 means no subsample, 4:2:0 means YCbCr withCb and Cr subsampled horizontally and vertically, 4:4:4:4 means a CMYKimage with no subsampling.

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

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

vips_jpegload_buffer ()

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

Optional arguments:

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

You must not free the buffer whileout is active. The“postclose” signal onout is a good place to free.

See also:vips_jpegload().

vips_jpegload_source ()

intvips_jpegload_source (VipsSource *source,VipsImage **out,...);

Optional arguments:

Read a JPEG-formatted memory block into a VIPS image. Exactly asvips_jpegload(), but read from a source.

See also:vips_jpegload().

vips_jpegsave_target ()

intvips_jpegsave_target (VipsImage *in,VipsTarget *target,...);

Optional arguments:

Asvips_jpegsave(), but save to a target.

See also:vips_jpegsave(),vips_image_write_to_target().

[method]

vips_jpegsave ()

intvips_jpegsave (VipsImage *in,constchar *filename,...);

Optional arguments:

Write a VIPS image to a file as JPEG.

UseQ to set the JPEG compression factor. Default 75.

Ifoptimize_coding is set, the Huffman tables are optimized. This isslightly slower and produces slightly smaller files.

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

Chroma subsampling is normally automatically disabled for Q >= 90. You canforce the subsampling mode withsubsample_mode.

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

Ifovershoot_deringing is set and the version of libjpeg supports it(e.g. mozjpeg >= 3.0), apply overshooting to samples with extreme valuesfor example 0 and 255 for 8-bit. Overshooting may reduce ringing artifactsfrom compression, in particular in areas where black text appears on awhite background.

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

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

Quantization table 0 is the default in vips and libjpeg(-turbo), but ittends to favor detail over color accuracy, producing colored patches andstripes as well as heavy banding in flat areas at high compression ratios.Quantization table 2 is a good candidate to try if the default quantizationtable 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 producegood 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 worsecompression ratios and/or quality than 2 or 4.

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

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

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

EXIF data is constructed fromVIPS_META_EXIF_NAME, thenmodified with any other related tags on the image before being written tothe file.VIPS_META_RESOLUTION_UNIT is used to set the EXIF resolutionunit.VIPS_META_ORIENTATION is used to set the EXIF orientation tag.

IPTC asVIPS_META_IPTC_NAME and XMP asVIPS_META_XMP_NAMEare coded and attached.

See also:vips_jpegsave_buffer(),vips_image_write_to_file().

[method]

vips_jpegsave_buffer ()

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

Optional arguments:

Asvips_jpegsave(), but save to a memory buffer.

The address of the buffer is returned inobuf, the length of the buffer inolen. You are responsible for freeing the buffer withg_free() when youare done with it.

See also:vips_jpegsave(),vips_image_write_to_file().

[method]

vips_jpegsave_mime ()

intvips_jpegsave_mime (VipsImage *in,...);

Optional arguments:

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

See also:vips_jpegsave(),vips_image_write_to_file().

[method]

vips_webpload_source ()

intvips_webpload_source (VipsSource *source,VipsImage **out,...);

Optional arguments:

Exactly asvips_webpload(), but read from a source.

See also:vips_webpload()

vips_webpload ()

intvips_webpload (constchar *filename,VipsImage **out,...);

Optional arguments:

Read a WebP file into a VIPS image.

Usepage to select a page to render, numbering from zero.

Usen to select the number of pages to render. The default is 1. Pages arerendered in a vertical column, with each individual page aligned to theleft. Set to -1 to mean "until the end of the document". Usevips_grid()to change page layout.

Usescale to specify a scale-on-load factor. For example, 2.0 to doublethe size on load. Animated webp images don't support shrink-on-load, so afurther resize may be necessary.

The loader supports ICC, EXIF and XMP metadata.

See also:vips_image_new_from_file().

vips_webpload_buffer ()

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

Optional arguments:

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

You must not free the buffer whileout is active. The“postclose” signal onout is a good place to free.

See also:vips_webpload()

vips_webpsave_target ()

intvips_webpsave_target (VipsImage *in,VipsTarget *target,...);

Optional arguments:

Asvips_webpsave(), but save to a target.

See also:vips_webpsave().

[method]

vips_webpsave ()

intvips_webpsave (VipsImage *in,constchar *filename,...);

Optional arguments:

Write an image to a file in WebP format.

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

Usepreset to hint the image type to the lossy compressor. The default isVIPS_FOREIGN_WEBP_PRESET_DEFAULT.

Setsmart_subsample to enable high quality chroma subsampling.

Setsmart_deblock to enable auto-adjusting of the deblocking filter. Thiscan improve image quality, especially on low-contrast edges, but encodingcan take significantly longer.

Usealpha_q to set the quality for the alpha channel in lossy mode. It hasthe range 1 - 100, with the default 100.

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

Usetarget_size to set the desired target size in bytes.

Usepasses to set the number of entropy-analysis passes, by default 1,unlesstarget_size is set, in which case the default is 3. It is notrecommended to setpasses unless you settarget_size. Doing so willresult in longer encoding times for no benefit.

Setlossless to use lossless compression, or combinenear_losslesswithQ 80, 60, 40 or 20 to apply increasing amounts of preprocessingwhich 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 betweenkeyframes. Setting 0 means only keyframes.kmin sets the minimum number offrames between frames. Setting 0 means no keyframes. By default, keyframesare disabled.

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

Use the metadata itemsloop anddelay to set the number ofloops for the animation and the frame delays.

See also:vips_webpload(),vips_image_write_to_file().

[method]

vips_webpsave_buffer ()

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

Optional arguments:

Asvips_webpsave(), but save to a memory buffer.

The address of the buffer is returned inbuf, the length of the buffer inlen. You are responsible for freeing the buffer withg_free() when youare done with it.

See also:vips_webpsave().

[method]

vips_webpsave_mime ()

intvips_webpsave_mime (VipsImage *in,...);

Optional arguments:

Asvips_webpsave(), but save as a mime webp on stdout.

See also:vips_webpsave(),vips_image_write_to_file().

[method]

vips_tiffload ()

intvips_tiffload (constchar *filename,VipsImage **out,...);

Optional arguments:

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 colourspace, pyramidal images and JPEG compression, including CMYK and YCbCr.

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

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

Settingautorotate toTRUE will make the loader interpret theorientation tag and automatically rotate the image appropriately duringload.

Ifautorotate isFALSE, the metadata fieldVIPS_META_ORIENTATION is setto the value of the orientation tag. Applications may read and interpretthis fieldas they wish later in processing. Seevips_autorot(). Saveoperations will useVIPS_META_ORIENTATION, if present, to set theorientation of output images.

Ifautorotate is TRUE, the image will be rotated upright during load andno metadata attached. This can be very slow.

Ifsubifd 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 isselected. This can be used to read lower resolution layers frombioformats-style image pyramids.

Any ICC profile is read and attached to the VIPS image asVIPS_META_ICC_NAME. Any XMP metadata is read and attached to the imageasVIPS_META_XMP_NAME. Any IPTC is attached asVIPS_META_IPTC_NAME. Theimage description isattached asVIPS_META_IMAGEDESCRIPTION. Data in the photoshop tag isattached asVIPS_META_PHOTOSHOP_NAME.

See also:vips_image_new_from_file(),vips_autorot().

vips_tiffload_buffer ()

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

Optional arguments:

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

You must not free the buffer whileout is active. The“postclose” signal onout is a good place to free.

See also:vips_tiffload().

vips_tiffload_source ()

intvips_tiffload_source (VipsSource *source,VipsImage **out,...);

Optional arguments:

Exactly asvips_tiffload(), but read from a source.

See also:vips_tiffload().

vips_tiffsave ()

intvips_tiffsave (VipsImage *in,constchar *filename,...);

Optional arguments:

Write a VIPS image to a file as TIFF.

Ifin has theVIPS_META_PAGE_HEIGHT metadata item, this is assumed to be a"toilet roll" image. It will bewritten as series of pages, eachVIPS_META_PAGE_HEIGHT pixels high.

Usecompression to set the tiff compression. Currently jpeg, packbits,fax4, lzw, none, deflate, webp and zstd are supported. The default is nocompression.JPEG compression is a good lossy compressor for photographs, packbits isgood for 1-bit images, and deflate is the best lossless compression TIFFcan do.

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

UseQ to set the JPEG compression factor. Default 75.

Userlevel to set the ZSTD (1-22) or Deflate (1-9) compression level. Uselossless toset WEBP lossless mode on. UseQ to set the WEBP compression level.

Usepredictor to set the predictor for lzw, deflate and zstd compression.It defaults toVIPS_FOREIGN_TIFF_PREDICTOR_HORIZONTAL, meaning horizontaldifferencing. Please refer to the libtiffspecifications for further discussion of various predictors.

Settile to TRUE to write a tiled tiff. By default tiff are written instrips. Usetile_width andtile_height to set the tile size. The defaiultis 128 by 128.

Setpyramid to write the image as a set of images, one per page, ofdecreasing size. Useregion_shrink to set how images will be shrunk: bydefault each 2x2 block is just averaged, but you can set MODE or MEDIAN aswell.

By default, the pyramid stops when the image is small enough to fit in onetile. Usedepth to stop when the image fits in one pixel, or to only writea single layer.

Setbitdepth 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 yousetminiswhite, it will use 0 for a white bit. Many pre-press applicationsonly work with images which use this sense.miniswhite only affects one-bitimages, 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 < 192they are written as light gray and values above are written as white.In caseminiswhite is set to true this behavior is inverted.In case of depth 4: values < 16 are written as black, and so on for thelighter shades. In caseminiswhite is set to true this behavior is inverted.

Useresunit to override the default resolution unit.The defaultresolution unit is taken from the header fieldVIPS_META_RESOLUTION_UNIT. If this field is not set, thenVIPS defaults to cm.

Usexres andyres to override the default horizontal and verticalresolutions. By default these values are taken from the VIPS image header.libvips resolution is always in pixels per millimetre.

Setbigtiff to attempt to write a bigtiff. Bigtiff is a variant of the TIFFformat that allows more than 4GB in a file.

Setproperties to write all vips metadata to the IMAGEDESCRIPTION tag asxml. Ifproperties is not set, the value ofVIPS_META_IMAGEDESCRIPTION isused instead.

The value ofVIPS_META_XMP_NAME is written tothe XMP tag.VIPS_META_ORIENTATION (if set) is used to set the value ofthe orientationtag.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 PHOTOSHOPtag.

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

Setpremultiply to save with premultiplied alpha. Some programs, such asInDesign, will only work with premultiplied alpha.

See also:vips_tiffload(),vips_image_write_to_file().

[method]

vips_tiffsave_buffer ()

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

Optional arguments:

Asvips_tiffsave(), but save to a memory buffer.

The address of the buffer is returned inbuf, the length of the buffer inlen. You are responsible for freeing the buffer withg_free() when youare done with it.

See also:vips_tiffsave(),vips_image_write_to_file().

[method]

vips_tiffsave_target ()

intvips_tiffsave_target (VipsImage *in,VipsTarget *target,...);

Optional arguments:

Asvips_tiffsave(), but save to a target.

See also:vips_tiffsave(),vips_image_write_to_target().

[method]

vips_openexrload ()

intvips_openexrload (constchar *filename,VipsImage **out,...);

Read a OpenEXR file into a VIPS image.

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

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

See also:vips_image_new_from_file().

vips_fitsload ()

intvips_fitsload (constchar *filename,VipsImage **out,...);

Read a FITS image file into a VIPS image.

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

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

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

See also:vips_image_new_from_file().

vips_fitssave ()

intvips_fitssave (VipsImage *in,constchar *filename,...);

Write a VIPS image to a file in FITS format.

See also:vips_image_write_to_file().

[method]

vips_analyzeload ()

intvips_analyzeload (constchar *filename,VipsImage **out,...);

Load an Analyze 6.0 file. Iffilename is "fred.img", this will look foran image header called "fred.hdr" and pixel data in "fred.img". You canalso load "fred" or "fred.hdr".

Images areloaded lazilly and byte-swapped, if necessary. The Analyze metadata is readand attached.

See also:vips_image_new_from_file().

vips_rawload ()

intvips_rawload (constchar *filename,VipsImage **out,int width,int height,int bands,...);

Optional arguments:

This operation mmaps the file, setting upout so that access to thatimage will read from the file.

By default, it assumes uchar pixels. Useformat to select something else.

The image will be tagged asVIPS_INTERPRETATION_MULTIBAND. Useinterpretation to select something else.

Usevips_byteswap() to reverse the byte ordering if necessary.

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

vips_rawsave ()

intvips_rawsave (VipsImage *in,constchar *filename,...);

Writes the pixels inin to the filefilename with no header or othermetadata.

See also:vips_image_write_to_file().

[method]

vips_rawsave_buffer ()

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

Asvips_rawsave(), but save to a memory buffer.

The address of the buffer is returned inbuf, the length of the buffer inlen. You are responsible for freeing the buffer withg_free() when youare done with it.

See also:vips_rawsave(),vips_image_write_to_memory(),vips_image_write_to_file().

[method]

vips_rawsave_target ()

intvips_rawsave_target (VipsImage *in,VipsTarget *target,...);

Asvips_rawsave(), but save to a target.

See also:vips_rawsave().

[method]

vips_csvload ()

intvips_csvload (constchar *filename,VipsImage **out,...);

Optional arguments:

Load a CSV (comma-separated values) file. The output image is always 1band (monochrome),VIPS_FORMAT_DOUBLE. Usevips_bandfold() to turnRGBRGBRGB mono images into colour images.

Items in lines can be either floating point numbers in the C locale, orstrings enclosed in double-quotes ("), or empty.You can use abackslash() 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.Defaultspace.Whitespace characters are always run together.

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

Usefail_on to set the type of error that will cause load to fail. Bydefault, loaders are permissive, that is,VIPS_FAIL_ON_NONE.

See also:vips_image_new_from_file(),vips_bandfold().

vips_csvload_source ()

intvips_csvload_source (VipsSource *source,VipsImage **out,...);

Optional arguments:

Exactly asvips_csvload(), but read from a source.

See also:vips_csvload().

vips_csvsave ()

intvips_csvsave (VipsImage *in,constchar *filename,...);

Optional arguments:

Writes the pixels inin to thefilename as CSV (comma-separated values).The image is writtenone line of text per scanline. Complex numbers are written as"(real,imaginary)" and will need extra parsing I guess. Only the first bandis 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]

vips_csvsave_target ()

intvips_csvsave_target (VipsImage *in,VipsTarget *target,...);

Optional arguments:

Asvips_csvsave(), but save to a target.

See also:vips_csvsave().

[method]

vips_matrixload ()

intvips_matrixload (constchar *filename,VipsImage **out,...);

Reads a matrix from a file.

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

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

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

Extra characters at the ends of lines or at the end of the file areignored.

See also:vips_matrixload().

vips_matrixload_source ()

intvips_matrixload_source (VipsSource *source,VipsImage **out,...);

Exactly asvips_matrixload(), but read from a source.

See also:vips_matrixload().

vips_matrixsave ()

intvips_matrixsave (VipsImage *in,constchar *filename,...);

Writein tofilename in matrix format. Seevips_matrixload() for adescription of the format.

See also:vips_matrixload().

[method]

vips_matrixsave_target ()

intvips_matrixsave_target (VipsImage *in,VipsTarget *target,...);

Asvips_matrixsave(), but save to a target.

See also:vips_matrixsave().

[method]

vips_matrixprint ()

intvips_matrixprint (VipsImage *in,...);

Printin tostdout in matrix format. Seevips_matrixload() for adescription of the format.

See also:vips_matrixload().

[method]

vips_magickload ()

intvips_magickload (constchar *filename,VipsImage **out,...);

Optional arguments:

Read in an image using libMagick, the ImageMagick library. This library canread more than 80 file formats, including SVG, BMP, EPS, DICOM and manyothers.The reader can handle any ImageMagick image, including the float and doubleformats. It will work with any quantum size, including HDR. Any metadataattached 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 sniffedfrom the file contents.

Normally it will only load the first image in a many-image sequence (suchas a GIF or a PDF). Usepage andn to set the start page and number ofpages to load. Setn to -1 to load all pages frompage onwards.

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

See also:vips_image_new_from_file().

vips_magickload_buffer ()

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

Optional arguments:

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

You must not free the buffer whileout is active. The“postclose” signal onout is a good place to free.

See also:vips_magickload().

vips_magicksave ()

intvips_magicksave (VipsImage *in,constchar *filename,...);

Optional arguments:

Write an image using libMagick.

Usequality to set the quality factor. Default 0.

Useformat to explicitly set the save format, for example, "BMP". Otherwisethe format is guessed from the filename suffix.

Ifoptimize_gif_frames is set, GIF frames are cropped to the smallest sizewhile preserving the results of the GIF animation. This takes some time forcomputation but saves some time on encoding and produces smaller files insome cases.

Ifoptimize_gif_transparency is set, pixels that don't change the imagethrough animation are made transparent. This takes some time for computationbut saves some time on encoding and produces smaller files in some cases.

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

See also:vips_magicksave_buffer(),vips_magickload().

[method]

vips_magicksave_buffer ()

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

Optional arguments:

Asvips_magicksave(), but save to a memory buffer.

The address of the buffer is returned inobuf, the length of the buffer inolen. You are responsible for freeing the buffer withg_free() when youare done with it.

See also:vips_magicksave(),vips_image_write_to_file().

[method]

vips_pngload_source ()

intvips_pngload_source (VipsSource *source,VipsImage **out,...);

Optional arguments:

Exactly asvips_pngload(), but read from a source.

See also:vips_pngload().

vips_pngload ()

intvips_pngload (constchar *filename,VipsImage **out,...);

Optional arguments:

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

Any ICC profile is read and attached to the VIPS image. It also supportsXMP metadata.

Usefail_on to set the type of error that will cause load to fail. Bydefault, loaders are permissive, that is,VIPS_FAIL_ON_NONE.

By default, the PNG loader limits the number of text and data chunks toblock some denial of service attacks. Setunlimited to disable theselimits.

See also:vips_image_new_from_file().

vips_pngload_buffer ()

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

Optional arguments:

Exactly asvips_pngload(), but read from a PNG-formatted memory block.

You must not free the buffer whileout is active. The“postclose” signal onout is a good place to free.

See also:vips_pngload().

vips_pngsave_target ()

intvips_pngsave_target (VipsImage *in,VipsTarget *target,...);

Optional arguments:

Asvips_pngsave(), but save to a target.

See also:vips_pngsave(),vips_image_write_to_target().

[method]

vips_pngsave ()

intvips_pngsave (VipsImage *in,constchar *filename,...);

Optional arguments:

Write a VIPS image to a file as PNG.

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

Setinterlace toTRUE to interlace the image with ADAM7interlacing. Bewarethan an interlaced PNG can be up to 7 times slower to write than anon-interlaced image.

Usefilter to specify one or more filters, defaults to none,seeVipsForeignPngFilter.

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

Setpalette toTRUE to enable palette mode for RGB or RGBA images. Apalette will be computed with enough space forbitdepth (1, 2, 4 or 8)bits. UseQ to set the optimisation effort,dither to set the degree ofFloyd-Steinberg dithering andeffort 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 defaultbitdepth is either 8 or 16 depending on the interpretation.You can also setbitdepth for mono and mono + alpha images, and the imagewill be quantized.

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

See also:vips_image_new_from_file().

[method]

vips_pngsave_buffer ()

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

Optional arguments:

Asvips_pngsave(), but save to a memory buffer.

The address of the buffer is returned inbuf, the length of the buffer inlen. You are responsible for freeing the buffer withg_free() when youare done with it.

See also:vips_pngsave(),vips_image_write_to_file().

[method]

vips_ppmload ()

intvips_ppmload (constchar *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().

vips_ppmload_source ()

intvips_ppmload_source (VipsSource *source,VipsImage **out,...);

Exactly asvips_ppmload(), but read from a source.

See also:vips_ppmload().

vips_ppmsave ()

intvips_ppmsave (VipsImage *in,constchar *filename,...);

Optional arguments:

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

Setascii toTRUE to write as human-readable ASCII. Normally data iswritten in binary.

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

vips_ppmsave_target ()

intvips_ppmsave_target (VipsImage *in,VipsTarget *target,...);