A picture element. Cast this to whatever the associated VipsBandFormat says to get the value.

Allocate memory for an array of objects of type @T. The memory is not cleared. This macro cannot fail. See vips_tracked_malloc() if you are allocating large amounts of memory. See also: vips_malloc().

allocate memory local to @OBJ, or %NULL for no auto-free number of @T 's to allocate type of thing to allocate

Areas under curves for illuminant A (2856K), 2 degree observer.

The type of access an operation has to supply. See vips_tilecache() and #VipsForeign. @VIPS_ACCESS_RANDOM means requests can come in any order. @VIPS_ACCESS_SEQUENTIAL means requests will be top-to-bottom, but with some amount of buffering behind the read point for small non-local accesses. can read anywhere top-to-bottom reading only, but with a small buffer See vips_join() and so on. Operations like vips_join() need to be told whether to align images on the low or high coordinate edge, or centre. See also: vips_join(). align low coordinate edge align centre align high coordinate edge See vips_rot() and so on. Fixed rotate angles. See also: vips_rot(). no rotate 90 degrees clockwise 180 degree rotate 90 degrees anti-clockwise See vips_rot45() and so on. Fixed rotate angles. See also: vips_rot45(). no rotate 45 degrees clockwise 90 degrees clockwise 135 degrees clockwise 180 degrees 135 degrees anti-clockwise 90 degrees anti-clockwise 45 degrees anti-clockwise

A VipsArea wraps a chunk of memory. It adds reference counting and a free function. It also keeps a count and a %GType, so the area can be an array. This type is used for things like passing an array of double or an array of #VipsObject pointers to operations, and for reference-counted immutable strings. Initial count == 1, so _unref() after attaching somewhere. See also: vips_area_unref().

the new #VipsArea.

@data will be freed with this function data will be freed with this function

An area which holds an array of elements of some %GType. To set values for the elements, get the pointer and write. See also: vips_area_unref().

the new #VipsArea.

%GType of elements to store sizeof() an element in the array number of elements in the array

An area which holds an array of %GObject s. See vips_area_new_array(). When the area is freed, each %GObject will be unreffed. Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc. See also: vips_area_unref().

the new #VipsArea.

number of elements in the array

Return the data pointer plus optionally the length in bytes of an area, the number of elements, the %GType of each element and the sizeof() each element.

The pointer held by @area.

#VipsArea to fetch from

optionally return length in bytes here optionally return number of elements here optionally return element type here optionally return sizeof() element type here

Allocate a new property id. See g_object_class_install_property().

a new property id > 0

Loop over the vips_arguments to an object. Stop when @fn returns non-%NULL and return that value.

%NULL if @fn returns %NULL for all arguments, otherwise the first non-%NULL value from @fn.

object whose args should be enumerated call this function for every argument client data client data

And loop over a class. Same as ^^, but with no VipsArgumentInstance.

Flags we associate with each object argument. Have separate input & output flags. Both set is an error; neither set is OK. Input gobjects are automatically reffed, output gobjects automatically ref us. We also automatically watch for "destroy" and unlink. @VIPS_ARGUMENT_SET_ALWAYS is handy for arguments which are set from C. For example, VipsImage::width is a property that gives access to the Xsize member of struct _VipsImage. We default its 'assigned' to TRUE since the field is always set directly by C. @VIPS_ARGUMENT_DEPRECATED arguments are not shown in help text, are not looked for if required, are not checked for "have-been-set". You can deprecate a required argument, but you must obviously add a new required argument if you do. Input args with @VIPS_ARGUMENT_MODIFY will be modified by the operation. This is used for things like the in-place drawing operations. @VIPS_ARGUMENT_NON_HASHABLE stops the argument being used in hash and equality tests. It's useful for arguments like `revalidate` which control the behaviour of the operator cache. no flags must be set in the constructor can only be set in the constructor can only be set once don't do use-before-set checks is an input argument (one we depend on) is an output argument (depends on us) just there for back-compat, hide the input argument will be modified the argument is non-hashable

Allocate a new array of doubles and copy @array into it. Free with vips_area_unref(). See also: #VipsArea.

A new #VipsArrayDouble.

array of double number of doubles

Allocate a new array of @n doubles and copy @... into it. Free with vips_area_unref(). See also: vips_array_double_new()

A new #VipsArrayDouble.

number of doubles list of double arguments

Fetch a double array from a #VipsArrayDouble. Useful for language bindings.

array of double

the #VipsArrayDouble to fetch from

length of array

Make an empty image array. Handy with vips_array_image_add() for bindings which can't handle object array arguments. See also: vips_array_image_add().

A new #VipsArrayImage.

Allocate a new array of images and copy @array into it. Free with vips_area_unref(). The images will all be reffed by this function. They will be automatically unreffed for you by vips_area_unref(). Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc. See also: #VipsArea.

A new #VipsArrayImage.

array of #VipsImage number of images

Allocate a new array of @n #VipsImage and copy @... into it. Free with vips_area_unref(). The images will all be reffed by this function. They will be automatically unreffed for you by vips_area_unref(). Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc. See also: vips_array_image_new()

A new #VipsArrayImage.

number of images list of #VipsImage arguments

Make a new #VipsArrayImage, one larger than @array, with @image appended to the end. Handy with vips_array_image_empty() for bindings which can't handle object array arguments. See also: vips_array_image_empty().

A new #VipsArrayImage.

append to this

add this

Fetch an image array from a #VipsArrayImage. Useful for language bindings.

array of #VipsImage

the #VipsArrayImage to fetch from

length of array

Allocate a new array of ints and copy @array into it. Free with vips_area_unref(). See also: #VipsArea.

A new #VipsArrayInt.

array of int number of ints

Allocate a new array of @n ints and copy @... into it. Free with vips_area_unref(). See also: vips_array_int_new()

A new #VipsArrayInt.

number of ints list of int arguments

Fetch an int array from a #VipsArrayInt. Useful for language bindings.

array of int

the #VipsArrayInt to fetch from

length of array

Areas under curves for illuminant B (4874K), 2 degree observer.

The format used for each band element. Each corresponds to a native C type for the current machine. For example, #VIPS_FORMAT_USHORT is <type>unsigned short</type>. invalid setting unsigned char format char format unsigned short format short format unsigned int format int format float format complex (two floats) format double float format double complex (two double) format Return %TRUE if @format is uchar or schar.

format to test

Return %TRUE if @fmt is one of the complex types.

format to test

Return %TRUE if @format is one of the float types.

format to test

Return %TRUE if @format is one of the integer types.

format to test

Return %TRUE if @format is one of the unsigned integer types.

format to test

The various Porter-Duff and PDF blend modes. See vips_composite(), for example. The Cairo docs have a nice explanation of all the blend modes: https://www.cairographics.org/operators The non-separable modes are not implemented. where the second object is drawn, the first is removed the second object is drawn as if nothing were below the image shows what you would expect if you held two semi-transparent slides on top of each other the first object is removed completely, the second is only drawn where the first was the second is drawn only where the first isn't this leaves the first object mostly intact, but mixes both objects in the overlapping area leaves the first object untouched, the second is discarded completely like OVER, but swaps the arguments like IN, but swaps the arguments like OUT, but swaps the arguments like ATOP, but swaps the arguments something like a difference operator a bit like adding the two images a bit like the darker of the two at least as dark as the darker of the two inputs at least as light as the lighter of the inputs multiplies or screens colors, depending on the lightness the darker of each component the lighter of each component brighten first by a factor second darken first by a factor of second multiply or screen, depending on lightness darken or lighten, depending on lightness difference of the two somewhat like DIFFERENCE, but lower-contrast

Like vips_area_new(), but track a length as well. The returned #VipsBlob takes ownership of @data and will free it with @free_fn. Pass %NULL for @free_fn to not transfer ownership. An area of mem with a free func and a length (some sort of binary object, like an ICC profile). See also: vips_area_unref().

the new #VipsBlob.

@data will be freed with this function data to store number of bytes in @data

Get the data from a #VipsBlob. See also: vips_blob_new().

the data

#VipsBlob to fetch from

return number of bytes of data

Any old data is freed and new data attached. It's sometimes useful to be able to create blobs as empty and then fill them later. See also: vips_blob_new().

#VipsBlob to set

@data will be freed with this function data to store number of bytes in @data

Like vips_blob_new(), but take a copy of the data. Useful for bindings which struggle with callbacks. See also: vips_blob_new().

the new #VipsBlob.

data to store number of bytes in @data

Areas under curves for illuminant C (6774K), 2 degree observer.

How pixels are coded. Normally, pixels are uncoded and can be manipulated as you would expect. However some file formats code pixels for compression, and sometimes it's useful to be able to manipulate images in the coded format. The gaps in the numbering are historical and must be maintained. Allocate new numbers from the end. pixels are not coded pixels encode 3 float CIELAB values as 4 uchar pixels encode 3 float RGB as 4 uchar (Radiance coding) How to combine values. See vips_compass(), for example. take the maximum of the possible values sum all the values take the minimum value See vips_draw_image() and so on. Operations like vips_draw_image() need to be told how to combine images from two sources. See also: vips_join(). set pixels to the new value add pixels A direction on a compass. Used for vips_gravity(), for example. centre north east south west north-east south-east south-west north-west Areas under curves for black body at 3250K, 2 degree observer.

Areas under curves for D50, 2 degree observer.

Areas under curves for D55, 2 degree observer.

Areas under curves for D65, 2 degree observer.

Areas under curves for D75, 2 degree observer.

Areas under curves for D93, 2 degree observer.

See vips_image_pipelinev(). Operations can hint the kind of demand geometry they prefer to the VIPS image IO system. These demand styles are given below in order of increasing specialisation. When demanding output from a pipeline, vips_image_generate() will use the most general style requested by the operations in the pipeline. #VIPS_DEMAND_STYLE_SMALLTILE --- This is the most general demand format. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizarre operations like 45 degree rotate. #VIPS_DEMAND_STYLE_FATSTRIP --- This operation would like to output strips the width of the image and as high as possible. This option is suitable for area operations which do not violently transform coordinates, such as vips_conv(). #VIPS_DEMAND_STYLE_THINSTRIP --- This operation would like to output strips the width of the image and a few pels high. This option is suitable for point-to-point operations, such as those in the arithmetic package. #VIPS_DEMAND_STYLE_ANY --- This image is not being demand-read from a disc file (even indirectly) so any demand style is OK. It's used for things like vips_black() where the pixels are calculated. See also: vips_image_pipelinev(). demand in small (typically 128x128 pixel) tiles demand in fat (typically 16 pixel high) strips demand in thin (typically 1 pixel high) strips demand geometry does not matter See vips_flip(), vips_join() and so on. Operations like vips_flip() need to be told whether to flip left-right or top-bottom. See also: vips_flip(), vips_join(). left-right top-bottom

Areas under curves for equal energy illuminant E.

See vips_embed(), vips_conv(), vips_affine() and so on. When the edges of an image are extended, you can specify how you want the extension done. #VIPS_EXTEND_BLACK --- new pixels are black, ie. all bits are zero. #VIPS_EXTEND_COPY --- each new pixel takes the value of the nearest edge pixel #VIPS_EXTEND_REPEAT --- the image is tiled to fill the new area #VIPS_EXTEND_MIRROR --- the image is reflected and tiled to reduce hash edges #VIPS_EXTEND_WHITE --- new pixels are white, ie. all bits are set #VIPS_EXTEND_BACKGROUND --- colour set from the @background property We have to specify the exact value of each enum member since we have to keep these frozen for back compat with vips7. See also: vips_embed(). extend with black (all 0) pixels copy the image edges repeat the whole image mirror the whole image extend with white (all bits set) pixels extend with colour from the @background property

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. never stop stop on image truncated, nothing else stop on serious error or truncation stop on anything, even warnings

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

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

file to find a loader for

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

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

start of memory buffer number of bytes in @data

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

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

source to load from

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

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

name to find a saver for

Searches for an operation you could use to write to a buffer in @suffix format. See also: vips_image_write_to_buffer().

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

name to find a saver for

Searches for an operation you could use to write to a target in @suffix format. See also: vips_image_write_to_buffer().

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

format to find a saver for

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

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

Return %TRUE if @filename can be loaded by @loader. @loader is something like "tiffload" or "VipsForeignLoadTiff".

%TRUE if @filename can be loaded by @loader.

name of loader to use for test file to test

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

%TRUE if @data can be loaded by @loader.

name of loader to use for test pointer to the buffer to test size of the buffer to test

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

%TRUE if @data can be loaded by @source.

name of loader to use for test source to test

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

the result of iteration

base class to search below (eg. "VipsForeignLoad") function to apply to each #VipsForeignClass user data user data

How many pyramid layers to create. write tiles to the filesystem write tiles to a zip file write to a szi file How many pyramid layers to create. create layers down to 1x1 pixel create layers down to 1x1 tile only create a single layer What directory layout and metadata standard to use. use DeepZoom directory layout use Zoomify directory layout use Google maps directory layout use IIIF v2 directory layout use IIIF v3 directory layout 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(). no flags set the image may be read lazilly image pixels are most-significant byte first top-to-bottom lazy reading The compression format to use inside a HEIF container. This is assumed to use the same numbering as %heif_compression_format. x265 x264 jpeg aom 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. auto aom RAV1E SVT-AV1 x265 Which metadata to retain. don't attach metadata keep Exif metadata keep XMP metadata keep IPTC metadata keep ICC metadata keep other metadata (e.g. PNG comments and some TIFF tags) keep all metadata

http://www.w3.org/TR/PNG-Filters.html The values mirror those of png.h in libpng. no filtering difference to the left difference up average of left and up pick best neighbor predictor automatically adaptive 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. portable bitmap portable greymap portable pixmap portable float map portable anymap

Set subsampling mode. prevent subsampling when quality >= 90 always perform subsampling never perform subsampling 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. no compression jpeg compression deflate (zip) compression packbits compression fax4 compression LZW compression WEBP compression ZSTD compression JP2K compression The predictor can help deflate and lzw compression. The values are fixed by the tiff library. no prediction horizontal differencing float predictor Use inches or centimeters as the resolution unit for a tiff file. use centimeters use inches Tune lossy encoder settings for different image types. default preset digital picture, like portrait, inner shot outdoor photograph, with natural lighting hand or line drawing, with high-contrast details small-sized colorful images text-like Fill @out->valid with pixels. @seq contains per-thread state, such as the input regions. Set @stop to %TRUE to stop processing. See also: vips_image_generate(), vips_stop_many().

0 on success, -1 on error.

#VipsRegion to fill sequence value user data user data set this to stop processing

This macro returns a pointer to a pixel in an image, cast to a #VipsPel *. It only works for images which are fully available in memory, so memory buffers and small mapped images only. If VIPS_DEBUG is defined, you get a version that checks bounds for you. See also: vips_image_wio_input(), vips_image_inplace(), VIPS_REGION_ADDR().

a #VipsImage x coordinate y coordinate

a #VipsImage

VIPS_INIT() starts up the world of VIPS. You should call this on program startup before using any other VIPS operations. If you do not call VIPS_INIT(), VIPS will call it for you when you use your first VIPS operation, but it may not be able to get hold of @ARGV0 and VIPS may therefore be unable to find its data files. It is much better to call this macro yourself. @ARGV0 is used to help discover message catalogues if libvips has been relocated. If you don't need a relocatable package, you can just pass `""` and it'll be fine. Additionally, VIPS_INIT() can be run from any thread, but it must not be called from more than one thread at the same time. This is much easier to guarantee if you call it yourself. VIPS_INIT() is a macro, since it tries to check ABI compatibility between the caller and the library. You can also call vips_init(), the non-macro version, if macros are not available to you. You may call VIPS_INIT() many times and vips_shutdown() many times, but you must not call VIPS_INIT() after vips_shutdown(). In other words, you cannot stop and restart vips. Use the environment variable `VIPS_MIN_STACK_SIZE` to set the minimum stack size. For example, `2m` for a minimum of two megabytes of stack. This can be important for systems like musl where the default stack is very small. VIPS_INIT() does approximately the following: + checks that the libvips your program is expecting is binary-compatible with the vips library you're running against + sets a minimum stack size, see above + initialises any libraries that VIPS is using, including GObject and the threading system, if necessary + guesses where the VIPS data files are and sets up internationalisation --- see vips_guess_prefix() + creates the main vips types, including #VipsImage and friends + loads any plugins from $libdir/vips-x.y/, where x and y are the major and minor version numbers for this VIPS. Example: |[ int main(int argc, char **argv) { if (VIPS_INIT(argv[0])) vips_error_exit("unable to start VIPS"); vips_shutdown(); return 0; } ]| See also: vips_shutdown(), vips_add_option_entries(), vips_version(), vips_guess_prefix(), vips_guess_libdir().

name of application

#VIPS_INTERPOLATE_SHIFT as a multiplicative constant.

Many of the vips interpolators use fixed-point arithmetic for value calculation. This is how many bits of precision they use.

An image. These can represent an image on disc, a memory buffer, an image in the process of being written to disc or a partially evaluated image in memory.

A renamed vips_image_new_memory() ... Some gobject binding systems do not like more than one _new() method. See also: vips_image_new_memory().

the new #VipsImage, or %NULL on error.

vips_image_new() creates a new, empty #VipsImage. If you write to one of these images, vips will just attach some callbacks, no pixels will be generated. Write pixels to an image with vips_image_generate() or vips_image_write_line(). Write a whole image to another image with vips_image_write().

the new #VipsImage, or %NULL on error.

Loads an image from the formatted area of memory @buf, @len using the loader recommended by vips_foreign_find_load_buffer(). To load an unformatted area of memory, use vips_image_new_from_memory(). VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example #VipsObject::close. Load options may be given in @option_string as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. See also: vips_image_write_to_buffer().

the new #VipsImage, or %NULL on error.

image data length of memory buffer set of extra options as a string %NULL-terminated list of optional named arguments

Optional arguments: * @access: hint #VipsAccess mode to loader * @memory: force load via memory vips_image_new_from_file() opens @name for reading. It can load files in many image formats, including VIPS, TIFF, PNG, JPEG, FITS, Matlab, OpenEXR, CSV, WebP, Radiance, RAW, PPM and others. Load options may be appended to @filename as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. Many loaders add extra options, see vips_jpegload(), for example. vips_image_new_from_file() always returns immediately with the header fields filled in. No pixels are actually read until you first access them. @access lets you set a #VipsAccess hint giving the expected access pattern for this file. #VIPS_ACCESS_RANDOM means you can fetch pixels randomly from the image. This is the default mode. #VIPS_ACCESS_SEQUENTIAL means you will read the whole image exactly once, top-to-bottom. In this mode, vips can avoid converting the whole image in one go, for a large memory saving. You are allowed to make small non-local references, so area operations like convolution will work. In #VIPS_ACCESS_RANDOM mode, small images are decompressed to memory and then processed from there. Large images are decompressed to temporary random-access files on disc and then processed from there. Set @memory to %TRUE to force loading via memory. The default is to load large random access images via temporary disc files. See vips_image_new_temp_file() for an explanation of how VIPS selects a location for the temporary file. The disc threshold can be set with the "--vips-disc-threshold" command-line argument, or the `VIPS_DISC_THRESHOLD` environment variable. The value is a simple integer, but can take a unit postfix of "k", "m" or "g" to indicate kilobytes, megabytes or gigabytes. The default threshold is 100 MB. For example: |[ VipsImage *image = vips_image_new_from_file("fred.tif", "page", 12, NULL); ]| Will open "fred.tif", reading page 12. |[ VipsImage *image = vips_image_new_from_file("fred.jpg[shrink=2]", NULL); ]| Will open "fred.jpg", downsampling by a factor of two. Use vips_foreign_find_load() or vips_foreign_is_a() to see what format a file is in and therefore what options are available. If you need more control over the loading process, you can call loaders directly, see vips_jpegload(), for example. See also: vips_foreign_find_load(), vips_foreign_is_a(), vips_image_write_to_file().

the new #VipsImage, or %NULL on error.

file to open %NULL-terminated list of optional named arguments

Opens the named file for simultaneous reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications. See also: vips_draw_circle().

the new #VipsImage, or %NULL on error.

filename to open

This function maps the named file and returns a #VipsImage you can use to read it. It returns an 8-bit image with @bands bands. If the image is not 8-bit, use vips_copy() to transform the descriptor after loading it. See also: vips_copy(), vips_rawload(), vips_image_new_from_file().

the new #VipsImage, or %NULL on error.

filename to open image width image height image bands (or bytes per pixel) bytes to skip at start of file

Creates a new image with width, height, format, interpretation, resolution and offset taken from @image, but with number of bands taken from @n and the value of each band element set from @c. See also: vips_image_new_from_image1()

the new #VipsImage, or %NULL on error.

image to copy array of constants number of constants

Creates a new image with width, height, format, interpretation, resolution and offset taken from @image, but with one band and each pixel having the value @c. See also: vips_image_new_from_image()

the new #VipsImage, or %NULL on error.

image to copy constants

This function wraps a #VipsImage around a memory area. The memory area must be a simple array, for example RGBRGBRGB, left-to-right, top-to-bottom. Use vips_image_new_from_buffer() to load an area of memory containing an image in a format. VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example #VipsObject::close. Because VIPS is "borrowing" @data from the caller, this function is extremely dangerous. Unless you are very careful, you will get crashes or memory corruption. Use vips_image_new_from_memory_copy() instead if you are at all unsure. Use vips_copy() to set other image properties. See also: vips_image_new(), vips_image_write_to_memory(), vips_image_new_from_memory_copy().

the new #VipsImage, or %NULL on error.

start of memory area length of memory area image width image height image bands (or bytes per pixel) image format

Like vips_image_new_from_memory(), but VIPS will make a copy of the memory area. This means more memory use and an extra copy operation, but is much simpler and safer. See also: vips_image_new_from_memory().

the new #VipsImage, or %NULL on error.

start of memory area length of memory area image width image height image bands (or bytes per pixel) image format

Loads an image from the formatted source @input, loader recommended by vips_foreign_find_load_source(). Load options may be given in @option_string as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the string. See also: vips_image_write_to_target().

the new #VipsImage, or %NULL on error.

source to fetch image from set of extra options as a string %NULL-terminated list of optional named arguments

This convenience function makes an image which is a matrix: a one-band #VIPS_FORMAT_DOUBLE image held in memory. Use VIPS_IMAGE_ADDR(), or VIPS_MATRIX() to address pixels in the image. Use vips_image_set_double() to set "scale" and "offset", if required. See also: vips_image_new_matrixv()

the new #VipsImage, or %NULL on error.

image width image height

A binding-friendly version of vips_image_new_matrixv().

the new #VipsImage, or %NULL on error.

image width image height array of elements number of elements

As vips_image_new_matrix(), but initialise the matrix from the argument list. After @height should be @width * @height double constants which are used to set the matrix elements. See also: vips_image_new_matrix()

the new #VipsImage, or %NULL on error.

image width image height matrix coefficients

vips_image_new_memory() creates a new #VipsImage which, when written to, will create a memory image. See also: vips_image_new().

the new #VipsImage, or %NULL on error.

Make a #VipsImage which, when written to, will create a temporary file on disc. The file will be automatically deleted when the image is destroyed. @format is something like "&percnt;s.v" for a vips file. The file is created in the temporary directory. This is set with the environment variable TMPDIR. If this is not set, then on Unix systems, vips will default to /tmp. On Windows, vips uses GetTempPath() to find the temporary directory. See also: vips_image_new().

the new #VipsImage, or %NULL on error.

format of file

the maximum numeric value possible for this format.

the format

A renamed vips_image_new_matrix_from_array(). Some gobject bindings do not like more than one _new method.

the new #VipsImage, or %NULL on error.

image width image height array of elements number of elements

Turn LCh to CMC. See also: vips_LCh2CMC().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Turn CMYK to XYZ. If the image has an embedded ICC profile this will be used for the conversion. If there is no embedded profile, a generic fallback profile will be used. Conversion is to D65 XYZ with relative intent. If you need more control over the process, use vips_icc_import() instead.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert HSV to sRGB. HSV is a crude polar coordinate system for RGB images. It is provided for compatibility with other image processing systems. See vips_Lab2LCh() for a much better colour space. See also: vips_sRGB2HSV().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Turn LCh to CMC. The CMC colourspace is described in "Uniform Colour Space Based on the CMC(l:c) Colour-difference Formula", M R Luo and B Rigg, Journal of the Society of Dyers and Colourists, vol 102, 1986. Distances in this colourspace approximate, within 10% or so, differences in the CMC(l:c) colour difference formula. This operation generates CMC(1:1). For CMC(2:1), halve Lucs and double Cucs. See also: vips_CMC2LCh().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Turn LCh to Lab.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Turn Lab to LCh.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert a Lab three-band float image to LabQ (#VIPS_CODING_LABQ). See also: vips_LabQ2Lab().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Turn Lab to LabS, signed 16-bit int fixed point. See also: vips_LabQ2Lab().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @temp: #VipsArrayDouble, colour temperature Turn Lab to XYZ. The colour temperature defaults to D65, but can be specified with @temp.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band float image. See also: vips_LabQ2Lab(), vips_LabQ2LabS(), vips_rad2float().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band short image. See also: vips_LabS2LabQ(), vips_LabQ2LabS(), vips_rad2float().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band short image. See also: vips_LabS2LabQ(), vips_LabQ2sRGB(), vips_rad2float().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Convert a LabS three-band signed short image to a three-band float image. See also: vips_LabS2Lab().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Convert a LabS three-band signed short image to LabQ See also: vips_LabQ2LabS().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Turn XYZ to CMYK. Conversion is from D65 XYZ with relative intent. If you need more control over the process, use vips_icc_export() instead.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @temp: #VipsArrayDouble, colour temperature Turn XYZ to Lab, optionally specifying the colour temperature. @temp defaults to D65.

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Turn XYZ to Yxy.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Turn XYZ to scRGB.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Turn XYZ to Yxy.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

This operation finds the absolute value of an image. It does a copy for unsigned integer types, negate for negative values in signed integer types, <function>fabs(3)</function> for float types, and calculates modulus for complex types. See also: vips_sign().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_ACOS on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_ACOSH on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Append an alpha channel. See also: vips_image_hasalpha().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @interpolate: #VipsInterpolate, interpolate pixels with this * @oarea: #VipsArrayInt, output rectangle * @idx: %gdouble, input horizontal offset * @idy: %gdouble, input vertical offset * @odx: %gdouble, output horizontal offset * @ody: %gdouble, output vertical offset * @extend: #VipsExtend how to generate new pixels * @background: #VipsArrayDouble colour for new pixels * @premultiplied: %gboolean, images are already premultiplied This operator performs an affine transform on an image using @interpolate. The transform is: |[ X = @a * (x + @idx) + @b * (y + @idy) + @odx Y = @c * (x + @idx) + @d * (y + @idy) + @doy where: x and y are the coordinates in input image. X and Y are the coordinates in output image. (0,0) is the upper left corner. ]| The section of the output space defined by @oarea is written to @out. @oarea is a four-element int array of left, top, width, height. By default @oarea is just large enough to cover the whole of the transformed input image. By default, new pixels are filled with @background. This defaults to zero (black). You can set other extend types with @extend. #VIPS_EXTEND_COPY is better for image upsizing. @interpolate defaults to bilinear. @idx, @idy, @odx, @ody default to zero. Image are normally treated as unpremultiplied, so this operation can be used directly on PNG images. If your images have been through vips_premultiply(), set @premultiplied. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_shrink(), vips_resize(), #VipsInterpolate.

0 on success, -1 on error

input image

output image transformation matrix coefficient transformation matrix coefficient transformation matrix coefficient transformation matrix coefficient %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_AND on an image and an array of constants. See vips_boolean_const(). See also: vips_boolean(), vips_boolean_const1().

0 on success, -1 on error

input image

output image array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_AND on an image and a constant. See vips_boolean_const1(). See also: vips_boolean(), vips_boolean_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_ASIN on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_ASINH on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_ATAN on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_ATAN2 on an image and a constant. See vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_ATAN2 on an image and a constant. See vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_ATANH on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @angle: output #VipsAngle the image was rotated by * @flip: output %gboolean whether the image was flipped Look at the image metadata and rotate and flip the image to make it upright. The #VIPS_META_ORIENTATION tag is removed from @out to prevent accidental double rotation. Read @angle to find the amount the image was rotated by. Read @flip to see if the image was also flipped.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Remove the orientation tag on @image. Also remove any exif orientation tags. You must vips_copy() the image before calling this function since it modifies metadata.

image to remove orientation from

This operation finds the average value in an image. It operates on all bands of the input image: use vips_stats() if you need to calculate an average for each band. For complex images, return the average modulus. See also: vips_stats(), vips_bandmean(), vips_deviate(), vips_rank()

0 on success, -1 on error

input #VipsImage

output pixel average %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_AND on an image. See vips_bandbool().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform various boolean operations across the bands of an image. For example, a three-band uchar image operated on with #VIPS_OPERATION_BOOLEAN_AND will produce a one-band uchar image where each pixel is the bitwise and of the band elements of the corresponding pixel in the input image. The output image is the same format as the input image for integer types. Float types are cast to int before processing. Complex types are not supported. The output image always has one band. This operation is useful in conjunction with vips_relational(). You can use it to see if all image bands match exactly. See also: vips_boolean_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage boolean operation to perform %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_EOR on an image. See vips_bandbool().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @factor: fold by this factor Fold up an image horizontally: width is collapsed into bands. Use @factor to set how much to fold by: @factor 3, for example, will make the output image three times narrower than the input, and with three times as many bands. By default the whole of the input width is folded up. See also: vips_csvload(), vips_bandunfold().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Append a set of constant bands to an image. See also: vips_bandjoin().

0 on success, -1 on error

input image

output image array of constants to append number of constants %NULL-terminated list of optional named arguments

Append a single constant band to an image.

0 on success, -1 on error

input image

output image constant to append %NULL-terminated list of optional named arguments

This operation writes a one-band image where each pixel is the average of the bands for that pixel in the input image. The output band format is the same as the input band format. Integer types use round-to-nearest averaging. See also: vips_add(), vips_avg(), vips_recomb()

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_OR on an image. See vips_bandbool().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @factor: unfold by this factor Unfold image bands into x axis. Use @factor to set how much to unfold by: @factor 3, for example, will make the output image three times wider than the input, and with one third as many bands. By default, all bands are unfolded. See also: vips_csvload(), vips_bandfold().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Perform various boolean operations on an image against an array of constants. The output type is always uchar, with 0 for FALSE and 255 for TRUE. If the array of constants has just one element, that constant is used for all image bands. If the array has more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element. See also: vips_boolean(), vips_boolean_const1().

0 on success, -1 on error

input image

output image boolean operation to perform array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform various boolean operations on an image with a single constant. See vips_boolean_const(). See also: vips_boolean(), vips_boolean_const().

0 on success, -1 on error

input image

output image boolean operation to perform constant %NULL-terminated list of optional named arguments

This operation builds a lookup table from a set of points. Intermediate values are generated by piecewise linear interpolation. The lookup table is always of type #VIPS_FORMAT_DOUBLE, use vips_cast() to change it to the type you need. For example, consider this 2 x 2 matrix of (x, y) coordinates: <tgroup cols='2' align='left' colsep='1' rowsep='1'> <tbody> <row> <entry>0</entry> <entry>0</entry> </row> <row> <entry>255</entry> <entry>100</entry> </row> </tbody> </tgroup> We then generate a 1 x 256 element LUT like this: <tgroup cols='2' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>Index</entry> <entry>Value</entry> </row> </thead> <tbody> <row> <entry>0</entry> <entry>0</entry> </row> <row> <entry>1</entry> <entry>0.4</entry> </row> <row> <entry>etc.</entry> <entry>0.4</entry> </row> <row> <entry>255</entry> <entry>100</entry> </row> </tbody> </tgroup> This is then written as the output image, with the left column giving the index in the image to place the value. The (x, y) points don't need to be sorted: we do that. You can have several Ys, each becomes a band in the output LUT. You don't need to start at zero, any integer will do, including negatives. See also: vips_identity(), vips_invertlut(), vips_cast(), vips_maplut().

0 on success, -1 on error

input matrix

output image %NULL-terminated list of optional named arguments

Swap the byte order in an image. See also: vips_rawload().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @sigma: %gdouble, sigma for gaussian blur * @precision: #VipsPrecision, calculation accuracy Find edges by Canny's method: The maximum of the derivative of the gradient in the direction of the gradient. Output is float, except for uchar input, where output is uchar, and double input, where output is double. Non-complex images only. Use @sigma to control the scale over which gradient is measured. 1.4 is usually a good value. Use @precision to set the precision of edge detection. For uchar images, setting this to #VIPS_PRECISION_INTEGER will make edge detection much faster, but sacrifice some sensitivity. You will probably need to process the output further to eliminate weak edges. See also: vips_sobel().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Use values in @index to select pixels from @cases. @index must have one band. @cases can have up to 256 elements. Values in @index greater than or equal to @n use the final image in @cases. The images in @cases must have either one band or the same number of bands. The output image is the same size as @index. Images in @cases are expanded to the smallest common format and number of bands. Combine this with vips_switch() to make something like a case statement or a multi-way vips_ifthenelse(). See also: vips_maplut(), vips_switch(), vips_ifthenelse().

0 on success, -1 on error

index image

array of case images output image number of case images %NULL-terminated list of optional named arguments

Optional arguments: * @shift: %gboolean, integer values are shifted Convert @in to @format. You can convert between any pair of formats. Floats are truncated (not rounded). Out of range values are clipped. Casting from complex to real returns the real part. If @shift is %TRUE, integer values are shifted up and down. For example, casting from unsigned 8 bit to unsigned 16 bit would shift every value left by 8 bits. The bottom bit is copied into the new bits, so 255 would become 65535. See also: vips_scale(), vips_complexform(), vips_real(), vips_imag(), vips_cast_uchar(), vips_msb().

0 on success, -1 on error

input image

output image format to convert to %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_CHAR. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_COMPLEX. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_DOUBLE. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_DPCOMPLEX. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_FLOAT. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_INT. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_SHORT. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_UCHAR. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_UINT. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Convert @in to #VIPS_FORMAT_USHORT. See vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Round to an integral value with #VIPS_OPERATION_ROUND_CEIL. See vips_round().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @min: %gdouble, minimum value * @max: %gdouble, maximum value This operation clamps pixel values to a range, by default 0 - 1. Use @min and @max to change the range. See also: vips_sign(), vips_abs(), vips_sdf().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @source_space: input colour space This operation looks at the interpretation field of @in (or uses @source_space, if set) and runs a set of colourspace conversion functions to move it to @space. For example, given an image tagged as #VIPS_INTERPRETATION_YXY, running vips_colourspace() with @space set to #VIPS_INTERPRETATION_LAB will convert with vips_Yxy2XYZ() and vips_XYZ2Lab(). See also: vips_colourspace_issupported(), vips_image_guess_interpretation().

0 on success, -1 on error.

input image

output image convert to this colour space %NULL-terminated list of optional named arguments

Test if @image is in a colourspace that vips_colourspace() can process.

%TRUE if @image is in a supported colourspace.

input image

Optional arguments: * @times: %gint, how many times to rotate and convolve * @angle: #VipsAngle45, rotate mask by this much between colvolutions * @combine: #VipsCombine, combine results like this * @precision: #VipsPrecision, precision for blur, default float * @layers: %gint, number of layers for approximation * @cluster: %gint, cluster lines closer than this distance This convolves @in with @mask @times times, rotating @mask by @angle each time. By default, it comvolves twice, rotating by 90 degrees, taking the maximum result. See also: vips_conv().

0 on success, -1 on error.

input image

output image convolve with this mask %NULL-terminated list of optional named arguments

Perform various operations on complex images. Angles are expressed in degrees. The output type is complex unless the input is double or dpcomplex, in which case the output is dpcomplex.

0 on success, -1 on error

input #VipsImage

output #VipsImage complex operation to perform %NULL-terminated list of optional named arguments

Get components of complex images. The output type is the same as the input type, except #VIPS_FORMAT_COMPLEX becomes #VIPS_FORMAT_FLOAT and #VIPS_FORMAT_DPCOMPLEX becomes #VIPS_FORMAT_DOUBLE.

0 on success, -1 on error

input #VipsImage

output #VipsImage complex operation to perform %NULL-terminated list of optional named arguments

Optional arguments: * @compositing_space: #VipsInterpretation to composite in * @premultiplied: %gboolean, images are already premultiplied * @x: %gint, position of overlay * @y: %gint, position of overlay Composite @overlay on top of @base with @mode. See vips_composite().

0 on success, -1 on error

first input image

second input image output image composite with this blend mode %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_COMPLEX_CONJ on an image. See vips_complex().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @precision: #VipsPrecision, calculation accuracy * @layers: %gint, number of layers for approximation * @cluster: %gint, cluster lines closer than this distance Convolution. Perform a convolution of @in with @mask. Each output pixel is calculated as: |[ sigma[i]{pixel[i] * mask[i]} / scale + offset ]| where scale and offset are part of @mask. By default, @precision is #VIPS_PRECISION_FLOAT. The output image is always #VIPS_FORMAT_FLOAT unless @in is #VIPS_FORMAT_DOUBLE, in which case @out is also #VIPS_FORMAT_DOUBLE. If @precision is #VIPS_PRECISION_INTEGER, then elements of @mask are converted to integers before convolution, using rint(), and the output image always has the same #VipsBandFormat as the input image. For #VIPS_FORMAT_UCHAR images and #VIPS_PRECISION_INTEGER @precision, vips_conv() uses a fast vector path based on half-float arithmetic. This can produce slightly different results. Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or vips_vector_set_enabled(). If @precision is #VIPS_PRECISION_APPROXIMATE then, like #VIPS_PRECISION_INTEGER, @mask is converted to int before convolution, and the output image always has the same #VipsBandFormat as the input image. Larger values for @layers give more accurate results, but are slower. As @layers approaches the mask radius, the accuracy will become close to exact convolution and the speed will drop to match. For many large masks, such as Gaussian, @n_layers need be only 10% of this value and accuracy will still be good. Smaller values of @cluster will give more accurate results, but be slower and use more memory. 10% of the mask radius is a good rule of thumb. See also: vips_convsep().

0 on success, -1 on error

input image

output image convolve with this mask %NULL-terminated list of optional named arguments

Optional arguments: * @layers: %gint, number of layers for approximation * @cluster: %gint, cluster lines closer than this distance Perform an approximate integer convolution of @in with @mask. This is a low-level operation, see vips_conv() for something more convenient. The output image always has the same #VipsBandFormat as the input image. Elements of @mask are converted to integers before convolution. Larger values for @layers give more accurate results, but are slower. As @layers approaches the mask radius, the accuracy will become close to exact convolution and the speed will drop to match. For many large masks, such as Gaussian, @layers need be only 10% of this value and accuracy will still be good. Smaller values of @cluster will give more accurate results, but be slower and use more memory. 10% of the mask radius is a good rule of thumb. See also: vips_conv().

0 on success, -1 on error

input image

output image convolution mask %NULL-terminated list of optional named arguments

Optional arguments: * @layers: %gint, number of layers for approximation Approximate separable integer convolution. This is a low-level operation, see vips_convsep() for something more convenient. The image is convolved twice: once with @mask and then again with @mask rotated by 90 degrees. @mask must be 1xn or nx1 elements. Elements of @mask are converted to integers before convolution. Larger values for @layers give more accurate results, but are slower. As @layers approaches the mask radius, the accuracy will become close to exact convolution and the speed will drop to match. For many large masks, such as Gaussian, @layers need be only 10% of this value and accuracy will still be good. The output image always has the same #VipsBandFormat as the input image. See also: vips_convsep().

0 on success, -1 on error

input image

output image convolve with this mask %NULL-terminated list of optional named arguments

Convolution. This is a low-level operation, see vips_conv() for something more convenient. Perform a convolution of @in with @mask. Each output pixel is calculated as sigma[i]{pixel[i] * mask[i]} / scale + offset, where scale and offset are part of @mask. The convolution is performed with floating-point arithmetic. The output image is always #VIPS_FORMAT_FLOAT unless @in is #VIPS_FORMAT_DOUBLE, in which case @out is also #VIPS_FORMAT_DOUBLE. See also: vips_conv().

0 on success, -1 on error

input image

output image convolve with this mask %NULL-terminated list of optional named arguments

Integer convolution. This is a low-level operation, see vips_conv() for something more convenient. @mask is converted to an integer mask with rint() of each element, rint of scale and rint of offset. Each output pixel is then calculated as |[ sigma[i]{pixel[i] * mask[i]} / scale + offset ]| The output image always has the same #VipsBandFormat as the input image. For #VIPS_FORMAT_UCHAR images, vips_convi() uses a fast vector path based on half-float arithmetic. This can produce slightly different results. Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or vips_vector_set_enabled(). See also: vips_conv().

0 on success, -1 on error

input image

output image convolve with this mask %NULL-terminated list of optional named arguments

Optional arguments: * @precision: calculation accuracy * @layers: number of layers for approximation * @cluster: cluster lines closer than this distance Perform a separable convolution of @in with @mask. See vips_conv() for a detailed description. The mask must be 1xn or nx1 elements. The image is convolved twice: once with @mask and then again with @mask rotated by 90 degrees. This is much faster for certain types of mask (gaussian blur, for example) than doing a full 2D convolution. See also: vips_conv(), vips_gaussmat().

0 on success, -1 on error

input image

output image convolution mask %NULL-terminated list of optional named arguments

Optional arguments: * @width: %gint, set image width * @height: %gint, set image height * @bands: %gint, set image bands * @format: #VipsBandFormat, set image format * @coding: #VipsCoding, set image coding * @interpretation: #VipsInterpretation, set image interpretation * @xres: %gdouble, set image xres * @yres: %gdouble, set image yres * @xoffset: %gint, set image xoffset * @yoffset: %gint, set image yoffset Copy an image, optionally modifying the header. VIPS copies images by copying pointers, so this operation is instant, even for very large images. You can optionally change any or all header fields during the copy. You can make any change which does not change the size of a pel, so for example you can turn a 4-band uchar image into a 2-band ushort image, but you cannot change a 100 x 100 RGB image into a 300 x 100 mono image. See also: vips_byteswap(), vips_bandfold(), vips_bandunfold().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

A simple convenience function to copy an image to a file, then copy again to output. If the image is already a file, just copy straight through. The file is allocated with vips_image_new_temp_file(). The file is automatically deleted when @out is closed. See also: vips_copy(), vips_image_new_temp_file().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

This function allocates memory, renders @image into it, builds a new image around the memory area, and returns that. If the image is already a simple area of memory, it just refs @image and returns it. Call this before using the draw operations to make sure you have a memory image that can be modified. vips_copy() adds a null "copy" node to a pipeline. Use that instead if you want to change metadata and not pixels. This operation is thread-safe, unlike vips_image_wio_input(). If you are sure that @image is not shared with another thread (perhaps you have made it yourself), use vips_image_wio_input() instead. See also: vips_image_wio_input().

the new #VipsImage, or %NULL on error.

image to copy to a memory buffer

Perform #VIPS_OPERATION_MATH_COS on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_COSH on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Function which calculates the number of transitions between black and white for the horizontal or the vertical direction of an image. black<128 , white>=128 The function calculates the number of transitions for all Xsize or Ysize and returns the mean of the result Input should be one band, 8-bit. See also: vips_morph(), vips_conv().

0 on success, -1 on error.

input image

output average number of lines count lines horizontally or vertically %NULL-terminated list of optional named arguments

A synonym for vips_extract_area(). See also: vips_extract_bands(), vips_smartcrop().

0 on success, -1 on error.

input image

output image left edge of area to extract top edge of area to extract width of area to extract height of area to extract %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

Optional arguments: * @separator: separator string As vips_csvsave(), but save to a target. See also: vips_csvsave().

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

A convenience function to unpack to a format that we can compute with. @out.coding is always #VIPS_CODING_NONE. This unpacks LABQ to plain LAB. Use vips_LabQ2LabS() for a bit more speed if you need it. See also: vips_image_encode(), vips_LabQ2Lab(), vips_rad2float().

0 on success, or -1 on error.

image to decode

write to this image

We often need to know what an image will decode to without actually decoding it, for example, in arg checking. See also: vips_image_decode().

image to decode

predict bands here predict format here

This operation finds the standard deviation of all pixels in @in. It operates on all bands of the input image: use vips_stats() if you need to calculate an average for each band. Non-complex images only. See also: vips_avg(), vips_stats()..

0 on success, -1 on error

input #VipsImage

output pixel standard deviation %NULL-terminated list of optional named arguments

Optional arguments: * @fill: fill the draw_circle Draws a circle on @image. If @fill is %TRUE then the circle is filled, otherwise a 1-pixel-wide perimeter is drawn. @ink is an array of double containing values to draw. See also: vips_draw_circle1(), vips_draw_line().

0 on success, or -1 on error.

image to draw on

value to draw length of ink array centre of draw_circle centre of draw_circle draw_circle radius %NULL-terminated list of optional named arguments

Optional arguments: * @fill: fill the draw_circle As vips_draw_circle(), but just takes a single double for @ink. See also: vips_draw_circle().

0 on success, or -1 on error.

image to draw on

value to draw centre of draw_circle centre of draw_circle draw_circle radius %NULL-terminated list of optional named arguments

Optional arguments: * @test: test this image * @equal: fill while equal to edge * @left: output left edge of bounding box of modified area * @top: output top edge of bounding box of modified area * @width: output width of bounding box of modified area * @height: output height of bounding box of modified area Flood-fill @image with @ink, starting at position @x, @y. The filled area is bounded by pixels that are equal to the ink colour, in other words, it searches for pixels enclosed by an edge of @ink. If @equal is set, it instead searches for pixels which are equal to the start point and fills them with @ink. Normally it will test and set pixels in @image. If @test is set, it will test pixels in @test and set pixels in @image. This lets you search an image (@test) for continuous areas of pixels without modifying it. @left, @top, @width, @height output the bounding box of the modified pixels. @ink is an array of double containing values to draw. See also: vips_draw_flood1().

0 on success, or -1 on error.

image to draw on

value to draw length of ink array centre of circle centre of circle %NULL-terminated list of optional named arguments

0 on success, or -1 on error.

image to draw on

value to draw centre of circle centre of circle %NULL-terminated list of optional named arguments

Optional arguments: * @mode: how to combine pixels Draw @sub on top of @image at position @x, @y. The two images must have the same Coding. If @sub has 1 band, the bands will be duplicated to match the number of bands in @image. @sub will be converted to @image's format, see vips_cast(). Use @mode to set how pixels are combined. If you use #VIPS_COMBINE_MODE_ADD, both images muct be uncoded. See also: vips_draw_mask(), vips_insert().

0 on success, or -1 on error.

image to draw on

image to paint draw @sub here draw @sub here %NULL-terminated list of optional named arguments

Draws a 1-pixel-wide line on an image. @ink is an array of double containing values to draw. See also: vips_draw_line1(), vips_draw_circle(), vips_draw_mask().

0 on success, or -1 on error.

image to draw on

value to draw length of ink array start of draw_line start of draw_line end of draw_line end of draw_line %NULL-terminated list of optional named arguments

As vips_draw_line(), but just take a single double for @ink. See also: vips_draw_line().

0 on success, or -1 on error.

image to draw on

value to draw start of draw_line start of draw_line end of draw_line end of draw_line %NULL-terminated list of optional named arguments

Draw @mask on the image. @mask is a monochrome 8-bit image with 0/255 for transparent or @ink coloured points. Intermediate values blend the ink with the pixel. Use with vips_text() to draw text on an image. Use in a vips_draw_line() subclass to draw an object along a line. @ink is an array of double containing values to draw. See also: vips_text(), vips_draw_line().

0 on success, or -1 on error.

image to draw on

value to draw size of ink array mask of 0/255 values showing where to plot draw mask here draw mask here %NULL-terminated list of optional named arguments

As vips_draw_mask(), but just takes a single double for @ink. See also: vips_draw_mask().

0 on success, or -1 on error.

image to draw on

value to draw mask of 0/255 values showing where to plot draw mask here draw mask here %NULL-terminated list of optional named arguments

As vips_draw_rect(), but draw a single pixel at @x, @y. See also: vips_draw_rect().

0 on success, or -1 on error.

image to draw on

value to draw length of ink array point to paint point to paint %NULL-terminated list of optional named arguments

As vips_draw_point(), but just take a single double for @ink. See also: vips_draw_point().

0 on success, or -1 on error.

image to draw on

value to draw point to draw point to draw %NULL-terminated list of optional named arguments

Optional arguments: * @fill: fill the rect Paint pixels within @left, @top, @width, @height in @image with @ink. If @fill is zero, just paint a 1-pixel-wide outline. See also: vips_draw_circle().

0 on success, or -1 on error.

image to draw on

value to draw length of ink array area to paint area to paint area to paint area to paint %NULL-terminated list of optional named arguments

Optional arguments: * @fill: fill the rect As vips_draw_rect(), but just take a single double for @ink. See also: vips_draw_rect().

0 on success, or -1 on error.

image to draw on

value to draw area to paint area to paint area to paint area to paint %NULL-terminated list of optional named arguments

Smudge a section of @image. Each pixel in the area @left, @top, @width, @height is replaced by the average of the surrounding 3x3 pixels. See also: vips_draw_line().

0 on success, or -1 on error.

image to draw on

point to paint point to paint area to paint area to paint %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

name to save to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Optional arguments: * @extend: #VipsExtend to generate the edge pixels (default: black) * @background: #VipsArrayDouble colour for edge pixels The opposite of vips_extract_area(): embed @in within an image of size @width by @height at position @x, @y. @extend controls what appears in the new pels, see #VipsExtend. See also: vips_extract_area(), vips_insert().

0 on success, -1 on error.

input image

output image place @in at this x position in @out place @in at this y position in @out @out should be this many pixels across @out should be this many pixels down %NULL-terminated list of optional named arguments

A convenience function to pack to a coding. The inverse of vips_image_decode(). See also: vips_image_decode().

0 on success, or -1 on error.

image to encode

write to this image coding to apply

Perform #VIPS_OPERATION_BOOLEAN_EOR on an image and an array of constants. See vips_boolean_const(). See also: vips_boolean(), vips_boolean_const1().

0 on success, -1 on error

input image

output image array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_EOR on an image and a constant. See vips_boolean_const1(). See also: vips_boolean(), vips_boolean_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_EQUAL on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_EQUAL on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_EXP on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_EXP10 on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Extract an area from an image. The area must fit within @in. See also: vips_extract_bands(), vips_smartcrop().

0 on success, -1 on error.

input image

output image left edge of area to extract top edge of area to extract width of area to extract height of area to extract %NULL-terminated list of optional named arguments

Optional arguments: * @n: number of bands to extract Extract a band or bands from an image. Extracting out of range is an error. See also: vips_extract_area().

0 on success, -1 on error.

input image

output image band to extract %NULL-terminated list of optional named arguments

Force @in to 1 band, 8-bit, then transform to a 3-band 8-bit image with a false colour map. The map is supposed to make small differences in brightness more obvious. See also: vips_maplut().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Calculate a fast correlation surface. @ref is placed at every position in @in and the sum of squares of differences calculated. The output image is the same size as the input. Extra input edge pixels are made by copying the existing edges outwards. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The output type is uint if both inputs are integer, float if both are float or complex, and double if either is double or double complex. In other words, the output type is just large enough to hold the whole range of possible values. See also: vips_spcor().

0 on success, -1 on error

input image

reference image output image %NULL-terminated list of optional named arguments

Optional arguments: * @distance: output image of distance to nearest non-zero pixel Fill outwards from every non-zero pixel in @in, setting pixels in @distance and @value. At the position of zero pixels in @in, @distance contains the distance to the nearest non-zero pixel in @in, and @value contains the value of that pixel. @distance is a one-band float image. @value has the same number of bands and format as @in. See also: vips_hist_find_indexed().

0 on success, -1 on error.

image to test

image with zero pixels filled with the nearest non-zero pixel %NULL-terminated list of optional named arguments

Optional arguments: * @threshold: %gdouble, background / object threshold * @background: #VipsArrayDouble, background colour * @line_art: %gboolean, enable line art mode Search @in for the bounding box of the non-background area. Any alpha is flattened out, then the image is median-filtered (unless @line_art is set, see below). The absolute difference from @background is computed and binarized according to @threshold. Row and column sums of the absolute difference are calculated from this binary image and searched for the first row or column in each direction to obtain the bounding box. If the image is entirely background, vips_find_trim() returns @width == 0 and @height == 0. @background defaults to 255, or 65535 for 16-bit images. Set another value, or use vips_getpoint() to pick a value from an edge. You'll need to flatten before vips_getpoint() to get a correct background value. @threshold defaults to 10. The detector is designed for photographic or compressed images where there is a degree of noise that needs filtering. If your images are synthetic (eg. rendered from vector art, perhaps), set @line_art to disable this filtering. The image needs to be at least 3x3 pixels in size. See also: vips_getpoint(), vips_extract_area(), vips_smartcrop().

0 on success, -1 on error

image to find_trim

output left edge output top edge output width output height %NULL-terminated list of optional named arguments

Write a VIPS image to a file in FITS format. See also: vips_image_write_to_file().

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

Optional arguments: * @background: #VipsArrayDouble colour for new pixels * @max_alpha: %gdouble, maximum value for alpha Take the last band of @in as an alpha and use it to blend the remaining channels with @background. The alpha channel is 0 - @max_alpha, where @max_alpha means 100% image and 0 means 100% background. @background defaults to zero (black). @max_alpha has the default value 255, or 65535 for images tagged as #VIPS_INTERPRETATION_RGB16 or #VIPS_INTERPRETATION_GREY16. Useful for flattening PNG images to RGB. Non-complex images only. See also: vips_premultiply(), vips_pngload().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Flips an image left-right or up-down. See also: vips_rot().

0 on success, -1 on error

input image

output image flip horizontally or vertically %NULL-terminated list of optional named arguments

Convert a three-band float image to Radiance 32-bit packed format. See also: vips_rad2float(), #VIPS_CODING_RAD, vips_LabQ2Lab().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Round to an integral value with #VIPS_OPERATION_ROUND_FLOOR. See vips_round().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

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.

image to invalidate

Free the externally allocated buffer found in the input image. This function is intended to be used with g_signal_connect.

the image that contains the buffer

the original buffer that was stolen

Multiply @in by @mask in Fourier space. @in is transformed to Fourier space, multiplied with @mask, then transformed back to real space. If @in is already a complex image, just multiply then inverse transform. See also: vips_invfft(), vips_mask_ideal().

0 on success, -1 on error.

input image

mask image output image %NULL-terminated list of optional named arguments

Transform an image to Fourier space. VIPS uses the fftw Fourier Transform library. If this library was not available when VIPS was configured, these functions will fail. See also: vips_invfft().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @exponent: gamma, default 1.0 / 2.4 Calculate @in ** (1 / @exponent), normalising to the maximum range of the input type. For float types use 1.0 as the maximum. See also: vips_identity(), vips_pow_const1(), vips_maplut()

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @precision: #VipsPrecision, precision for blur, default int * @min_ampl: minimum amplitude, default 0.2 This operator runs vips_gaussmat() and vips_convsep() for you on an image. Set @min_ampl smaller to generate a larger, more accurate mask. Set @sigma larger to make the blur more blurry. See also: vips_gaussmat(), vips_convsep().

0 on success, -1 on error.

input image

output image how large a mask to use %NULL-terminated list of optional named arguments

Fill @value_copy with a copy of the header field. @value_copy must be zeroed but uninitialised. This will return -1 and add a message to the error buffer if the field does not exist. Use vips_image_get_typeof() to test for the existence of a field first if you are not certain it will be there. For example, to read a double from an image (though of course you would use vips_image_get_double() in practice): |[ GValue value = G_VALUE_INIT; double d; if (vips_image_get(image, name, &value)) return -1; if (G_VALUE_TYPE(&value) != G_TYPE_DOUBLE) { vips_error("mydomain", _("field \"%s\" is of type %s, not double"), name, g_type_name(G_VALUE_TYPE(&value))); g_value_unset(&value); return -1; } d = g_value_get_double(&value); g_value_unset(&value); ]| See also: vips_image_get_typeof(), vips_image_get_double().

0 on success, -1 otherwise.

image to get the field from from

the name to fetch the %GValue is copied into this

Gets @data from @image under the name @name. A convenience function over vips_image_get(). Use vips_image_get_typeof() to test for the existence of a piece of metadata. See also: vips_image_set_area(), vips_image_get(), vips_image_get_typeof()

0 on success, -1 otherwise.

image to get the metadata from

metadata name return metadata value

Gets @out from @im under the name @name. The field must be of type #VIPS_TYPE_ARRAY_INT. Do not free @out. @out is valid as long as @image is valid. Use vips_image_get_typeof() to test for the existence of a piece of metadata. See also: vips_image_get(), vips_image_set_image()

0 on success, -1 otherwise.

image to get the metadata from

metadata name return pointer to array return the number of elements here, optionally

0 on success, -1 otherwise.

image to get the metadata from

metadata name return pointer to array return the number of elements here, optionally

Returns @name from @image in @out. This function will read any field, returning it as a printable string. You need to free the string with g_free() when you are done with it. This will base64-encode BLOBs, for example. Use vips_buf_appendgv() to make a string that's for humans. See also: vips_image_get(), vips_image_get_typeof(), vips_buf_appendgv().

0 on success, -1 otherwise.

image to get the header field from

field name return field value as string

the number of bands (channels) in the image.

image to get from

Gets @data from @image under the name @name, optionally returns its length in @length. Use vips_image_get_typeof() to test for the existence of a piece of metadata. See also: vips_image_get(), vips_image_get_typeof(), vips_blob_get(),

0 on success, -1 otherwise.

image to get the metadata from

metadata name pointer to area of memory return the blob length here, optionally

the image coding

image to get from

Fetch and sanity-check #VIPS_CONCURRENCY. Default to 1 if not present or crazy.

the suggested concurrency for this image

image to get from

Return a pointer to the image's pixel data, if possible. This can involve allocating large amounts of memory and performing a long computation. Image pixels are laid out in band-packed rows. Since this function modifies @image, it is not threadsafe. Only call it on images which you are sure have not been shared with another thread. See also: vips_image_wio_input(), vips_image_copy_memory().

a pointer to pixel data, if possible.

image to get data for

Gets @out from @im under the name @name. The value will be transformed into a double, if possible. See also: vips_image_get(), vips_image_get_typeof()

0 on success, -1 otherwise.

image to get the header field from

field name return field value

Get a %NULL-terminated array listing all the metadata field names on @image. Free the return result with g_strfreev(). This is handy for language bindings. From C, it's usually more convenient to use vips_image_map().

metadata fields in image, as a %NULL-terminated array.

image to get fields from

the name of the file the image was loaded from, or NULL if there is no filename.

image to get from

the format of each band element.

image to get from

the number of pixels down the image.

image to get from

This function reads the image history as a C string. The string is owned by VIPS and must not be freed. VIPS tracks the history of each image, that is, the sequence of operations that generated that image. Applications built on VIPS need to call vips_image_history_printf() for each action they perform, setting the command-line equivalent for the action. See also: vips_image_history_printf().

The history of @image as a C string. Do not free!

get history from here

Gets @out from @im under the name @name. The field must be of type #VIPS_TYPE_IMAGE. You must unref @out with g_object_unref(). Use vips_image_get_typeof() to test for the existence of a piece of metadata. See also: vips_image_get(), vips_image_set_image()

0 on success, -1 otherwise.

image to get the metadata from

metadata name return metadata value

Gets @out from @im under the name @name. The value will be transformed into an int, if possible. See also: vips_image_get(), vips_image_get_typeof()

0 on success, -1 otherwise.

image to get the header field from

field name return field value

Return the #VipsInterpretation set in the image header. Use vips_image_guess_interpretation() if you want a sanity-checked value.

the #VipsInterpretation from the image header.

image to get from

Image modes are things like `"t"`, meaning a memory buffer, and `"p"` meaning a delayed computation.

the image mode.

image to get from

Fetch and sanity-check #VIPS_META_N_PAGES. Default to 1 if not present or crazy. This is the number of pages in the image file, not the number of pages that have been loaded into @image.

the number of pages in the image file

image to get from

Fetch and sanity-check #VIPS_META_N_SUBIFDS. Default to 0 if not present or crazy.

the number of subifds in the image file

image to get from

Matrix images can have an optional `offset` field for use by integer convolution.

the offset.

image to get from

Fetch and sanity-check #VIPS_META_ORIENTATION. Default to 1 (no rotate, no flip) if not present or crazy.

the image orientation.

image to get from

Return %TRUE if applying the orientation would swap width and height.

if width/height will swap

image to get from

Multi-page images can have a page height. Fetch it, and sanity check it. If page-height is not set, it defaults to the image height.

the page height.

image to get from

Matrix images can have an optional `scale` field for use by integer convolution.

the scale.

image to get from

Gets @out from @im under the name @name. The field must be of type G_TYPE_STRING, VIPS_TYPE_REF_STRING. Do not free @out. Use vips_image_get_as_string() to fetch any field as a string. See also: vips_image_get(), vips_image_get_typeof()

0 on success, -1 otherwise.

image to get the header field from

field name return field value

Read the %GType for a header field. Returns zero if there is no field of that name. See also: vips_image_get().

the %GType of the field, or zero if there is no field of that name.

image to test

the name to search for

the number of pixels across the image.

image to get from

the horizontal position of the image origin, in pixels.

image to get from

the horizontal image resolution in pixels per millimeter.

image to get from

the vertical position of the image origin, in pixels.

image to get from

the vertical image resolution in pixels per millimeter.

image to get from

Reads a single pixel on an image. The pixel values are returned in @vector, the length of the array in @n. You must free the array with g_free() when you are done with it. The result array has an element for each band. If @unpack_complex is set, pixels in complex images are returned as double-length arrays. See also: vips_draw_point().

0 on success, or -1 on error.

image to read from

output pixel value here length of output vector position to read position to read %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Optional arguments: * @gamma: gamma of source images * @int_output: %TRUE for integer image output vips_globalbalance() can be used to remove contrast differences in an assembled mosaic. It reads the History field attached to @in and builds a list of the source images that were used to make the mosaic and the position that each ended up at in the final image. It opens each of the source images in turn and extracts all parts which overlap with any of the other images. It finds the average values in the overlap areas and uses least-mean-square to find a set of correction factors which will minimise overlap differences. It uses @gamma to gamma-correct the source images before calculating the factors. A value of 1.0 will stop this. Each of the source images is transformed with the appropriate correction factor, then the mosaic is reassembled. @out is #VIPS_FORMAT_FLOAT, but if @int_output is set, the output image is the same format as the input images. There are some conditions that must be met before this operation can work: the source images must all be present under the filenames recorded in the history on @in, and the mosaic must have been built using only operations in this package. See also: vips_remosaic().

0 on success, -1 on error

mosaic to rebuild

output image %NULL-terminated list of optional named arguments

Chop a tall thin image up into a set of tiles, lay the tiles out in a grid. The input image should be a very tall, thin image containing a list of smaller images. Volumetric or time-sequence images are often laid out like this. This image is chopped into a series of tiles, each @tile_height pixels high and the width of @in. The tiles are then rearranged into a grid @across tiles across and @down tiles down in row-major order. Supplying @tile_height, @across and @down is not strictly necessary, we only really need two of these. Requiring three is a double-check that the image has the expected geometry. See also: vips_embed(), vips_insert(), vips_join().

0 on success, -1 on error

input image

output image chop into tiles this high tiles across tiles down %NULL-terminated list of optional named arguments

Return the #VipsBandFormat for an image, guessing a sane value if the set value looks crazy. For example, for a float image tagged as rgb16, we'd return ushort.

a sensible #VipsBandFormat for the image.

image to guess for

Return the #VipsInterpretation for an image, guessing a sane value if the set value looks crazy.

a sensible #VipsInterpretation for the image.

image to guess for

Look at an image's interpretation and see if it has extra alpha bands. For example, a 4-band #VIPS_INTERPRETATION_sRGB would, but a six-band #VIPS_INTERPRETATION_MULTIBAND would not. Return %TRUE if @image has an alpha channel.

image to check

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Form cumulative histogram. See also: vips_hist_norm().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Estimate image entropy from a histogram. Entropy is calculated as: |[ -sum(p * log2(p)) ]| where p is histogram-value / sum-of-histogram-values.

0 on success, -1 on error

input histogram

image entropy %NULL-terminated list of optional named arguments

Optional arguments: * @band: band to equalise Histogram-equalise @in. Equalise using band @bandno, or if @bandno is -1, equalise bands independently. The output format is always the same as the input format. See also:

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @band: band to equalise Find the histogram of @in. Find the histogram for band @band (producing a one-band histogram), or for all bands (producing an n-band histogram) if @band is -1. char and uchar images are cast to uchar before histogramming, all other image types are cast to ushort. See also: vips_hist_find_ndim(), vips_hist_find_indexed().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @combine: #VipsCombine, combine bins like this Make a histogram of @in, but use image @index to pick the bins. In other words, element zero in @out contains the combination of all the pixels in @in whose corresponding pixel in @index is zero. char and uchar @index images are cast to uchar before histogramming, all other image types are cast to ushort. @index must have just one band. @in must be non-complex. @out always has the same size and format as @in. Normally, bins are summed, but you can use @combine to set other combine modes. This operation is useful in conjunction with vips_labelregions(). You can use it to find the centre of gravity of blobs in an image, for example. See also: vips_hist_find(), vips_labelregions().

0 on success, -1 on error

input #VipsImage

input index #VipsImage output image %NULL-terminated list of optional named arguments

Optional arguments: * @bins: number of bins to make on each axis Make a one, two or three dimensional histogram of a 1, 2 or 3 band image. Divide each axis into @bins bins .. ie. output is 1 x bins, bins x bins, or bins x bins x bins bands. @bins defaults to 10. char and uchar images are cast to uchar before histogramming, all other image types are cast to ushort. See also: vips_hist_find(), vips_hist_find_indexed().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Test @in for monotonicity. @out is set non-zero if @in is monotonic.

0 on success, -1 on error

lookup-table to test

set non-zero if @in is monotonic %NULL-terminated list of optional named arguments

Optional arguments: * @max_slope: maximum brightening Performs local histogram equalisation on @in using a window of size @width by @height centered on the input pixel. The output image is the same size as the input image. The edge pixels are created by mirroring the input image outwards. If @max_slope is greater than 0, it sets the maximum value for the slope of the cumulative histogram, that is, the maximum brightening that is performed. A value of 3 is often used. Local histogram equalization with contrast limiting is usually called CLAHE. See also: vips_hist_equal().

0 on success, -1 on error

input image

output image width of region height of region %NULL-terminated list of optional named arguments

Adjust @in to match @ref. If @in and @ref are normalised cumulative histograms, @out will be a LUT that adjusts the PDF of the image from which @in was made to match the PDF of @ref's image. See also: vips_maplut(), vips_hist_find(), vips_hist_norm(), vips_hist_cum().

0 on success, -1 on error

input histogram

reference histogram output histogram %NULL-terminated list of optional named arguments

Normalise histogram. The maximum of each band becomes equal to the maximum index, so for example the max for a uchar image becomes 255. Normalise each band separately. See also: vips_hist_cum().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Plot a 1 by any or any by 1 image file as a max by any or any by max image using these rules: <emphasis>unsigned char</emphasis> max is always 256 <emphasis>other unsigned integer types</emphasis> output 0 - maximum value of @in. <emphasis>signed int types</emphasis> min moved to 0, max moved to max + min. <emphasis>float types</emphasis> min moved to 0, max moved to any (square output)

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Formats the name/argv as a single string and calls vips_image_history_printf(). A convenience function for command-line prorams. See also: vips_image_get_history().

0 on success, -1 on error.

image to attach history line to

program name number of program arguments program arguments

Add a line to the image history. The @format and arguments are expanded, the date and time is appended prefixed with a hash character, and the whole string is appended to the image history and terminated with a newline. For example: |[ vips_image_history_printf(image, "vips invert %s %s", in->filename, out->filename); ]| Might add the string |[ "vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n" ]| VIPS operations don't add history lines for you because a single action at the application level might involve many VIPS operations. History must be recorded by the application.

0 on success, -1 on error.

add history line to this image

printf() format string arguments to format string

Optional arguments: * @scale: scale down dimensions by this much * @min_radius: smallest radius to search for * @max_radius: largest radius to search for Find the circular Hough transform of an image. @in must be one band, with non-zero pixels for image edges. @out is three-band, with the third channel representing the detected circle radius. The operation scales the number of votes by circle circumference so circles of differing size are given equal weight. The output pixel at (x, y, band) is the strength of the circle centred on (x, y) and with radius (band). Use @max_radius and @min_radius to set the range of radii to search for. Use @scale to set how @in coordinates are scaled to @out coordinates. A @scale of 3, for example, will make @out 1/3rd of the width and height of @in, and reduce the number of radii tested (and hence the number of bands int @out) by a factor of three as well. See also: vips_hough_line().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @width: horizontal size of parameter space * @height: vertical size of parameter space Find the line Hough transform for @in. @in must have one band. @out has one band, with pixels being the number of votes for that line. The X dimension of @out is the line angle in 0 - 180 degrees, the Y dimension is the distance of the closest part of that line to the origin in the top-left. Use @width @height to set the size of the parameter space image (@out), that is, how accurate the line determination should be. See also: vips_hough_circle().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Transform an image from absolute to relative colorimetry using the MediaWhitePoint stored in the ICC profile. See also: vips_icc_transform(), vips_icc_import().

0 on success, -1 on error.

input image

output image use this profile

Optional arguments: * @pcs: #VipsPCS, use XYZ or LAB PCS * @intent: #VipsIntent, transform with this intent * @black_point_compensation: %gboolean, enable black point compensation * @output_profile: %gchararray, get the output profile from here * @depth: %gint, depth of output image in bits Export an image from D65 LAB to device space with an ICC profile. If @pcs is set to #VIPS_PCS_XYZ, use CIE XYZ PCS instead. If @output_profile is not set, use the embedded profile, if any. If @output_profile is set, export with that and attach it to the output image. If @black_point_compensation is set, LCMS black point compensation is enabled.

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @pcs: #VipsPCS, use XYZ or LAB PCS * @intent: #VipsIntent, transform with this intent * @black_point_compensation: %gboolean, enable black point compensation * @embedded: %gboolean, use profile embedded in input image * @input_profile: %gchararray, get the input profile from here Import an image from device space to D65 LAB with an ICC profile. If @pcs is set to #VIPS_PCS_XYZ, use CIE XYZ PCS instead. The input profile is searched for in three places: 1. If @embedded is set, libvips will try to use any profile in the input image metadata. You can test for the presence of an embedded profile with vips_image_get_typeof() with #VIPS_META_ICC_NAME as an argument. This will return %GType 0 if there is no profile. 2. Otherwise, if @input_profile is set, libvips will try to load a profile from the named file. This can aslso be the name of one of the built-in profiles. 3. Otherwise, libvips will try to pick a compatible profile from the set of built-in profiles. If @black_point_compensation is set, LCMS black point compensation is enabled.

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @pcs: #VipsPCS, use XYZ or LAB PCS * @intent: #VipsIntent, transform with this intent * @black_point_compensation: %gboolean, enable black point compensation * @embedded: %gboolean, use profile embedded in input image * @input_profile: %gchararray, get the input profile from here * @depth: %gint, depth of output image in bits Transform an image with a pair of ICC profiles. The input image is moved to profile-connection space with the input profile and then to the output space with the output profile. The input profile is searched for in three places: 1. If @embedded is set, libvips will try to use any profile in the input image metadata. You can test for the presence of an embedded profile with vips_image_get_typeof() with #VIPS_META_ICC_NAME as an argument. This will return %GType 0 if there is no profile. 2. Otherwise, if @input_profile is set, libvips will try to load a profile from the named file. This can aslso be the name of one of the built-in profiles. 3. Otherwise, libvips will try to pick a compatible profile from the set of built-in profiles. If @black_point_compensation is set, LCMS black point compensation is enabled. @depth defaults to 8, or 16 if @in is a 16-bit image. The output image has the output profile attached to the #VIPS_META_ICC_NAME field. Use vips_icc_import() and vips_icc_export() to do either the first or second half of this operation in isolation.

0 on success, -1 on error.

input image

output image get the output profile from here %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_COMPLEXGET_IMAG on an image. See vips_complexget().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

A convenience function to set the header fields after creating an image. Normally you copy the fields from your input images with vips_image_pipelinev() and then make any adjustments you need, but if you are creating an image from scratch, for example vips_black() or vips_jpegload(), you do need to set all the fields yourself. See also: vips_image_pipelinev().

image to init

image width image height image bands band format image coding image type horizontal resolution, pixels per millimetre vertical resolution, pixels per millimetre

Gets @image ready for an in-place operation, such as vips_draw_circle(). After calling this function you can both read and write the image with VIPS_IMAGE_ADDR(). This method is called for you by the base class of the draw operations, there's no need to call it yourself. Since this function modifies @image, it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. All in-place operations are inherently not thread-safe, so you need to take great care in any case. See also: vips_draw_circle(), vips_image_wio_input().

0 on success, or -1 on error.

image to make read-write

Optional arguments: * @expand: expand output to hold whole of both images * @background: colour for new pixels Insert @sub into @main at position @x, @y. Normally @out shows the whole of @main. If @expand is #TRUE then @out is made large enough to hold all of @main and @sub. Any areas of @out not coming from either @main or @sub are set to @background (default 0). If @sub overlaps @main, @sub will appear on top of @main. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). See also: vips_join(), vips_embed(), vips_extract_area().

0 on success, -1 on error

big image

small image output image left position of @sub top position of @sub %NULL-terminated list of optional named arguments

Invalidate all pixel caches on @image and any downstream images, that is, images which depend on this image. Additionally, all operations which depend upon this image are dropped from the VIPS operation cache. You should call this function after destructively modifying an image with something like vips_draw_circle(). The #VipsImage::invalidate signal is emitted for all invalidated images. See also: vips_region_invalidate().

#VipsImage to invalidate

For unsigned formats, this operation calculates (max - @in), eg. (255 - @in) for uchar. For signed and float formats, this operation calculates (-1 @in). For complex images, only the real part is inverted. See also vips_conj(). See also: vips_linear().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @size: generate this much Given a mask of target values and real values, generate a LUT which will map reals to targets. Handy for linearising images from measurements of a colour chart. All values in [0,1]. Piecewise linear interpolation, extrapolate head and tail to 0 and 1. Eg. input like this: <tgroup cols='4' align='left' colsep='1' rowsep='1'> <tbody> <row> <entry>4</entry> <entry>3</entry> </row> <row> <entry>0.1</entry> <entry>0.2</entry> <entry>0.3</entry> <entry>0.1</entry> </row> <row> <entry>0.2</entry> <entry>0.4</entry> <entry>0.4</entry> <entry>0.2</entry> </row> <row> <entry>0.7</entry> <entry>0.5</entry> <entry>0.6</entry> <entry>0.3</entry> </row> </tbody> </tgroup> Means a patch with 10% reflectance produces an image with 20% in channel 1, 30% in channel 2, and 10% in channel 3, and so on. Inputs don't need to be sorted (we do that). Generate any precision LUT, default to 256 elements. It won't work too well for non-monotonic camera responses (we should fix this). Interpolation is simple piecewise linear; we ought to do something better really. See also: vips_buildlut().

0 on success, -1 on error

input mask

output LUT %NULL-terminated list of optional named arguments

Optional arguments: * @real: only output the real part Transform an image from Fourier space to real space. The result is complex. If you are OK with a real result, set @real, it's quicker. VIPS uses the fftw Fourier Transform library. If this library was not available when VIPS was configured, these functions will fail. See also: vips_fwfft().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Return %TRUE if @image is in most-significant- byte first form. This is the byte order used on the SPARC architecture and others.

image to test

TRUE if any of the images upstream from @image were opened in sequential mode. Some operations change behaviour slightly in sequential mode to optimize memory behaviour.

%TRUE if @image is in sequential mode.

#VipsImage to minimise

Return %TRUE if @image represents a file on disc in some way.

image to test

If @image has been killed (see vips_image_set_kill()), set an error message, clear the #VipsImage.kill flag and return %TRUE. Otherwise return %FALSE. Handy for loops which need to run sets of threads which can fail. See also: vips_image_set_kill().

%TRUE if @image has been killed.

image to test

Return %TRUE if @im represents a partial image (a delayed calculation).

image to test

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

%NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

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.

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Optional arguments: * @segments: return number of regions found here Repeatedly scans @in for regions of 4-connected pixels with the same pixel value. Every time a region is discovered, those pixels are marked in @mask with a unique serial number. Once all pixels have been labelled, the operation returns, setting @segments to the number of discrete regions which were detected. @mask is always a 1-band #VIPS_FORMAT_INT image of the same dimensions as @in. This operation is useful for, for example, blob counting. You can use the morphological operators to detect and isolate a series of objects, then use vips_labelregions() to number them all. Use vips_hist_find_indexed() to (for example) find blob coordinates. See also: vips_hist_find_indexed().

0 on success, -1 on error.

image to test

write labelled regions here %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_LESS on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_LESS on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_LESSEQ on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_LESSEQ on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Optional arguments: * @uchar: output uchar pixels Pass an image through a linear transform, ie. (@out = @in * @a + @b). Output is float for integer input, double for double input, complex for complex input and double complex for double complex input. Set @uchar to output uchar pixels. If the arrays of constants have just one element, that constant is used for all image bands. If the arrays have more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element. See also: vips_linear1(), vips_add().

0 on success, -1 on error

image to transform

output image array of constants for multiplication array of constants for addition length of constant arrays %NULL-terminated list of optional named arguments

Optional arguments: * @uchar: output uchar pixels Run vips_linear() with a single constant. See also: vips_linear().

0 on success, -1 on error

image to transform

output image constant for multiplication constant for addition %NULL-terminated list of optional named arguments

Optional arguments: * @access: hint expected access pattern #VipsAccess * @tile_height: height of tiles in cache * @threaded: allow many threads This operation behaves rather like vips_copy() between images @in and @out, except that it keeps a cache of computed scanlines. The number of lines cached is enough for a small amount of non-local access. Each cache tile is made with a single call to vips_region_prepare(). When the cache fills, a tile is chosen for reuse. If @access is #VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If @access is #VIPS_ACCESS_SEQUENTIAL, then the top-most tile is reused. @access defaults to #VIPS_ACCESS_RANDOM. @tile_height can be used to set the size of the strips that vips_linecache() uses. The default is 1 (a single scanline). Normally, only a single thread at once is allowed to calculate tiles. If you set @threaded to %TRUE, vips_linecache() will allow many threads to calculate tiles at once and share the cache between them. See also: vips_cache(), vips_tilecache().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_LOG on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_LOG10 on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_LSHIFT on an image and an array of constants. See vips_boolean_const(). See also: vips_boolean(), vips_boolean_const1().

0 on success, -1 on error

input image

output image array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_LSHIFT on an image and a constant. See vips_boolean_const1(). See also: vips_boolean(), vips_boolean_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

This function calls @fn for every header field, including every item of metadata. Like all _map functions, the user function should return %NULL to continue iteration, or a non-%NULL pointer to indicate early termination. See also: vips_image_get_typeof(), vips_image_get().

%NULL on success, the failing pointer otherwise.

image to map over

function to call for each header field user data for function

Optional arguments: * @interpolate: interpolate pixels with this * @extend: #VipsExtend how to generate new pixels * @background: #VipsArrayDouble colour for new pixels * @premultiplied: %gboolean, images are already premultiplied This operator resamples @in using @index to look up pixels. @out is the same size as @index, with each pixel being fetched from that position in @in. That is: |[ out[x, y] = in[index[x, y]] ]| If @index has one band, that band must be complex. Otherwise, @index must have two bands of any format. Coordinates in @index are in pixels, with (0, 0) being the top-left corner of @in, and with y increasing down the image. Use vips_xyz() to build index images. @interpolate defaults to bilinear. By default, new pixels are filled with @background. This defaults to zero (black). You can set other extend types with @extend. #VIPS_EXTEND_COPY is better for image upsizing. Image are normally treated as unpremultiplied, so this operation can be used directly on PNG images. If your images have been through vips_premultiply(), set @premultiplied. This operation does not change xres or yres. The image resolution needs to be updated by the application. See vips_maplut() for a 1D equivalent of this operation. See also: vips_xyz(), vips_affine(), vips_resize(), vips_maplut(), #VipsInterpolate.

0 on success, -1 on error

input image

output image index image %NULL-terminated list of optional named arguments

Optional arguments: * @band: apply one-band @lut to this band of @in Map an image through another image acting as a LUT (Look Up Table). The lut may have any type and the output image will be that type. The input image will be cast to one of the unsigned integer types, that is, VIPS_FORMAT_UCHAR, VIPS_FORMAT_USHORT or VIPS_FORMAT_UINT. If @lut is too small for the input type (for example, if @in is VIPS_FORMAT_UCHAR but @lut only has 100 elements), the lut is padded out by copying the last element. Overflows are reported at the end of computation. If @lut is too large, extra values are ignored. If @lut has one band and @band is -1 (the default), then all bands of @in pass through @lut. If @band is >= 0, then just that band of @in passes through @lut and other bands are just copied. If @lut has same number of bands as @in, then each band is mapped separately. If @in has one band, then @lut may have many bands and the output will have the same number of bands as @lut. See also: vips_hist_find(), vips_identity().

0 on success, -1 on error

input image

output image look-up table %NULL-terminated list of optional named arguments

Perform various functions in -lm, the maths library, on images. Angles are expressed in degrees. The output type is float unless the input is double, in which case the output is double. Non-complex images only. See also: vips_math2().

0 on success, -1 on error

input #VipsImage

output #VipsImage math operation to perform %NULL-terminated list of optional named arguments

This operation calculates various 2-ary maths operations on an image and an array of constants and writes the result to @out. The image may have any non-complex format. @out is float except in the case that @in is double, in which case @out is also double. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently! If the array of constants has just one element, that constant is used for all image bands. If the array has more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element. See also: vips_math2(), vips_math().

0 on success, -1 on error

input image

output image math operation to perform array of constants number of constants in @c %NULL-terminated list of optional named arguments

This operation calculates various 2-ary maths operations on an image and a constant. See vips_math2_const().

0 on success, -1 on error

input image

output image math operation to perform constant %NULL-terminated list of optional named arguments

This operation calculates the inverse of the matrix represented in @m. The scale and offset members of the input matrix are ignored. See also: vips_matrixload().

0 on success, -1 on error

matrix to invert

output matrix %NULL-terminated list of optional named arguments

Print @in to %stdout in matrix format. See vips_matrixload() for a description of the format. See also: vips_matrixload().

0 on success, -1 on error.

image to print

%NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

As vips_matrixsave(), but save to a target. See also: vips_matrixsave().

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Optional arguments: * @x: horizontal position of maximum * @y: vertical position of maximum * @size: number of maxima to find * @out_array: return array of maximum values * @x_array: corresponding horizontal positions * @y_array: corresponding vertical positions This operation finds the maximum value in an image. By default it finds the single largest value. If @size is set >1, it will find the @size largest values. It will stop searching early if has found enough values. Equal values will be sorted by y then x. It operates on all bands of the input image: use vips_stats() if you need to find an maximum for each band. For complex images, this operation finds the maximum modulus. You can read out the position of the maximum with @x and @y. You can read out arrays of the values and positions of the top @size maxima with @out_array, @x_array and @y_array. These values are returned sorted from largest to smallest. If there are more than @size maxima, the maxima returned will be a random selection of the maxima in the image. See also: vips_min(), vips_stats().

0 on success, -1 on error

input #VipsImage

output pixel maximum %NULL-terminated list of optional named arguments

Optional arguments: * @left: area of image containing chart * @top: area of image containing chart * @width: area of image containing chart * @height: area of image containing chart Analyse a grid of colour patches, producing an array of patch averages. The mask has a row for each measured patch and a column for each image band. The operations issues a warning if any patch has a deviation more than 20% of the mean. Only the central 50% of each patch is averaged. If the chart does not fill the whole image, use the optional @left, @top, @width, @height arguments to indicate the position of the chart. See also: vips_avg(), vips_deviate().

0 on success, -1 on error

image to measure

array of measurements patches across chart patches down chart %NULL-terminated list of optional named arguments

A convenience function equivalent to: vips_rank(in, out, size, size, (size * size) / 2); See also: vips_rank().

0 on success, -1 on error

input image

output image size of region %NULL-terminated list of optional named arguments

Optional arguments: * @x: horizontal position of minimum * @y: vertical position of minimum * @size: number of minima to find * @out_array: return array of minimum values * @x_array: corresponding horizontal positions * @y_array: corresponding vertical positions This operation finds the minimum value in an image. By default it finds the single smallest value. If @size is set >1, it will find the @size smallest values. It will stop searching early if has found enough values. Equal values will be sorted by y then x. It operates on all bands of the input image: use vips_stats() if you need to find an minimum for each band. For complex images, this operation finds the minimum modulus. You can read out the position of the minimum with @x and @y. You can read out arrays of the values and positions of the top @size minima with @out_array, @x_array and @y_array. These values are returned sorted from smallest to largest. If there are more than @size minima, the minima returned will be a random selection of the minima in the image. See also: vips_min(), vips_stats().

0 on success, -1 on error

input #VipsImage

output pixel minimum %NULL-terminated list of optional named arguments

Minimise memory use on this image and any upstream images, that is, images which this image depends upon. This function is called automatically at the end of a computation, but it might be useful to call at other times. The #VipsImage::minimise signal is emitted for all minimised images.

#VipsImage to minimise

Perform #VIPS_OPERATION_RELATIONAL_MORE on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_MORE on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_MOREEQ on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_MOREEQ on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Performs a morphological operation on @in using @mask as a structuring element. The image should have 0 (black) for no object and 255 (non-zero) for an object. Note that this is the reverse of the usual convention for these operations, but more convenient when combined with the boolean operators. The output image is the same size as the input image: edge pxels are made by expanding the input image as necessary. Mask coefficients can be either 0 (for object) or 255 (for background) or 128 (for do not care). The origin of the mask is at location (m.xsize / 2, m.ysize / 2), integer division. All algorithms have been based on the book "Fundamentals of Digital Image Processing" by A. Jain, pp 384-388, Prentice-Hall, 1989. For #VIPS_OPERATION_MORPHOLOGY_ERODE, the whole mask must match for the output pixel to be set, that is, the result is the logical AND of the selected input pixels. For #VIPS_OPERATION_MORPHOLOGY_DILATE, the output pixel is set if any part of the mask matches, that is, the result is the logical OR of the selected input pixels. See the boolean operations vips_andimage(), vips_orimage() and vips_eorimage() for analogues of the usual set difference and set union operations. Operations are performed using the processor's vector unit, if possible. Disable this with `--vips-novector` or `VIPS_NOVECTOR` or vips_vector_set_enabled()

0 on success, -1 on error

input image

output image morphology with this mask operation to perform %NULL-terminated list of optional named arguments

Optional arguments: * @band: %gint, msb just this band Turn any integer image to 8-bit unsigned char by discarding all but the most significant byte. Signed values are converted to unsigned by adding 128. Use @band to make a one-band 8-bit image. This operator also works for LABQ coding. See also: vips_scale(), vips_cast().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_NOTEQ on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_NOTEQ on an image and a constant. See vips_relational_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_OR on an image and an array of constants. See vips_boolean_const(). See also: vips_boolean(), vips_boolean_const1().

0 on success, -1 on error

input image

output image array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_OR on an image and a constant. See vips_boolean_const1(). See also: vips_boolean(), vips_boolean_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

vips_percent() returns (through the @threshold parameter) the threshold below which there are @percent values of @in. For example: |[ $ vips percent k2.jpg 90 214 ]| Means that 90% of pixels in `k2.jpg` have a value less than 214. The function works for uchar and ushort images only. It can be used to threshold the scaled result of a filtering operation. See also: vips_hist_find(), vips_profile().

0 on success, -1 on error

input image

threshold percentage output threshold value %NULL-terminated list of optional named arguments

Check that an image is readable with vips_region_prepare() and friends. If it isn't, try to transform the image so that vips_region_prepare() can work. See also: vips_image_pio_output(), vips_region_prepare().

0 on success, or -1 on error.

image to check

Check that an image is writeable with vips_image_generate(). If it isn't, try to transform the image so that vips_image_generate() can work. See also: vips_image_pio_input().

0 on success, or -1 on error.

image to check

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_COMPLEX_POLAR on an image. See vips_complex().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_POW on an image and a constant. See vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_POW on an image and a constant. See vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage constant %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Optional arguments: * @max_alpha: %gdouble, maximum value for alpha Premultiplies any alpha channel. The final band is taken to be the alpha and the bands are transformed as: |[ alpha = clip(0, in[in.bands - 1], @max_alpha); norm = alpha / @max_alpha; out = [in[0] * norm, ..., in[in.bands - 1] * norm, alpha]; ]| So for an N-band image, the first N - 1 bands are multiplied by the clipped and normalised final band, the final band is clipped. If there is only a single band, the image is passed through unaltered. The result is #VIPS_FORMAT_FLOAT unless the input format is #VIPS_FORMAT_DOUBLE, in which case the output is double as well. @max_alpha has the default value 255, or 65535 for images tagged as #VIPS_INTERPRETATION_RGB16 or #VIPS_INTERPRETATION_GREY16. Non-complex images only. See also: vips_unpremultiply(), vips_flatten().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Prewitt edge detector. uchar images are computed using a fast, low-precision path. Cast to float for a high-precision implementation. See also: vips_canny(), vips_sobel(), vips_prewitt(), vips_scharr().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Prints field @name to stdout as ASCII. Handy for debugging.

image to get the header field from

field name

vips_profile() searches inward from the edge of @in and finds the first non-zero pixel. Pixels in @columns have the distance from the top edge to the first non-zero pixel in that column, @rows has the distance from the left edge to the first non-zero pixel in that row. See also: vips_project(), vips_hist_find().

0 on success, -1 on error

input image

distances from top edge distances from left edge %NULL-terminated list of optional named arguments

Find the horizontal and vertical projections of an image, ie. the sum of every row of pixels, and the sum of every column of pixels. The output format is uint, int or double, depending on the input format. Non-complex images only. See also: vips_hist_find(), vips_profile().

0 on success, -1 on error

input image

sums of columns sums of rows %NULL-terminated list of optional named arguments

Optional arguments: * @interpolate: use this interpolator (default bilinear) This operation is unfinished and unusable, sorry. See also: vips_affine().

0 on success, -1 on error

input image

output image horizontal quadratic %NULL-terminated list of optional named arguments

Unpack a RAD (#VIPS_CODING_RAD) image to a three-band float image. See also: vips_float2rad(), vips_LabQ2LabS().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

As vips_radsave(), but save to a target. See also: vips_radsave().

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

vips_rank() does rank filtering on an image. A window of size @width by @height is passed over the image. At each position, the pixels inside the window are sorted into ascending order and the pixel at position @index is output. @index numbers from 0. It works for any non-complex image type, with any number of bands. The input is expanded by copying edge pixels before performing the operation so that the output image has the same size as the input. Edge pixels in the output image are therefore only approximate. For a median filter with mask size m (3 for 3x3, 5 for 5x5, etc.) use vips_rank(in, out, m, m, m * m / 2); The special cases n == 0 and n == m * m - 1 are useful dilate and expand operators. See also: vips_conv(), vips_median(), vips_spcor().

0 on success, -1 on error

input image

output image width of region height of region select pixel %NULL-terminated list of optional named arguments

Writes the pixels in @in to the file @filename with no header or other metadata. See also: vips_image_write_to_file().

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

As vips_rawsave(), 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_rawsave(), vips_image_write_to_memory(), vips_image_write_to_file().

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

As vips_rawsave(), but save to a target. See also: vips_rawsave().

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_COMPLEXGET_REAL on an image. See vips_complexget().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

This operation recombines an image's bands. Each pixel in @in is treated as an n-element vector, where n is the number of bands in @in, and multiplied by the n x m matrix @m to produce the m-band image @out. @out is always float, unless @in is double, in which case @out is double too. No complex images allowed. It's useful for various sorts of colour space conversions. See also: vips_bandmean().

0 on success, -1 on error

input image

output image recombination matrix %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_COMPLEX_RECT on an image. See vips_complex().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @kernel: #VipsKernel to use to interpolate (default: lanczos3) * @gap: reducing gap to use (default: 0.0) Reduce @in by a pair of factors with a pair of 1D kernels. This will not work well for shrink factors greater than three. Set @gap to speed up reducing by having vips_shrink() to shrink with a box filter first. The bigger @gap, the closer the result to the fair resampling. The smaller @gap, the faster resizing. The default value is 0.0 (no optimization). This is a very low-level operation: see vips_resize() for a more convenient way to resize images. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_shrink(), vips_resize(), vips_affine().

0 on success, -1 on error

input image

output image horizontal shrink vertical shrink %NULL-terminated list of optional named arguments

Optional arguments: * @kernel: #VipsKernel to use to interpolate (default: lanczos3) * @gap: reducing gap to use (default: 0.0) Reduce @in horizontally by a float factor. The pixels in @out are interpolated with a 1D mask generated by @kernel. Set @gap to speed up reducing by having vips_shrinkh() to shrink with a box filter first. The bigger @gap, the closer the result to the fair resampling. The smaller @gap, the faster resizing. The default value is 0.0 (no optimization). This is a very low-level operation: see vips_resize() for a more convenient way to resize images. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_shrink(), vips_resize(), vips_affine().

0 on success, -1 on error

input image

output image horizontal reduce %NULL-terminated list of optional named arguments

Optional arguments: * @kernel: #VipsKernel to use to interpolate (default: lanczos3) * @gap: reducing gap to use (default: 0.0) Reduce @in vertically by a float factor. The pixels in @out are interpolated with a 1D mask generated by @kernel. Set @gap to speed up reducing by having vips_shrinkv() to shrink with a box filter first. The bigger @gap, the closer the result to the fair resampling. The smaller @gap, the faster resizing. The default value is 0.0 (no optimization). This is a very low-level operation: see vips_resize() for a more convenient way to resize images. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_shrink(), vips_resize(), vips_affine().

0 on success, -1 on error

input image

output image vertical reduce %NULL-terminated list of optional named arguments

Perform various relational operations on an image and an array of constants. The output type is always uchar, with 0 for FALSE and 255 for TRUE. If the array of constants has just one element, that constant is used for all image bands. If the array has more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element. See also: vips_boolean(), vips_relational().

0 on success, -1 on error

input image

output image relational operation to perform array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform various relational operations on an image and a constant. See vips_relational_const(). See also: vips_boolean(), vips_relational().

0 on success, -1 on error

input image

output image relational operation to perform constant %NULL-terminated list of optional named arguments

This operation calculates @in % @c (remainder after division by an array of constants) and writes the result to @out. The image may have any non-complex format. For float formats, vips_remainder_const() calculates @in - @c * floor (@in / @c). If the array of constants has just one element, that constant is used for all image bands. If the array has more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element. See also: vips_remainder(), vips_divide(), vips_round().

0 on success, -1 on error

input image

output image array of constants number of constants in @c %NULL-terminated list of optional named arguments

This operation calculates @in % @c (remainder after division by a constant) and writes the result to @out. The image may have any non-complex format. For float formats, vips_remainder_const() calculates @in - @c * floor (@in / @c). If the array of constants has just one element, that constant is used for all image bands. If the array has more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element. See also: vips_remainder(), vips_divide(), vips_round().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

vips_remosaic() works rather as vips_globalbalance(). It takes apart the mosaiced image @in and rebuilds it, substituting images. Unlike vips_globalbalance(), images are substituted based on their file‐ names. The rightmost occurrence of the string @old_str is swapped for @new_str, that file is opened, and that image substituted for the old image. It's convenient for multispectral images. You can mosaic one band, then use that mosaic as a template for mosaicing the others automatically. See also: vips_globalbalance().

0 on success, -1 on error

mosaic to rebuild

output image gamma of source images gamma of source images %NULL-terminated list of optional named arguments

Find and remove an item of metadata. Return %FALSE if no metadata of that name was found. See also: vips_image_set(), vips_image_get_typeof().

%TRUE if an item of metadata of that name was found and removed

image to test

the name to search for

vips_reorder_margin_hint() sets a hint that @image contains a margin, that is, that each vips_region_prepare() on @image will request a slightly larger region from it's inputs. A good value for @margin is (width * height) for the window the operation uses. This information is used by vips_image_prepare_many() to attempt to reorder computations to minimise recomputation. See also: vips_image_prepare_many().

the image to hint on

the size of the margin this operation has added

vips_reorder_prepare_many() runs vips_region_prepare() on each region in @regions, requesting the pixels in @r. It tries to request the regions in the order which will cause least recomputation. This can give a large speedup, in some cases. See also: vips_region_prepare(), vips_reorder_margin_hint().

0 on success, or -1 on error.

the image that's being written

the set of regions to prepare the #VipsRect to prepare on each region

Repeats an image many times. See also: vips_extract_area().

0 on success, -1 on error

input image

output image repeat input this many times across repeat input this many times down %NULL-terminated list of optional named arguments

Optional arguments: * @vscale: %gdouble vertical scale factor * @kernel: #VipsKernel to reduce with * @gap: reducing gap to use (default: 2.0) Resize an image. Set @gap to speed up downsizing by having vips_shrink() to shrink with a box filter first. The bigger @gap, the closer the result to the fair resampling. The smaller @gap, the faster resizing. The default value is 2.0 (very close to fair resampling while still being faster in many cases). vips_resize() normally uses #VIPS_KERNEL_LANCZOS3 for the final reduce, you can change this with @kernel. Downsizing is done with centre convention. When upsizing (@scale > 1), the operation uses vips_affine() with a #VipsInterpolate selected depending on @kernel. It will use #VipsInterpolateBicubic for #VIPS_KERNEL_CUBIC and above. It adds a 0.5 pixel displacement to the input pixels to get centre convention scaling. vips_resize() normally maintains the image aspect ratio. If you set @vscale, that factor is used for the vertical scale and @scale for the horizontal. If either axis would drop below 1px in size, the shrink in that dimension is limited. This breaks the image aspect ratio, but prevents errors due to fractional pixel sizes. This operation does not change xres or yres. The image resolution needs to be updated by the application. This operation does not premultiply alpha. If your image has an alpha channel, you should use vips_premultiply() on it first. See also: vips_premultiply(), vips_shrink(), vips_reduce().

0 on success, -1 on error

input image

output image scale factor %NULL-terminated list of optional named arguments

Round to an integral value with #VIPS_OPERATION_ROUND_RINT. See vips_round().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Rotate @in by a multiple of 90 degrees. Use vips_similarity() to rotate by an arbitrary angle. vips_rot45() is useful for rotating convolution masks by 45 degrees. See also: vips_flip(), vips_similarity(), vips_rot45().

0 on success, -1 on error

input image

output image rotation angle %NULL-terminated list of optional named arguments

Rotate @in by 180 degrees. A convenience function over vips_rot(). See also: vips_rot().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Rotate @in by 270 degrees clockwise. A convenience function over vips_rot(). See also: vips_rot().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @angle: #VipsAngle45 rotation angle Rotate @in by a multiple of 45 degrees. Odd-length sides and square images only. This operation is useful for rotating convolution masks. Use vips_similarity() to rotate images by arbitrary angles. See also: vips_rot(), vips_similarity().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @interpolate: #VipsInterpolate, interpolate pixels with this * @background: #VipsArrayDouble colour for new pixels * @idx: %gdouble, input horizontal offset * @idy: %gdouble, input vertical offset * @odx: %gdouble, output horizontal offset * @ody: %gdouble, output vertical offset This operator calls vips_affine() for you, calculating the matrix for the affine transform from @scale and @angle. Other parameters are passed on to vips_affine() unaltered. See also: vips_affine(), #VipsInterpolate.

0 on success, -1 on error

input image

output image %gdouble, rotate by this many degrees clockwise %NULL-terminated list of optional named arguments

Round to an integral value. Copy for integer types, round float and complex types. The format of @out is always the same as @in, so you may wish to cast to an integer format afterwards. See also: vips_cast()

0 on success, -1 on error

input #VipsImage

output #VipsImage #VipsOperationRound rounding operation to perform %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_LSHIFT on an image and an array of constants. See vips_boolean_const(). See also: vips_boolean(), vips_boolean_const1().

0 on success, -1 on error

input image

output image array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_RSHIFT on an image and a constant. See vips_boolean_const1(). See also: vips_boolean(), vips_boolean_const().

0 on success, -1 on error

input image

output image constant %NULL-terminated list of optional named arguments

Convert to HSV. HSV is a crude polar coordinate system for RGB images. It is provided for compatibility with other image processing systems. See vips_Lab2LCh() for a much better colour space. See also: vips_HSV2sRGB(), vips_Lab2LCh().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Convert an sRGB image to scRGB. The input image can be 8 or 16-bit. If the input image is tagged as #VIPS_INTERPRETATION_RGB16, any extra channels after RGB are divided by 256. Thus, scRGB alpha is always 0 - 255.99. See also: vips_scRGB2XYZ(), vips_scRGB2sRGB(), vips_rad2float().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @depth: depth of output image in bits Convert an scRGB image to greyscale. Set @depth to 16 to get 16-bit output. If @depth is 16, any extra channels after RGB are multiplied by 256. See also: vips_LabS2LabQ(), vips_sRGB2scRGB(), vips_rad2float().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Turn XYZ to scRGB.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @depth: depth of output image in bits Convert an scRGB image to sRGB. Set @depth to 16 to get 16-bit output. If @depth is 16, any extra channels after RGB are multiplied by 256. See also: vips_LabS2LabQ(), vips_sRGB2scRGB(), vips_rad2float().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @log: log scale pixels * @exp: exponent for log scale Search the image for the maximum and minimum value, then return the image as unsigned 8-bit, scaled so that the maximum value is 255 and the minimum is zero. If @log is set, transform with log10(1.0 + pow(x, @exp)) + .5, then scale so max == 255. By default, @exp is 0.25. See also: vips_cast().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Scharr edge detector. uchar images are computed using a fast, low-precision path. Cast to float for a high-precision implementation. See also: vips_canny(), vips_sobel(), vips_prewitt(), vips_scharr().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @tile_height: height of cache strips This operation behaves rather like vips_copy() between images @in and @out, except that it checks that pixels on @in are only requested top-to-bottom. This operation is useful for loading file formats which are strictly top-to-bottom, like PNG. @tile_height can be used to set the size of the tiles that vips_sequential() uses. The default value is 1. See also: vips_cache(), vips_linecache(), vips_tilecache().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Set a piece of metadata on @image. Any old metadata with that name is destroyed. The %GValue is copied into the image, so you need to unset the value when you're done with it. For example, to set an integer on an image (though you would use the convenience function vips_image_set_int() in practice), you would do: |[ GValue value = G_VALUE_INIT; g_value_init(&value, G_TYPE_INT); g_value_set_int(&value, 42); vips_image_set(image, name, &value); g_value_unset(&value); ]| See also: vips_image_get().

image to set the metadata on

the name to give the metadata the %GValue to copy into the image

Attaches @data as a metadata item on @image under the name @name. When VIPS no longer needs the metadata, it will be freed with @free_fn. See also: vips_image_get_double(), vips_image_set()

image to attach the metadata to

metadata name free function for @data pointer to area of memory

Attaches @array as a metadata item on @image as @name. A convenience function over vips_image_set(). See also: vips_image_get_image(), vips_image_set().

image to attach the metadata to

metadata name array of doubles the number of elements

Attaches @array as a metadata item on @image as @name. A convenience function over vips_image_set(). See also: vips_image_get_image(), vips_image_set().

image to attach the metadata to

metadata name array of ints the number of elements

Attaches @data as a metadata item on @image under the name @name. See also: vips_image_get_blob(), vips_image_set().

image to attach the metadata to

metadata name free function for @data pointer to area of memory length of memory area

Attaches @data as a metadata item on @image under the name @name, taking a copy of the memory area. See also: vips_image_get_blob(), vips_image_set().

image to attach the metadata to

metadata name pointer to area of memory length of memory area

Sets the delete_on_close flag for the image. If this flag is set, when @image is finalized, the filename held in @image->filename at the time of this call is deleted. This function is clearly extremely dangerous, use with great caution. See also: vips_image_new_temp_file().

image to set

format of file

Attaches @d as a metadata item on @image as @name. A convenience function over vips_image_set(). See also: vips_image_get_double(), vips_image_set()

image to attach the metadata to

metadata name metadata value

Attaches @im as a metadata item on @image as @name. A convenience function over vips_image_set(). See also: vips_image_get_image(), vips_image_set().

image to attach the metadata to

metadata name metadata value

Attaches @i as a metadata item on @image under the name @name. A convenience function over vips_image_set(). See also: vips_image_get_int(), vips_image_set()

image to attach the metadata to

metadata name metadata value

Set the #VipsImage.kill flag on an image. Handy for stopping sets of threads. See also: vips_image_iskilled().

image to test

the kill state

vips signals evaluation progress via the #VipsImage::preeval, #VipsImage::eval and #VipsImage::posteval signals. Progress is signalled on the most-downstream image for which vips_image_set_progress() was called.

image to signal progress on

turn progress reporting on or off

Attaches @str as a metadata item on @image as @name. A convenience function over vips_image_set() using #VIPS_TYPE_REF_STRING. See also: vips_image_get_double(), vips_image_set().

image to attach the metadata to

metadata name metadata value

Optional arguments: * @sigma: sigma of gaussian * @x1: flat/jaggy threshold * @y2: maximum amount of brightening * @y3: maximum amount of darkening * @m1: slope for flat areas * @m2: slope for jaggy areas Selectively sharpen the L channel of a LAB image. The input image is transformed to #VIPS_INTERPRETATION_LABS. The operation performs a gaussian blur and subtracts from @in to generate a high-frequency signal. This signal is passed through a lookup table formed from the five parameters and added back to @in. The lookup table is formed like this: |[ . ^ . y2 |- - - - - ----------- . | / . | / slope m2 . | .../ . -x1 | ... | . -------------------...----------------------> . | ... | x1 . |... slope m1 . / | . / m2 | . / | . / | . / | . / | . ______/ _ _ _ _ _ _ | -y3 . | ]| For screen output, we suggest the following settings (the defaults): |[ sigma == 0.5 x1 == 2 y2 == 10 (don't brighten by more than 10 L*) y3 == 20 (can darken by up to 20 L*) m1 == 0 (no sharpening in flat areas) m2 == 3 (some sharpening in jaggy areas) ]| If you want more or less sharpening, we suggest you just change the m2 parameter. The @sigma parameter changes the width of the fringe and can be adjusted according to the output printing resolution. As an approximate guideline, use 0.5 for 4 pixels/mm (display resolution), 1.0 for 12 pixels/mm and 1.5 for 16 pixels/mm (300 dpi == 12 pixels/mm). These figures refer to the image raster, not the half-tone resolution. See also: vips_conv().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @ceil: round-up output dimensions Shrink @in by a pair of factors with a simple box filter. For non-integer factors, vips_shrink() will first shrink by the integer part with a box filter, then use vips_reduce() to shrink by the remaining fractional part. This is a very low-level operation: see vips_resize() for a more convenient way to resize images. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_resize(), vips_reduce().

0 on success, -1 on error

input image

output image horizontal shrink vertical shrink %NULL-terminated list of optional named arguments

Optional arguments: * @ceil: round-up output dimensions Shrink @in horizontally by an integer factor. Each pixel in the output is the average of the corresponding line of @hshrink pixels in the input. This is a very low-level operation: see vips_resize() for a more convenient way to resize images. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_shrinkv(), vips_shrink(), vips_resize(), vips_affine().

0 on success, -1 on error

input image

output image horizontal shrink %NULL-terminated list of optional named arguments

Optional arguments: * @ceil: round-up output dimensions Shrink @in vertically by an integer factor. Each pixel in the output is the average of the corresponding column of @vshrink pixels in the input. This is a very low-level operation: see vips_resize() for a more convenient way to resize images. This operation does not change xres or yres. The image resolution needs to be updated by the application. See also: vips_shrinkh(), vips_shrink(), vips_resize(), vips_affine().

0 on success, -1 on error

input image

output image vertical shrink %NULL-terminated list of optional named arguments

Finds the unit vector in the direction of the pixel value. For non-complex images, it returns a signed char image with values -1, 0, and 1 for negative, zero and positive pixels. For complex images, it returns a complex normalised to length 1. See also: vips_abs().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @scale: %gdouble, scale by this factor * @angle: %gdouble, rotate by this many degrees clockwise * @interpolate: #VipsInterpolate, interpolate pixels with this * @background: #VipsArrayDouble colour for new pixels * @idx: %gdouble, input horizontal offset * @idy: %gdouble, input vertical offset * @odx: %gdouble, output horizontal offset * @ody: %gdouble, output vertical offset This operator calls vips_affine() for you, calculating the matrix for the affine transform from @scale and @angle. Other parameters are passed on to vips_affine() unaltered. See also: vips_affine(), #VipsInterpolate.

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_SIN on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_SINH on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @interesting: #VipsInteresting to use to find interesting areas (default: #VIPS_INTERESTING_ATTENTION) * @premultiplied: %gboolean, input image already has premultiplied alpha * @attention_x: %gint, horizontal position of attention centre when using attention based cropping * @attention_y: %gint, vertical position of attention centre when using attention based cropping Crop an image down to a specified width and height by removing boring parts. Use @interesting to pick the method vips uses to decide which bits of the image should be kept. You can test xoffset / yoffset on @out to find the location of the crop within the input image. See also: vips_extract_area().

0 on success, -1 on error.

input image

output image width of area to extract height of area to extract %NULL-terminated list of optional named arguments

Sobel edge detector. uchar images are computed using a fast, low-precision path. Cast to float for a high-precision implementation. See also: vips_canny(), vips_sobel(), vips_prewitt(), vips_scharr().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Calculate a correlation surface. @ref is placed at every position in @in and the correlation coefficient calculated. The output image is always float. The output image is the same size as the input. Extra input edge pixels are made by copying the existing edges outwards. The correlation coefficient is calculated as: |[ sumij (ref(i,j)-mean(ref))(inkl(i,j)-mean(inkl)) c(k,l) = ------------------------------------------------ sqrt(sumij (ref(i,j)-mean(ref))^2) * sqrt(sumij (inkl(i,j)-mean(inkl))^2) ]| where inkl is the area of @in centred at position (k,l). from Niblack "An Introduction to Digital Image Processing", Prentice/Hall, pp 138. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The output image is always float, unless either of the two inputs is double, in which case the output is also double. See also: vips_fastcor().

0 on success, -1 on error

input image

reference image output image %NULL-terminated list of optional named arguments

Make a displayable (ie. 8-bit unsigned int) power spectrum. If @in is non-complex, it is transformed to Fourier space. Then the absolute value is passed through vips_scale() in log mode, and vips_wrap(). See also: vips_fwfft(), vips_scale(), vips_wrap().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Find many image statistics in a single pass through the data. @out is a one-band #VIPS_FORMAT_DOUBLE image of at least 10 columns by n + 1 (where n is number of bands in image @in) rows. Columns are statistics, and are, in order: minimum, maximum, sum, sum of squares, mean, standard deviation, x coordinate of minimum, y coordinate of minimum, x coordinate of maximum, y coordinate of maximum. Later versions of vips_stats() may add more columns. Row 0 has statistics for all bands together, row 1 has stats for band 1, and so on. If there is more than one maxima or minima, one of them will be chosen at random. See also: vips_avg(), vips_min().

0 on success, -1 on error

image to scan

image of statistics %NULL-terminated list of optional named arguments

Optional arguments: * @a: weight of new mean * @m0: target mean * @b: weight of new deviation * @s0: target deviation vips_stdif() performs statistical differencing according to the formula given in page 45 of the book "An Introduction to Digital Image Processing" by Wayne Niblack. This transformation emphasises the way in which a pel differs statistically from its neighbours. It is useful for enhancing low-contrast images with lots of detail, such as X-ray plates. At point (i,j) the output is given by the equation: |[ vout(i,j) = @a * @m0 + (1 - @a) * meanv + (vin(i,j) - meanv) * (@b * @s0) / (@s0 + @b * stdv) ]| Values @a, @m0, @b and @s0 are entered, while meanv and stdv are the values calculated over a moving window of size @width, @height centred on pixel (i,j). @m0 is the new mean, @a is the weight given to it. @s0 is the new standard deviation, @b is the weight given to it. Try: |[ vips stdif $VIPSHOME/pics/huysum.v fred.v 0.5 128 0.5 50 11 11 ]| The operation works on one-band uchar images only, and writes a one-band uchar image as its result. The output image has the same size as the input. See also: vips_hist_local().

0 on success, -1 on error

input image

output image width of region height of region %NULL-terminated list of optional named arguments

Optional arguments: * @point: turn on point sample mode Subsample an image by an integer fraction. This is fast, nearest-neighbour shrink. For small horizontal shrinks, this operation will fetch lines of pixels from @in and then subsample that line. For large shrinks it will fetch single pixels. If @point is set, @in will always be sampled in points. This can be faster if the previous operations in the pipeline are very slow. See also: vips_affine(), vips_shrink(), vips_zoom().

0 on success, -1 on error.

input image

output image horizontal shrink factor vertical shrink factor %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_TAN on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH_TANH on an image. See vips_math().

0 on success, -1 on error

input #VipsImage

output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @height: %gint, target height in pixels * @size: #VipsSize, upsize, downsize, both or force * @no_rotate: %gboolean, don't rotate upright using orientation tag * @crop: #VipsInteresting, shrink and crop to fill target * @linear: %gboolean, perform shrink in linear light * @import_profile: %gchararray, fallback import ICC profile * @export_profile: %gchararray, export ICC profile * @intent: #VipsIntent, rendering intent * @fail_on: #VipsFailOn, load error types to fail on Exactly as vips_thumbnail(), but read from an existing image. This operation is not able to exploit shrink-on-load features of image load libraries, so it can be much slower than `vips_thumbnail()` and produce poorer quality output. Only use it if you really have to. See also: vips_thumbnail().

0 on success, -1 on error.

input image

output image target width in pixels %NULL-terminated list of optional named arguments

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 or Deflate (zlib) 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 (1-22) or Deflate (1-9) 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().

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Optional arguments: * @tile_width: width of tiles in cache * @tile_height: height of tiles in cache * @max_tiles: maximum number of tiles to cache * @access: hint expected access pattern #VipsAccess * @threaded: allow many threads * @persistent: don't drop cache at end of computation This operation behaves rather like vips_copy() between images @in and @out, except that it keeps a cache of computed pixels. This cache is made of up to @max_tiles tiles (a value of -1 means any number of tiles), and each tile is of size @tile_width by @tile_height pixels. Each cache tile is made with a single call to vips_region_prepare(). When the cache fills, a tile is chosen for reuse. If @access is #VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If @access is #VIPS_ACCESS_SEQUENTIAL the top-most tile is reused. By default, @tile_width and @tile_height are 128 pixels, and the operation will cache up to 1,000 tiles. @access defaults to #VIPS_ACCESS_RANDOM. Normally, only a single thread at once is allowed to calculate tiles. If you set @threaded to %TRUE, vips_tilecache() will allow many threads to calculate tiles at once, and share the cache between them. Normally the cache is dropped when computation finishes. Set @persistent to %TRUE to keep the cache between computations. See also: vips_cache(), vips_linecache().

0 on success, -1 on error.

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @page_height: %gint, size of each input page Transpose a volumetric image. Volumetric images are very tall, thin images, with the metadata item #VIPS_META_PAGE_HEIGHT set to the height of each sub-image. This operation swaps the two major dimensions, so that page N in the output contains the Nth scanline, in order, from each input page. You can override the #VIPS_META_PAGE_HEIGHT metadata item with the optional @page_height parameter. #VIPS_META_PAGE_HEIGHT in the output image is the number of pages in the input image. See also: vips_grid().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Optional arguments: * @max_alpha: %gdouble, maximum value for alpha * @alpha_band: %gint, band containing alpha data Unpremultiplies any alpha channel. Band @alpha_band (by default the final band) contains the alpha and all other bands are transformed as: |[ alpha = (int) clip(0, in[in.bands - 1], @max_alpha); norm = (double) alpha / @max_alpha; if (alpha == 0) out = [0, ..., 0, alpha]; else out = [in[0] / norm, ..., in[in.bands - 1] / norm, alpha]; ]| So for an N-band image, the first N - 1 bands are divided by the clipped and normalised final band, the final band is clipped. If there is only a single band, the image is passed through unaltered. The result is #VIPS_FORMAT_FLOAT unless the input format is #VIPS_FORMAT_DOUBLE, in which case the output is double as well. @max_alpha has the default value 255, or 65535 for images tagged as #VIPS_INTERPRETATION_RGB16 or #VIPS_INTERPRETATION_GREY16. Non-complex images only. See also: vips_premultiply(), vips_flatten().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Write @in to @filename in VIPS format. See also: vips_vipsload().

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

As vips_vipssave(), but save to a target.

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

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 * @smart_deblock: %gboolean, enables auto-adjusting of the deblocking filter * @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 * @target_size: %gint, desired target size in bytes * @passes: %gint, number of entropy-analysis passes * @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. Set @smart_deblock to enable auto-adjusting of the deblocking filter. This can improve image quality, especially on low-contrast edges, but encoding can take significantly longer. 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. Use @target_size to set the desired target size in bytes. Use @passes to set the number of entropy-analysis passes, by default 1, unless @target_size is set, in which case the default is 3. It is not recommended to set @passes unless you set @target_size. Doing so will result in longer encoding times for no benefit. 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().

0 on success, -1 on error.

image to save

file to write to %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

return output buffer here return output length here %NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

%NULL-terminated list of optional named arguments

0 on success, -1 on error.

image to save

save image to this target %NULL-terminated list of optional named arguments

Check that an image is readable via the VIPS_IMAGE_ADDR() macro, that is, that the entire image is in memory and all pixels can be read with VIPS_IMAGE_ADDR(). If it isn't, try to transform it so that VIPS_IMAGE_ADDR() can work. Since this function modifies @image, it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. If the image might have been shared, use the less efficient vips_image_copy_memory() instead. See also: vips_image_copy_memory(), vips_image_pio_input(), vips_image_inplace(), VIPS_IMAGE_ADDR().

0 on success, or -1 on error.

image to transform

Perform #VIPS_OPERATION_MATH2_WOP on an image and a constant. See vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage array of constants number of constants in @c %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_WOP on an image and a constant. See vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage

output #VipsImage constant %NULL-terminated list of optional named arguments

Optional arguments: * @x: horizontal displacement * @y: vertical displacement Slice an image up and move the segments about so that the pixel that was at 0, 0 is now at @x, @y. If @x and @y are not set, they default to the centre of the image. See also: vips_embed(), vips_replicate().

0 on success, -1 on error

input image

output image %NULL-terminated list of optional named arguments

Write @image to @out. Use vips_image_new() and friends to create the #VipsImage you want to write to. See also: vips_image_new(), vips_copy(), vips_image_write_to_file().

0 on success, or -1 on error.

image to write

write to this image

Write a line of pixels to an image. This function must be called repeatedly with @ypos increasing from 0 to #VipsImage::height . @linebuffer must be VIPS_IMAGE_SIZEOF_LINE() bytes long. See also: vips_image_generate().

0 on success, or -1 on error.

image to write to

vertical position of scan-line to write scanline of pixels

Call this after setting header fields (width, height, and so on) to allocate resources ready for writing. Normally this function is called for you by vips_image_generate() or vips_image_write_line(). You will need to call it yourself if you plan to write directly to the ->data member of a memory image.

0 on success, or -1 on error.

image to prepare

Writes @in to a memory buffer in a format specified by @suffix. Save options may be appended to @suffix as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. Currently only TIFF, JPEG and PNG formats are supported. You can call the various save operations directly if you wish, see vips_jpegsave_buffer(), for example. See also: vips_image_write_to_memory(), vips_image_new_from_buffer().

0 on success, -1 on error

image to write

format to write return buffer start here return buffer length here %NULL-terminated list of optional named arguments

Writes @in to @name using the saver recommended by vips_foreign_find_save(). Save options may be appended to @filename as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. See also: vips_image_new_from_file().

0 on success, or -1 on error.

image to write

write to this file %NULL-terminated list of optional named arguments

Writes @in to memory as a simple, unformatted C-style array. The caller is responsible for freeing this memory with g_free(). See also: vips_image_write_to_buffer().

return buffer start here

image to write

return buffer length here

Writes @in to @output in format @suffix. Save options may be appended to @suffix as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. You can call the various save operations directly if you wish, see vips_jpegsave_target(), for example. See also: vips_image_write_to_file().

0 on success, -1 on error

image to write

format to write target to write to %NULL-terminated list of optional named arguments

Zoom an image by repeating pixels. This is fast nearest-neighbour zoom. See also: vips_affine(), vips_subsample().

0 on success, -1 on error.

input image

output image horizontal scale factor vertical scale factor %NULL-terminated list of optional named arguments

The ::eval signal is emitted once per work unit (typically a 128 x 128 area of pixels) during image computation. You can use this signal to update user-interfaces with progress feedback. Beware of updating too frequently: you will usually need some throttling mechanism. Use vips_image_set_progress() to turn on progress reporting for an image.

#VipsProgress for this image The ::invalidate signal is emitted when an image or one of it's upstream data sources has been destructively modified. See vips_image_invalidate_all().

The ::minimise signal is emitted when an image has been asked to minimise memory usage. All non-essential caches are dropped. See vips_image_minimise_all().

The ::posteval signal is emitted once at the end of the computation of @image. It's a good place to shut down evaluation feedback. Use vips_image_set_progress() to turn on progress reporting for an image.

#VipsProgress for this image The ::preeval signal is emitted once before computation of @image starts. It's a good place to set up evaluation feedback. Use vips_image_set_progress() to turn on progress reporting for an image.

#VipsProgress for this image The ::written signal is emitted just after an image has been written to. It is used by vips to implement things like write to foreign file formats.

set to non-zero to indicate error

The rendering intent. #VIPS_INTENT_ABSOLUTE is best for scientific work, #VIPS_INTENT_RELATIVE is usually best for accurate communication with other imaging libraries. perceptual rendering intent relative colorimetric rendering intent saturation rendering intent absolute colorimetric rendering intent Pick the algorithm vips uses to decide image "interestingness". This is used by vips_smartcrop(), for example, to decide what parts of the image to keep. #VIPS_INTERESTING_NONE and #VIPS_INTERESTING_LOW mean the same -- the crop is positioned at the top or left. #VIPS_INTERESTING_HIGH positions at the bottom or right. See also: vips_smartcrop(). do nothing just take the centre use an entropy measure look for features likely to draw human attention position the crop towards the low coordinate position the crop towards the high coordinate everything is interesting

Look up an interpolator from a nickname and make one. You need to free the result with g_object_unref() when you're done with it. See also: vips_type_find().

an interpolator, or %NULL on error.

nickname for interpolator

A convenience function that returns a bilinear interpolator you don't need to free.

a bilinear interpolator

A convenience function that returns a nearest-neighbour interpolator you don't need to free.

a nearest-neighbour interpolator

Look up an interpolators desired window offset.

the interpolators required window offset

interpolator to use

Look up an interpolators desired window size.

the interpolators required window size

interpolator to use

the interpolation method

the interpolator

write the interpolated pixel here read source pixels from here interpolate value at this position interpolate value at this position

Look up the @interpolate method in the class and call it. Use vips_interpolate_get_method() to get a direct pointer to the function and avoid the lookup overhead. You need to set @in and @out up correctly.

interpolator to use

write result here read source data from here interpolate value at this position interpolate value at this position

Look up the @interpolate method in the class and return it. Use this instead of vips_interpolate() to cache method dispatch.

a pointer to the interpolation function

interpolator to use

Look up an interpolators desired window offset.

the interpolators required window offset

interpolator to use

Look up an interpolators desired window size.

the interpolators required window size

interpolator to use

The abstract base class for the various VIPS interpolation functions. Use "vips --list classes" to see all the interpolators available. An interpolator consists of a function to perform the interpolation, plus some extra data fields which tell vips how to call the function and what data it needs. @window_size is the size of the window that the interpolator needs. For example, a bicubic interpolator needs to see a window of 4x4 pixels to be able to interpolate a value. You can either have a function in @get_window_size which returns the window that a specific interpolator needs, or you can leave @get_window_size %NULL and set a constant value in @window_size. @window_offset is how much to offset the window up and left of (x, y). For example, a bicubic interpolator will want a @window_offset of 1. You can either have a function in @get_window_offset which returns the offset that a specific interpolator needs, or you can leave @get_window_offset %NULL and set a constant value in @window_offset. You also need to set @nickname and @description in #VipsObject. See also: #VipsInterpolateMethod, #VipsObject, vips_interpolate_bilinear_static().

the interpolation method return the size of the window needed by this method

the interpolators required window size

interpolator to use

or just set this for a constant window size return the window offset for this method

the interpolators required window offset

interpolator to use

or just set this for a constant window offset

An interpolation function. It should read source pixels from @in with VIPS_REGION_ADDR(), it can look left and up from (x, y) by @window_offset pixels and it can access pixels in a window of size @window_size. The interpolated value should be written to the pixel pointed to by @out. See also: #VipsInterpolateClass.

the interpolator write the interpolated pixel here read source pixels from here interpolate value at this position interpolate value at this position

How the values in an image should be interpreted. For example, a three-band float image of type #VIPS_INTERPRETATION_LAB should have its pixels interpreted as coordinates in CIE Lab space. RGB and sRGB are treated in the same way. Use the colourspace functions if you want some other behaviour. The gaps in numbering are historical and must be maintained. Allocate new numbers from the end. generic many-band image some kind of single-band image a 1D image, eg. histogram or lookup table the first three bands are CIE XYZ pixels are in CIE Lab space the first four bands are in CMYK space implies #VIPS_CODING_LABQ generic RGB space a uniform colourspace based on CMC(1:1) pixels are in CIE LCh space CIE LAB coded as three signed 16-bit values pixels are sRGB pixels are CIE Yxy image is in fourier space generic 16-bit RGB generic 16-bit mono a matrix pixels are scRGB pixels are HSV

the maximum alpha value for an interpretation.

image interpretation

The resampling kernels vips supports. See vips_reduce(), for example. The nearest pixel to the point. Convolve with a triangle filter. Convolve with a cubic filter. Convolve with a Mitchell kernel. Convolve with a two-lobe Lanczos kernel. Convolve with a three-lobe Lanczos kernel.

The first four bytes of a VIPS file in Intel byte ordering.

The first four bytes of a VIPS file in SPARC byte ordering.

This macro returns a pointer to a pixel in an image, cast to a double*. The image must have a single band, be #VIPS_FORMAT_DOUBLE and be fully available in memory, so memory buffers and small mapped images only. If VIPS_DEBUG is defined, you get a version that checks bounds and image type for you. See also: vips_image_wio_input(), vips_image_inplace(), vips_check_matrix().

a #VipsImage x coordinate y coordinate

The bits per sample for each channel.

If set, the suggested concurrency for this image.

The name that read and write operations use for the image's EXIF data.

The name we use to attach an ICC profile. The file read and write operations for TIFF, JPEG, PNG and others use this item of metadata to attach and save ICC profiles. The profile is updated by the vips_icc_transform() operations.

The IMAGEDESCRIPTION tag. Often has useful metadata.

The name that read and write operations use for the image's IPTC data.

Record the name of the original loader here. Handy for hinting file formats and for debugging.

If set, the number of pages in the original file.

If set, the number of subifds in the first page of the file.

The orientation tag for this image. An int from 1 - 8 using the standard exif/tiff meanings. * 1 - The 0th row represents the visual top of the image, and the 0th column represents the visual left-hand side. * 2 - The 0th row represents the visual top of the image, and the 0th column represents the visual right-hand side. * 3 - The 0th row represents the visual bottom of the image, and the 0th column represents the visual right-hand side. * 4 - The 0th row represents the visual bottom of the image, and the 0th column represents the visual left-hand side. * 5 - The 0th row represents the visual left-hand side of the image, and the 0th column represents the visual top. * 6 - The 0th row represents the visual right-hand side of the image, and the 0th column represents the visual top. * 7 - The 0th row represents the visual right-hand side of the image, and the 0th column represents the visual bottom. * 8 - The 0th row represents the visual left-hand side of the image, and the 0th column represents the visual bottom.

If set, the height of each page when this image was loaded. If you save an image with "page-height" set to a format that supports multiple pages, such as tiff, the image will be saved as a series of pages.

Does this image have a palette?

The name that TIFF read and write operations use for the image's TIFFTAG_PHOTOSHOP data.

The JPEG and TIFF read and write operations use this to record the file's preferred unit for resolution.

Images loaded via vips_sequential() have this int field defined. Some operations (eg. vips_shrinkv()) add extra caches if they see it on their input.

The name that read and write operations use for the image's XMP data.

Allocate memory for a thing of type @T. The memory is not cleared. This macro cannot fail. See vips_tracked_malloc() if you are allocating large amounts of memory. See also: vips_malloc().

allocate memory local to @OBJ, or %NULL for no auto-free type of thing to allocate

g_object_new() the object, set any arguments with @set, call vips_object_build() and return the complete object.

the new object

object to create set arguments with this client data client data

Call a function for all alive objects. Stop when @fn returns non-%NULL and return that value.

%NULL if @fn returns %NULL for all arguments, otherwise the first non-%NULL value from @fn.

function to call for all objects client data client data

Generate a human-readable summary for a class.

class to summarise write summary here

Dump everything that vips knows about an object to a string.

object to dump

write dump here

Generate a human-readable summary for an object.

object to summarise

write summary here

The inverse of vips_object_new_from_string(): turn @object into eg. "VipsInterpolateSnohalo1(blur=.333333)".

object to stringify

write string here

Convenience: has an argument been assigned. Useful for bindings.

%TRUE if the argument has been assigned.

the object to fetch the args from

arg to fetch

Dump everything that vips knows about an object to a string.

object to dump

write dump here

Get all %GParamSpec names and #VipsArgumentFlags for an object. This is handy for language bindings. From C, it's usually more convenient to use vips_argument_map().

0 on success, -1 on error

object whose args should be retrieved

output array of %GParamSpec names output array of #VipsArgumentFlags length of output arrays

Look up the three things you need to work with a vips argument.

0 on success, or -1 on error.

the object to fetch the args from

arg to fetch the pspec for this arg the argument_class for this arg the argument_instance for this arg

Convenience: get the flags for an argument. Useful for bindings.

The #VipsArgumentFlags for this argument.

the object to fetch the args from

arg to fetch

Convenience: get the priority for an argument. Useful for bindings.

The priority of this argument.

the object to fetch the args from

arg to fetch

Fetch the object description. Useful for language bindings. @object.description is only available after _build(), which can be too late. This function fetches from the instance, if possible, but falls back to the class description if we are too early.

the object description

object to fetch description from

Make an array of NULL VipsObject pointers. When @parent closes, every non-NULL pointer in the array will be unreffed and the array will be freed. Handy for creating a set of temporary images for a function. The array is NULL-terminated, ie. contains an extra NULL element at the end. Example: |[ VipsObject **t; t = vips_object_local_array(parent, 5); if (vips_add(a, b, &t[0], NULL) || vips_invert(t[0], &t[1], NULL) || vips_add(t[1], t[0], &t[2], NULL) || vips_costra(t[2], out, NULL)) return -1; ]| See also: vips_object_local().

an array of NULL pointers of length @n

objects unref when this object unrefs

array size

Set a list of vips object arguments. For example: |[ vips_object_set(operation, "input", in, "output", &out, NULL); ]| Input arguments are given in-line, output arguments are given as pointers to where the output value should be written. See also: vips_object_set_valist(), vips_object_set_from_string().

0 on success, -1 on error

object to set arguments on

%NULL-terminated list of argument/value pairs

Set object arguments from a string. The string can be something like "a=12", or "a = 12, b = 13", or "fred". The string can optionally be enclosed in brackets. You'd typically use this between creating the object and building it. See also: vips_object_set(), vips_object_build(), vips_cache_operation_buildp().

0 on success, -1 on error

object to set arguments on

arguments as a string

See vips_object_set().

0 on success, -1 on error

object to set arguments on

%NULL-terminated list of argument/value pairs

Generate a human-readable summary for an object.

object to summarise

write summary here

The inverse of vips_object_new_from_string(): turn @object into eg. "VipsInterpolateSnohalo1(blur=.333333)".

object to stringify

write string here

Unref all assigned output objects. Useful for language bindings. After an object is built, all output args are owned by the caller. If something goes wrong before then, we have to unref the outputs that have been made so far. This function can also be useful for callers when they've finished processing outputs themselves. See also: vips_cache_operation_build().

object to drop output refs from

The ::close signal is emitted once during object close. The object is dying and may not work.

The ::postbuild signal is emitted once just after successful object construction. Return non-zero to cause object construction to fail.

The ::postclose signal is emitted once after object close. The object pointer is still valid, but nothing else.

The ::preclose signal is emitted once just before object close starts. The object is still alive.

object to summarise write summary here

object to dump write dump here

object to stringify write string here

Return a new #VipsOperation with the specified nickname. Useful for language bindings. You'll need to set any arguments and build the operation before you can use it. See vips_call() for a higher-level way to make new operations.

the new operation.

nickname of operation to create

Set the block state on all operations in the libvips class hierarchy at @name and below. For example: |[ vips_operation_block_set("VipsForeignLoad", TRUE); vips_operation_block_set("VipsForeignLoadJpeg", FALSE); ]| Will block all load operations, except JPEG. Use `vips -l` at the command-line to see the class hierarchy. This call does nothing if the named operation is not found. See also: vips_block_untrusted_set().

set block state at this point and below the block state to set

Returns the set of flags for this operation.

0 on success, or -1 on error.

operation to fetch flags from

Returns the set of flags for this operation.

0 on success, or -1 on error.

operation to fetch flags from

See also: vips_boolean(). & | ^ >> <<

0 on success, or -1 on error.

operation to fetch flags from

Print a usage message for the operation to stdout.

class to print usage for

See also: vips_complex(). convert to polar coordinates convert to rectangular coordinates complex conjugate See also: vips_complex2(). convert to polar coordinates See also: vips_complexget(). get real component get imaginary component Flags we associate with an operation. @VIPS_OPERATION_SEQUENTIAL means that the operation works like vips_conv(): it can process images top-to-bottom with only small non-local references. Every scan-line must be requested, you are not allowed to skip ahead, but as a special case, the very first request can be for a region not at the top of the image. In this case, the first part of the image will be read and discarded Every scan-line must be requested, you are not allowed to skip ahead, but as a special case, the very first request can be for a region not at the top of the image. In this case, the first part of the image will be read and discarded @VIPS_OPERATION_NOCACHE means that the operation must not be cached by vips. @VIPS_OPERATION_DEPRECATED means this is an old operation kept in vips for compatibility only and should be hidden from users. @VIPS_OPERATION_UNTRUSTED means the operation depends on external libraries which have not been hardened against attack. It should probably not be used on untrusted input. Use vips_block_untrusted_set() to block all untrusted operations. @VIPS_OPERATION_BLOCKED means the operation is prevented from executing. Use vips_operation_block_set() to enable and disable groups of operations. @VIPS_OPERATION_REVALIDATE force the operation to run, updating the cache with the new value. This is used by eg. VipsForeignLoad to implement the "revalidate" argument. no flags can work sequentially with a small buffer must not be cached a compatibility thing not hardened for untrusted input prevent this operation from running force the operation to run See also: vips_math(). sin(), angles in degrees cos(), angles in degrees tan(), angles in degrees asin(), angles in degrees acos(), angles in degrees atan(), angles in degrees log base e log base 10 e to the something 10 to the something sinh(), angles in radians cosh(), angles in radians tanh(), angles in radians asinh(), angles in radians acosh(), angles in radians atanh(), angles in radians See also: vips_math(). pow(left, right) pow(right, left) atan2(left, right) More like hit-miss, really. See also: vips_morph(). true if all set true if one set See also: vips_relational(). == != < <= > >= See also: vips_round(). round to nearest the smallest integral value not less than largest integral value not greater than Pick a Profile Connection Space for vips_icc_import() and vips_icc_export(). LAB is usually best, XYZ can be more convenient in some cases. use CIELAB D65 as the Profile Connection Space use XYZ as the Profile Connection Space How accurate an operation should be. int everywhere float everywhere approximate integer output A structure available to eval callbacks giving information on evaluation progress. See #VipsImage::eval.

Time we have been running Estimated seconds of computation left Number of pels we expect to calculate Number of pels calculated so far Percent complete Start time If set, vips will print messages about the progress of computation to stdout. This can also be enabled with the --vips-progress option, or by setting the environment variable VIPS_PROGRESS.

%TRUE to enable progress messages

This macro returns a pointer to a pixel in a region. The (@X, @Y) coordinates need to be within the #VipsRect (@R->valid). If DEBUG is defined, you get a version that checks bounds for you. See also: vips_region_prepare().

a #VipsRegion x coordinate y coordinate

This macro returns a pointer to the top-left pixel in the #VipsRegion, that is, the pixel at (@R->valid.left, @R->valid.top). See also: vips_region_prepare().

a #VipsRegion

A #VipsRect is a rectangular area of pixels. This is a struct for performing simple rectangle algebra.

left edge of rectangle top edge of rectangle width of rectangle height of rectangle Duplicate a rect to the heap. You need to free the result with g_free().

a pointer to copy of @r allocated on the heap.

rectangle to duplicate

Is @r1 equal to @r2?

%TRUE if @r1 is equal to @r2.

first rectangle

second rectangle

Does @r contain point (@x, @y)?

%TRUE if @r contains (@x, @y).

rectangle to test

position to test for position to test for

Is @r2 a subset of @r1?

%TRUE if @r2 is a subset of @r1.

outer rectangle

inner rectangle

Fill @out with the intersection of @r1 and @r2. @out can equal @r1 or @r2.

input rectangle 1

input rectangle 2 output rectangle

Is @r empty? ie. zero width or height.

%TRUE if @r contains no pixels.

rectangle to test

Enlarge @r by @n. +1 means out one pixel.

rectangle to adjust

enlarge by

Make sure width and height are >0 by moving the origin and flipping the rect.

rect to normalise

Do @r1 and @r2 have a non-empty intersection?

%TRUE if @r2 and @r1 overlap.

first rectangle

second rectangle

Fill @out with the bounding box of @r1 and @r2. @out can equal @r1 or @r2.

input rectangle 1

input rectangle 2 output rectangle

Create a new refstring. These are reference-counted immutable strings, used to store string data in vips image metadata. Strings must be valid utf-8; use blob for binary data. See also: vips_area_unref().

the new #VipsRefString, or NULL on error.

string to store

Get a pointer to the private string inside a refstr. Handy for language bindings. See also: vips_value_get_ref_string().

The C string held by @refstr.

the #VipsRefString to fetch from

return length here, optionally

A small part of a #VipsImage. @valid holds the left/top/width/height of the area of pixels that are available from the region. See also: VIPS_REGION_ADDR(), vips_region_new(), vips_region_prepare().

Create a region. #VipsRegion s start out empty, you need to call vips_region_prepare() to fill them with pixels. See also: vips_region_prepare().

image to create this region on

Paints 0 into the valid part of @reg. See also: vips_region_paint().

region to operate upon

The region is transformed so that at least @r pixels are available as a memory buffer that can be written to.

0 on success, or -1 for error.

region to operate upon

#VipsRect of pixels you need to be able to address

Copy from one region to another. Copy area @r from inside @reg to @dest, positioning the area of pixels at @x, @y. The two regions must have pixels which are the same size. See also: vips_region_paint().

source region

destination region #VipsRect of pixels you need to copy position of @r in @dest position of @r in @dest

Do two regions point to the same piece of image? ie. |[ VIPS_REGION_ADDR(reg1, x, y) == VIPS_REGION_ADDR(reg2, x, y) && *VIPS_REGION_ADDR(reg1, x, y) == *VIPS_REGION_ADDR(reg2, x, y) for all x, y, reg1, reg2. ]|

non-zero on equality.

region to test

Generate an area of pixels and return a copy. The result must be freed with g_free(). The requested area must be completely inside the image. This is equivalent to vips_region_prepare(), followed by a memcpy. It is convenient for language bindings.

A copy of the pixel data.

region to fetch pixels from

area of pixels to fetch area of pixels to fetch area of pixels to fetch area of pixels to fetch

Height of the pixels held in region.

fetch height from this

The region is transformed so that at least @r pixels are available to be read from the image. The image needs to be a memory buffer or represent a file on disc that has been mapped or can be mapped.

0 on success, or -1 for error.

region to operate upon

#VipsRect of pixels you need to be able to address

Mark a region as containing invalid pixels. Calling this function means that the next time vips_region_prepare() is called, the region will be recalculated. This is faster than calling vips_image_invalidate_all(), but obviously only affects a single region. See also: vips_image_invalidate_all(), vips_region_prepare().

region to invalidate

Paints @value into @reg covering rectangle @r. @r is clipped against @reg->valid. For int images, @value is passed to memset(), so it usually needs to be 0 or 255. For float images, value is cast to a float and copied in to each band element. @r is clipped against @reg->valid. See also: vips_region_black().

region to operate upon

area to paint value to paint

Paints @ink into @reg covering rectangle @r. @r is clipped against @reg->valid. @ink should be a byte array of the same size as an image pixel containing the binary value to write into the pixels. See also: vips_region_paint().

region to operate upon

area to paint value to paint

Set the position of a region. This only affects reg->valid, ie. the way pixels are addressed, not reg->data, the pixels which are addressed. Clip against the size of the image. Do not allow negative positions, or positions outside the image.

0 on success, or -1 for error.

region to operate upon

position to move to position to move to

vips_region_prepare() fills @reg with pixels. After calling, you can address at least the area @r with VIPS_REGION_ADDR() and get valid pixels. vips_region_prepare() runs in-line, that is, computation is done by the calling thread, no new threads are involved, and computation blocks until the pixels are ready. Use vips_sink_screen() to calculate an area of pixels in the background. See also: vips_sink_screen(), vips_region_prepare_to().

0 on success, or -1 on error.

region to prepare

#VipsRect of pixels you need to be able to address

Like vips_region_prepare(): fill @reg with the pixels in area @r. Unlike vips_region_prepare(), rather than writing the result to @reg, the pixels are written into @dest at offset @x, @y. Also unlike vips_region_prepare(), @dest is not set up for writing for you with vips_region_buffer(). You can point @dest at anything, and pixels really will be written there. This makes vips_region_prepare_to() useful for making the ends of pipelines. See also: vips_region_prepare(), vips_sink_disc().

0 on success, or -1 on error

region to prepare

region to write to #VipsRect of pixels you need to be able to address position of @r in @dest position of @r in @dest

Make VIPS_REGION_ADDR() on @reg go to @dest instead. @r is the part of @reg which you want to be able to address (this effectively becomes the valid field), (@x, @y) is the top LH corner of the corresponding area in @dest. Performs all clipping necessary to ensure that @reg->valid is indeed valid. If the region we attach to is moved or destroyed, we can be left with dangling pointers! If the region we attach to is on another image, the two images must have the same sizeof(pel).

0 on success, or -1 for error.

region to operate upon

region to connect to #VipsRect of pixels you need to be able to address position of @r in @dest position of @r in @dest

Write the pixels @target in @to from the x2 larger area in @from. Non-complex uncoded images and LABQ only. Images with alpha (see vips_image_hasalpha()) shrink with pixels scaled by alpha to avoid fringing. This is a compatibility stub that just calls vips_region_shrink_method(). See also: vips_region_shrink_method().

source region

destination region #VipsRect of pixels you need to copy

Write the pixels @target in @to from the x2 larger area in @from. Non-complex uncoded images and LABQ only. Images with alpha (see vips_image_hasalpha()) shrink with pixels scaled by alpha to avoid fringing. @method selects the method used to do the 2x2 shrink. See also: vips_region_copy().

source region

destination region #VipsRect of pixels you need to copy method to use when generating target pixels

Width of the pixels held in region.

fetch width from this

the #VipsImage that this region is defined on the #VipsRect of pixels that this region represents

How to calculate the output pixels when shrinking a 2x2 region. use the average use the median use the mode use the maximum use the minimum use the top-left pixel

See also: #VipsForeignSave. 1 band (eg. CSV) 1 or 3 bands (eg. PPM) 1, 2, 3 or 4 bands (eg. PNG) 3 or 4 bands (eg. WEBP) 1, 3 or 4 bands (eg. JPEG) any number of bands (eg. TIFF) The SDF to generate, See also: vips_sdf(). a circle at @a, radius @r a box from @a to @b a box with rounded @corners from @a to @b a line from @a to @b Controls whether an operation should upsize, downsize, both up and downsize, or force a size. See also: vips_thumbnail(). size both up and down only upsize only downsize force size, that is, break aspect ratio

Start a new processing sequence for this generate function. This allocates per-thread state, such as an input region. See also: vips_start_one(), vips_start_many().

a new sequence value

image being calculated user data user data

Stop a processing sequence. This frees per-thread state, such as an input region. See also: vips_stop_one(), vips_stop_many().

0 on success, -1 on error.

sequence value user data user data

#VIPS_TRANSFORM_SHIFT as a multiplicative constant.

Many of the vips interpolators use fixed-point arithmetic for coordinate calculation. This is how many bits of precision they use.

Sets the word wrapping style for vips_text() when used with a maximum width. See also: vips_text(). wrap at word boundaries wrap at character boundaries wrap at word boundaries, but fall back to character boundaries if there is not enough space for a full word no wrapping

a new #VipsThing.

This operation calculates @in1 + @in2 and writes the result to @out. If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), then the following table is used to determine the output type: <table> <title>VipsAdd type promotion</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>input type</entry> <entry>output type</entry> </row> </thead> <tbody> <row> <entry>uchar</entry> <entry>ushort</entry> </row> <row> <entry>char</entry> <entry>short</entry> </row> <row> <entry>ushort</entry> <entry>uint</entry> </row> <row> <entry>short</entry> <entry>int</entry> </row> <row> <entry>uint</entry> <entry>uint</entry> </row> <row> <entry>int</entry> <entry>int</entry> </row> <row> <entry>float</entry> <entry>float</entry> </row> <row> <entry>double</entry> <entry>double</entry> </row> <row> <entry>complex</entry> <entry>complex</entry> </row> <row> <entry>double complex</entry> <entry>double complex</entry> </row> </tbody> </tgroup> </table> In other words, the output type is just large enough to hold the whole range of possible values. See also: vips_subtract(), vips_linear().

0 on success, -1 on error

input image input image output image %NULL-terminated list of optional named arguments

Add the standard vips %GOptionEntry to a %GOptionGroup. See also: g_option_group_new().

group to add to

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_AND on a pair of images. See vips_boolean().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

And loop over a class. Same as ^^, but with no VipsArgumentInstance.

Allocate a new property id. See g_object_class_install_property().

a new property id > 0

Loop over the vips_arguments to an object. Stop when @fn returns non-%NULL and return that value.

%NULL if @fn returns %NULL for all arguments, otherwise the first non-%NULL value from @fn.

object whose args should be enumerated call this function for every argument client data client data

These operations perform pixel arithmetic, that is, they perform an arithmetic operation, such as addition, on every pixel in an image or a pair of images. All (except in a few cases noted below) will work with images of any type or any mixture of types, of any size and of any number of bands. For binary operations, if the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. In the same way, for operations that take an array constant, such as vips_remainder_const(), you can mix single-element arrays or single-band images freely. Arithmetic operations try to preserve precision by increasing the number of bits in the output image when necessary. Generally, this follows the ANSI C conventions for type promotion, so multiplying two #VIPS_FORMAT_UCHAR images together, for example, produces a #VIPS_FORMAT_USHORT image, and taking the vips_cos() of a #VIPS_FORMAT_USHORT image produces #VIPS_FORMAT_FLOAT image. After processing, use vips_cast() and friends to take then format back down again. vips_cast_uchar(), for example, will cast any image down to 8-bit unsigned. Images have an *interpretation*: a meaning for the pixel values. With #VIPS_INTERPRETATION_sRGB, for example, the first three bands will be interpreted (for example, by a saver like vips_jpegsave()) as R, G and B, with values in 0 - 255, and any fourth band will be interpreted as an alpha channel. After arithmetic, you may wish to change the interpretation (for example to save as 16-bit PNG). Use vips_copy() to change the interpretation without changing pixels. For binary arithmetic operations, type promotion occurs in two stages. First, the two input images are cast up to the smallest common format, that is, the type with the smallest range that can represent the full range of both inputs. This conversion can be represented as a table: <table> <title>Smallest common format</title> <tgroup cols='10' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>@in2/@in1</entry> <entry>uchar</entry> <entry>char</entry> <entry>ushort</entry> <entry>short</entry> <entry>uint</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> </thead> <tbody> <row> <entry>uchar</entry> <entry>ushort</entry> <entry>short</entry> <entry>ushort</entry> <entry>short</entry> <entry>uint</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>char</entry> <entry>short</entry> <entry>short</entry> <entry>short</entry> <entry>short</entry> <entry>int</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>ushort</entry> <entry>ushort</entry> <entry>short</entry> <entry>ushort</entry> <entry>short</entry> <entry>uint</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>short</entry> <entry>short</entry> <entry>short</entry> <entry>short</entry> <entry>short</entry> <entry>int</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>uint</entry> <entry>uint</entry> <entry>int</entry> <entry>uint</entry> <entry>int</entry> <entry>uint</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>int</entry> <entry>int</entry> <entry>int</entry> <entry>int</entry> <entry>int</entry> <entry>int</entry> <entry>int</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>float</entry> <entry>float</entry> <entry>float</entry> <entry>float</entry> <entry>float</entry> <entry>float</entry> <entry>float</entry> <entry>float</entry> <entry>double</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double</entry> <entry>double complex</entry> <entry>double complex</entry> </row> <row> <entry>complex</entry> <entry>complex</entry> <entry>complex</entry> <entry>complex</entry> <entry>complex</entry> <entry>complex</entry> <entry>complex</entry> <entry>complex</entry> <entry>double complex</entry> <entry>complex</entry> <entry>double complex</entry> </row> <row> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> <entry>double complex</entry> </row> </tbody> </tgroup> </table> In the second stage, the operation is performed between the two identical types to form the output. The details vary between operations, but generally the principle is that the output type should be large enough to represent the whole range of possible values, except that int never becomes float. Optional arguments: * @across: %gint, number of images per row * @shim: %gint, space between images, in pixels * @background: #VipsArrayDouble, background ink colour * @halign: #VipsAlign, low, centre or high alignment * @valign: #VipsAlign, low, centre or high alignment * @hspacing: %gint, horizontal distance between images * @vspacing: %gint, vertical distance between images Lay out the images in @in in a grid. The grid is @across images across and however high is necessary to use up all of @in. Images are set down left-to-right and top-to-bottom. @across defaults to @n. Each input image is placed with a box of size @hspacing by @vspacing pixels and cropped. These default to the largest width and largest height of the input images. Space between images is filled with @background. This defaults to 0 (black). Images are positioned within their @hspacing by @vspacing box at low, centre or high coordinate values, controlled by @halign and @valign. These default to left-top. Boxes are joined and separated by @shim pixels. This defaults to 0. If the number of bands in the input images differs, all but one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the n-band images are operated upon. The input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). vips_colourspace() can be useful for moving the images to a common colourspace for compositing. See also: vips_join(), vips_insert(), vips_colourspace().

0 on success, -1 on error

array of input images output image number of input images %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_ATAN2 on a pair of images. See vips_math2().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Return %TRUE if @format is uchar or schar.

format to test

Return %TRUE if @fmt is one of the complex types.

format to test

Return %TRUE if @format is one of the float types.

format to test

Return %TRUE if @format is one of the integer types.

format to test

Return %TRUE if @format is one of the unsigned integer types.

format to test

Join a set of images together, bandwise. If the images have n and m bands, then the output image will have n + m bands, with the first n coming from the first image and the last m from the second. If the images differ in size, the smaller images are enlarged to match the larger by adding zero pixels along the bottom and right. The input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). See also: vips_insert().

0 on success, -1 on error

array of input images output image number of input images %NULL-terminated list of optional named arguments

Join a pair of images together, bandwise. See vips_bandjoin().

0 on success, -1 on error

first input image second input image output image %NULL-terminated list of optional named arguments

Optional arguments: * @index: pick this index from list of sorted values Sorts the images @in band-element-wise, then outputs an image in which each band element is selected from the sorted list by the @index parameter. For example, if @index is zero, then each output band element will be the minimum of all the corresponding input band elements. By default, @index is -1, meaning pick the median value. It works for any uncoded, non-complex image type. Images are cast up to the smallest common-format. Any image can have either 1 band or n bands, where n is the same for all the non-1-band images. Single band images are then effectively copied to make n-band images. Smaller input images are expanded by adding black pixels. See also: vips_rank().

0 on success, -1 on error

array of input images output image number of input images %NULL-terminated list of optional named arguments

A few simple typedefs used by VIPS. Optional arguments: * @bands: output bands Make a black unsigned char image of a specified size. See also: vips_xyz(), vips_text(), vips_gaussnoise().

0 on success, -1 on error

output image output width output height %NULL-terminated list of optional named arguments

Like vips_blob_new(), but take a copy of the data. Useful for bindings which struggle with callbacks. See also: vips_blob_new().

the new #VipsBlob.

data to store number of bytes in @data

Set the block state on all untrusted operations. |[ vips_block_untrusted_set(TRUE); ]| Will block all untrusted operations from running. Use `vips -l` at the command-line to see the class hierarchy and which operations are marked as untrusted. Set the environment variable `VIPS_BLOCK_UNTRUSTED` to block all untrusted operations on vips_init().

the block state to set

Perform various boolean operations on pairs of images. The output image is the same format as the upcast input images for integer types. Float types are cast to int before processing. Complex types are not supported. If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). See also: vips_boolean_const().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage boolean operation to perform %NULL-terminated list of optional named arguments

A message buffer you can append stuff to safely and quickly. If the message gets too long, you get "..." and truncation. Message buffers can be on the stack or heap. For example: |[ char txt[256]; VipsBuf buf = VIPS_BUF_STATIC(txt); int i; vips_buf_appends(&buf, "Numbers are: "); for (i = 0; i < array_length; i++) { if (i > 0) vips_buf_appends(&buf, ", "); vips_buf_appendg(&buf, array[i]); } printf("%s", vips_buf_all(&buf)); ]| Drop the whole operation cache, handy for leak tracking. Also called automatically on vips_shutdown().

Get the maximum number of operations we keep in cache.

the maximum number of operations we keep in cache

Get the maximum number of tracked files we allow before we start dropping cached operations. See vips_tracked_get_files(). libvips only tracks file descriptors it allocates, it can't track ones allocated by external libraries. If you use an operation like vips_magickload(), most of the descriptors it uses won't be included. See also: vips_tracked_get_files().

the maximum number of tracked files we allow

Get the maximum amount of tracked memory we allow before we start dropping cached operations. See vips_tracked_get_mem(). See also: vips_tracked_get_mem().

the maximum amount of tracked memory we allow

Get the current number of operations in cache.

get the current number of operations in cache.

A binding-friendly version of vips_cache_operation_buildp(). After calling this, @operation has the same ref count as when it went in, and the result must be freed with vips_object_unref_outputs() and g_object_unref().

The built operation.

operation to lookup

Look up @operation in the cache. If we get a hit, unref @operation, ref the old one and return that through the argument pointer. If we miss, build and add @operation. Operators that have been tagged as invalid by the `invalidate` signal are removed from cache. Operators with the #VIPS_OPERATION_BLOCKED flag are never executed. Operators with the #VIPS_OPERATION_REVALIDATE flag are always executed and any old cache value is replaced. Operators with the #VIPS_OPERATION_NOCACHE flag are never cached.

0 on success, or -1 on error.

pointer to operation to lookup

Print the whole operation cache to stdout. Handy for debugging.

Handy for debugging. Print the operation cache to stdout just before exit. See also: vips_cache_set_trace().

if %TRUE, dump the operation cache on exit

Set the maximum number of operations we keep in cache.

maximum number of operation to cache

Set the maximum number of tracked files we allow before we start dropping cached operations. See vips_tracked_get_files(). See also: vips_tracked_get_files().

max open files we allow

Set the maximum amount of tracked memory we allow before we start dropping cached operations. See vips_tracked_get_mem(). libvips only tracks memory it allocates, it can't track memory allocated by external libraries. If you use an operation like vips_magickload(), most of the memory it uses won't be included. See also: vips_tracked_get_mem().

maximum amount of tracked memory we use

Handy for debugging. Print operation cache actions to stdout as we run. You can set the environment variable `VIPS_TRACE` to turn this option on, or use the command-line flag `--vips-cache-trace`. See also: vips_cache_set_dump().

if %TRUE, trace the operation cache

vips_call() calls the named operation, passing in required arguments and then setting any optional ones from the remainder of the arguments as a set of name/value pairs. For example, vips_embed() takes six required arguments, @in, @out, @x, @y, @width, @height, and has two optional arguments, @extend and @background. You can run it with vips_call() like this: |[ VipsImage *in = ... VipsImage *out; if (vips_call("embed", in, &out, 10, 10, 100, 100, "extend", VIPS_EXTEND_COPY, NULL)) ... error ]| Normally of course you'd just use the vips_embed() wrapper function and get type-safety for the required arguments. See also: vips_call_split(), vips_call_options().

0 on success, -1 on error

name of operation to call required args, then a %NULL-terminated list of argument/value pairs

This is the main entry point for the C and C++ varargs APIs. @operation is executed, supplying @required and @optional arguments. Beware, this can change @operation to point at an old, cached one.

0 on success, -1 on error

the operation to execute %va_list of required arguments NULL-terminated %va_list of name / value pairs

Check that the image is 8 or 16-bit integer, signed or unsigned. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

@bandno should be a valid band number (ie. 0 to im->Bands - 1), or can be -1, meaning all bands. If not, set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check band number

Check that the image has @bands bands. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check must have this many bands

Check that the image has either one or three bands. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the images have the same number of bands, or that one of the images has just 1 band. If not, set an error message and return non-zero. See also: vips_error().

0 on OK, or -1 on error.

the originating domain for the error message first image to check second image to check

Check that an image has 1 or @n bands. Handy for unary operations, cf. vips_check_bands_1orn(). If not, set an error message and return non-zero. See also: vips_check_bands_1orn().

0 on OK, or -1 on error.

the originating domain for the error message image to check number of bands, or 1

Check that the image has at least @bands bands. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check at least this many bands

Check that the images have the same number of bands. If not, set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message first image to check second image to check

Check that the image has the required @coding. If not, set an error message and return non-zero. See also: vips_error().

0 on OK, or -1 on error.

the originating domain for the error message image to check required coding

Check that the image is uncoded, LABQ coded or RAD coded. If not, set an error message and return non-zero. See also: vips_error().

0 on OK, or -1 on error.

the originating domain for the error message image to check

Check that the image is uncoded or LABQ coded. If not, set an error message and return non-zero. See also: vips_error().

0 on OK, or -1 on error.

the originating domain for the error message image to check

Check that the images have the same coding. If not, set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message first image to check second image to check

Check that the image is complex. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image has the specified format. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check format to test for

Check that the images have the same format. If not, set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message first image to check second image to check

Histogram images must have width or height 1, and must not have more than 65536 elements. Return 0 if the image will pass as a histogram, or -1 and set an error message otherwise. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is in one of the integer formats. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Matrix images must have width and height less than 100000 and have 1 band. Return 0 if the image will pass as a matrix, or -1 and set an error message otherwise. @out is set to be @im cast to double and stored in memory. Use VIPS_MATRIX() to address values in @out. You must unref @out when you are done with it. See also: VIPS_MATRIX(), vips_object_local()

0 if OK, -1 otherwise.

the originating domain for the error message image to check put image as in-memory doubles here

Check that the image has exactly one band. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is not complex. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is square and that the sides are odd. If not, set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that @prec image is either float or int. If not, set an error message and return non-zero. See also: vips_error().

0 on OK, or -1 on error.

the originating domain for the error message precision to check

Separable matrix images must have width or height 1. Return 0 if the image will pass, or -1 and set an error message otherwise. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the images have the same size. If not, set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message first image to check second image to check

Check that the image is has two "components", ie. is a one-band complex or a two-band non-complex. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is 8 or 16-bit unsigned integer. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is 8 or 16-bit unsigned integer, or float. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is in one of the unsigned integer formats. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is unsigned int or float. Otherwise set an error message and return non-zero. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message image to check

Check that the image is not coded. If not, set an error message and return non-zero. See also: vips_error().

0 on OK, or -1 on error.

the originating domain for the error message image to check

Operations with a vector constant need a 1-element vector, or a vector with the same number of elements as there are bands in the image, or a 1-band image and a many-element vector. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message number of elements in vector image to check against

Check that @n == @len. See also: vips_error().

0 if OK, -1 otherwise.

the originating domain for the error message number of elements in vector number of elements vector should have

Search below @basename, return the first class whose name or @nickname matches. See also: vips_type_find()

the found class.

name of base class search for a class with this nickname

Loop over all the subclasses of @type. Non-abstract classes only. Stop when @fn returns non-%NULL and return that value.

%NULL if @fn returns %NULL for all arguments, otherwise the first non-%NULL value from @fn.

base type call this function for every type client data

Calculate Ccmc from C.

Ccmc.

Chroma

Calculate C from Ccmc using a table. Call vips_col_make_tables_CMC() at least once before using this function.

Ccmc

Calculate ab from Ch, h in degrees.

Chroma Hue angle (degrees) return CIE a* value return CIE b* value

Calculate hcmc from C and h.

hcmc.

Chroma Hue (degrees)

Calculate h from C and hcmc, using a table. Call vips_col_make_tables_CMC() at least once before using this function.

Chroma Hue cmc (degrees)

Calculate Lcmc from L.

Lcmc

CIE L*

Calculate XYZ from Lab, D65. See also: vips_Lab2XYZ().

Input CIE Lab value Input CIE Lab value Input CIE Lab value Return CIE XYZ colour Return CIE XYZ colour Return CIE XYZ colour

Calculate L from Lcmc using a table. Call vips_col_make_tables_CMC() at least once before using this function.

L cmc

Calculate XYZ from Lab, D65. See also: vips_XYZ2Lab().

Input CIE XYZ colour Input CIE XYZ colour Input CIE XYZ colour Return CIE Lab value Return CIE Lab value Return CIE Lab value

Turn XYZ into scRGB. See also: vips_XYZ2scRGB().

Input XYZ value Input XYZ value Input XYZ value Return scRGB colour Return scRGB colour Return scRGB colour

Hue (degrees)

CIE a CIE b

CIEDE2000, from: Luo, Cui, Rigg, "The Development of the CIE 2000 Colour-Difference Formula: CIEDE2000", COLOR research and application, pp 340

CIE dE2000 colour difference.

Input coordinate 1 Input coordinate 1 Input coordinate 1 Input coordinate 2 Input coordinate 2 Input coordinate 2

Make the lookup tables for cmc.

Turn scRGB into XYZ. See also: vips_scRGB2XYZ().

Input scRGB value Input scRGB value Input scRGB value Return XYZ colour Return XYZ colour Return XYZ colour

These operators let you transform coordinates and images between colour spaces, calculate colour differences, and move to and from device spaces. All operations process colour from the first few bands and pass other bands through unaltered. This means you can operate on images with alpha channels safely. If you move to or from 16-bit RGB, any alpha channels are rescaled for you. Radiance images have four 8-bits bands and store 8 bits of R, G and B and another 8 bits of exponent, common to all channels. They are widely used in the HDR imaging community. The colour functions can be divided into three main groups. First, functions to transform images between the different colour spaces supported by VIPS: #VIPS_INTERPRETATION_sRGB, #VIPS_INTERPRETATION_scRGB, #VIPS_INTERPRETATION_B_W, #VIPS_INTERPRETATION_XYZ, #VIPS_INTERPRETATION_YXY, #VIPS_INTERPRETATION_LAB, #VIPS_INTERPRETATION_LCH, and #VIPS_INTERPRETATION_CMC. There are also a set of minor colourspaces which are one of the above in a slightly different format: #VIPS_INTERPRETATION_LAB, #VIPS_INTERPRETATION_LABQ, #VIPS_INTERPRETATION_LABS, #VIPS_INTERPRETATION_LCH, #VIPS_INTERPRETATION_RGB16, and #VIPS_INTERPRETATION_GREY16. Use vips_colourspace() to move an image to a target colourspace using the best sequence of colour transform operations. Secondly, there are a set of operations for calculating colour difference metrics. Finally, VIPS wraps LittleCMS and uses it to provide a set of operations for reading and writing images with ICC profiles. This figure shows how the VIPS colour spaces interconvert: <para> <inlinegraphic fileref="interconvert.png" format="PNG" /> </para> The colour spaces supported by VIPS are: * #VIPS_INTERPRETATION_LAB -- CIELAB '76 colourspace with a D65 white. This uses three floats for each band, and bands have the obvious range. There are two variants, #VIPS_INTERPRETATION_LABQ and #VIPS_INTERPRETATION_LABS, which use ints to store values. These are less precise, but can be quicker to store and process. #VIPS_INTERPRETATION_LCH is the same, but with a*b* as polar coordinates. Hue is expressed in degrees. * #VIPS_INTERPRETATION_XYZ -- CIE XYZ. This uses three floats. See #VIPS_D75_X0 and friends for values for the ranges under various illuminants. #VIPS_INTERPRETATION_YXY is the same, but with little x and y. * #VIPS_INTERPRETATION_scRGB -- a linear colourspace with the sRGB primaries. This is useful if you need linear light and don't care much what the primaries are. Linearization is performed with the usual sRGB equations, see below. * #VIPS_INTERPRETATION_sRGB -- the standard sRGB colourspace, see: [wikipedia sRGB](http://en.wikipedia.org/wiki/SRGB). This uses three 8-bit values for each of RGB. #VIPS_INTERPRETATION_RGB16 is the same, but using three 16-bit values for RGB. #VIPS_INTERPRETATION_HSV is sRGB, but in polar coordinates. #VIPS_INTERPRETATION_LCH is much better, only use HSV if you have to. * #VIPS_INTERPRETATION_B_W -- a monochrome image, roughly G from sRGB. The grey value is calculated in linear #VIPS_INTERPRETATION_scRGB space with RGB ratios 0.2126, 0.7152, 0.0722 as defined by CIE 1931 linear luminance. #VIPS_INTERPRETATION_GREY16 is the same, but using 16 bits. * #VIPS_INTERPRETATION_CMC -- a colour space based on the CMC(1:1) colour difference measurement. This is a highly uniform colour space, and much better than CIELAB for expressing small differences. The CMC colourspace is described in "Uniform Colour Space Based on the CMC(l:c) Colour-difference Formula", M R Luo and B Rigg, Journal of the Society of Dyers and Colourists, vol 102, 1986. Distances in this colourspace approximate, within 10% or so, differences in the CMC(l:c) colour difference formula. You can calculate metrics like CMC(2:1) by scaling the spaces before finding differences. Perform various binary operations on complex images. Angles are expressed in degrees. The output type is complex unless the input is double or dpcomplex, in which case the output is dpcomplex.

0 on success, -1 on error

input #VipsImage input #VipsImage output #VipsImage complex2 operation to perform %NULL-terminated list of optional named arguments

Compose two real images to make a complex image. If either @left or @right are #VIPS_FORMAT_DOUBLE, @out is #VIPS_FORMAT_DPCOMPLEX. Otherwise @out is #VIPS_FORMAT_COMPLEX. @left becomes the real component of @out and @right the imaginary. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. See also: vips_complexget().

0 on success, -1 on error

input image input image output image %NULL-terminated list of optional named arguments

Optional arguments: * @compositing_space: #VipsInterpretation to composite in * @premultiplied: %gboolean, images are already premultiplied * @x: #VipsArrayInt, array of (@n - 1) x coordinates * @y: #VipsArrayInt, array of (@n - 1) y coordinates Composite an array of images together. Images are placed in a stack, with @in[0] at the bottom and @in[@n - 1] at the top. Pixels are blended together working from the bottom upwards, with the blend mode at each step being set by the corresponding #VipsBlendMode in @mode. Images are transformed to a compositing space before processing. This is #VIPS_INTERPRETATION_sRGB, #VIPS_INTERPRETATION_B_W, #VIPS_INTERPRETATION_RGB16, or #VIPS_INTERPRETATION_GREY16 by default, depending on how many bands and bits the input images have. You can select any other space, such as #VIPS_INTERPRETATION_LAB or #VIPS_INTERPRETATION_scRGB. The output image is in the compositing space. It will always be #VIPS_FORMAT_FLOAT unless one of the inputs is #VIPS_FORMAT_DOUBLE, in which case the output will be double as well. Complex images are not supported. The output image will always have an alpha band. A solid alpha is added to any input missing an alpha. The images do not need to match in size or format. The output image is always the size of @in[0], with other images being positioned with the @x and @y parameters and clipped against that rectangle. Image are normally treated as unpremultiplied, so this operation can be used directly on PNG images. If your images have been through vips_premultiply(), set @premultiplied. See also: vips_insert().

0 on success, -1 on error

array of input images output image number of input images array of (@n - 1) #VipsBlendMode %NULL-terminated list of optional named arguments

Returns the number of worker threads that vips should use when running a #VipsThreadPool. vips gets this values from these sources in turn: If vips_concurrency_set() has been called, this value is used. The special value 0 means "default". You can also use the command-line argument "--vips-concurrency" to set this value. If vips_concurrency_set() has not been called and no command-line argument was used, vips uses the value of the environment variable VIPS_CONCURRENCY, If VIPS_CONCURRENCY has not been set, vips finds the number of hardware threads that the host machine can run in parallel and uses that value. The final value is clipped to the range 1 - 1024. See also: vips_concurrency_get().

number of worker threads to use.

Sets the number of worker threads that vips should use when running a #VipsThreadPool. The special value 0 means "default". In this case, the number of threads is set by the environment variable VIPS_CONCURRENCY, or if that is not set, the number of threads available on the host machine. See also: vips_concurrency_get().

number of threads to run

A #VipsConnection is a source or sink of bytes for something like jpeg loading, see for example vips_jpegload_source(). It can be connected to a network socket, for example, or perhaps a node.js stream, or to an area of memory. Subclass to add other input sources. Use #VipsSourceCustom and #VipsTargetCustom to make a source or target with action signals for ::read, ::write and ::seek. These operations convert an image in some way. They can be split into a two main groups. The first set of operations change an image's format in some way. You can change the band format (for example, cast to 32-bit unsigned int), form complex images from real images, convert images to matrices and back, change header fields, and a few others. The second group move pixels about in some way. You can flip, rotate, extract, insert and join pairs of images in various ways. These operations convolve an image in some way, or are operations based on simple convolution, or are useful with convolution. These functions generate various images. You can combine them with the arithmetic and rotate functions to build more complicated images. Perform #VIPS_OPERATION_COMPLEX2_CROSS_PHASE on an image. See vips_complex2().

0 on success, -1 on error

input #VipsImage input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

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 <emphasis>space</emphasis>. Whitespace characters are always run together. @separator sets the characters that separate fields. Default ;,<emphasis>tab</emphasis>. 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().

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load output image %NULL-terminated list of optional named arguments

Calculate dE 00.

0 on success, -1 on error

first input image second input image output image %NULL-terminated list of optional named arguments

Calculate dE 76.

0 on success, -1 on error

first input image second input image output image %NULL-terminated list of optional named arguments

Calculate dE CMC. The input images are transformed to CMC colour space and the euclidean distance between corresponding pixels calculated. To calculate a colour difference with values for (l:c) other than (1:1), transform the two source images to CMC yourself, scale the channels appropriately, and call this function. See also: vips_colourspace()

0 on success, -1 on error

first input image second input image output image %NULL-terminated list of optional named arguments

This operation calculates @in1 / @in2 and writes the result to @out. If any pixels in @in2 are zero, the corresponding pixel in @out is also zero. If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), then the following table is used to determine the output type: <table> <title>vips_divide() type promotion</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>input type</entry> <entry>output type</entry> </row> </thead> <tbody> <row> <entry>uchar</entry> <entry>float</entry> </row> <row> <entry>char</entry> <entry>float</entry> </row> <row> <entry>ushort</entry> <entry>float</entry> </row> <row> <entry>short</entry> <entry>float</entry> </row> <row> <entry>uint</entry> <entry>float</entry> </row> <row> <entry>int</entry> <entry>float</entry> </row> <row> <entry>float</entry> <entry>float</entry> </row> <row> <entry>double</entry> <entry>double</entry> </row> <row> <entry>complex</entry> <entry>complex</entry> </row> <row> <entry>double complex</entry> <entry>double complex</entry> </row> </tbody> </tgroup> </table> In other words, the output type is just large enough to hold the whole range of possible values. See also: vips_multiply(), vips_linear(), vips_pow().

0 on success, -1 on error

input image input image output image %NULL-terminated list of optional named arguments

These operations directly modify the image. They do not thread, on 32-bit machines they will be limited to 2GB images, and a little care needs to be taken if you use them as part of an image pipeline. They are mostly supposed to be useful for paintbox-style programs. libvips operations are all functional: they take zero or more existing input images and generate zero or more new output images. Images are never altered, you always create new images. This means libvips can cache and thread very aggressively. The downside is that creating entirely fresh images each time can be very slow. libvips has a range of tricks to avoid these problems, but there are still times when you really have to be able to modify an image. An example might be drawing a curved line from a set of straight line segments: if you need to draw 1,000 straight lines, a 1,000 operation-deep pipeline is going to be a slow way to do it. This is where the draw operations come in. To use these operations, use vips_image_copy_memory() to make a private memory copy of the image you want to modify, then call a series of draw operations. Once you are done drawing, return to normal use of vips operations. Any time you want to start drawing again, you'll need to copy again. Perform #VIPS_OPERATION_BOOLEAN_EOR on a pair of images. See vips_boolean().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_EQUAL on a pair of images. See vips_relational().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Format the string in the style of printf() and append to the error buffer. See also: vips_error_system(), vips_verror().

the source of the error printf()-style format string for the error arguments to the format string

Get a pointer to the start of the error buffer as a C string. The string is owned by the error system and must not be freed. See also: vips_error_clear().

the error buffer as a C string which must not be freed

Return a copy of the vips error buffer, and clear it.

a copy of the libvips error buffer

Clear and reset the error buffer. This is typically called after presenting an error to the user. See also: vips_error_buffer().

Sends a formatted error message to stderr, then sends the contents of the error buffer, if any, then shuts down vips and terminates the program with an error code. @fmt may be %NULL, in which case only the error buffer is printed before exiting. See also: vips_error().

printf()-style format string for the message arguments to the format string

Stop errors being logged. Use vips_error_thaw() to unfreeze. You can nest freeze/thaw pairs.

This function sets the glib error pointer from the vips error buffer and clears it. It's handy for returning errors to glib functions from vips. See vips_g_error() for the inverse operation. See also: g_set_error(), vips_g_error().

Format the string in the style of printf() and append to the error buffer. Then create and append a localised message based on the system error code, usually the value of errno. See also: vips_verror_system().

the system error code the source of the error printf()-style format string for the error arguments to the format string

Re-enable error logging.

VIPS maintains an error buffer (a log of localised text messages), a set of functions for adding messages, and a way to access and clear the buffer. The error buffer is global, that is, it is shared between all threads. You can add to the buffer from any thread (there is a lock to prevent corruption), but it's sensible to only read and clear the buffer from the main thread of execution. The general principle is: if you detect an error, log a message for the user. If a function you call detects an error, just propagate it and don't add another message. |[ VipsImage *im; if (!(im = vips_image_new_from_file(filename, NULL))) // vips_image_new_from_file() will set a message, we don't need to return -1; if (vips_image_get_width(im) < 100) { // we have detected an error, we must set a message vips_error("myprogram", "%s", _("width too small")); return -1; } ]| The domain argument most of these functions take is not localised and is supposed to indicate the component which failed. libvips uses g_warning() and g_info() to send warning and information messages to the user. You can use the usual glib mechanisms to display or divert these messages. For example, info messages are hidden by default, but you can see them with: |[ $ G_MESSAGES_DEBUG=VIPS vipsthumbnail k2.jpg VIPS-INFO: thumbnailing k2.jpg VIPS-INFO: selected loader is VipsForeignLoadJpegFile VIPS-INFO: input size is 1450 x 2048 VIPS-INFO: loading jpeg with factor 8 pre-shrink VIPS-INFO: converting to processing space srgb VIPS-INFO: residual reducev by 0.5 VIPS-INFO: 13 point mask VIPS-INFO: using vector path VIPS-INFO: residual reduceh by 0.5 VIPS-INFO: 13 point mask VIPS-INFO: thumbnailing k2.jpg as ./tn_k2.jpg ]| Optional arguments: * @factor: %gdouble, maximum spatial frequency * @uchar: %gboolean, output a uchar image Create a test pattern with increasing spatial frequency in X and amplitude in Y. @factor should be between 0 and 1 and determines the maximum spatial frequency. Set @uchar to output a uchar image. See also: vips_zone().

0 on success, -1 on error

output image image size image size %NULL-terminated list of optional named arguments

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the filename part, "fred.jpg" in this case. Useful for language bindings. See also: vips_filename_get_options().

transfer full: just the filename component.

a filename including a set of options

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the options part, "[Q=90]" in this case. Useful for language bindings. See also: vips_filename_get_filename().

transfer full: just the options component.

a filename including a set of options

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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: |[ 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. |[ 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. |[ 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"); } ]| Return the flags for @filename using @loader. @loader is something like "tiffload" or "VipsForeignLoadTiff".

the flags for @filename.

name of loader to use for test file to test

number of bytes for a band format.

format type

A fast but dangerous version of vips_format_sizeof(). You must have previously range-checked @format or you'll crash.

number of bytes for a band format.

format type

Generate an image of size @width by @height and fractal dimension @fractal_dimension. The dimension should be between 2 and 3. See also: vips_gaussnoise(), vips_mask_fractal().

0 on success, -1 on error

output image output width output height fractal dimension %NULL-terminated list of optional named arguments

To and from Fourier space, filter in Fourier space, convert Fourier-space images to a displayable form. This function adds the %GError to the vips error buffer and clears it. It's the opposite of vips_error_g(). See also: vips_error_g().

Optional arguments: * @separable: generate a separable gaussian * @precision: #VipsPrecision for @out Creates a circularly symmetric Gaussian image of radius @sigma. The size of the mask is determined by the variable @min_ampl; if for instance the value .1 is entered this means that the produced mask is clipped at values less than 10 percent of the maximum amplitude. The program uses the following equation: H(r) = exp(-(r * r) / (2 * @sigma * @sigma)) The generated image has odd size and its maximum value is normalised to 1.0, unless @precision is #VIPS_PRECISION_INTEGER. If @separable is set, only the centre horizontal is generated. This is useful for separable convolutions. If @precision is #VIPS_PRECISION_INTEGER, an integer gaussian is generated. This is useful for integer convolutions. "scale" is set to the sum of all the mask elements. See also: vips_logmat(), vips_conv().

0 on success, -1 on error

output image standard deviation of mask minimum amplitude %NULL-terminated list of optional named arguments

Optional arguments: * @mean: mean of generated pixels * @sigma: standard deviation of generated pixels Make a one band float image of gaussian noise with the specified distribution. The noise distribution is created by averaging 12 random numbers with the appropriate weights. See also: vips_black(), vips_xyz(), vips_text().

0 on success, -1 on error

output image output width output height %NULL-terminated list of optional named arguments

These functions let you attach generate functions to images and ask for regions of images to be calculated. See also: VIPS_INIT().

a pointer to an internal copy of the argv0 string passed to VIPS_INIT(). Do not free this value

Return the number of bytes at which we flip between open via memory and open via disc. This defaults to 100mb, but can be changed with the VIPS_DISC_THRESHOLD environment variable or the --vips-disc-threshold command-line flag. See vips_image_new_from_file().

disc threshold in bytes.

Return the program name. This can be useful for the user tio see,. See also: VIPS_INIT().

a pointer to an internal copy of the program name. Do not free this value

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_gifload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load image to write %NULL-terminated list of optional named arguments

Optional arguments: * @extend: #VipsExtend to generate the edge pixels (default: black) * @background: #VipsArrayDouble colour for edge pixels The opposite of vips_extract_area(): place @in within an image of size @width by @height at a certain gravity. @extend controls what appears in the new pels, see #VipsExtend. See also: vips_extract_area(), vips_insert().

0 on success, -1 on error.

input image output image place @in at this direction in @out @out should be this many pixels across @out should be this many pixels down %NULL-terminated list of optional named arguments

Optional arguments: * @uchar: output a uchar image Create a one-band float image with the left-most column zero and the right-most 1. Intermediate pixels are a linear ramp. Set @uchar to output a uchar image with the leftmost pixel 0 and the rightmost 255. See also: vips_xyz(), vips_identity().

0 on success, -1 on error

output image image size image size %NULL-terminated list of optional named arguments

vips_guess_libdir() tries to guess the install directory (usually the configure libdir, or $prefix/lib). You should pass in the value of argv[0] (the name your program was run as) as a clue to help it out, plus the name of the environment variable you let the user override your package install area with (eg. "VIPSHOME"). On success, vips_guess_libdir() returns the libdir it discovered, and as a side effect, sets the prefix environment variable (if it's not set). Don't free the return string! See also: vips_guess_prefix().

the libdir as a static string, do not free.

program name (typically argv[0]) save prefix in this environment variable

vips_guess_prefix() tries to guess the install directory. You should pass in the value of argv[0] (the name your program was run as) as a clue to help it out, plus the name of the environment variable you let the user override your package install area with (eg. "VIPSHOME"). On success, vips_guess_prefix() returns the prefix it discovered, and as a side effect, sets the environment variable (if it's not set). Don't free the return string! See also: vips_guess_libdir().

the install prefix as a static string, do not free.

program name (typically argv[0]) save prefix in this environment variable

These functions let you get at image header data (including metadata) in a uniform way. Use vips_image_get_typeof() to test for the existence and #GType of a header field. You can attach arbitrary metadata to images. Metadata is copied as images are processed, so all images which used this image as input, directly or indirectly, will have this same bit of metadata attached to them. Copying is implemented with reference-counted pointers, so it is efficient, even for large items of data. This does however mean that metadata items need to be immutable. Metadata is handy for things like ICC profiles or EXIF data. Various convenience functions (eg. vips_image_set_int()) let you easily attach simple types like numbers, strings and memory blocks to images. Use vips_image_map() to loop over an image's fields, including all metadata. Items of metadata are identified by strings. Some strings are reserved, for example the ICC profile for an image is known by convention as "icc-profile-data". If you save an image in VIPS format, all metadata (with a restriction, see below) is automatically saved for you in a block of XML at the end of the file. When you load a VIPS image, the metadata is restored. You can use the `vipsedit` command-line tool to extract or replace this block of XML. VIPS metadata is based on %GValue. See the docs for that system if you want to do fancy stuff such as defining a new metadata type. VIPS defines a new %GValue called `vips_save_string`, a variety of string, see vips_value_set_save_string(). If your %GValue can be transformed to `vips_save_string`, it will be saved and loaded to and from VIPS files for you. VIPS provides a couple of base classes which implement reference-counted areas of memory. If you base your metadata on one of these types, it can be copied between images efficiently. 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().

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_heifload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load from image to write %NULL-terminated list of optional named arguments

Histograms and look-up tables are 1xn or nx1 images, where n is less than 256 or less than 65536, corresponding to 8- and 16-bit unsigned int images. They are tagged with a #VipsInterpretation of #VIPS_INTERPRETATION_HISTOGRAM and usually displayed by user-interfaces such as nip2 as plots rather than images. These functions can be broadly grouped as things to find or build histograms (vips_hist_find(), vips_hist_find_indexed(), vips_hist_find_ndim(), vips_buildlut(), vips_identity()), operations that manipulate histograms in some way (vips_hist_cum(), vips_hist_norm()), operations to apply histograms (vips_maplut()), and a variety of utility operations. A final group of operations build tone curves. These are useful in pre-press work for adjusting the appearance of images. They are designed for CIELAB images, but might be useful elsewhere.

VIPS can optionally be built without the ICC library. Use this function to test for its availability.

non-zero if the ICC library is present.

Optional arguments: * @bands: number of bands to create * @ushort: %TRUE for an unsigned short identity * @size: number of LUT elements for a ushort image Creates an identity lookup table, ie. one which will leave an image unchanged when applied with vips_maplut(). Each entry in the table has a value equal to its position. Use the arithmetic operations on these tables to make LUTs representing arbitrary functions. Normally LUTs are 8-bit. Set @ushort to create a 16-bit table. Normally 16-bit tables have 65536 entries. You can set this smaller with @size. See also: vips_xyz(), vips_maplut().

0 on success, -1 on error

output image %NULL-terminated list of optional named arguments

Optional arguments: * @blend: blend smoothly between @in1 and @in2 This operation scans the condition image @cond and uses it to select pixels from either the then image @in1 or the else image @in2. Non-zero means @in1, 0 means @in2. Any image can have either 1 band or n bands, where n is the same for all the non-1-band images. Single band images are then effectively copied to make n-band images. Images @in1 and @in2 are cast up to the smallest common format. @cond is cast to uchar. If the images differ in size, the smaller images are enlarged to match the largest by adding zero pixels along the bottom and right. If @blend is %TRUE, then values in @out are smoothly blended between @in1 and @in2 using the formula: @out = (@cond / 255) * @in1 + (1 - @cond / 255) * @in2 See also: vips_equal().

0 on success, -1 on error

condition #VipsImage then #VipsImage else #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

The image class and associated types and macros. Images can be created from formatted files on disc, from C-style arrays on disc, from formatted areas of memory, or from C-style arrays in memory. See vips_image_new_from_file() and friends. Creating an image is fast. VIPS reads just enough of the image to be able to get the various properties, such as width in pixels. It delays reading any pixels until they are really needed. Once you have an image, you can get properties from it in the usual way. You can use projection functions, like vips_image_get_width() or g_object_get(), to get %GObject properties. VIPS images are three-dimensional arrays, the dimensions being width, height and bands. Each dimension can be up to 2 ** 31 pixels (or band elements). An image has a format, meaning the machine number type used to represent each value. VIPS supports 10 formats, from 8-bit unsigned integer up to 128-bit double complex, see vips_image_get_format(). In VIPS, images are uninterpreted arrays, meaning that from the point of view of most operations, they are just large collections of numbers. There's no difference between an RGBA (RGB with alpha) image and a CMYK image, for example, they are both just four-band images. It's up to the user of the library to pass the right sort of image to each operation. To take an example, VIPS has vips_Lab2XYZ(), an operation to transform an image from CIE LAB colour space to CIE XYZ space. It assumes the first three bands represent pixels in LAB colour space and returns an image where the first three bands are transformed to XYZ and any remaining bands are just copied. Pass it a RGB image by mistake and you'll just get nonsense. VIPS has a feature to help (a little) with this: it sets a #VipsInterpretation hint for each image (see vips_image_get_interpretation()); a hint which says how pixels should be interpreted. For example, vips_Lab2XYZ() will set the interpretation of the output image to #VIPS_INTERPRETATION_XYZ. A few utility operations will also use interpretation as a guide. For example, you can give vips_colourspace() an input image and a desired colourspace and it will use the input's interpretation hint to apply the best sequence of colourspace transforms to get to the desired space. Use things like vips_invert() to manipulate your images. When you are done, you can write images to disc files (with vips_image_write_to_file()), to formatted memory buffers (with vips_image_write_to_buffer()) and to C-style memory arrays (with vips_image_write_to_memory(). You can also write images to other images. Create, for example, a temporary disc image with vips_image_new_temp_file(), then write your image to that with vips_image_write(). You can create several other types of image and write to them, see vips_image_new_memory(), for example. See <link linkend="VipsOperation">operation</link> for an introduction to running operations on images, see <link linkend="libvips-header">header</link> for getting and setting image metadata. See <link linkend="VipsObject">object</link> for a discussion of the lower levels. This function starts up libvips, see VIPS_INIT(). This function is for bindings which need to start up vips. C programs should use the VIPS_INIT() macro, which does some extra checks. See also: VIPS_INIT().

0 on success, -1 otherwise

name of application

interpolator to use write result here read source data from here interpolate value at this position interpolate value at this position

A number of image interpolators.

the maximum alpha value for an interpretation.

image interpretation

Optional arguments: * @expand: %TRUE to expand the output image to hold all of the input pixels * @shim: space between images, in pixels * @background: background ink colour * @align: low, centre or high alignment Join @in1 and @in2 together, left-right or up-down depending on the value of @direction. If one is taller or wider than the other, @out will be has high as the smaller. If @expand is %TRUE, then the output will be expanded to contain all of the input pixels. Use @align to set the edge that the images align on. By default, they align on the edge with the lower value coordinate. Use @background to set the colour of any pixels in @out which are not present in either @in1 or @in2. Use @shim to set the spacing between the images. By default this is 0. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). If you are going to be joining many thousands of images in a regular grid, vips_arrayjoin() is a better choice. See also: vips_arrayjoin(), vips_insert().

0 on success, -1 on error

first input image second input image output image join horizontally or vertically %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free.

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

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.

0 on success, -1 on error.

source to load from decompressed image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_jpegload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load image to write %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load from decompressed image %NULL-terminated list of optional named arguments

Turn on or off vips leak checking. See also --vips-leak, vips_add_option_entries() and the `VIPS_LEAK` environment variable. You should call this very early in your program.

turn leak checking on or off

Perform #VIPS_OPERATION_RELATIONAL_LESS on a pair of images. See vips_relational().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_LESSEQ on a pair of images. See vips_relational().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @separable: generate a separable mask * @precision: #VipsPrecision for @out Creates a circularly symmetric Laplacian of Gaussian mask of radius @sigma. The size of the mask is determined by the variable @min_ampl; if for instance the value .1 is entered this means that the produced mask is clipped at values within 10 percent of zero, and where the change between mask elements is less than 10%. The program uses the following equation: (from Handbook of Pattern Recognition and image processing by Young and Fu, AP 1986 pages 220-221): H(r) = (1 / (2 * M_PI * s4)) * (2 - (r2 / s2)) * exp(-r2 / (2 * s2)) where s2 = @sigma * @sigma, s4 = s2 * s2, r2 = r * r. The generated mask has odd size and its maximum value is normalised to 1.0, unless @precision is #VIPS_PRECISION_INTEGER. If @separable is set, only the centre horizontal is generated. This is useful for separable convolutions. If @precision is #VIPS_PRECISION_INTEGER, an integer mask is generated. This is useful for integer convolutions. "scale" is set to the sum of all the mask elements. See also: vips_gaussmat(), vips_conv().

0 on success, -1 on error

output image standard deviation of mask minimum amplitude %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_LSHIFT on a pair of images. See vips_boolean().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

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](http://www.imagemagick.org/script/command-line-options.php#density) on the imagemagick website. See also: vips_image_new_from_file().

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_magickload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

g_malloc() local to @object, that is, the memory will be automatically freed for you when the object is closed. If @object is %NULL, you need to free the memory explicitly with g_free(). This function cannot fail. See vips_tracked_malloc() if you are allocating large amounts of memory. See also: vips_tracked_malloc().

a pointer to the allocated memory.

allocate memory local to this #VipsObject, or %NULL number of bytes to allocate

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make an butterworth high- or low-pass filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff, where @frequency_cutoff is in range 0 - 1. The shape of the curve is controlled by @order --- higher values give a sharper transition. See Gonzalez and Wintz, Digital Image Processing, 1987. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size filter order frequency threshold amplitude threshold %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make an butterworth band-pass or band-reject filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff_x, @frequency_cutoff_y, of radius @radius. The shape of the curve is controlled by @order --- higher values give a sharper transition. See Gonzalez and Wintz, Digital Image Processing, 1987. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size filter order band position band position band radius amplitude threshold %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make a butterworth ring-pass or ring-reject filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff of width @width, where @frequency_cutoff is in the range 0 - 1. The shape of the curve is controlled by @order --- higher values give a sharper transition. See Gonzalez and Wintz, Digital Image Processing, 1987. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size filter order frequency threshold amplitude threshold ringwidth %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image This operation should be used to create fractal images by filtering the power spectrum of Gaussian white noise. See vips_gaussnoise(). See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size fractal dimension %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make a gaussian high- or low-pass filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size frequency threshold amplitude threshold %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make a gaussian band-pass or band-reject filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff_x, @frequency_cutoff_y, of radius @radius. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size band position band position band radius amplitude threshold %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make a gaussian ring-pass or ring-reject filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff of width @ringwidth. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size frequency threshold amplitude threshold ringwidth %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make an ideal high- or low-pass filter, that is, one with a sharp cutoff positioned at @frequency_cutoff, where @frequency_cutoff is in the range 0 - 1. This operation creates a one-band float image of the specified size. The image has values in the range [0, 1] and is typically used for multiplying against frequency domain images to filter them. Masks are created with the DC component at (0, 0). The DC pixel always has the value 1.0. Set @nodc to not set the DC pixel. Set @optical to position the DC component in the centre of the image. This makes the mask suitable for multiplying against optical Fourier transforms. See vips_wrap(). Set @reject to invert the sense of the filter. For example, low-pass becomes low-reject. Set @uchar to output an 8-bit unsigned char image rather than a float image. In this case, pixels are in the range [0 - 255]. See also: vips_mask_ideal(), vips_mask_ideal_ring(), vips_mask_ideal_band(), vips_mask_butterworth(), vips_mask_butterworth_ring(), vips_mask_butterworth_band(), vips_mask_gaussian(), vips_mask_gaussian_ring(), vips_mask_gaussian_band().

0 on success, -1 on error

output image image size image size threshold at which filter ends %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make an ideal band-pass or band-reject filter, that is, one with a sharp cutoff around the point @frequency_cutoff_x, @frequency_cutoff_y, of size @radius. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size position of band position of band size of band %NULL-terminated list of optional named arguments

Optional arguments: * @nodc: don't set the DC pixel * @reject: invert the filter sense * @optical: coordinates in optical space * @uchar: output a uchar image Make an ideal ring-pass or ring-reject filter, that is, one with a sharp ring positioned at @frequency_cutoff of width @width, where @frequency_cutoff and @width are expressed as the range 0 - 1. See also: vips_mask_ideal().

0 on success, -1 on error

output image image size image size threshold at which filter ends ring width %NULL-terminated list of optional named arguments

Optional arguments: * @search: search to improve tie-points * @hwindow: half window size * @harea: half search size * @interpolate: interpolate pixels with this Scale, rotate and translate @sec so that the tie-points line up. If @search is %TRUE, before performing the transformation, the tie-points are improved by searching an area of @sec of size @harea for a match of size @hwindow to @ref. This function will only work well for small rotates and scales.

0 on success, -1 on error

reference image secondary image output image first reference tie-point first reference tie-point first secondary tie-point first secondary tie-point second reference tie-point second reference tie-point second secondary tie-point second secondary tie-point %NULL-terminated list of optional named arguments

This operation calculates a 2-ary maths operation on a pair of images and writes the result to @out. The images may have any non-complex format. @out is float except in the case that either of @left or @right are double, in which case @out is also double. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently! If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the result type. See also: vips_math2_const().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage math operation to perform %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load output image %NULL-terminated list of optional named arguments

Return the maximum coordinate value. This can be the default, a value set set by the `--vips-max-coord` CLI arg, or a value set in the `VIPS_MAX_COORD` environment variable. These strings can include unit specifiers, eg. "10m" for 10 million pixels. Values above INT_MAX are not supported.

The maximum value a coordinate, or image dimension, can have.

For each pixel, pick the maximum of a pair of images. See also: vips_minpair().

0 on success, -1 on error

input image input image output image %NULL-terminated list of optional named arguments

These functions cover two main areas. First, some simple utility functions over the underlying g_malloc()/g_free() functions. Memory allocated and freeded using these functions is interchangeable with any other glib library. Second, a pair of functions, vips_tracked_malloc() and vips_tracked_free(), which are NOT compatible. If you g_free() memory that has been allocated with vips_tracked_malloc() you will see crashes. The tracked functions are only suitable for large allocations internal to the library, for example pixel buffers. libvips watches the total amount of live tracked memory and uses this information to decide when to trim caches. Optional arguments: * @mblend: %gint, maximum blend size This operation joins two images left-right (with @ref on the left) or up-down (with @ref above) with a smooth seam. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). @dx and @dy give the displacement of @sec relative to @ref, in other words, the vector to get from the origin of @sec to the origin of @ref, in other words, @dx will generally be a negative number. @mblend limits the maximum width of the blend area. A value of "-1" means "unlimited". The two images are blended with a raised cosine. Pixels with all bands equal to zero are "transparent", that is, zero pixels in the overlap area do not contribute to the merge. This makes it possible to join non-rectangular images. See also: vips_mosaic(), vips_insert().

0 on success, -1 on error

reference image secondary image output image horizontal or vertical merge displacement of ref from sec displacement of ref from sec %NULL-terminated list of optional named arguments

For each pixel, pick the minimum of a pair of images. See also: vips_minpair().

0 on success, -1 on error

input image input image output image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_MORE on a pair of images. See vips_relational().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_MOREEQ on a pair of images. See vips_relational().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

The morphological functions search images for particular patterns of pixels, specified with the mask argument, either adding or removing pixels when they find a match. They are useful for cleaning up images --- for example, you might threshold an image, and then use one of the morphological functions to remove all single isolated pixels from the result. If you combine the morphological operators with the mask rotators (vips_rot45(), for example) and apply them repeatedly, you can achieve very complicated effects: you can thin, prune, fill, open edges, close gaps, and many others. For example, see `Fundamentals of Digital Image Processing' by A. Jain, pp 384-388, Prentice-Hall, 1989 for more ideas. Beware that VIPS reverses the usual image processing convention, by assuming white objects (non-zero pixels) on a black background (zero pixels). The mask you give to the morphological functions should contain only the values 0 (for background), 128 (for don't care) and 255 (for object). The mask must have odd length sides --- the origin of the mask is taken to be the centre value. For example, the mask: VipsImage *mask = vips_image_new_matrixv(3, 3, 128.0, 255.0, 128.0, 255.0, 255.0, 255.0, 128.0, 255.0, 128.0); applied to an image with vips_morph() #VIPS_OPERATION_MORPHOLOGY_DILATE will do a 4-connected dilation. Dilate sets pixels in the output if any part of the mask matches, whereas erode sets pixels only if all of the mask matches. See vips_andimage(), vips_orimage() and vips_eorimage() for analogues of the usual set difference and set union operations. Use vips_image_new_matrixv() to create a mask in source, vips_matrixload() to load a mask from a simple text file, and vips_mask_ideal() and friends to create square, circular and ring masks of specific sizes. Optional arguments: * @bandno: %gint, band to search for features * @hwindow: %gint, half window size * @harea: %gint, half search size * @mblend: %gint, maximum blend size * @dx0: %gint, output, detected displacement * @dy0: %gint, output, detected displacement * @scale1: %gdouble, output, detected first order scale * @angle1: %gdouble, output, detected first order rotation * @dx1: %gdouble, output, detected first order displacement * @dy1: %gdouble, output, detected first order displacement This operation joins two images left-right (with @ref on the left) or top-bottom (with @ref above) given an approximate overlap. @sec is positioned so that the pixel (@xsec, @ysec) in @sec lies on top of the pixel (@xref, @yref) in @ref. The overlap area is divided into three sections, 20 high-contrast points in band @bandno of image @ref are found in each, and a window of pixels of size @hwindow around each high-contrast point is searched for in @sec over an area of @harea. A linear model is fitted to the 60 tie-points, points a long way from the fit are discarded, and the model refitted until either too few points remain or the model reaches good agreement. The detected displacement is used with vips_merge() to join the two images together. You can read out the detected transform with @dx0, @dy0, @scale1, @angle1, @dx1, @dy1. See also: vips_merge(), vips_insert().

0 on success, -1 on error

reference image secondary image output image horizontal or vertical join position in reference image position in reference image position in secondary image position in secondary image %NULL-terminated list of optional named arguments

Optional arguments: * @search: search to improve tie-points * @hwindow: half window size * @harea: half search size * @interpolate: interpolate pixels with this * @mblend: maximum blend size This operation joins two images top-bottom (with @sec on the right) or left-right (with @sec at the bottom) given an approximate pair of tie-points. @sec is scaled and rotated as necessary before the join. If @search is %TRUE, before performing the transformation, the tie-points are improved by searching an area of @sec of size @harea for a object of size @hwindow in @ref. @mblend limits the maximum size of the blend area. A value of "-1" means "unlimited". The two images are blended with a raised cosine. Pixels with all bands equal to zero are "transparent", that is, zero pixels in the overlap area do not contribute to the merge. This makes it possible to join non-rectangular images. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). See also: vips_merge(), vips_insert(), vips_globalbalance().

0 on success, -1 on error

reference image secondary image output image horizontal or vertical join first reference tie-point first reference tie-point first secondary tie-point first secondary tie-point second reference tie-point second reference tie-point second secondary tie-point second secondary tie-point %NULL-terminated list of optional named arguments

These functions are useful for joining many small images together to make one large image. They can cope with unstable contrast and arbitrary sub-image layout, but will not do any geometric correction. Geometric errors should be removed before using these functions. The mosaicing functions can be grouped into layers: The lowest level operation is vips_merge() which joins two images together left-right or up-down with a smooth seam. Next, vips_mosaic() uses search functions plus the two low-level merge operations to join two images given just an approximate overlap as a start point. vips_mosaic1() is a first-order analogue of the basic mosaic functions: it takes two approximate tie-points and uses them to rotate and scale the right-hand or bottom image before starting to join. Finally, vips_globalbalance() can be used to remove contrast differences in a mosaic which has been assembled with these functions. It takes the mosaic apart, measures image contrast differences along the seams, finds a set of correction factors which will minimise these differences, and reassembles the mosaic. vips_remosaic() uses the same techniques, but will reassemble the image from a different set of source images. This operation calculates @left * @right and writes the result to @out. If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), then the following table is used to determine the output type: <table> <title>VipsMultiply type promotion</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>input type</entry> <entry>output type</entry> </row> </thead> <tbody> <row> <entry>uchar</entry> <entry>ushort</entry> </row> <row> <entry>char</entry> <entry>short</entry> </row> <row> <entry>ushort</entry> <entry>uint</entry> </row> <row> <entry>short</entry> <entry>int</entry> </row> <row> <entry>uint</entry> <entry>uint</entry> </row> <row> <entry>int</entry> <entry>int</entry> </row> <row> <entry>float</entry> <entry>float</entry> </row> <row> <entry>double</entry> <entry>double</entry> </row> <row> <entry>complex</entry> <entry>complex</entry> </row> <row> <entry>double complex</entry> <entry>double complex</entry> </row> </tbody> </tgroup> </table> In other words, the output type is just large enough to hold the whole range of possible values. See also: vips_add(), vips_linear().

0 on success, -1 on error

left-hand image right-hand image output image %NULL-terminated list of optional named arguments

Return the VIPS nickname for a %GType. Handy for language bindings.

the class nickname.

#GType to search for

Read a NIFTI image file into a VIPS image. NIFTI metadata is attached with the "nifti-" prefix. See also: vips_image_new_from_file().

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load from decompressed image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_RELATIONAL_NOTEQ on a pair of images. See vips_relational().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

The #VipsObject class and associated types and macros. #VipsObject is the base class for all objects in libvips. It has the following major features: <emphasis>Functional class creation</emphasis> Vips objects have a very regular lifecycle: initialise, build, use, destroy. They behave rather like function calls and are free of side-effects. <emphasis>Run-time introspection</emphasis> Vips objects can be fully introspected at run-time. There is no need for separate source-code analysis. <emphasis>Command-line interface</emphasis> Any vips object can be run from the command-line with the `vips` driver program. ## The #VipsObject lifecycle #VipsObject s have a strictly defined lifecycle, split broadly as construct and then use. In detail, the stages are: 1. g_object_new(). The #VipsObject is created with g_object_new(). Objects in this state are blank slates and need to have their various parameters set. 2. g_object_set(). You loop over the #VipsArgument that the object has defined with vips_argument_map(). Arguments have a set of flags attached to them for required, optional, input, output, type, and so on. You must set all required arguments. 3. vips_object_build(). Call this to construct the object and get it ready for use. Building an object happens in four stages, see below. 4. g_object_get(). The object has now been built. You can read out any computed values. 5. g_object_unref(). When you are done with an object, you can unref it. See the section on reference counting for an explanation of the convention that #VipsObject uses. When the last ref to an object is released, the object is closed. Objects close in three stages, see below. The stages inside vips_object_build() are: 1. Chain up through the object's @build class methods. At each stage, each class does any initial setup and checking, then chains up to its superclass. 2. The innermost @build method inside #VipsObject itself checks that all input arguments have been set and then returns. 3. All object @build methods now finish executing, from innermost to outermost. They know all input arguments have been checked and supplied, so now they set all output arguments. 4. vips_object_build() finishes the process by checking that all output objects have been set, and then triggering the #VipsObject::postbuild signal. #VipsObject::postbuild only runs if the object has constructed successfully. #VipsOperation has a cache of recent operation objects, see that class for an explanation of vips_cache_operation_build(). Finally the stages inside close are: 1. #VipsObject::preclose. This is emitted at the start of the #VipsObject dispose. The object is still functioning. 2. #VipsObject::close. This runs just after all #VipsArgument held by the object have been released. 3. #VipsObject::postclose. This runs right at the end. The object pointer is still valid, but nothing else is. ## #VipsArgument libvips has a simple mechanism for automating at least some aspects of %GObject properties. You add a set of macros to your _class_init() which describe the arguments, and set the get and set functions to the vips ones. See <link linkend="extending">extending</link> for a complete example. ## The #VipsObject reference counting convention #VipsObject has a set of conventions to simplify reference counting. 1. All input %GObject have a ref added to them, owned by the object. When a #VipsObject is unreffed, all of these refs to input objects are automatically dropped. 2. All output %GObject hold a ref to the object. When a %GObject which is an output of a #VipsObject is disposed, it must drop this reference. #VipsObject which are outputs of other #VipsObject will do this automatically. See #VipsOperation for an example of #VipsObject reference counting. 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().

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load from decompressed image %NULL-terminated list of optional named arguments

The #VipsOperation class and associated types and macros. #VipsOperation is the base class for all operations in libvips. It builds on #VipsObject to provide the introspection and command-line interface to libvips. It also maintains a cache of recent operations. See below. vips_call(), vips_call_split() and vips_call_split_option_string() are used by vips to implement the C API. They can execute any #VipsOperation, passing in a set of required and optional arguments. Normally you would not use these functions directly: every operation has a tiny wrapper function which provides type-safety for the required arguments. For example, vips_embed() is defined as: |[ int vips_embed(VipsImage *in, VipsImage **out, int x, int y, int width, int height, ...) { va_list ap; int result; va_start(ap, height); result = vips_call_split("embed", ap, in, out, x, y, width, height); va_end(ap); return result; } ]| Use vips_call_argv() to run any vips operation from a command-line style argc/argv array. This is the thing used by the vips main program to implement the vips command-line interface. ## #VipsOperation and reference counting After calling a #VipsOperation you are responsible for unreffing any output objects. For example, consider: |[ VipsImage *im = ...; VipsImage *t1; if (vips_invert(im, &t1, NULL)) error .. ]| This will invert @im and return a new #VipsImage, @t1. As the caller of vips_invert(), you are responsible for @t1 and must unref it when you no longer need it. If vips_invert() fails, no @t1 is returned and you don't need to do anything. If you don't need to use @im for another operation, you can unref @im immediately after the call. If @im is needed to calculate @t1, vips_invert() will add a ref to @im and automatically drop it when @t1 is unreffed. Consider running two operations, one after the other. You could write: |[ VipsImage *im = ...; VipsImage *t1, *t2; if (vips_invert(im, &t1, NULL)) { g_object_unref(im); return -1; } g_object_unref(im); if (vips_flip(t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) { g_object_unref(t1); return -1; } g_object_unref(t1); ]| This is correct, but rather long-winded. libvips provides a handy thing to make a vector of auto-freeing object references. You can write this as: |[ VipsObject *parent = ...; VipsImage *im = ...; VipsImage *t = (VipsImage **) vips_object_local_array(parent, 2); if (vips_invert(im, &t[0], NULL) || vips_flip(t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL)) return -1; ]| where @parent is some enclosing object which will be unreffed when this task is complete. vips_object_local_array() makes an array of #VipsObject (or #VipsImage, in this case) where when @parent is freed, all non-NULL #VipsObject in the array are also unreffed. ## The #VipsOperation cache Because all #VipsObject are immutable, they can be cached. The cache is very simple to use: instead of calling vips_object_build(), call vips_cache_operation_build(). This function calculates a hash from the operations's input arguments and looks it up in table of all recent operations. If there's a hit, the new operation is unreffed, the old operation reffed, and the old operation returned in place of the new one. The cache size is controlled with vips_cache_set_max() and friends. Perform #VIPS_OPERATION_BOOLEAN_OR on a pair of images. See vips_boolean().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Return the filename part of a vips7 path. For testing only.

path to split

Return the mode part of a vips7 path. For testing only.

path to split

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_pdfload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load from image to write %NULL-terminated list of optional named arguments

Optional arguments: * @cell_size: %gint, size of Perlin cells * @uchar: output a uchar image Create a one-band float image of Perlin noise. See: https://en.wikipedia.org/wiki/Perlin_noise Use @cell_size to set the size of the cells from which the image is constructed. The default is 256 x 256. If @width and @height are multiples of @cell_size, the image will tessellate. Normally, output pixels are #VIPS_FORMAT_FLOAT in the range [-1, +1]. Set @uchar to output a uchar image with pixels in [0, 255]. See also: vips_worley(), vips_fractsurf(), vips_gaussnoise().

0 on success, -1 on error

output image horizontal size vertical size %NULL-terminated list of optional named arguments

Convert the two input images to Fourier space, calculate phase-correlation, back to real space. See also: vips_fwfft(), vips_cross_phase(),

0 on success, -1 on error.

first input image second input image output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_pngload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load from image to write %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_POW on a pair of images. See vips_math2().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load output image %NULL-terminated list of optional named arguments

Load a named profile. Profiles are loaded from four sources: - The special name `"none"` means no profile. @profile will be %NULL in this case. - @name can be the name of one of the ICC profiles embedded in libvips. These names can be at least `"cmyk"`, `"p3"` and `"srgb"`. - @name can be the full path to a file. - @name can be the name of an ICC profile in the system profile directory for your platform.

0 on success, -1 on error

name of profile to load loaded profile %NULL-terminated list of optional named arguments

If set, vips will print messages about the progress of computation to stdout. This can also be enabled with the --vips-progress option, or by setting the environment variable VIPS_PROGRESS.

%TRUE to enable progress messages

Pythagorean distance between two points in colour space. Lab/XYZ/CMC etc.

Input coordinate 1 Input coordinate 1 Input coordinate 1 Input coordinate 2 Input coordinate 2 Input coordinate 2

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

Exactly as vips_radload(), but read from a HDR-formatted memory block. You must not free the buffer while @out is active. The #VipsObject::postclose signal on @out is a good place to free. See also: vips_radload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

Exactly as vips_radload(), but read from a source. See also: vips_radload().

0 on success, -1 on error.

source to load from output image %NULL-terminated list of optional named arguments

Optional arguments: * @offset: %guint64, offset in bytes from start of file * @format: #VipsBandFormat, set image format * @interpretation: #VipsInterpretation, set image interpretation This operation mmaps the file, setting up @out so that access to that image will read from the file. By default, it assumes uchar pixels. Use @format to select something else. The image will be tagged as #VIPS_INTERPRETATION_MULTIBAND. Use @interpretation to select something else. Use vips_byteswap() to reverse the byte ordering if necessary. See also: vips_image_new_from_file(), vips_copy(), vips_byteswap().

0 on success, -1 on error.

file to load output image width of image in pixels height of image in pixels number of image bands %NULL-terminated list of optional named arguments

The #VipsRect class and associated types and macros. A #VipsRegion is a small part of an image. You use regions to read pixels out of images without having to have the whole image in memory at once. A region can be a memory buffer, part of a memory-mapped file, part of some other image, or part of some other region. Regions must be created, used and freed all within the same thread, since they can reference private per-thread caches. VIPS sanity-checks region ownership in various places, so you are likely to see g_assert() errors if you don't follow this rule. There is API to transfer ownership of regions between threads, but hopefully this is only needed within VIPS, so we don't expose it. Hopefully. Perform various relational operations on pairs of images. The output type is always uchar, with 0 for FALSE and 255 for TRUE. Less-than and greater-than for complex images compare the modulus. If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>). To decide if pixels match exactly, that is have the same value in every band, use vips_bandbool() after this operation to AND or OR image bands together. See also: vips_boolean(), vips_bandbool(), vips_relational_const().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage relational operation to perform %NULL-terminated list of optional named arguments

This operation calculates @left % @right (remainder after integer division) and writes the result to @out. The images may have any non-complex format. For float formats, vips_remainder() calculates @in1 - @in2 * floor (@in1 / @in2). If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the result type. See also: vips_remainder_const(), vips_divide(), vips_round().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

These operations build on each other in a set of layers. First, vips_affine() applies an affine transform to an image. This is any sort of 2D transform which preserves straight lines; so any combination of stretch, sheer, rotate and translate. You supply an interpolator for it to use to generate pixels, see vips_interpolate_new(). It will not produce good results for very large shrinks: you'll see aliasing. vips_reduce() is like vips_affine(), but it can only shrink images, it can't enlarge, rotate, or skew. It's very fast and uses an adaptive kernel for interpolation. vips_shrink() is a fast block shrinker. It can quickly reduce images by large integer factors. It will give poor results for small size reductions: again, you'll see aliasing. Next, vips_resize() specialises in the common task of image reduce and enlarge. It strings together combinations of vips_shrink(), vips_reduce(), vips_affine() and others to implement a general, high-quality image resizer. Finally, vips_thumbnail() combines load and resize in one operation, and adds colour management and correct handling of alpha transparency. Because load and resize happen together, it can exploit tricks like JPEG and TIFF shrink-on-load, giving a (potentially) huge speedup. vips_thumbnail_image() is only there for emergencies, don't use it unless you really have to. As a separate thing, `vips_mapim() can apply arbitrary 2D image transforms to an image. Rotate @in by 90 degrees clockwise. A convenience function over vips_rot(). See also: vips_rot().

0 on success, -1 on error

input image output image %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_BOOLEAN_RSHIFT on a pair of images. See vips_boolean().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

#VipsSbuf wraps up a #VipsSource and provides a set of calls for text-oriented buffered reading. You can fetch lines of text, skip whitespace, and so on. It is useful for implementing things like CSV readers, for example. Optional arguments: * @a: #VipsArrayDouble, first point * @b: #VipsArrayDouble, second point * @r: %gfloat, radius * @corners: #VipsArrayDouble, corner radii Create a signed distance field (SDF) image of the given shape. Different shapes use different combinations of the optional arguments, see below. @shape #VIPS_SDF_SHAPE_CIRCLE: create a circle centred on @a, radius @r. @shape #VIPS_SDF_SHAPE_BOX: create a box with top-left corner @a and bottom-right corner @b. @shape #VIPS_SDF_SHAPE_ROUNDED_BOX: create a box with top-left corner @a and bottom-right corner @b, whose four corners are rounded by the four-element float array @corners. @corners will default to 0.0. @shape #VIPS_SDF_SHAPE_LINE: draw a line from @a to @b. See also: vips_grey(), vips_grid(), vips_xyz().

0 on success, -1 on error

output image horizontal size vertical size SDF to create %NULL-terminated list of optional named arguments

Call this to drop caches, close plugins, terminate background threads, and finalize any internal library testing. vips_shutdown() is optional. If you don't call it, your platform will clean up for you. The only negative consequences are that the leak checker and the profiler will not work. You may call VIPS_INIT() many times and vips_shutdown() many times, but you must not call VIPS_INIT() after vips_shutdown(). In other words, you cannot stop and restart libvips. See also: vips_profile_set(), vips_leak_set().

Optional arguments: * @hfreq: horizontal frequency * @vreq: vertical frequency * @uchar: output a uchar image Creates a float one band image of the a sine waveform in two dimensions. The number of horizontal and vertical spatial frequencies are determined by the variables @hfreq and @vfreq respectively. The function is useful for creating displayable sine waves and square waves in two dimensions. If horfreq and verfreq are integers the resultant image is periodical and therefore the Fourier transform does not present spikes Pixels are normally in [-1, +1], set @uchar to output [0, 255]. See also: vips_grey(), vips_xyz().

0 on success, -1 on error

output image image size image size %NULL-terminated list of optional named arguments

g_strdup() a string. When @object is freed, the string will be freed for you. If @object is %NULL, you need to free the memory yourself with g_free(). This function cannot fail. See also: vips_malloc().

a pointer to the allocated memory

allocate memory local to this #VipsObject, or %NULL string to copy

This operation calculates @in1 - @in2 and writes the result to @out. If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right. If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon. The two input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), then the following table is used to determine the output type: <table> <title>VipsSubtract type promotion</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>input type</entry> <entry>output type</entry> </row> </thead> <tbody> <row> <entry>uchar</entry> <entry>short</entry> </row> <row> <entry>char</entry> <entry>short</entry> </row> <row> <entry>ushort</entry> <entry>int</entry> </row> <row> <entry>short</entry> <entry>int</entry> </row> <row> <entry>uint</entry> <entry>int</entry> </row> <row> <entry>int</entry> <entry>int</entry> </row> <row> <entry>float</entry> <entry>float</entry> </row> <row> <entry>double</entry> <entry>double</entry> </row> <row> <entry>complex</entry> <entry>complex</entry> </row> <row> <entry>double complex</entry> <entry>double complex</entry> </row> </tbody> </tgroup> </table> In other words, the output type is just large enough to hold the whole range of possible values. See also: vips_add(), vips_linear().

0 on success, -1 on error

input image input image output image %NULL-terminated list of optional named arguments

This operation sums all images in @in and writes the result to @out. If the images differ in size, the smaller images are enlarged to match the largest by adding zero pixels along the bottom and right. If the number of bands differs, all but one of the images must have one band. In this case, n-band images are formed from the one-band images by joining n copies of the one-band images together, and then the n-band images are operated upon. The input images are cast up to the smallest common format (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>), then the following table is used to determine the output type: <table> <title>VipsSum type promotion</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <thead> <row> <entry>input type</entry> <entry>output type</entry> </row> </thead> <tbody> <row> <entry>uchar</entry> <entry>uint</entry> </row> <row> <entry>char</entry> <entry>int</entry> </row> <row> <entry>ushort</entry> <entry>uint</entry> </row> <row> <entry>short</entry> <entry>int</entry> </row> <row> <entry>uint</entry> <entry>uint</entry> </row> <row> <entry>int</entry> <entry>int</entry> </row> <row> <entry>float</entry> <entry>float</entry> </row> <row> <entry>double</entry> <entry>double</entry> </row> <row> <entry>complex</entry> <entry>complex</entry> </row> <row> <entry>double complex</entry> <entry>double complex</entry> </row> </tbody> </tgroup> </table> In other words, the output type is just large enough to hold the whole range of possible values. See also: vips_add().

0 on success, -1 on error

array of input images output image number of input images %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load output image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_svgload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load from image to write %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

string to load image to write %NULL-terminated list of optional named arguments

The @tests images are evaluated and at each point the index of the first non-zero value is written to @out. If all @tests are false, the value (@n + 1) is written. Images in @tests must have one band. They are expanded to the bounding box of the set of images in @tests, and that size is used for @out. @tests can have up to 255 elements. Combine with vips_case() to make an efficient multi-way vips_ifthenelse(). See also: vips_maplut(), vips_case(), vips_ifthenelse().

0 on success, -1 on error

test these images output index image number of input images %NULL-terminated list of optional named arguments

Optional arguments: * @in: array of input images * @out: output image * @in_format: write input files like this * @out_format: write output filename like this * @log: stdout of command is returned here vips_system() runs a command, optionally passing a set of images in and optionally getting an image back. The command's stdout is returned in @log. First, if @in is set, the array of images are written to files. See vips_image_new_temp_file() to see how temporary files are created. If @in_format is something like &percnt;s.png, the file will be written in PNG format. By default, @in_format is &percnt;s.tif. If @out_format is set, an output filename is formed in the same way. Any trailing [options] are stripped from @out_format. The command string to run is made by substituting the first set of &percnt;s in @cmd_format for the names of the input files, if @in is set, and then the next &percnt;s for the output filename, if @out_format is set. You can put a number between the &percnt; and the s to change the order in which the substitution occurs. The command is executed with popen() and the output captured in @log. After the command finishes, if @out_format is set, the output image is opened and returned in @out. You can append [options] to @out_format to control how this open happens. Closing @out image will automatically delete the output file. Finally the input images are deleted. For example, this call will run the ImageMagick convert program on an image, using JPEG files to pass images into and out of the convert command. |[ VipsArrayImage *in; VipsImage *out; char *log; if (vips_system("convert %s -swirl 45 %s", "in", in, "out", &out, "in_format", "%s.jpg", "out_format", "%s.jpg", "log", &log, NULL)) error ... ]|

0 on success, -1 on failure.

command to run %NULL-terminated list of optional named arguments

Optional arguments: * @font: %gchararray, font to render with * @fontfile: %gchararray, load this font file * @width: %gint, image should be no wider than this many pixels * @height: %gint, image should be no higher than this many pixels * @align: #VipsAlign, set justification alignment * @justify: %gboolean, justify lines * @dpi: %gint, render at this resolution * @autofit_dpi: %gint, read out auto-fitted DPI * @rgba: %gboolean, enable RGBA output * @spacing: %gint, space lines by this in points * @wrap: #VipsTextWrap, wrap lines on characters or words Draw the string @text to an image. @out is normally a one-band 8-bit unsigned char image, with 0 for no text and 255 for text. Values between are used for anti-aliasing. Set @rgba to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like `<span foreground="red">Red!</span>`. @text is the text to render as a UTF-8 string. It can contain Pango markup, for example `<i>The</i>Guardian`. @font is the font to render with, as a fontconfig name. Examples might be `sans 12` or perhaps `bitstream charter bold 10`. You can specify a font to load with @fontfile. You'll need to also set the name of the font with @font. @width is the number of pixels to word-wrap at. By default, lines of text wider than this will be broken at word boundaries. Use @wrap to set lines to wrap on word or character boundaries, or to disable line breaks. Set @justify to turn on line justification. @align can be used to set the alignment style for multi-line text to the low (left) edge centre, or high (right) edge. Note that the output image can be wider than @width if there are no word breaks, or narrower if the lines don't break exactly at @width. @height is the maximum number of pixels high the generated text can be. This only takes effect when @dpi is not set, and @width is set, making a box. In this case, vips_text() will search for a @dpi and set of line breaks which will just fit the text into @width and @height. You can use @autofit_dpi to read out the DPI selected by auto fit. @dpi sets the resolution to render at. "sans 12" at 72 dpi draws characters approximately 12 pixels high. @spacing sets the line spacing, in points. It would typically be something like font size times 1.2. You can read the coordinate of the top edge of the character from `Xoffset` / `Yoffset`. This can be helpful if you need to line up the output of several vips_text(). See also: vips_bandjoin(), vips_composite().

0 on success, -1 on error

output image utf-8 text string to render %NULL-terminated list of optional named arguments

Free any thread-private data and flush any profiling information. This function needs to be called when a thread that has been using vips exits. It is called for you by vips_shutdown() and for any threads created within the #VipsThreadPool. You will need to call it from threads created in other ways or there will be memory leaks. If you do not call it, vips will generate a warning message. It may be called many times, and you can continue using vips after calling it. Calling it too often will reduce performance.

vips_threadpool_run() loops a set of threads over an image. Threads take it in turns to allocate units of work (a unit might be a tile in an image), then run in parallel to process those units. An optional progress function can be used to give feedback. Optional arguments: * @height: %gint, target height in pixels * @size: #VipsSize, upsize, downsize, both or force * @no_rotate: %gboolean, don't rotate upright using orientation tag * @crop: #VipsInteresting, shrink and crop to fill target * @linear: %gboolean, perform shrink in linear light * @import_profile: %gchararray, fallback import ICC profile * @export_profile: %gchararray, export ICC profile * @intent: #VipsIntent, rendering intent * @fail_on: #VipsFailOn, load error types to fail on Make a thumbnail from a file. Shrinking is done in three stages: using any shrink-on-load features available in the file import library, using a block shrink, and using a lanczos3 shrink. At least the final 200% is done with lanczos3. The output should be high quality, and the operation should be quick. See vips_thumbnail_buffer() to thumbnail from a memory buffer, or vips_thumbnail_source() to thumbnail from an arbitrary byte source. By default, libvips will only use the first frame of animated or multipage images. To thumbnail all pages or frames, pass `n=-1` to the loader in @filename, for example `"x.gif[n=-1]"`. The output image will fit within a square of size @width x @width. You can specify a separate height with the @height option. Set either @width or @height to a very large number to ignore that dimension. If you set @crop, then the output image will fill the whole of the @width x @height rectangle, with any excess cropped away. See vips_smartcrop() for details on the cropping strategy. Normally the operation will upsize or downsize as required to fit the image inside or outside the target size. If @size is set to #VIPS_SIZE_UP, the operation will only upsize and will just copy if asked to downsize. If @size is set to #VIPS_SIZE_DOWN, the operation will only downsize and will just copy if asked to upsize. If @size is #VIPS_SIZE_FORCE, the image aspect ratio will be broken and the image will be forced to fit the target. Normally any orientation tags on the input image (such as EXIF tags) are interpreted to rotate the image upright. If you set @no_rotate to %TRUE, these tags will not be interpreted. Shrinking is normally done in sRGB colourspace. Set @linear to shrink in linear light colourspace instead. This can give better results, but can also be far slower, since tricks like JPEG shrink-on-load cannot be used in linear space. If you set @export_profile to the filename of an ICC profile, the image will be transformed to the target colourspace before writing to the output. You can also give an @import_profile which will be used if the input image has no ICC profile, or if the profile embedded in the input image is broken. Use @intent to set the rendering intent for any ICC transform. The default is #VIPS_INTENT_RELATIVE. Use @fail_on to control the types of error that will cause loading to fail. The default is #VIPS_FAIL_ON_NONE, ie. thumbnail is permissive. See also: vips_thumbnail_buffer().

0 on success, -1 on error.

file to read from output image target width in pixels %NULL-terminated list of optional named arguments

Optional arguments: * @height: %gint, target height in pixels * @size: #VipsSize, upsize, downsize, both or force * @no_rotate: %gboolean, don't rotate upright using orientation tag * @crop: #VipsInteresting, shrink and crop to fill target * @linear: %gboolean, perform shrink in linear light * @import_profile: %gchararray, fallback import ICC profile * @export_profile: %gchararray, export ICC profile * @intent: #VipsIntent, rendering intent * @fail_on: #VipsFailOn, load error types to fail on * @option_string: %gchararray, extra loader options Exactly as vips_thumbnail(), but read from a memory buffer. One extra optional argument, @option_string, lets you pass options to the underlying loader. See also: vips_thumbnail().

0 on success, -1 on error.

memory area to load size of memory area output image target width in pixels %NULL-terminated list of optional named arguments

Optional arguments: * @height: %gint, target height in pixels * @size: #VipsSize, upsize, downsize, both or force * @no_rotate: %gboolean, don't rotate upright using orientation tag * @crop: #VipsInteresting, shrink and crop to fill target * @linear: %gboolean, perform shrink in linear light * @import_profile: %gchararray, fallback import ICC profile * @export_profile: %gchararray, export ICC profile * @intent: #VipsIntent, rendering intent * @fail_on: #VipsFailOn, load error types to fail on * @option_string: %gchararray, extra loader options Exactly as vips_thumbnail(), but read from a source. One extra optional argument, @option_string, lets you pass options to the underlying loader. See also: vips_thumbnail().

0 on success, -1 on error.

source to thumbnail output image target width in pixels %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_tiffload().

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

0 on success, -1 on error.

source to load image to write %NULL-terminated list of optional named arguments

Optional arguments: * @in_max: input range * @out_max: output range * @Lb: black-point [0-100] * @Lw: white-point [0-100] * @Ps: shadow point (eg. 0.2) * @Pm: mid-tone point (eg. 0.5) * @Ph: highlight point (eg. 0.8) * @S: shadow adjustment (+/- 30) * @M: mid-tone adjustment (+/- 30) * @H: highlight adjustment (+/- 30) vips_tonelut() generates a tone curve for the adjustment of image levels. It is mostly designed for adjusting the L* part of a LAB image in a way suitable for print work, but you can use it for other things too. The curve is an unsigned 16-bit image with (@in_max + 1) entries, each in the range [0, @out_max]. @Lb, @Lw are expressed as 0-100, as in LAB colour space. You specify the scaling for the input and output images with the @in_max and @out_max parameters.

0 on success, -1 on error

output image %NULL-terminated list of optional named arguments

Allocate an area of memory aligned on a boundary specified by @align that will be tracked by vips_tracked_get_mem() and friends. If allocation fails, vips_tracked_aligned_alloc() returns %NULL and sets an error message. You must only free the memory returned with vips_tracked_aligned_free(). See also: vips_tracked_malloc(), vips_tracked_aligned_free(), vips_malloc().

a pointer to the allocated memory, or %NULL on error.

number of bytes to allocate specifies the alignment

Only use it to free memory that was previously allocated with vips_tracked_aligned_alloc() with a %NULL first argument. See also: vips_tracked_aligned_alloc().

memory to free

Exactly as close(2), but update the number of files currently open via vips_tracked_get_files(). This is used by the vips operation cache to drop cache when the number of files available is low. You must only close file descriptors opened with vips_tracked_open(). See also: vips_tracked_open(), vips_tracked_get_files().

a file descriptor, or -1 on error.

file to close()

Only use it to free memory that was previously allocated with vips_tracked_malloc() with a %NULL first argument. See also: vips_tracked_malloc().

memory to free

Returns the number of active allocations.

the number of active allocations

Returns the number of open files.

the number of open files

Returns the number of bytes currently allocated via vips_malloc() and friends. vips uses this figure to decide when to start dropping cache, see #VipsOperation.

the number of currently allocated bytes

Returns the largest number of bytes simultaneously allocated via vips_tracked_malloc(). Handy for estimating max memory requirements for a program.

the largest number of currently allocated bytes

Allocate an area of memory that will be tracked by vips_tracked_get_mem() and friends. If allocation fails, vips_tracked_malloc() returns %NULL and sets an error message. You must only free the memory returned with vips_tracked_free(). See also: vips_tracked_free(), vips_malloc().

a pointer to the allocated memory, or %NULL on error.

number of bytes to allocate

Exactly as open(2), but the number of files currently open via vips_tracked_open() is available via vips_tracked_get_files(). This is used by the vips operation cache to drop cache when the number of files available is low. You must only close the file descriptor with vips_tracked_close(). @pathname should be utf8. See also: vips_tracked_close(), vips_tracked_get_files().

a file descriptor, or -1 on error.

name of file to open flags for open() open mode

A selection of %GType definitions used by VIPS.

Search below @basename, return the %GType of the class whose name or @nickname matches, or 0 for not found. If @basename is NULL, the whole of #VipsObject is searched. This function uses a cache, so it should be quick. See also: vips_class_find()

the %GType of the class, or 0 if the class is not found.

name of base class search for a class with this nickname

Map over a type's children. Stop when @fn returns non-%NULL and return that value.

%NULL if @fn returns %NULL for all arguments, otherwise the first non-%NULL value from @fn.

base type call this function for every type client data client data

Map over a type's children, direct and indirect. Stop when @fn returns non-%NULL and return that value.

%NULL if @fn returns %NULL for all arguments, otherwise the first non-%NULL value from @fn.

base type call this function for every type client data

Get the pointer from an area. Don't touch count (area is static).

The pointer held by @value.

get from this value optionally return length here

Return the pointer to the array held by @value. Optionally return the other properties of the array in @n, @type, @sizeof_type. See also: vips_value_set_array().

The array address.

%GValue to get from return the number of elements here, optionally return the type of each element here, optionally return the sizeof each element here, optionally

Return the start of the array of doubles held by @value. optionally return the number of elements in @n. See also: vips_array_double_new().

The array address.

%GValue to get from return the number of elements here, optionally

Return the start of the array of images held by @value. optionally return the number of elements in @n. See also: vips_value_set_array_image().

The array address.

%GValue to get from return the number of elements here, optionally

Return the start of the array of ints held by @value. optionally return the number of elements in @n. See also: vips_array_int_new().

The array address.

%GValue to get from return the number of elements here, optionally

Return the start of the array of %GObject held by @value. Optionally return the number of elements in @n. See also: vips_area_new_array_object().

The array address.

%GValue to get from return the number of elements here, optionally

Returns the data pointer from a blob. Optionally returns the length too. blobs are things like ICC profiles or EXIF data. They are relocatable, and are saved to VIPS files for you coded as base64 inside the XML. They are copied by copying reference-counted pointers. See also: vips_value_set_blob()

The pointer held by @value.

GValue to set optionally return length of memory area

Get the C string held internally by the %GValue.

The C string held by @value.

%GValue to get from return length here, optionally

Get the C string held internally by the GValue.

The C string held by @value.

GValue to get from

Set value to be a ref-counted area of memory with a free function.

set this value data will be freed with this function set @value to track this pointer

Set @value to be an array of things. This allocates memory but does not initialise the contents: get the pointer and write instead.

%GValue to set number of elements the type of each element the sizeof each element

Set @value to hold a copy of @array. Pass in the array length in @n. See also: vips_array_double_get().

%GValue to get from array of doubles the number of elements

Set @value to hold an array of images. Pass in the array length in @n. See also: vips_array_image_get().

%GValue to get from the number of elements

Set @value to hold a copy of @array. Pass in the array length in @n. See also: vips_array_int_get().

%GValue to get from array of ints the number of elements

Set @value to hold an array of %GObject. Pass in the array length in @n. See also: vips_value_get_array_object().

%GValue to set the number of elements

Sets @value to hold a @data. When @value is freed, @data will be freed with @free_fn. @value also holds a note of the size of the memory area. blobs are things like ICC profiles or EXIF data. They are relocatable, and are saved to VIPS files for you coded as base64 inside the XML. They are copied by copying reference-counted pointers. See also: vips_value_get_blob()

GValue to set free function for @data pointer to area of memory length of memory area

Just like vips_value_set_blob(), but when @value is freed, @data will be freed with g_free(). This can be easier to call for language bindings. See also: vips_value_set_blob()

GValue to set pointer to area of memory length of memory area

Copies the C string @str into @value. vips_ref_string are immutable C strings that are copied between images by copying reference-counted pointers, making them much more efficient than regular %GValue strings. @str should be a valid utf-8 string.

%GValue to set C string to copy into the GValue

Copies the C string into @value. @str should be a valid utf-8 string.

GValue to set C string to copy into the GValue

Generates a string and copies it into @value.

GValue to set printf()-style format string arguments to printf()-formatted @fmt

Append a message to the error buffer. See also: vips_error().

the source of the error printf()-style format string for the error arguments to the format string

the system error code the source of the error printf()-style format string for the error arguments to the format string

Get the major, minor or micro library version, with @flag values 0, 1 and 2. Get the ABI current, revision and age (as used by Meson) with @flag values 3, 4, 5.

library version number

which field of the version to get

Get the VIPS version as a static string, including a build date and time. Do not free.

a static version string

Read an image from a video source. Start VIPS up, shut VIPS down, get version information, relocation. VIPS is a relocatable package, meaning you can move the directory tree you compiled it to at runtime and it will still be able to find all data files. This is required for OS X and Windows, but slightly unusual in the Unix world. See vips_init() and vips_guess_prefix(). Read in a vips image. See also: vips_vipssave().

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load from decompressed image %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

file to load decompressed image %NULL-terminated list of optional named arguments

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 #VipsObject::postclose signal on @out is a good place to free. See also: vips_webpload()

0 on success, -1 on error.

memory area to load size of memory area image to write %NULL-terminated list of optional named arguments

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

0 on success, -1 on error.

source to load from image to write %NULL-terminated list of optional named arguments

Perform #VIPS_OPERATION_MATH2_WOP on a pair of images. See vips_math2().

0 on success, -1 on error

left-hand input #VipsImage right-hand input #VipsImage output #VipsImage %NULL-terminated list of optional named arguments

Optional arguments: * @cell_size: %gint, size of Worley cells Create a one-band float image of Worley noise. See: https://en.wikipedia.org/wiki/Worley_noise Use @cell_size to set the size of the cells from which the image is constructed. The default is 256 x 256. If @width and @height are multiples of @cell_size, the image will tessellate. See also: vips_perlin(), vips_fractsurf(), vips_gaussnoise().

0 on success, -1 on error

output image horizontal size vertical size %NULL-terminated list of optional named arguments

Optional arguments: * @csize: %gint, size for third dimension * @dsize: %gint, size for fourth dimension * @esize: %gint, size for fifth dimension Create a two-band uint32 image where the elements in the first band have the value of their x coordinate and elements in the second band have their y coordinate. You can make any image where the value of a pixel is a function of its (x, y) coordinate by combining this operator with the arithmetic operators. Set @csize, @dsize, @esize to generate higher dimensions and add more bands. The extra dimensions are placed down the vertical axis. Use vips_grid() to change the layout. See also: vips_grey(), vips_grid(), vips_identity().

0 on success, -1 on error

output image horizontal size vertical size %NULL-terminated list of optional named arguments

Optional arguments: * @uchar: output a uchar image Create a one-band image of a zone plate. Pixels are normally in [-1, +1], set @uchar to output [0, 255]. See also: vips_eye(), vips_xyz().

0 on success, -1 on error

output image image size image size %NULL-terminated list of optional named arguments