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 [func@tracked_malloc] if you are allocating large amounts of memory. ::: seealso [func@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 [method@Image.tilecache] and [class@Foreign]. [enum@Vips.Access.RANDOM] means requests can come in any order. [enum@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 deprecated, use [enum@Vips.Access.SEQUENTIAL] instead See [method@Image.join] and so on. Operations like [method@Image.join] need to be told whether to align images on the low or high coordinate edge, or centre. ::: seealso [method@Image.join]. align low coordinate edge align centre align high coordinate edge See [method@Image.rot] and so on. Fixed rotate angles. ::: seealso [method@Image.rot]. no rotate 90 degrees clockwise 180 degree rotate 90 degrees anti-clockwise See [method@Image.rot45] and so on. Fixed rotate angles. ::: seealso [method@Image.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 [alias@GObject.Type], so the area can be an array. This type is used for things like passing an array of double or an array of [class@Object] pointers to operations, and for reference-counted immutable strings. Initial count == 1, so [method@Area.unref] after attaching somewhere. ::: seealso [method@Area.unref]. the new [struct@Area]. @data will be freed with this function data will be freed with this function An area which holds an array of elements of some [alias@GObject.Type]. To set values for the elements, get the pointer and write. ::: seealso [method@Area.unref]. the new [struct@Area]. [alias@GObject.Type] of elements to store `sizeof()` an element in the array number of elements in the array An area which holds an array of [class@GObject.Object] s. See [ctor@Area.new_array]. When the area is freed, each [class@GObject.Object] will be unreffed. Add an extra `NULL` element at the end, handy for eg. [func@Image.pipeline_array] etc. ::: seealso [method@Area.unref]. the new [struct@Area]. number of elements in the array Return the data pointer plus optionally the length in bytes of an area, the number of elements, the [alias@GObject.Type] of each element and the `sizeof()` each element. The pointer held by @area. [struct@Area] 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 libvips has a simple mechanism for automating at least some aspects of [class@GObject.Object] properties. You add a set of macros to your `_class_init()` which describe the arguments, and set the get and set functions to the libvips ones. See [extending](extending.html) for a complete example. Allocate a new property id. See [method@GObject.ObjectClass.install_property]. a new property id > 0 Loop over the [struct@Argument] of 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. [flags@Vips.ArgumentFlags.SET_ALWAYS] is handy for arguments which are set from C. For example, [property@Image: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. [flags@Vips.ArgumentFlags.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 [flags@Vips.ArgumentFlags.MODIFY] will be modified by the operation. This is used for things like the in-place drawing operations. [flags@Vips.ArgumentFlags.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 [method@Area.unref]. ::: seealso [struct@Area]. A new [struct@ArrayDouble]. array of double number of doubles Allocate a new array of @n doubles and copy @... into it. Free with [method@Area.unref]. ::: seealso [ctor@ArrayDouble.new] A new [struct@ArrayDouble]. number of doubles list of double arguments Fetch a double array from a [struct@ArrayDouble]. Useful for language bindings. array of double the [struct@ArrayDouble] to fetch from length of array Make an empty image array. Handy with [method@ArrayImage.append] for bindings which can't handle object array arguments. ::: seealso [method@ArrayImage.append]. A new [struct@ArrayImage]. Allocate a new array of images and copy @array into it. Free with [method@Area.unref]. The images will all be reffed by this function. They will be automatically unreffed for you by [method@Area.unref]. Add an extra `NULL` element at the end, handy for eg. [func@Image.pipeline_array] etc. ::: seealso [struct@Area]. A new [struct@ArrayImage]. array of [class@Image] number of images Allocate a new array of @n [class@Image] and copy @... into it. Free with [method@Area.unref]. The images will all be reffed by this function. They will be automatically unreffed for you by [method@Area.unref]. Add an extra `NULL` element at the end, handy for eg. [func@Image.pipeline_array] etc. ::: seealso [ctor@ArrayImage.new] A new [struct@ArrayImage]. number of images list of [class@Image] arguments Make a new [struct@ArrayImage], one larger than @array, with @image appended to the end. Handy with [ctor@ArrayImage.empty] for bindings which can't handle object array arguments. ::: seealso [ctor@ArrayImage.empty]. A new [struct@ArrayImage]. append to this add this Fetch an image array from a [struct@ArrayImage]. Useful for language bindings. array of [class@Image] the [struct@ArrayImage] to fetch from length of array Allocate a new array of ints and copy @array into it. Free with [method@Area.unref]. ::: seealso [struct@Area]. A new [struct@ArrayInt]. array of int number of ints Allocate a new array of @n ints and copy @... into it. Free with [method@Area.unref]. ::: seealso [ctor@ArrayInt.new] A new [struct@ArrayInt]. number of ints list of int arguments Fetch an int array from a [struct@ArrayInt]. Useful for language bindings. array of int the [struct@ArrayInt] to fetch from length of array Initialize a heap buffer. For example: ```c char txt[256]; VipsBuf buf = VIPS_BUF_STATIC(txt); ``` the storage area to use 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, [enum@Vips.BandFormat.USHORT] is `unsigned short`. 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 [func@Image.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 [ctor@Area.new], but track a length as well. The returned [struct@Blob] 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). ::: seealso [method@Area.unref]. the new [struct@Blob]. @data will be freed with this function data to store number of bytes in @data Get the data from a [struct@Blob]. ::: seealso [ctor@Blob.new]. the data [struct@Blob] 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. ::: seealso [ctor@Blob.new]. [struct@Blob] to set @data will be freed with this function data to store number of bytes in @data Like [ctor@Blob.new], but take a copy of the data. Useful for bindings which struggle with callbacks. ::: seealso [ctor@Blob.new]. the new [struct@Blob]. data to store number of bytes in @data 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: ```c 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)); ``` Return the contents of the buffer as a C string. the `NULL`-terminated contents of the buffer. This is a pointer to the memory managed by the buffer and must not be freed. the buffer Turn a number of bytes into a sensible string ... eg "12", "12KB", "12MB", "12GB" etc. `FALSE` on overflow, `TRUE` otherwise. the buffer the number of bytes Append a single character @ch to @buf. `FALSE` on overflow, `TRUE` otherwise. the buffer the character to append to the buffer Append a number. If the number is -ve, add brackets. Needed for building function arguments. `FALSE` on overflow, `TRUE` otherwise. the buffer value to format and append Format the string and append to @buf. `FALSE` on overflow, `TRUE` otherwise. the buffer `printf()`-style format string arguments to format string Append a double, non-localised. Useful for config files etc. `FALSE` on overflow, `TRUE` otherwise. the buffer value to format and append Format and append a [struct@GObject.Value] as a printable thing. We display text like "3144 bytes of binary data" for BLOBs like icc-profile-data. Use [method@Image.get_as_string] to make a text representation of a field. That will base64-encode blobs, for example. `FALSE` on overflow, `TRUE` otherwise. the buffer [struct@GObject.Value] to format and append Append at most @sz chars from @str to @buf. @sz < 0 means unlimited. This is the low-level append operation: functions like [method@Buf.appendf] build on top of this. `FALSE` on overflow, `TRUE` otherwise. the buffer the string to append to the buffer the size of the string to append Append the whole of @str to @buf. `FALSE` on overflow, `TRUE` otherwise. the buffer the string to append to the buffer Swap the rightmost occurrence of @o for @n. `FALSE` on overflow, `TRUE` otherwise. the buffer the string to search for the string to substitute Destroy a buffer. Only needed for heap buffers. Leaves the buffer in the _init state. the buffer Trim to just the first line (excluding "\n"). the `NULL`-terminated contents of the buffer. This is a pointer to the memory managed by the buffer and must not be freed. the buffer Initialize a buffer. the buffer Initialise and attach to a heap memory area. The memory area needs to be at least 4 bytes long. ```c VipsBuf buf; vips_buf_init_dynamic(&buf, 256); ``` Dynamic buffers must be freed with [method@Buf.destroy], but their size can be set at runtime. the buffer the size of the storage area Initialise and attach to a static memory area. [func@BUF_STATIC] is usually more convenient. For example: ```c char txt[256]; VipsBuf buf; vips_buf_init_static(&buf, txt, 256); ``` Static buffers don't need to be freed when they go out of scope, but their size must be set at compile-time. the buffer the start of the memory area to use for storage the size of the storage area `TRUE` if the buffer is empty. the buffer `TRUE` if the buffer is full. the buffer the number of characters currently in the buffer. the buffer Remove the last character, if it's @ch. `TRUE` if a character was removed, `FALSE` otherwise. the buffer the character to remove Reset the buffer to the empty string. the buffer Attach the buffer to a heap memory area. The buffer needs to have been initialised. The memory area needs to be at least 4 bytes long. the buffer the size of the storage area Attach the buffer to a static memory area. The buffer needs to have been initialised. The memory area needs to be at least 4 bytes long. the buffer the start of the memory area to use for storage the size of the storage area Append to @buf, args as [`vprintf()`](man:vprintf(3)). `FALSE` on overflow, `TRUE` otherwise. the buffer `printf()`-style format string arguments to format string 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 [method@Image.compass], for example. take the maximum of the possible values sum all the values take the minimum value See [method@Image.draw_image] and so on. Operations like [method@Image.draw_image] need to be told how to combine images from two sources. ::: seealso [method@Image.join]. set pixels to the new value add pixels A direction on a compass. Used for [method@Image.gravity], for example. centre north east south west north-east south-east south-west north-west An abstract base class representing a source or sink of bytes. It can be connected to a network socket, for example, or perhaps a Node.js stream, or to an area of memory. This allows it to support operations like JPEG loading, see for example [ctor@Image.jpegload_source]. Subclass to add other input sources. Use [class@SourceCustom] and [class@TargetCustom] to make a source or target with action signals. These classes provide action signals such as: - [signal@SourceCustom::read] for reading data from a custom source. - [signal@SourceCustom::seek] for seeking within a data stream. - [signal@TargetCustom::write] for writing data to a custom target. any filename associated with this connection, or `NULL`. connection to operate on a string describing this connection which could be displayed to a user. connection to operate on 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. Make sure @dbuf has at least @size bytes available after the write point. `FALSE` on out of memory, `TRUE` otherwise. the buffer the size to allocate Destroy @dbuf. This frees any allocated memory. Useful for dbufs on the stack. the buffer Return a pointer to an area you can write to, return length of area in @size. Use [method@Dbuf.allocate] before this call to set a minimum amount of space to have available. The write point moves to just beyond the returned block. Use [method@Dbuf.seek] to move it back again. start of write area. the buffer optionally return length in bytes here Initialize @dbuf. You can also just init to zero, eg. `VipsDbuf buf = {0};`. Destroy with [method@Dbuf.destroy]. the buffer Make sure @dbuf is at least @size bytes. `FALSE` on out of memory, `TRUE` otherwise. the buffer the minimum size Up to @size bytes are read from the buffer and copied to @data. The number of bytes transferred is returned. the number of bytes transferred. the buffer read to this area read up to this many bytes Reset the buffer to empty. No memory is freed, just the data size and write point are reset. the buffer Move the write point. @whence can be `SEEK_SET`, `SEEK_CUR`, `SEEK_END`, with the usual meaning. the buffer how to move the write point from start, from end, from current Destroy a buffer, but rather than freeing memory, a pointer is returned. This must be freed with [func@GLib.free]. A `\0` is appended, but not included in the character count. This is so the pointer can be safely treated as a C string. The pointer held by @dbuf. the buffer optionally return length in bytes here Return a pointer to @dbuf's internal data. A `\0` is appended, but not included in the character count. This is so the pointer can be safely treated as a C string. The pointer held by @dbuf. the buffer optionally return length in bytes here the current write point the buffer Truncate the data so that it ends at the write point. No memory is freed. the buffer Append @size bytes from @data. @dbuf expands if necessary. `FALSE` on out of memory, `TRUE` otherwise. the buffer the data to write to the buffer the size of the len to write Write @str to @dbuf, but escape stuff that xml hates in text. Our argument string is utf-8. XML rules: - We must escape &<> - Don't escape \n, \t, \r - Do escape the other ASCII codes. `FALSE` on out of memory, `TRUE` otherwise. the buffer string to write Format the string and write to @dbuf. `FALSE` on out of memory, `TRUE` otherwise. the buffer `printf()`-style format string arguments to format string See [method@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, [method@Image.generate] will use the most general style requested by the operations in the pipeline. [enum@Vips.DemandStyle.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. [enum@Vips.DemandStyle.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 [method@Image.conv]. [enum@Vips.DemandStyle.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. [enum@Vips.DemandStyle.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 [ctor@Image.black] where the pixels are calculated. ::: seealso [method@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 [method@Image.flip], [method@Image.join] and so on. Operations like [method@Image.flip] need to be told whether to flip left-right or top-bottom. ::: seealso [method@Image.flip], [method@Image.join]. left-right top-bottom Areas under curves for equal energy illuminant E. See [method@Image.embed], [method@Image.conv], [method@Image.affine] and so on. When the edges of an image are extended, you can specify how you want the extension done. [enum@Vips.Extend.BLACK] -- new pixels are black, ie. all bits are zero. [enum@Vips.Extend.COPY] -- each new pixel takes the value of the nearest edge pixel [enum@Vips.Extend.REPEAT] -- the image is tiled to fill the new area [enum@Vips.Extend.MIRROR] -- the image is reflected and tiled to reduce hash edges [enum@Vips.Extend.WHITE] -- new pixels are white, ie. all bits are set [enum@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. ::: seealso [method@Image.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 [enum@Vips.FailOn.ERROR] implies [enum@Vips.FailOn.TRUNCATED]. never stop stop on image truncated, nothing else stop on serious error or truncation stop on anything, even warnings An abstract base class to 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, [class@Source] and [class@Target]. Use [func@Foreign.find_load] [func@Foreign.find_load_buffer] and [func@Foreign.find_load_source] to find a loader for an object. Use [func@Foreign.find_save], [func@Foreign.find_save_buffer] and [func@Foreign.find_save_target] to find a saver for a format. You can then run these operations using [func@call] and friends to perform the load or save. [method@Image.write_to_file] and [ctor@Image.new_from_file] and friends use these functions to automate file load and save. You can also invoke the operations directly, for example: ```c 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 [method@Image.set_int] and friends. During save, you can use `keep` to specify which metadata to retain, defaults to all, see [flags@ForeignKeep]. 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 [method@Image.get_page_height] and [method@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 [class@ForeignLoad] or [class@ForeignSave]. If you define a new operation which is a subclass of [class@Foreign], support for it automatically appears in all libvips user-interfaces. It will also be transparently supported by [ctor@Image.new_from_file] and friends. Searches for an operation you could use to load @filename. Any trailing options on @filename are stripped and ignored. ::: seealso [func@Foreign.find_load_buffer], [ctor@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 ::: seealso [ctor@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 ::: seealso [ctor@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. ::: seealso [func@Foreign.find_save_buffer], [method@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. ::: seealso [method@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. ::: seealso [method@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 [func@Foreign.find_load] to detect type for a specific file. Free the return result with [func@GLib.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 [class@Foreign] 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`. ::: seealso [func@slist_map2]. the result of iteration base class to search below (eg. "VipsForeignLoad") function to apply to each [class@Foreign] user data user data The set of coding types supported by a saver. ::: seealso [enum@Coding]. saver supports [enum@Vips.Coding.NONE] saver supports [enum@Vips.Coding.LABQ] saver supports [enum@Vips.Coding.RAD] saver supports all coding types What container format to use. 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. [flags@Vips.ForeignFlags.PARTIAL] means that the image can be read directly from the file without needing to be unpacked to a temporary image first. [flags@Vips.ForeignFlags.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. [flags@Vips.ForeignFlags.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 [method@Image.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) keep the gainmap metadata keep all metadata An abstract base class to load images in a variety of formats. ## Writing a new loader Add a new loader to libvips by subclassing [class@ForeignLoad]. Subclasses need to implement at least [vfunc@ForeignLoad.header]. [vfunc@ForeignLoad.header] must set at least the header fields of `out`. [vfunc@ForeignLoad.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 [func@Foreign.is_a]. You should also define [property@Object:nickname] and [property@Object:description] in [class@Object]. As a complete example, here's code for a PNG loader, minus the actual calls to libpng. ```c 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) { } ``` Each page of a PDF document can contain multiple page boxes, also known as boundary boxes or print marks. Each page box defines a region of the complete page that should be rendered. The default region is the crop box. media box crop box trim box bleed box art box 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. [enum@Vips.ForeignPpmFormat.PBM] images are single bit. [enum@Vips.ForeignPpmFormat.PGM] images are 8, 16, or 32-bits, one band. [enum@Vips.ForeignPpmFormat.PPM] images are 8, 16, or 32-bits, three bands. [enum@Vips.ForeignPpmFormat.PFM] images are 32-bit float pixels. [enum@Vips.ForeignPpmFormat.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 An abstract base class to save images in a variety of formats. ## Writing a new saver Call your saver in the class' [vfunc@Object.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. ```c 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_FOREIGN_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"); } ``` The set of image types supported by a saver. ::: seealso [class@ForeignSave]. saver supports everything (eg. TIFF) 1 band 3 bands 4 bands an extra band 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 Create a new [class@Gio.InputStream] wrapping a [class@Source]. This is useful for loaders like SVG and PDF which support [class@Gio.InputStream] methods. ::: seealso [ctor@SourceGInputStream.new] a new [class@Gio.InputStream] vips source to wrap Fill @out->valid with pixels. @seq contains per-thread state, such as the input regions. Set @stop to `TRUE` to stop processing. ::: seealso [method@Image.generate], [func@stop_many]. 0 on success, -1 on error. [class@Region] 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 [alias@Pel] \*. 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. ::: seealso [method@Image.wio_input], [method@Image.inplace], [func@REGION_ADDR]. a [class@Image] x coordinate y coordinate a [class@Image] a [class@Image] a [class@Image] a [class@Image] a [class@Image] [func@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 [func@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, [func@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. [func@INIT] is a macro, since it tries to check ABI compatibility between the caller and the library. You can also call [func@init], the non-macro version, if macros are not available to you. You may call [func@INIT] many times and [func@shutdown] many times, but you must not call [func@INIT] after [func@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. [func@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 [func@guess_prefix] - creates the main vips types, including [class@Image] 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: ```c int main(int argc, char **argv) { if (VIPS_INIT(argv[0])) vips_error_exit("unable to start VIPS"); vips_shutdown(); return 0; } ``` ::: seealso [func@shutdown], [func@add_option_entries], [func@version], [func@guess_prefix], [func@guess_libdir]. name of application [const@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. The [class@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 [ctor@Image.new_from_file] and friends. Creating an image is fast. libvips 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 [method@Image.get_width] or [method@GObject.Object.get], to get [class@GObject.Object] properties. `.v` 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. libvips supports 10 formats, from 8-bit unsigned integer up to 128-bit double complex, see [method@Image.get_format]. In libvips, 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, libvips has [method@Image.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 an RGB image by mistake and you'll just get nonsense. libvips has a feature to help (a little) with this: it sets a [enum@Interpretation] hint for each image (see [method@Image.get_interpretation]); a hint which says how pixels should be interpreted. For example, [method@Image.Lab2XYZ] will set the interpretation of the output image to [enum@Vips.Interpretation.XYZ]. A few utility operations will also use interpretation as a guide. For example, you can give [method@Image.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 [method@Image.invert] to manipulate your images. When you are done, you can write images to disc files (with [method@Image.write_to_file]), to formatted memory buffers (with [method@Image.write_to_buffer]) and to C-style memory arrays (with [method@Image.write_to_memory]). You can also write images to other images. Create, for example, a temporary disc image with [ctor@Image.new_temp_file], then write your image to that with [method@Image.write]. You can create several other types of image and write to them, see [ctor@Image.new_memory], for example. See [class@Operation] for an introduction to running operations on images, see [Image headers](libvips-header.html) for getting and setting image metadata. See [class@Object] for a discussion of the lower levels. A renamed [ctor@Image.new_memory] ... Some gobject binding systems do not like more than one `_new()` method. ::: seealso [ctor@Image.new_memory]. the new [class@Image], or `NULL` on error. [ctor@Image.new] creates a new, empty [class@Image]. 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 [method@Image.generate] or [method@Image.write_line]. Write a whole image to another image with [method@Image.write]. the new [class@Image], or `NULL` on error. Loads an image from the formatted area of memory @buf, @len using the loader recommended by [func@Foreign.find_load_buffer]. To load an unformatted area of memory, use [ctor@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 [signal@Object::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. ::: seealso [method@Image.write_to_buffer]. the new [class@Image], or `NULL` on error. image data length of memory buffer set of extra options as a string `NULL`-terminated list of optional named arguments [ctor@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 [ctor@Image.jpegload], for example. [ctor@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 [enum@Access] hint giving the expected access pattern for this file. [enum@Vips.Access.RANDOM] means you can fetch pixels randomly from the image. This is the default mode. [enum@Vips.Access.SEQUENTIAL] means you will read the whole image exactly once, top-to-bottom. In this mode, libvips 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 [enum@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 [ctor@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: ```c VipsImage *image = vips_image_new_from_file("fred.tif", "page", 12, NULL); ``` Will open "fred.tif", reading page 12. ```c VipsImage *image = vips_image_new_from_file("fred.jpg[shrink=2]", NULL); ``` Will open `fred.jpg`, downsampling by a factor of two. Use [func@Foreign.find_load] or [func@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 [ctor@Image.jpegload], for example. ::: tip "Optional arguments" * @access: [enum@Access], hint expected access pattern * @memory: `gboolean`, force load via memory ::: seealso [func@Foreign.find_load], [func@Foreign.is_a], [method@Image.write_to_file]. the new [class@Image], 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. ::: seealso [method@Image.draw_circle]. the new [class@Image], or `NULL` on error. filename to open This function maps the named file and returns a [class@Image] you can use to read it. It returns an 8-bit image with @bands bands. If the image is not 8-bit, use [method@Image.copy] to transform the descriptor after loading it. ::: seealso [method@Image.copy], [ctor@Image.rawload], [ctor@Image.new_from_file]. the new [class@Image], 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. ::: seealso [ctor@Image.new_from_image1] the new [class@Image], 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. ::: seealso [ctor@Image.new_from_image] the new [class@Image], or `NULL` on error. image to copy constants This function wraps a [class@Image] around a memory area. The memory area must be a simple array, for example RGBRGBRGB, left-to-right, top-to-bottom. Use [ctor@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 [signal@Object::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 [ctor@Image.new_from_memory_copy] instead if you are at all unsure. Use [method@Image.copy] to set other image properties. ::: seealso [ctor@Image.new], [method@Image.write_to_memory], [ctor@Image.new_from_memory_copy]. the new [class@Image], 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 [ctor@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. ::: seealso [ctor@Image.new_from_memory]. the new [class@Image], 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 [func@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. ::: seealso [method@Image.write_to_target]. the new [class@Image], 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 [enum@Vips.BandFormat.DOUBLE] image held in memory. Use [func@IMAGE_ADDR], or [func@MATRIX] to address pixels in the image. Use [method@Image.set_double] to set "scale" and "offset", if required. ::: seealso [ctor@Image.new_matrixv] the new [class@Image], or `NULL` on error. image width image height A binding-friendly version of [ctor@Image.new_matrixv]. the new [class@Image], or `NULL` on error. image width image height array of elements number of elements As [ctor@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. ::: seealso [ctor@Image.new_matrix] the new [class@Image], or `NULL` on error. image width image height matrix coefficients [ctor@Image.new_memory] creates a new [class@Image] which, when written to, will create a memory image. ::: seealso [ctor@Image.new]. the new [class@Image], or `NULL` on error. Make a [class@Image] 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. ::: seealso [ctor@Image.new]. the new [class@Image], or `NULL` on error. format of file the maximum numeric value possible for this format. the format A renamed [ctor@Image.new_matrix_from_array]. Some gobject bindings do not like more than one _new method. the new [class@Image], or `NULL` on error. image width image height array of elements number of elements Add an image to a pipeline. @image depends on all of the images in @in, @image prefers to supply pixels according to @hint. Operations can set demand hints, that is, hints to the VIPS IO system about the type of region geometry they work best with. For example, operations which transform coordinates will usually work best with [enum@Vips.DemandStyle.SMALLTILE], operations which work on local windows of pixels will like [enum@Vips.DemandStyle.FATSTRIP]. Header fields in @image are set from the fields in @in, with lower-numbered images in @in taking priority. For example, if @in[0] and @in[1] both have an item called "icc-profile", it's the profile attached to @in[0] that will end up on @image. Image history is completely copied from all @in. @image will have the history of all the input images. The array of input images can be empty, meaning @image is at the start of a pipeline. VIPS uses the list of input images to build the tree of operations it needs for the cache invalidation system. ::: seealso [method@Image.pipelinev], [method@Image.generate]. 0 on success, -1 on error. output image demand hint for @image `NULL`-terminated array of input images Turn LCh to CMC. ::: seealso [method@Image.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 [method@Image.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 [method@Image.Lab2LCh] for a much better colour space. ::: seealso [method@Image.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. ::: seealso [method@Image.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 ([enum@Vips.Coding.LABQ]). ::: seealso [method@Image.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. ::: seealso [method@Image.LabQ2Lab]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Turn Lab to XYZ. The colour temperature defaults to D65, but can be specified with @temp. ::: tip "Optional arguments" * @temp: [struct@ArrayDouble], colour temperature 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Unpack a LabQ ([enum@Vips.Coding.LABQ]) image to a three-band float image. ::: seealso [method@Image.LabQ2Lab], [method@Image.LabQ2LabS], [method@Image.rad2float]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Unpack a LabQ ([enum@Vips.Coding.LABQ]) image to a three-band short image. ::: seealso [method@Image.LabS2LabQ], [method@Image.LabQ2LabS], [method@Image.rad2float]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Unpack a LabQ ([enum@Vips.Coding.LABQ]) image to a three-band short image. ::: seealso [method@Image.LabS2LabQ], [method@Image.LabQ2sRGB], [method@Image.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. ::: seealso [method@Image.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 ::: seealso [method@Image.LabQ2LabS]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Turn Oklab to Oklch. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Transform Oklab to XYZ using D65 illuminant. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Turn Oklch to Oklab. 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 [method@Image.icc_export] instead. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Turn XYZ to Lab, optionally specifying the colour temperature. @temp defaults to D65. ::: tip "Optional arguments" * @temp: [struct@ArrayDouble], colour temperature 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Transform XYZ to Oklab assuming D65 illuminant. 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, [`fabs()`](man:fabs(3)) for float types, and calculates modulus for complex types. ::: seealso [method@Image.sign]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.ACOS] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.ACOSH] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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 [arithmetic](libvips-arithmetic.html)), then the following table is used to determine the output type: ## [method@Image.add] type promotion | input type | output type | |----------------|----------------| | uchar | ushort | | char | short | | ushort | uint | | short | int | | uint | uint | | int | int | | float | float | | double | double | | complex | complex | | double complex | double complex | In other words, the output type is just large enough to hold the whole range of possible values. ::: seealso [method@Image.subtract], [method@Image.linear]. 0 on success, -1 on error input image input image output image `NULL`-terminated list of optional named arguments Append an alpha channel. ::: seealso [method@Image.hasalpha]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments 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. [enum@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 [method@Image.premultiply], set @premultiplied. This operation does not change xres or yres. The image resolution needs to be updated by the application. ::: tip "Optional arguments" * @interpolate: [class@Interpolate], interpolate pixels with this * @oarea: [struct@ArrayInt], output rectangle * @idx: `gdouble`, input horizontal offset * @idy: `gdouble`, input vertical offset * @odx: `gdouble`, output horizontal offset * @ody: `gdouble`, output vertical offset * @extend: [enum@Extend], how to generate new pixels * @background: [struct@ArrayDouble] colour for new pixels * @premultiplied: `gboolean`, images are already premultiplied ::: seealso [method@Image.shrink], [method@Image.resize], [class@Interpolate]. 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 [enum@Vips.OperationBoolean.AND] on a pair of images. See [method@Image.boolean]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.AND] on an image and an array of constants. See [method@Image.boolean_const]. ::: seealso [method@Image.boolean], [method@Image.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 [enum@Vips.OperationBoolean.AND] on an image and a constant. See [method@Image.boolean_const1]. ::: seealso [method@Image.boolean], [method@Image.boolean_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.ASIN] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.ASINH] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.ATAN] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.ATAN2] on a pair of images. See [method@Image.math2]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.ATAN2] on an image and a constant. See [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.ATAN2] on an image and a constant. See [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.ATANH] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Look at the image metadata and rotate and flip the image to make it upright. The [const@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. ::: tip "Optional arguments" * @angle: [enum@Angle], output, the image was rotated by * @flip: `gboolean`, output, whether the image was 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 [method@Image.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 [method@Image.stats] if you need to calculate an average for each band. For complex images, return the average modulus. ::: seealso [method@Image.stats], [method@Image.bandmean], [method@Image.deviate], [method@Image.rank] 0 on success, -1 on error input [class@Image] output pixel average `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.AND] on an image. See [method@Image.bandbool]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] `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 [enum@Vips.OperationBoolean.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 [method@Image.relational]. You can use it to see if all image bands match exactly. ::: seealso [method@Image.boolean_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] boolean operation to perform `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.EOR] on an image. See [method@Image.bandbool]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @factor: `gint`, fold by this factor ::: seealso [ctor@Image.csvload], [method@Image.bandunfold]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Join a pair of images together, bandwise. See [func@Image.bandjoin]. 0 on success, -1 on error first input image second input image output image `NULL`-terminated list of optional named arguments Append a set of constant bands to an image. ::: seealso [func@Image.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. ::: seealso [method@Image.add], [method@Image.avg], [method@Image.recomb] 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.OR] on an image. See [method@Image.bandbool]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @factor: `gint`, unfold by this factor ::: seealso [ctor@Image.csvload], [method@Image.bandfold]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments 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 [arithmetic](libvips-arithmetic.html)). ::: seealso [method@Image.boolean_const]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] boolean operation to perform `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. ::: seealso [method@Image.boolean], [method@Image.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 [method@Image.boolean_const]. ::: seealso [method@Image.boolean], [method@Image.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 [enum@Vips.BandFormat.DOUBLE], use [method@Image.cast] to change it to the type you need. For example, consider this 2 x 2 matrix of (x, y) coordinates: ``` 2 2 0 0 255 100 ``` We then generate a 1 x 256 element LUT like this: | Index | Value | |-------|-------| | 0 | 0 | | 1 | 0.4 | | etc. | 0.4 | | 255 | 100 | 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. ::: seealso [ctor@Image.identity], [method@Image.invertlut], [method@Image.cast], [method@Image.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. ::: seealso [ctor@Image.rawload]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments 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 [enum@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. ::: tip "Optional arguments" * @sigma: `gdouble`, sigma for gaussian blur * @precision: [enum@Precision], calculation accuracy ::: seealso [method@Image.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 [func@Image.switch] to make something like a case statement or a multi-way [method@Image.ifthenelse]. ::: seealso [method@Image.maplut], [func@Image.switch], [method@Image.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 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. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted ::: seealso [method@Image.scale], [method@Image.complexform], [method@Image.real], [method@Image.imag], [method@Image.cast_uchar], [method@Image.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 [enum@Vips.BandFormat.CHAR]. See [method@Image.cast]. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.COMPLEX]. See [method@Image.cast]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.DOUBLE]. See [method@Image.cast]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.DPCOMPLEX]. See [method@Image.cast]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.FLOAT]. See [method@Image.cast]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.INT]. See [method@Image.cast]. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.SHORT]. See [method@Image.cast]. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.UCHAR]. See [method@Image.cast]. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.UINT]. See [method@Image.cast]. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Convert @in to [enum@Vips.BandFormat.USHORT]. See [method@Image.cast]. ::: tip "Optional arguments" * @shift: `gboolean`, integer values are shifted 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Round to an integral value with [enum@Vips.OperationRound.CEIL]. See [method@Image.round]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments This operation clamps pixel values to a range, by default 0 - 1. Use @min and @max to change the range. ::: tip "Optional arguments" * @min: `gdouble`, minimum value * @max: `gdouble`, maximum value ::: seealso [method@Image.sign], [method@Image.abs], [ctor@Image.sdf]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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 [enum@Vips.Interpretation.YXY], running [method@Image.colourspace] with @space set to [enum@Vips.Interpretation.LAB] will convert with [method@Image.Yxy2XYZ] and [method@Image.XYZ2Lab]. ::: tip "Optional arguments" * @source_space: [enum@Interpretation], input colour space ::: seealso [method@Image.colourspace_issupported], [method@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 [method@Image.colourspace] can process. `TRUE` if @image is in a supported colourspace. input image 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. ::: tip "Optional arguments" * @times: `gint`, how many times to rotate and convolve * @angle: [enum@Angle45], rotate mask by this much between colvolutions * @combine: [enum@Combine], combine results like this * @precision: [enum@Precision], precision for blur, default float * @layers: `gint`, number of layers for approximation * @cluster: `gint`, cluster lines closer than this distance ::: seealso [method@Image.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 [class@Image] output [class@Image] complex operation to perform `NULL`-terminated list of optional named arguments 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 [class@Image] input [class@Image] output [class@Image] 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 [enum@Vips.BandFormat.DOUBLE], @out is [enum@Vips.BandFormat.DPCOMPLEX]. Otherwise @out is [enum@Vips.BandFormat.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. ::: seealso [method@Image.complexget]. 0 on success, -1 on error input image input image output image `NULL`-terminated list of optional named arguments Get components of complex images. The output type is the same as the input type, except [enum@Vips.BandFormat.COMPLEX] becomes [enum@Vips.BandFormat.FLOAT] and [enum@Vips.BandFormat.DPCOMPLEX] becomes [enum@Vips.BandFormat.DOUBLE]. 0 on success, -1 on error input [class@Image] output [class@Image] complex operation to perform `NULL`-terminated list of optional named arguments Composite @overlay on top of @base with @mode. See [func@Image.composite]. ::: tip "Optional arguments" * @compositing_space: [enum@Interpretation] to composite in * @premultiplied: `gboolean`, images are already premultiplied * @x: `gint`, position of overlay * @y: `gint`, position of overlay 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 [enum@Vips.OperationComplex.CONJ] on an image. See [method@Image.complex]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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 [enum@Vips.Precision.FLOAT]. The output image is always [enum@Vips.BandFormat.FLOAT] unless @in is [enum@Vips.BandFormat.DOUBLE], in which case @out is also [enum@Vips.BandFormat.DOUBLE]. If @precision is [enum@Vips.Precision.INTEGER], then elements of @mask are converted to integers before convolution, using `rint()`, and the output image always has the same [enum@BandFormat] as the input image. For [enum@Vips.BandFormat.UCHAR] images and [enum@Vips.Precision.INTEGER] @precision, [method@Image.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 [func@vector_set_enabled]. If @precision is [enum@Vips.Precision.APPROXIMATE] then, like [enum@Vips.Precision.INTEGER], @mask is converted to int before convolution, and the output image always has the same [enum@BandFormat] 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. ::: tip "Optional arguments" * @precision: [enum@Precision], calculation accuracy * @layers: `gint`, number of layers for approximation * @cluster: `gint`, cluster lines closer than this distance ::: seealso [method@Image.convsep]. 0 on success, -1 on error input image output image convolve with this mask `NULL`-terminated list of optional named arguments Perform an approximate integer convolution of @in with @mask. This is a low-level operation, see [method@Image.conv] for something more convenient. The output image always has the same [enum@BandFormat] 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. ::: tip "Optional arguments" * @layers: `gint`, number of layers for approximation * @cluster: `gint`, cluster lines closer than this distance ::: seealso [method@Image.conv]. 0 on success, -1 on error input image output image convolution mask `NULL`-terminated list of optional named arguments Approximate separable integer convolution. This is a low-level operation, see [method@Image.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 [enum@BandFormat] as the input image. ::: tip "Optional arguments" * @layers: `gint`, number of layers for approximation ::: seealso [method@Image.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 [method@Image.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 [enum@Vips.BandFormat.FLOAT] unless @in is [enum@Vips.BandFormat.DOUBLE], in which case @out is also [enum@Vips.BandFormat.DOUBLE]. ::: seealso [method@Image.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 [method@Image.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 [enum@BandFormat] as the input image. For [enum@Vips.BandFormat.UCHAR] images, [method@Image.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 [func@vector_set_enabled]. ::: seealso [method@Image.conv]. 0 on success, -1 on error input image output image convolve with this mask `NULL`-terminated list of optional named arguments Perform a separable convolution of @in with @mask. See [method@Image.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. ::: tip "Optional arguments" * @precision: [enum@Precision], calculation accuracy * @layers: `gint`, number of layers for approximation * @cluster: `gint`, cluster lines closer than this distance ::: seealso [method@Image.conv], [ctor@Image.gaussmat]. 0 on success, -1 on error input image output image convolution mask `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @width: `gint`, set image width * @height: `gint`, set image height * @bands: `gint`, set image bands * @format: [enum@BandFormat], set image format * @coding: [enum@Coding], set image coding * @interpretation: [enum@Interpretation], set image interpretation * @xres: `gdouble`, set image xres * @yres: `gdouble`, set image yres * @xoffset: `gint`, set image xoffset * @yoffset: `gint`, set image yoffset ::: seealso [method@Image.byteswap], [method@Image.bandfold], [method@Image.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 [ctor@Image.new_temp_file]. The file is automatically deleted when @out is closed. ::: seealso [method@Image.copy], [ctor@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. [method@Image.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 [method@Image.wio_input]. If you are sure that @image is not shared with another thread (perhaps you have made it yourself), use [method@Image.wio_input] instead. ::: seealso [method@Image.wio_input]. the new [class@Image], or `NULL` on error. image to copy to a memory buffer Perform [enum@Vips.OperationMath.COS] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.COSH] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `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. ::: seealso [method@Image.morph], [method@Image.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 [method@Image.extract_area]. ::: seealso [method@Image.extract_band], [method@Image.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 Perform [enum@Vips.OperationComplex2.CROSS_PHASE] on an image. See [method@Image.complex2]. 0 on success, -1 on error input [class@Image] input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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). ::: tip "Optional arguments" * @separator: `gchararray`, separator string ::: seealso [method@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 [method@Image.csvsave], but save to a target. ::: tip "Optional arguments" * @separator: `gchararray`, separator string ::: seealso [method@Image.csvsave]. 0 on success, -1 on error. image to save save image to this target `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. ::: seealso [method@Image.colourspace] 0 on success, -1 on error first input image second input image output image `NULL`-terminated list of optional named arguments A convenience function to unpack to a format that we can compute with. @out.coding is always [enum@Vips.Coding.NONE]. This unpacks LABQ to plain LAB. Use [method@Image.LabQ2LabS] for a bit more speed if you need it. ::: seealso [method@Image.encode], [method@Image.LabQ2Lab], [method@Image.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. ::: seealso [method@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 [method@Image.stats] if you need to calculate an average for each band. Non-complex images only. ::: seealso [method@Image.avg], [method@Image.stats].. 0 on success, -1 on error input [class@Image] output pixel standard deviation `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 [arithmetic](libvips-arithmetic.html)), then the following table is used to determine the output type: ## [method@Image.divide] type promotion | input type | output type | |----------------|----------------| | uchar | float | | char | float | | ushort | float | | short | float | | uint | float | | int | float | | float | float | | double | double | | complex | complex | | double complex | double complex | In other words, the output type is just large enough to hold the whole range of possible values. ::: seealso [method@Image.multiply], [method@Image.linear], [method@Image.pow]. 0 on success, -1 on error input image input image output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @fill: `gboolean`, fill the draw_circle ::: seealso [method@Image.draw_circle1], [method@Image.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 As [method@Image.draw_circle], but just takes a single double for @ink. ::: tip "Optional arguments" * @fill: `gboolean`, fill the draw_circle ::: seealso [method@Image.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 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. ::: tip "Optional arguments" * @test: [class@Image], test this image * @equal: `gboolean`, fill while equal to edge * @left: `gint`, output left edge of bounding box of modified area * @top: `gint`, output top edge of bounding box of modified area * @width: `gint`, output width of bounding box of modified area * @height: `gint`, output height of bounding box of modified area @ink is an array of double containing values to draw. ::: seealso [method@Image.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 As [method@Image.draw_flood], but just takes a single double for @ink. ::: tip "Optional arguments" * @test: [class@Image], test this image * @equal: `gboolean`, fill while equal to edge * @left: `gint`, output, left edge of bounding box of modified area * @top: `gint`, output, top edge of bounding box of modified area * @width: `gint`, output, width of bounding box of modified area * @height: `gint`, output, height of bounding box of modified area ::: seealso [method@Image.draw_flood]. 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 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 [method@Image.cast]. Use @mode to set how pixels are combined. If you use [enum@Vips.CombineMode.ADD], both images must be uncoded. ::: tip "Optional arguments" * @mode: [enum@CombineMode], how to combine pixels ::: seealso [method@Image.draw_mask], [method@Image.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. ::: seealso [method@Image.draw_line1], [method@Image.draw_circle], [method@Image.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 [method@Image.draw_line], but just take a single double for @ink. ::: seealso [method@Image.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 [ctor@Image.text] to draw text on an image. Use in a [method@Image.draw_line] subclass to draw an object along a line. @ink is an array of double containing values to draw. ::: seealso [ctor@Image.text], [method@Image.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 [method@Image.draw_mask], but just takes a single double for @ink. ::: seealso [method@Image.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 [method@Image.draw_rect], but draw a single pixel at @x, @y. ::: seealso [method@Image.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 [method@Image.draw_point], but just take a single double for @ink. ::: seealso [method@Image.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 Paint pixels within @left, @top, @width, @height in @image with @ink. If @fill is zero, just paint a 1-pixel-wide outline. ::: tip "Optional arguments" * @fill: `gboolean`, fill the rect ::: seealso [method@Image.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 As [method@Image.draw_rect], but just take a single double for @ink. ::: tip "Optional arguments" * @fill: `gboolean`, fill the rect ::: seealso [method@Image.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. ::: seealso [method@Image.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 Save an image as a set of tiles at various resolutions. By default dzsave uses DeepZoom layout -- use @layout to pick other conventions. [method@Image.dzsave] creates a directory called @name to hold the tiles. If @name ends `.zip`, [method@Image.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 [method@Image.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 [enum@Vips.ForeignDzLayout.IIIF3] for IIIF v3 layout. ::: tip "Optional arguments" * @basename: `gchararray`, base part of name * @layout: [enum@ForeignDzLayout], directory layout convention * @suffix: `gchararray`, suffix for tiles * @overlap: `gint`, set tile overlap * @tile_size: `gint`, set tile size * @background: [struct@ArrayDouble], background colour * @depth: [enum@ForeignDzDepth], how deep to make the pyramid * @centre: `gboolean`, centre the tiles * @angle: [enum@Angle], rotate the image by this much * @container: [enum@ForeignDzContainer], set container type * @compression: `gint`, zip deflate compression level * @region_shrink: [enum@RegionShrink], how to shrink each 2x2 region * @skip_blanks: `gint`, skip tiles which are nearly equal to the background * @id: `gchararray`, id for IIIF properties * @Q: `gint`, quality factor ::: seealso [method@Image.tiffsave]. 0 on success, -1 on error. image to save name to save to `NULL`-terminated list of optional named arguments As [method@Image.dzsave], but save to a memory buffer. Output is always in a zip container. Use @basename to set the name of the directory that the zip will create when unzipped. The address of the buffer is returned in @buf, the length of the buffer in @len. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "Optional arguments" * @basename: `gchararray`, base part of name * @layout: [enum@ForeignDzLayout], directory layout convention * @suffix: `gchararray`, suffix for tiles * @overlap: `gint`, set tile overlap * @tile_size: `gint`, set tile size * @background: [struct@ArrayDouble], background colour * @depth: [enum@ForeignDzDepth], how deep to make the pyramid * @centre: `gboolean`, centre the tiles * @angle: [enum@Angle], rotate the image by this much * @container: [enum@ForeignDzContainer], set container type * @compression: `gint`, zip deflate compression level * @region_shrink: [enum@RegionShrink], how to shrink each 2x2 region * @skip_blanks: `gint`, skip tiles which are nearly equal to the background * @id: `gchararray`, id for IIIF properties * @Q: `gint`, quality factor ::: seealso [method@Image.dzsave], [method@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 [method@Image.dzsave], but save to a target. ::: tip "Optional arguments" * @basename: `gchararray`, base part of name * @layout: [enum@ForeignDzLayout], directory layout convention * @suffix: `gchararray`, suffix for tiles * @overlap: `gint`, set tile overlap * @tile_size: `gint`, set tile size * @background: [struct@ArrayDouble], background colour * @depth: [enum@ForeignDzDepth], how deep to make the pyramid * @centre: `gboolean`, centre the tiles * @angle: [enum@Angle], rotate the image by this much * @container: [enum@ForeignDzContainer], set container type * @compression: `gint`, zip deflate compression level * @region_shrink: [enum@RegionShrink], how to shrink each 2x2 region * @skip_blanks: `gint`, skip tiles which are nearly equal to the background * @id: `gchararray`, id for IIIF properties * @Q: `gint`, quality factor ::: seealso [method@Image.dzsave], [method@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 The opposite of [method@Image.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 [enum@Extend]. ::: tip "Optional arguments" * @extend: [enum@Extend] to generate the edge pixels (default: [enum@Vips.Extend.BLACK]) * @background: [struct@ArrayDouble] colour for edge pixels ::: seealso [method@Image.extract_area], [method@Image.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 [method@Image.decode]. ::: seealso [method@Image.decode]. 0 on success, or -1 on error. image to encode write to this image coding to apply Perform [enum@Vips.OperationBoolean.EOR] on a pair of images. See [method@Image.boolean]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.EOR] on an image and an array of constants. See [method@Image.boolean_const]. ::: seealso [method@Image.boolean], [method@Image.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 [enum@Vips.OperationBoolean.EOR] on an image and a constant. See [method@Image.boolean_const1]. ::: seealso [method@Image.boolean], [method@Image.boolean_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.EQUAL] on a pair of images. See [method@Image.relational]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.EQUAL] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.EQUAL] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.EXP] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.EXP10] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Extract an area from an image. The area must fit within @in. ::: seealso [method@Image.extract_band], [method@Image.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 Extract a band or bands from an image. Extracting out of range is an error. @n defaults to 1. ::: tip "Optional arguments" * @n: `gint`, number of bands to extract ::: seealso [method@Image.extract_area]. 0 on success, -1 on error. input image output image index of first 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. ::: seealso [method@Image.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. ::: seealso [method@Image.spcor]. 0 on success, -1 on error input image reference image output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @distance: [class@Image], output, image of distance to nearest non-zero pixel ::: seealso [method@Image.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 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, [method@Image.find_trim] returns @width == 0 and @height == 0. @background defaults to 255, or 65535 for 16-bit images. Set another value, or use [method@Image.getpoint] to pick a value from an edge. You'll need to flatten before [method@Image.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. ::: tip "Optional arguments" * @threshold: `gdouble`, background / object threshold * @background: [struct@ArrayDouble], background colour * @line_art: `gboolean`, enable line art mode ::: seealso [method@Image.getpoint], [method@Image.extract_area], [method@Image.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. ::: seealso [method@Image.write_to_file]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments 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 [enum@Vips.Interpretation.RGB16] or [enum@Vips.Interpretation.GREY16]. Useful for flattening PNG images to RGB. Non-complex images only. ::: tip "Optional arguments" * @background: [struct@ArrayDouble] colour for new pixels * @max_alpha: `gdouble`, maximum value for alpha ::: seealso [method@Image.premultiply], [ctor@Image.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. ::: seealso [method@Image.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. ::: seealso [method@Image.rad2float], [enum@Vips.Coding.RAD], [method@Image.LabQ2Lab]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Round to an integral value with [enum@Vips.OperationRound.FLOOR]. See [method@Image.round]. 0 on success, -1 on error input [class@Image] output [class@Image] `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. ::: seealso [method@Image.invfft], [ctor@Image.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. ::: seealso [method@Image.invfft]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Calculate @in ** (1 / @exponent), normalising to the maximum range of the input type. For float types use 1.0 as the maximum. ::: tip "Optional arguments" * @exponent: `gdouble`, gamma, default 1.0 / 2.4 ::: seealso [ctor@Image.identity], [method@Image.pow_const1], [method@Image.maplut] 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments This operator runs [ctor@Image.gaussmat] and [method@Image.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. ::: tip "Optional arguments" * @precision: [enum@Precision], precision for blur, default int * @min_ampl: `gdouble`, minimum amplitude, default 0.2 ::: seealso [ctor@Image.gaussmat], [method@Image.convsep]. 0 on success, -1 on error. input image output image how large a mask to use `NULL`-terminated list of optional named arguments Generates an image. The action depends on the image type. For images created with [ctor@Image.new], [method@Image.generate] just attaches the start/generate/stop callbacks and returns. For images created with [ctor@Image.new_memory], memory is allocated for the whole image and it is entirely generated using [func@sink_memory]. For images created with [ctor@Image.new_temp_file] and friends, memory for a few scanlines is allocated and [method@Image.sink_disc] used to generate the image in small chunks. As each chunk is generated, it is written to disc. ::: seealso [func@sink_memory], [ctor@Image.new], [method@Region.prepare]. 0 on success, or -1 on error. generate this image start sequences with this function generate pixels with this function stop sequences with this function user data user data 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 [method@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 [method@Image.get_double] in practice): ```c 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); ``` ::: seealso [method@Image.get_typeof], [method@Image.get_double]. 0 on success, -1 otherwise. image to get the field from the name to fetch the [struct@GObject.Value] is copied into this Gets @data from @image under the name @name. A convenience function over [method@Image.get]. Use [method@Image.get_typeof] to test for the existence of a piece of metadata. ::: seealso [method@Image.set_area], [method@Image.get], [method@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 [method@Image.get_typeof] to test for the existence of a piece of metadata. ::: seealso [method@Image.get], [method@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 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 [method@Image.get_typeof] to test for the existence of a piece of metadata. ::: seealso [method@Image.get], [method@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 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 [func@GLib.free] when you are done with it. This will base64-encode BLOBs, for example. Use [method@Buf.appendg] to make a string that's for humans. ::: seealso [method@Image.get], [method@Image.get_typeof], [method@Buf.appendg]. 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 [method@Image.get_typeof] to test for the existence of a piece of metadata. ::: seealso [method@Image.get], [method@Image.get_typeof], [method@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 [enum@Coding] from the image header. image to get from Fetch and sanity-check [const@META_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. ::: seealso [method@Image.wio_input], [method@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. ::: seealso [method@Image.get], [method@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 [func@GLib.strfreev]. This is handy for language bindings. From C, it's usually more convenient to use [method@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 If the image has an attached `"gainmap"`, return that. If there's a compressed `"gainmap-data"`, decompress, and return it. You need to free the result with [method@GObject.Object.unref] when you're done with it. the gainmap image, if present, or NULL. image to get the gainmap 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 [method@Image.history_printf] for each action they perform, setting the command-line equivalent for the action. ::: seealso [method@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 [method@GObject.Object.unref]. Use [method@Image.get_typeof] to test for the existence of a piece of metadata. ::: seealso [method@Image.get], [method@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. ::: seealso [method@Image.get], [method@Image.get_typeof]. 0 on success, -1 otherwise. image to get the header field from field name return field value Return the [enum@Interpretation] set in the image header. Use [method@Image.guess_format] if you want a sanity-checked value. the [enum@Interpretation] 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 [const@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 [const@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 [const@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` or `VIPS_TYPE_REF_STRING`. Do not free @out. Use [method@Image.get_as_string] to fetch any field as a string. ::: seealso [method@Image.get], [method@Image.get_typeof]. 0 on success, -1 otherwise. image to get the header field from field name return field value Fetch and sanity-check [const@META_TILE_HEIGHT]. Default to -1 (no tiling) if not present or crazy. the height of the tiles encoded in the image. image to get from Pick a tile size and a buffer height for this image and the current value of [func@concurrency_get]. The buffer height will always be a multiple of tile_height. The buffer height is the height of each buffer we fill in sink disc. Since we have two buffers, the largest range of input locality is twice the output buffer size, plus whatever margin we add for things like convolution. image to guess for return selected tile width return selected tile height return buffer height in scanlines Fetch and sanity-check [const@META_TILE_WIDTH]. Default to -1 (no tiling) if not present or crazy. the width of the tiles encoded in the image. image to get from Read the [alias@GObject.Type] for a header field. Returns zero if there is no field of that name. ::: seealso [method@Image.get]. the [alias@GObject.Type] 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 [func@GLib.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. This operation is slow. If you want to read many points, use [method@Image.write_to_memory]. ::: seealso [method@Image.draw_point], [method@Image.write_to_memory]. 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 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. If @keep_duplicate_frames is `TRUE`, duplicate frames in the input will be kept in the output instead of combining them. ::: tip "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 * @keep_duplicate_frames: `gboolean`, keep duplicate frames in the output instead of combining them ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.gifsave], but save to a memory buffer. The address of the buffer is returned in @buf, the length of the buffer in @len. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "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 * @keep_duplicate_frames: `gboolean`, keep duplicate frames in the output instead of combining them ::: seealso [method@Image.gifsave], [method@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 [method@Image.gifsave], but save to a target. ::: tip "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 * @keep_duplicate_frames: `gboolean`, keep duplicate frames in the output instead of combining them ::: seealso [method@Image.gifsave], [method@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 [method@Image.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 [enum@Vips.BandFormat.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. ::: tip "Optional arguments" * @gamma: `gdouble`, gamma of source images * @int_output: `gboolean`, `TRUE` for integer image output ::: seealso [method@Image.mosaic]. 0 on success, -1 on error mosaic to rebuild output image `NULL`-terminated list of optional named arguments The opposite of [method@Image.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 [enum@Extend]. ::: tip "Optional arguments" * @extend: [enum@Extend] to generate the edge pixels (default: [enum@Vips.Extend.BLACK]) * @background: [struct@ArrayDouble] colour for edge pixels ::: seealso [method@Image.extract_area], [method@Image.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 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. ::: seealso [method@Image.embed], [method@Image.insert], [method@Image.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 [enum@BandFormat] 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 [enum@BandFormat] for the image. image to guess for Return the [enum@Interpretation] for an image, guessing a sane value if the set value looks crazy. a sensible [enum@Interpretation] 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 [enum@Vips.Interpretation.sRGB] would, but a six-band [enum@Vips.Interpretation.MULTIBAND] would not. Return `TRUE` if @image has an alpha channel. image to check 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. Use @tune to pass a set of tuning parameters to the encoder, see the libheif documentation. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @bitdepth: `gint`, set write bit depth to 8, 10, or 12 bits * @lossless: `gboolean`, enable lossless encoding * @compression: [enum@ForeignHeifCompression], write with this compression * @effort: `gint`, encoding effort * @subsample_mode: [enum@ForeignSubsample], chroma subsampling mode * @encoder: [enum@ForeignHeifEncoder], select encoder to use * @tune: `gchararray`, encoder tuning parameters ::: seealso [method@Image.write_to_file], [ctor@Image.heifload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.heifsave], but save to a memory buffer. The address of the buffer is returned in @obuf, the length of the buffer in @olen. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @bitdepth: `gint`, set write bit depth to 8, 10, or 12 bits * @lossless: `gboolean`, enable lossless encoding * @compression: [enum@ForeignHeifCompression], write with this compression * @effort: `gint`, encoding effort * @subsample_mode: [enum@ForeignSubsample], chroma subsampling mode * @encoder: [enum@ForeignHeifEncoder], select encoder to use * @tune: `gchararray`, encoder tuning parameters ::: seealso [method@Image.heifsave], [method@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 [method@Image.heifsave], but save to a target. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @bitdepth: `gint`, set write bit depth to 8, 10, or 12 bits * @lossless: `gboolean`, enable lossless encoding * @compression: [enum@ForeignHeifCompression], write with this compression * @effort: `gint`, encoding effort * @subsample_mode: [enum@ForeignSubsample], chroma subsampling mode * @encoder: [enum@ForeignHeifEncoder], select encoder to use * @tune: `gchararray`, encoder tuning parameters ::: seealso [method@Image.heifsave], [method@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 Form cumulative histogram. ::: seealso [method@Image.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 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. ::: tip "Optional arguments" * @band: `gint`, band to equalise 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @band: `gint`, band to equalise ::: seealso [method@Image.hist_find_ndim], [method@Image.hist_find_indexed]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments 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 [method@Image.labelregions]. You can use it to find the centre of gravity of blobs in an image, for example. ::: tip "Optional arguments" * @combine: [enum@Combine], combine bins like this ::: seealso [method@Image.hist_find], [method@Image.labelregions]. 0 on success, -1 on error input [class@Image] input index [class@Image] output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @bins: `gint`, number of bins to make on each axis ::: seealso [method@Image.hist_find], [method@Image.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 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. ::: tip "Optional arguments" * @max_slope: `gint`, maximum brightening ::: seealso [method@Image.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. ::: seealso [method@Image.maplut], [method@Image.hist_find], [method@Image.hist_norm], [method@Image.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. ::: seealso [method@Image.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: *unsigned char* max is always 256 *other unsigned integer types* output 0 - maximum value of @in. *signed int types* min moved to 0, max moved to max + min. *float types* 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 [method@Image.history_printf]. A convenience function for command-line programs. ::: seealso [method@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: ```c vips_image_history_printf(image, "vips invert %s %s", in->filename, out->filename); ``` Might add the string ```bash "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()`-style format string arguments to format string 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. ::: tip "Optional arguments" * @scale: `gint`, scale down dimensions by this much * @min_radius: `gint`, smallest radius to search for * @max_radius: `gint`, largest radius to search for ::: seealso [method@Image.hough_line]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @width: `gint`, horizontal size of parameter space * @height: `gint`, vertical size of parameter space ::: seealso [method@Image.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. ::: seealso [method@Image.icc_transform], [method@Image.icc_import]. 0 on success, -1 on error. input image output image use this profile Export an image from D65 LAB to device space with an ICC profile. If @pcs is set to [enum@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. ::: tip "Optional arguments" * @pcs: [enum@PCS], use XYZ or LAB PCS * @intent: [enum@Intent], 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 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Import an image from device space to D65 LAB with an ICC profile. If @pcs is set to [enum@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 [method@Image.get_typeof] with [const@META_ICC_NAME] as an argument. This will return [alias@GObject.Type] 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 also 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. ::: tip "Optional arguments" * @pcs: [enum@PCS], use XYZ or LAB PCS * @intent: [enum@Intent], 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 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments 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 [method@Image.get_typeof] with [const@META_ICC_NAME] as an argument. This will return [alias@GObject.Type] 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 also 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 [const@META_ICC_NAME] field. Use [method@Image.icc_import] and [method@Image.icc_export] to do either the first or second half of this operation in isolation. ::: tip "Optional arguments" * @pcs: [enum@PCS], use XYZ or LAB PCS * @intent: [enum@Intent], 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 0 on success, -1 on error. input image output image get the output profile from here `NULL`-terminated list of optional named arguments 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 ``` ::: tip "Optional arguments" * @blend: `gboolean`, blend smoothly between @in1 and @in2 ::: seealso [method@Image.equal]. 0 on success, -1 on error condition [class@Image] then [class@Image] else [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationComplexget.IMAG] on an image. See [method@Image.complexget]. 0 on success, -1 on error input [class@Image] output [class@Image] `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 [method.Image.pipelinev] and then make any adjustments you need, but if you are creating an image from scratch, for example [ctor@Image.black] or [ctor@Image.jpegload], you do need to set all the fields yourself. ::: seealso [method.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 [method@Image.draw_circle]. After calling this function you can both read and write the image with [func@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. ::: seealso [method@Image.draw_circle], [method@Image.wio_input]. 0 on success, or -1 on error. image to make read-write 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 [arithmetic](libvips-arithmetic.html)). ::: tip "Optional arguments" * @expand: `gdouble`, expand output to hold whole of both images * @background: [struct@ArrayDouble], colour for new pixels ::: seealso [method@Image.join], [method@Image.embed], [method@Image.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 [method@Image.draw_circle]. The [signal@Image::invalidate] signal is emitted for all invalidated images. ::: seealso [method@Region.invalidate]. [class@Image] 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 [method@Image.conj]. ::: seealso [method@Image.linear]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments 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: ``` 4 3 0.1 0.2 0.3 0.1 0.2 0.4 0.4 0.2 0.7 0.5 0.6 0.3 ``` 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. ::: tip "Optional arguments" * @size: `gint`, generate this much ::: seealso [method@Image.buildlut]. 0 on success, -1 on error input mask output LUT `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @real: `gboolean`, only output the real part ::: seealso [method@Image.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. [class@Image] to minimise Return `TRUE` if @image represents a file on disc in some way. image to test If @image has been killed (see [method@Image.set_kill]), set an error message, clear the [class@Image].kill flag and return `TRUE`. Otherwise return `FALSE`. Handy for loops which need to run sets of threads which can fail. ::: seealso [method@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 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 [arithmetic](libvips-arithmetic.html)). If you are going to be joining many thousands of images in a regular grid, [func@Image.arrayjoin] is a better choice. ::: tip "Optional arguments" * @expand: `gboolean`, `TRUE` to expand the output image to hold all of the input pixels * @shim: `gint`, space between images, in pixels * @background: [struct@ArrayDouble], background ink colour * @align: [enumAlign], low, centre or high alignment ::: seealso [func@Image.arrayjoin], [method@Image.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 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. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @tile_width: `gint`, tile width * @tile_height: `gint`, tile width * @subsample_mode: [enum@ForeignSubsample], chroma subsampling mode ::: seealso [method@Image.write_to_file], [ctor@Image.jp2kload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.jp2ksave], but save to a target. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @tile_width: `gint`, tile width * @tile_height: `gint`, tile width * @subsample_mode: [enum@ForeignSubsample], chroma subsampling mode ::: seealso [method@Image.jp2ksave], [method@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 As [method@Image.jp2ksave], but save to a target. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @tile_width: `gint`, tile width * @tile_height: `gint`, tile width * @subsample_mode: [enum@ForeignSubsample], chroma subsampling mode ::: seealso [method@Image.jp2ksave], [method@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 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 [const@META_EXIF_NAME], then modified with any other related tags on the image before being written to the file. [const@META_RESOLUTION_UNIT] is used to set the EXIF resolution unit. [const@META_ORIENTATION] is used to set the EXIF orientation tag. IPTC as [const@META_IPTC_NAME] and XMP as [const@META_XMP_NAME] are coded and attached. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @optimize_coding: `gboolean`, compute optimal Huffman coding tables * @interlace: `gboolean`, write an interlaced (progressive) jpeg * @subsample_mode: [enum@ForeignSubsample], 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 ::: seealso [method@Image.jpegsave_buffer], [method@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 [method@Image.jpegsave], but save to a memory buffer. The address of the buffer is returned in @obuf, the length of the buffer in @olen. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @optimize_coding: `gboolean`, compute optimal Huffman coding tables * @interlace: `gboolean`, write an interlaced (progressive) jpeg * @subsample_mode: [enum@ForeignSubsample], 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 ::: seealso [method@Image.jpegsave], [method@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 [method@Image.jpegsave], but save as a mime jpeg on stdout. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @optimize_coding: `gboolean`, compute optimal Huffman coding tables * @interlace: `gboolean`, write an interlaced (progressive) jpeg * @subsample_mode: [enum@ForeignSubsample], 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 ::: seealso [method@Image.jpegsave], [method@Image.write_to_file]. 0 on success, -1 on error. image to save `NULL`-terminated list of optional named arguments As [method@Image.jpegsave], but save to a target. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @optimize_coding: `gboolean`, compute optimal Huffman coding tables * @interlace: `gboolean`, write an interlaced (progressive) jpeg * @subsample_mode: [enum@ForeignSubsample], 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 ::: seealso [method@Image.jpegsave], [method@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 Write a VIPS image to a file in JPEG-XL format. The image can be unsigned 8 or 16-bit integer, or float. Use @bitdepth for fine control of the image bitdepth. @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. @bitdepth sets the bitdepth to save at. It defaults to the full range of the image numeric type, but can be set lower. It has no effect on float images. Set @lossless to enable lossless compression. ::: tip "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 * @bitdepth: `gint`, image bitdepth 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.jxlsave], but save to a memory buffer. ::: tip "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 ::: seealso [method@Image.jxlsave], [method@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 As [method@Image.jxlsave], but save to a target. ::: tip "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 ::: seealso [method@Image.jxlsave], [method@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 Label regions of equal pixels in an image. 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 [enum@Vips.BandFormat.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 [method@Image.labelregions] to number them all. Use [method@Image.hist_find_indexed] to (for example) find blob coordinates. ::: tip "Optional arguments" * @segments: `gint`, output, number of regions found ::: seealso [method@Image.hist_find_indexed]. 0 on success, -1 on error. image to test write labelled regions here `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.LESS] on a pair of images. See [method@Image.relational]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.LESS] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.LESS] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.LESSEQ] on a pair of images. See [method@Image.relational]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.LESSEQ] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.LESSEQ] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @uchar: `gboolean`, output uchar pixels ::: seealso [method@Image.linear1], [method@Image.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 Run [method@Image.linear] with a single constant. ::: tip "Optional arguments" * @uchar: `gboolean`, output uchar pixels ::: seealso [method@Image.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 This operation behaves rather like [method@Image.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 [method@Region.prepare]. When the cache fills, a tile is chosen for reuse. If @access is [enum@Vips.Access.RANDOM], then the least-recently-used tile is reused. If @access is [enum@Vips.Access.SEQUENTIAL], then the top-most tile is reused. @access defaults to [enum@Vips.Access.RANDOM]. @tile_height can be used to set the size of the strips that [method@Image.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`, [method@Image.linecache] will allow many threads to calculate tiles at once and share the cache between them. ::: tip "Optional arguments" * @access: [enum@Access], hint expected access pattern * @tile_height: `gint`, height of tiles in cache * @threaded: `gboolean`, allow many threads ::: seealso [method@Image.tilecache]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.LOG] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.LOG10] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.LSHIFT] on a pair of images. See [method@Image.boolean]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.LSHIFT] on an image and an array of constants. See [method@Image.boolean_const]. ::: seealso [method@Image.boolean], [method@Image.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 [enum@Vips.OperationBoolean.LSHIFT] on an image and a constant. See [method@Image.boolean_const1]. ::: seealso [method@Image.boolean], [method@Image.boolean_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments 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). ::: tip "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 ::: seealso [method@Image.magicksave_buffer], [ctor@Image.magickload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.magicksave], but save to a memory buffer. The address of the buffer is returned in @obuf, the length of the buffer in @olen. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "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 ::: seealso [method@Image.magicksave], [method@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 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. ::: seealso [method@Image.get_typeof], [method@Image.get]. `NULL` on success, the failing pointer otherwise. image to map over function to call for each header field user data for @fn 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 [ctor@Image.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. [enum@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 [method@Image.premultiply], set @premultiplied. This operation does not change xres or yres. The image resolution needs to be updated by the application. See [method@Image.maplut] for a 1D equivalent of this operation. ::: tip "Optional arguments" * @interpolate: [class@Interpolate], interpolate pixels with this * @extend: [enum@Vips.Extend], how to generate new pixels * @background: [struct@ArrayDouble], colour for new pixels * @premultiplied: `gboolean`, images are already premultiplied ::: seealso [ctor@Image.xyz], [method@Image.affine], [method@Image.resize], [method@Image.maplut], [class@Interpolate]. 0 on success, -1 on error input image output image index image `NULL`-terminated list of optional named arguments 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, [enum@Vips.BandFormat.UCHAR], [enum@Vips.BandFormat.USHORT] or [enum@Vips.BandFormat.UINT]. If @lut is too small for the input type (for example, if @in is [enum@Vips.BandFormat.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. ::: tip "Optional arguments" * @band: `gint`, apply one-band @lut to this band of @in ::: seealso [method@Image.hist_find], [ctor@Image.identity]. 0 on success, -1 on error input image output image look-up table `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @search: `gboolean`, search to improve tie-points * @hwindow: `gint`, half window size * @harea: `gint`, half search size * @interpolate: [class@Interpolate], interpolate pixels with this 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 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. ::: seealso [method@Image.math2]. 0 on success, -1 on error input [class@Image] output [class@Image] math operation to perform `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 [arithmetic](libvips-arithmetic.html)), and that format is the result type. ::: seealso [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] 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. ::: seealso [method@Image.math2], [method@Image.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 [method@Image.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. ::: seealso [ctor@Image.matrixload], [method@Image.matrixmultiply]. 0 on success, -1 on error matrix to invert output matrix `NULL`-terminated list of optional named arguments Multiplies two matrix images. The scale and offset members of @left and @right are ignored. ::: seealso [method@Image.matrixinvert]. 0 on success, -1 on error input matrix input matrix output matrix `NULL`-terminated list of optional named arguments Print @in to %stdout in matrix format. See [ctor@Image.matrixload] for a description of the format. ::: seealso [ctor@Image.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 [ctor@Image.matrixload] for a description of the format. ::: seealso [ctor@Image.matrixload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.matrixsave], but save to a target. ::: seealso [method@Image.matrixsave]. 0 on success, -1 on error. image to save save image to this target `NULL`-terminated list of optional named arguments 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 [method@Image.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. ::: tip "Optional arguments" * @x: `gint`, output, horizontal position of maximum * @y: `gint`, output, vertical position of maximum * @size: `gint`, number of maxima to find * @out_array: [struct@ArrayDouble], output, array of maximum values * @x_array: [struct@ArrayInt], output, corresponding horizontal positions * @y_array: [struct@ArrayInt]. output, corresponding vertical positions ::: seealso [method@Image.min], [method@Image.stats]. 0 on success, -1 on error input [class@Image] output pixel maximum `NULL`-terminated list of optional named arguments For each pixel, pick the maximum of a pair of images. ::: seealso [method@Image.minpair]. 0 on success, -1 on error input image input image output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @left: `gint`, area of image containing chart * @top: `gint`, area of image containing chart * @width: `gint`, area of image containing chart * @height: `gint`, area of image containing chart ::: seealso [method@Image.avg], [method@Image.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: ```c vips_rank(in, out, size, size, (size * size) / 2); ``` ::: seealso [method@Image.rank]. 0 on success, -1 on error input image output image size of region `NULL`-terminated list of optional named arguments 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 [arithmetic](libvips-arithmetic.html)). @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. ::: tip "Optional arguments" * @mblend: `gint`, maximum blend size ::: seealso [method@Image.mosaic], [method@Image.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 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 [method@Image.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. ::: tip "Optional arguments" * @x: `gint`, output, horizontal position of minimum * @y: `gint`, output, vertical position of minimum * @size: `gint`, number of minima to find * @out_array: [struct@ArrayDouble], output, array of minimum values * @x_array: [struct@ArrayInt], output, corresponding horizontal positions * @y_array: [struct@ArrayInt], output, corresponding vertical positions ::: seealso [method@Image.min], [method@Image.stats]. 0 on success, -1 on error input [class@Image] 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 [signal@Image::minimise] signal is emitted for all minimised images. [class@Image] to minimise For each pixel, pick the minimum of a pair of images. ::: seealso [method@Image.minpair]. 0 on success, -1 on error input image input image output image `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.MORE] on a pair of images. See [method@Image.relational]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.MORE] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.MORE] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.MOREEQ] on a pair of images. See [method@Image.relational]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.MOREEQ] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.MOREEQ] on an image and a constant. See [method@Image.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 [enum@Vips.OperationMorphology.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 [enum@Vips.OperationMorphology.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 [method@Image.andimage], [method@Image.orimage] and [method@Image.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 [func@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 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 [method@Image.merge] to join the two images together. You can read out the detected transform with @dx0, @dy0, @scale1, @angle1, @dx1, @dy1. ::: tip "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 ::: seealso [method@Image.merge], [method@Image.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 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 [arithmetic](libvips-arithmetic.html)). ::: tip "Optional arguments" * @search: `gboolean`, search to improve tie-points * @hwindow: `gint`, half window size * @harea: `gint`, half search size * @interpolate: [class@Interpolate], interpolate pixels with this * @mblend: `gint`, maximum blend size ::: seealso [method@Image.merge], [method@Image.insert], [method@Image.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 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. ::: tip "Optional arguments" * @band: `gint`, msb just this band ::: seealso [method@Image.scale], [method@Image.cast]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments 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 [arithmetic](libvips-arithmetic.html)), then the following table is used to determine the output type: ## [method@Image.multiply] type promotion | input type | output type | |----------------|----------------| | uchar | ushort | | char | short | | ushort | uint | | short | int | | uint | uint | | int | int | | float | float | | double | double | | complex | complex | | double complex | double complex | In other words, the output type is just large enough to hold the whole range of possible values. ::: seealso [method@Image.add], [method@Image.linear]. 0 on success, -1 on error left-hand image right-hand 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. ::: seealso [method@Image.write_to_file], [ctor@Image.niftiload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.NOTEQ] on a pair of images. See [method@Image.relational]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.NOTEQ] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationRelational.NOTEQ] on an image and a constant. See [method@Image.relational_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.OR] on a pair of images. See [method@Image.boolean]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.OR] on an image and an array of constants. See [method@Image.boolean_const]. ::: seealso [method@Image.boolean], [method@Image.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 [enum@Vips.OperationBoolean.OR] on an image and a constant. See [method@Image.boolean_const1]. ::: seealso [method@Image.boolean], [method@Image.boolean_const]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments [method@Image.percent] returns (through the @threshold parameter) the threshold below which there are @percent values of @in. For example: ```bash $ 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. ::: seealso [method@Image.hist_find], [method@Image.profile]. 0 on success, -1 on error input image threshold percentage output threshold value `NULL`-terminated list of optional named arguments Convert the two input images to Fourier space, calculate phase-correlation, back to real space. ::: seealso [method@Image.fwfft], [method@Image.cross_phase], 0 on success, -1 on error. first input image second input image output image `NULL`-terminated list of optional named arguments Check that an image is readable with [method@Region.prepare] and friends. If it isn't, try to transform the image so that [method@Region.prepare] can work. ::: seealso [method@Image.pio_output], [method@Region.prepare]. 0 on success, or -1 on error. image to check Check that an image is writeable with [method@Image.generate]. If it isn't, try to transform the image so that [method@Image.generate] can work. ::: seealso [method@Image.pio_input]. 0 on success, or -1 on error. image to check Build an array and call [func@Image.pipeline_array]. ::: seealso [method@Image.generate]. output image of pipeline hint for this image `NULL`-terminated list of input images 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 [flags@ForeignPngFilter]. 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. ::: tip "Optional arguments" * @compression: `gint`, compression level * @interlace: `gboolean`, interlace image * @filter: [flags@ForeignPngFilter], 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 ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.pngsave], but save to a memory buffer. The address of the buffer is returned in @buf, the length of the buffer in @len. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "Optional arguments" * @compression: `gint`, compression level * @interlace: `gboolean`, interlace image * @filter: [flags@ForeignPngFilter], 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 ::: seealso [method@Image.pngsave], [method@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 [method@Image.pngsave], but save to a target. ::: tip "Optional arguments" * @compression: `gint`, compression level * @interlace: `gboolean`, interlace image * @filter: [flags@ForeignPngFilter], 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 ::: seealso [method@Image.pngsave], [method@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 [enum@Vips.OperationComplex.POLAR] on an image. See [method@Image.complex]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.POW] on a pair of images. See [method@Image.math2]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.POW] on an image and a constant. See [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.POW] on an image and a constant. See [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] constant `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @format: [enum@ForeignPpmFormat], format to save in * @ascii: `gboolean`, save as ASCII rather than binary * @bitdepth: `gint`, bitdepth to save at ::: seealso [method@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 [method@Image.ppmsave], but save to a target. ::: tip "Optional arguments" * @format: [enum@ForeignPpmFormat], format to save in * @ascii: `gboolean`, save as ASCII rather than binary * @bitdepth: `gint`, bitdepth to save at ::: seealso [method@Image.ppmsave]. 0 on success, -1 on error. image to save save image to this target `NULL`-terminated list of optional named arguments 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 [enum@Vips.BandFormat.FLOAT] unless the input format is [enum@Vips.BandFormat.DOUBLE], in which case the output is double as well. @max_alpha has the default value 255, or 65535 for images tagged as [enum@Vips.Interpretation.RGB16] or [enum@Vips.Interpretation.GREY16], and 1.0 for images tagged as [enum@Vips.Interpretation.scRGB]. Non-complex images only. ::: tip "Optional arguments" * @max_alpha: `gdouble`, maximum value for alpha ::: seealso [method@Image.unpremultiply], [method@Image.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. ::: seealso [method@Image.canny], [method@Image.sobel], [method@Image.prewitt], [method@Image.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 [method@Image.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. ::: seealso [method@Image.project], [method@Image.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. ::: seealso [method@Image.hist_find], [method@Image.profile]. 0 on success, -1 on error input image sums of columns sums of rows `NULL`-terminated list of optional named arguments Transform an image with a 0, 1, 2, or 3rd order polynomial. The transform we compute: ``` x = x' + a : order 0 image shift only + b x' + c y' : order 1 + affine transf. + d x' y' : order 2 + bilinear transf. + e x' x' + f y' y' : order 3 + quadratic transf. y = y' + g + h y' + i x' + j y' x' + k y' y' + l x' x' ``` where: ``` x', y' = coordinates of srcim x, y = coordinates of dstim a .. l = coefficients ``` The coefficients are in the input matrix, ordered as: ``` a g -- b h c i -- d j -- e k f l ``` The matrix height may be 1, 3, 4, 6 ::: tip "Optional arguments" * @interpolate: [class@Interpolate], use this interpolator (default bilinear) ::: seealso [method@Image.affine]. 0 on success, -1 on error input image output image horizontal quadratic `NULL`-terminated list of optional named arguments Unpack a RAD ([enum@Vips.Coding.RAD]) image to a three-band float image. ::: seealso [method@Image.float2rad], [method@Image.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. ::: seealso [method@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 [method@Image.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 [func@GLib.free] when you are done with it. ::: seealso [method@Image.radsave], [method@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 [method@Image.radsave], but save to a target. ::: seealso [method@Image.radsave]. 0 on success, -1 on error. image to save save image to this target `NULL`-terminated list of optional named arguments [method@Image.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 ```c 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. ::: seealso [method@Image.conv], [method@Image.median], [method@Image.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. ::: seealso [method@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 [method@Image.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 [func@GLib.free] when you are done with it. ::: seealso [method@Image.rawsave], [method@Image.write_to_memory], [method@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 [method@Image.rawsave], but save to a target. ::: seealso [method@Image.rawsave]. 0 on success, -1 on error. image to save save image to this target `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationComplexget.REAL] on an image. See [method@Image.complexget]. 0 on success, -1 on error input [class@Image] output [class@Image] `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. ::: seealso [method@Image.bandmean]. 0 on success, -1 on error input image output image recombination matrix `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationComplex.RECT] on an image. See [method@Image.complex]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments 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 [method@Image.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 [method@Image.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. ::: tip "Optional arguments" * @kernel: [enum@Kernel], kernel to interpolate with (default: [enum@Vips.Kernel.LANCZOS3]) * @gap: `gdouble`, reducing gap to use (default: 0.0) ::: seealso [method@Image.shrink], [method@Image.resize], [method@Image.affine]. 0 on success, -1 on error input image output image horizontal shrink vertical shrink `NULL`-terminated list of optional named arguments 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 [method@Image.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 [method@Image.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. ::: tip "Optional arguments" * @kernel: [enum@Kernel], kernel to interpolate with (default: [enum@Vips.Kernel.LANCZOS3]) * @gap: `gboolean`, reducing gap to use (default: 0.0) ::: seealso [method@Image.shrink], [method@Image.resize], [method@Image.affine]. 0 on success, -1 on error input image output image horizontal reduce `NULL`-terminated list of optional named arguments 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 [method@Image.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 [method@Image.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. ::: tip "Optional arguments" * @kernel: [enum@Kernel], kernel to interpolate with (default: [enum@Vips.Kernel.LANCZOS3]) * @gap: `gboolean`, reducing gap to use (default: 0.0) ::: seealso [method@Image.shrink], [method@Image.resize], [method@Image.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 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 [arithmetic](libvips-arithmetic.html)). To decide if pixels match exactly, that is have the same value in every band, use [method@Image.bandbool] after this operation to AND or OR image bands together. ::: seealso [method@Image.boolean], [method@Image.bandbool], [method@Image.relational_const]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] relational operation to perform `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. ::: seealso [method@Image.boolean], [method@Image.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 [method@Image.relational_const]. ::: seealso [method@Image.boolean], [method@Image.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 @left % @right (remainder after integer division) and writes the result to @out. The images may have any non-complex format. For float formats, [method@Image.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 [arithmetic](libvips-arithmetic.html)), and that format is the result type. ::: seealso [method@Image.remainder_const], [method@Image.divide], [method@Image.round]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `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, [method@Image.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. ::: seealso [method@Image.remainder], [method@Image.divide], [method@Image.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, [method@Image.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. ::: seealso [method@Image.remainder], [method@Image.divide], [method@Image.round]. 0 on success, -1 on error input image output image constant `NULL`-terminated list of optional named arguments [method@Image.remosaic] works rather as [method@Image.globalbalance]. It takes apart the mosaiced image @in and rebuilds it, substituting images. Unlike [method@Image.globalbalance], images are substituted based on their filenames. 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. ::: seealso [method@Image.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. ::: seealso [method@Image.set], [method@Image.get_typeof]. `TRUE` if an item of metadata of that name was found and removed image to test the name to search for [method@Image.reorder_margin_hint] sets a hint that @image contains a margin, that is, that each [method@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 [method@Image.reorder_prepare_many] to attempt to reorder computations to minimise recomputation. ::: seealso [method@Image.reorder_prepare_many]. the image to hint on the size of the margin this operation has added [method@Image.reorder_prepare_many] runs [method@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. ::: seealso [method@Region.prepare], [method@Image.reorder_margin_hint]. 0 on success, or -1 on error. the image that's being written the set of regions to prepare the [struct@Rect] to prepare on each region Repeats an image many times. ::: seealso [method@Image.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 Resize an image. Set @gap to speed up downsizing by having [method@Image.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). [method@Image.resize] normally uses [enum@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 [method@Image.affine] with a [class@Interpolate] selected depending on @kernel. It will use [class@Interpolate] "bicubic" for [enum@Vips.Kernel.CUBIC] and above. It adds a 0.5 pixel displacement to the input pixels to get centre convention scaling. [method@Image.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 [method@Image.premultiply] on it first. ::: tip "optional arguments" * @vscale: `gdouble`, vertical scale factor * @kernel: [enum@Kernel], kernel to reduce with (default: [enum@Vips.Kernel.LANCZOS3]) * @gap: `gdouble`, reducing gap to use (default: 2.0) ::: seealso [method@Image.premultiply], [method@Image.shrink], [method@Image.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 [enum@Vips.OperationRound.RINT]. See [method@Image.round]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Rotate @in by a multiple of 90 degrees. Use [method@Image.similarity] to rotate by an arbitrary angle. [method@Image.rot45] is useful for rotating convolution masks by 45 degrees. ::: seealso [method@Image.flip], [method@Image.similarity], [method@Image.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 [method@Image.rot]. ::: seealso [method@Image.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 [method@Image.rot]. ::: seealso [method@Image.rot]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Rotate @in by a multiple of 45 degrees. Odd-length sides and square images only. This operation is useful for rotating convolution masks. Use [method@Image.similarity] to rotate images by arbitrary angles. ::: tip "Optional arguments" * @angle: [enum@Angle45], rotation angle ::: seealso [method@Image.rot], [method@Image.similarity]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Rotate @in by 90 degrees clockwise. A convenience function over [method@Image.rot]. ::: seealso [method@Image.rot]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments This operator calls [method@Image.affine] for you, calculating the matrix for the affine transform from @scale and @angle. Other parameters are passed on to [method@Image.affine] unaltered. ::: tip "Optional arguments" * @interpolate: [class@Interpolate], interpolate pixels with this * @background: [struct@ArrayDouble], colour for new pixels * @idx: `gdouble`, input horizontal offset * @idy: `gdouble`, input vertical offset * @odx: `gdouble`, output horizontal offset * @ody: `gdouble`, output vertical offset ::: seealso [method@Image.affine], [class@Interpolate]. 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. ::: seealso [method@Image.cast] 0 on success, -1 on error input [class@Image] output [class@Image] [class@Operation]Round rounding operation to perform `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.RSHIFT] on a pair of images. See [method@Image.boolean]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationBoolean.LSHIFT] on an image and an array of constants. See [method@Image.boolean_const]. ::: seealso [method@Image.boolean], [method@Image.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 [enum@Vips.OperationBoolean.RSHIFT] on an image and a constant. See [method@Image.boolean_const1]. ::: seealso [method@Image.boolean], [method@Image.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 [method@Image.Lab2LCh] for a much better colour space. ::: seealso [method@Image.HSV2sRGB], [method@Image.Lab2LCh]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Convert an sRGB image to scRGB. RGB16 images are also handled. ::: seealso [method@Image.scRGB2XYZ], [method@Image.scRGB2sRGB], [method@Image.rad2float]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Convert an scRGB image to greyscale. Set @depth to 16 to get 16-bit output. ::: tip "Optional arguments" * @depth: `gint`, depth of output image in bits ::: seealso [method@Image.LabS2LabQ], [method@Image.sRGB2scRGB], [method@Image.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 Convert an scRGB image to sRGB. Set @depth to 16 to get 16-bit output. ::: tip "Optional arguments" * @depth: `gint`, depth of output image in bits ::: seealso [method@Image.LabS2LabQ], [method@Image.sRGB2scRGB], [method@Image.rad2float]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @log: `gboolean`, log scale pixels * @exp: `gdouble`, exponent for log scale ::: seealso [method@Image.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. ::: seealso [method@Image.canny], [method@Image.sobel], [method@Image.prewitt], [method@Image.scharr]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments This operation behaves rather like [method@Image.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 [method@Image.sequential] uses. The default value is 1. ::: tip "Optional arguments" * @tile_height: `gint`, height of cache strips ::: seealso [method@Image.linecache], [method@Image.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 [struct@GObject.Value] 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 [method@Image.set_int] in practice), you would do: ```c 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); ``` ::: seealso [method@Image.get]. image to set the metadata on the name to give the metadata the [struct@GObject.Value] 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. ::: seealso [method@Image.get_double], [method@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 [method@Image.set]. ::: seealso [method@Image.get_image], [method@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 [method@Image.set]. ::: seealso [method@Image.get_image], [method@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. ::: seealso [method@Image.get_blob], [method@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. ::: seealso [method@Image.get_blob], [method@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. ::: seealso [ctor@Image.new_temp_file]. image to set format of file Attaches @d as a metadata item on @image as @name. A convenience function over [method@Image.set]. ::: seealso [method@Image.get_double], [method@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 [method@Image.set]. ::: seealso [method@Image.get_image], [method@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 [method@Image.set]. ::: seealso [method@Image.get_int], [method@Image.set]. image to attach the metadata to metadata name metadata value Set the [class@Image].kill flag on an image. Handy for stopping sets of threads. ::: seealso [method@Image.iskilled]. image to test the kill state vips signals evaluation progress via the [signal@Image::preeval], [signal@Image::eval] and [signal@Image::posteval] signals. Progress is signalled on the most-downstream image for which [method@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 [method@Image.set] using `VIPS_TYPE_REF_STRING`. ::: seealso [method@Image.get_double], [method@Image.set]. image to attach the metadata to metadata name metadata value Selectively sharpen the L channel of a LAB image. The input image is transformed to [enum@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. ::: tip "Optional arguments" * @sigma: `gdouble`, sigma of gaussian * @x1: `gdouble`, flat/jaggy threshold * @y2: `gdouble`, maximum amount of brightening * @y3: `gdouble`, maximum amount of darkening * @m1: `gdouble`, slope for flat areas * @m2: `gdouble`, slope for jaggy areas ::: seealso [method@Image.conv]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Shrink @in by a pair of factors with a simple box filter. For non-integer factors, [method@Image.shrink] will first shrink by the integer part with a box filter, then use [method@Image.reduce] to shrink by the remaining fractional part. This is a very low-level operation: see [method@Image.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. ::: tip "Optional arguments" * @ceil: `gboolean`, round-up output dimensions ::: seealso [method@Image.resize], [method@Image.reduce]. 0 on success, -1 on error input image output image horizontal shrink vertical shrink `NULL`-terminated list of optional named arguments 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 [method@Image.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. ::: tip "Optional arguments" * @ceil: `gboolean`, round-up output dimensions ::: seealso [method@Image.shrinkv], [method@Image.shrink], [method@Image.resize], [method@Image.affine]. 0 on success, -1 on error input image output image horizontal shrink `NULL`-terminated list of optional named arguments 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 [method@Image.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. ::: tip "Optional arguments" * @ceil: `gboolean`, round-up output dimensions ::: seealso [method@Image.shrinkh], [method@Image.shrink], [method@Image.resize], [method@Image.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. ::: seealso [method@Image.abs]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments This operator calls [method@Image.affine] for you, calculating the matrix for the affine transform from @scale and @angle. Other parameters are passed on to [method@Image.affine] unaltered. ::: tip "Optional arguments" * @scale: `gdouble`, scale by this factor * @angle: `gdouble`, rotate by this many degrees clockwise * @interpolate: [class@Interpolate], interpolate pixels with this * @background: [struct@ArrayDouble] colour for new pixels * @idx: `gdouble`, input horizontal offset * @idy: `gdouble`, input vertical offset * @odx: `gdouble`, output horizontal offset * @ody: `gdouble`, output vertical offset ::: seealso [method@Image.affine], [class@Interpolate]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.SIN] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.SINH] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Loops over an image. @generate_fn is called for every pixel in the image, with the @reg argument being a region of calculated pixels. [method@Image.sink] is used to implement operations like [method@Image.avg] which have no image output. Each set of pixels is sized according to the requirements of the image pipeline that generated @im. ::: seealso [method@Image.generate], [ctor@Image.new]. 0 on success, or -1 on error. scan over this image start sequences with this function generate pixels with this function stop sequences with this function user data user data [method@Image.sink_disc] loops over @im, top-to-bottom, generating it in sections. As each section is produced, @write_fn is called. @write_fn is always called single-threaded (though not always from the same thread), it's always given image sections in top-to-bottom order, and there are never any gaps. This operation is handy for making image sinks which output to things like disc files. Things like [method@Image.jpegsave], for example, use this to write images to files in JPEG format. ::: seealso [func@concurrency_set]. 0 on success, -1 on error. image to process called for every batch of pixels client data This operation renders @in in the background, making pixels available on @out as they are calculated. The @notify_fn callback is run every time a new set of pixels are available. Calculated pixels are kept in a cache with tiles sized @tile_width by @tile_height pixels and with at most @max_tiles tiles. If @max_tiles is -1, the cache is of unlimited size (up to the maximum image * size). The @mask image is a one-band uchar image and has 255 for pixels which are currently in cache and 0 for uncalculated pixels. Renders with a positive priority are assumed to be large, high-priority, foreground images. Although there can be many of these, only one is ever active, to avoid overcommitting threads. Renders with a negative priority are assumed to be small, thumbnail images, consisting of a single tile. Single tile images are effectively single-threaded, so all these renders are evaluated together. Calls to [method@Region.prepare] on @out return immediately and hold whatever is currently in cache for that [struct@Rect] (check @mask to see which parts of the [struct@Rect] are valid). Any pixels in the [struct@Rect] which are not in cache are added to a queue, and the @notify_fn callback will trigger when those pixels are ready. The @notify_fn callback is run from one of the background threads. In the callback you need to somehow send a message to the main thread that the pixels are ready. In a glib-based application, this is easily done with [func@GLib.idle_add]. If @notify_fn is `NULL` then [method@Image.sink_screen] runs synchronously. [method@Region.prepare] on @out will always block until the pixels have been calculated. ::: seealso [method@Image.tilecache], [method@Region.prepare], [method@Image.sink_disc], [method@Image.sink]. 0 on success, -1 on error. input image output image mask image indicating valid pixels tile width tile height maximum tiles to cache rendering priority pixels are ready notification callback client data for callback Loops over an image. @generate_fn is called for every pixel in the image, with the @reg argument being a region of calculated pixels. Each set of pixels is @tile_width by @tile_height pixels (less at the image edges). This is handy for things like writing a tiled TIFF image, where tiles have to be generated with a certain size. ::: seealso [method@Image.sink], [method@Image.get_tile_size]. 0 on success, or -1 on error. scan over this image tile width tile height start sequences with this function generate pixels with this function stop sequences with this function user data user data 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. ::: tip "Optional arguments" * @interesting: [enum@Interesting] to use to find interesting areas (default: [enum@Vips.Interesting.ATTENTION]) * @premultiplied: `gboolean`, input image already has premultiplied alpha * @attention_x: `gint`, output, horizontal position of attention centre when using attention based cropping * @attention_y: `gint`, output, vertical position of attention centre when using attention based cropping ::: seealso [method@Image.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. ::: seealso [method@Image.canny], [method@Image.sobel], [method@Image.prewitt], [method@Image.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. ::: seealso [method@Image.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 [method@Image.scale] in log mode, and [method@Image.wrap]. ::: seealso [method@Image.fwfft], [method@Image.scale], [method@Image.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 [enum@Vips.BandFormat.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 [method@Image.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. ::: seealso [method@Image.avg], [method@Image.min]. 0 on success, -1 on error image to scan image of statistics `NULL`-terminated list of optional named arguments [method@Image.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. ::: tip "Optional arguments" * @a: `gdouble`, weight of new mean * @m0: `gdouble`, target mean * @b: `gdouble`, weight of new deviation * @s0: `gdouble`, target deviation ::: seealso [method@Image.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 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. ::: tip "Optional arguments" * @point: `gboolean`, turn on point sample mode ::: seealso [method@Image.affine], [method@Image.shrink], [method@Image.zoom]. 0 on success, -1 on error. input image output image horizontal shrink factor vertical shrink factor `NULL`-terminated list of optional named arguments 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 [arithmetic](libvips-arithmetic.html)), then the following table is used to determine the output type: ## [method@Image.subtract] type promotion | input type | output type | |----------------|----------------| | uchar | short | | char | short | | ushort | int | | short | int | | uint | int | | int | int | | float | float | | double | double | | complex | complex | | double complex | double complex | In other words, the output type is just large enough to hold the whole range of possible values. ::: seealso [method@Image.add], [method@Image.linear]. 0 on success, -1 on error input image input image output image `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.TAN] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath.TANH] on an image. See [method@Image.math]. 0 on success, -1 on error input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.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 [ctor@Image.thumbnail] and produce poorer quality output. Only use this operation if you really have to. ::: tip "Optional arguments" * @height: `gint`, target height in pixels * @size: [enum@Size], upsize, downsize, both or force * @no_rotate: `gboolean`, don't rotate upright using orientation tag * @crop: [enum@Interesting], shrink and crop to fill target * @linear: `gboolean`, perform shrink in linear light * @input_profile: `gchararray`, fallback input ICC profile * @output_profile: `gchararray`, output ICC profile * @intent: [enum@Intent], rendering intent * @fail_on: [enum@FailOn], load error types to fail on ::: seealso [ctor@Image.thumbnail]. 0 on success, -1 on error. input image output image target width in pixels `NULL`-terminated list of optional named arguments Write a VIPS image to a file as TIFF. If @in has the [const@META_PAGE_HEIGHT] metadata item, this is assumed to be a "toilet roll" image. It will be written as series of pages, each [const@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 [enum@Vips.ForeignTiffPredictor.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 [const@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 [const@META_IMAGEDESCRIPTION] is used instead. The value of [const@META_XMP_NAME] is written to the XMP tag. [const@META_ORIENTATION] (if set) is used to set the value of the orientation tag. [const@META_IPTC_NAME] (if set) is used to set the value of the IPTC tag. [const@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. ::: tip "Optional arguments" * @compression: [enum@ForeignTiffCompression], write with this compression * @Q: `gint`, quality factor * @predictor: [enum@ForeignTiffPredictor], use this predictor * @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: `gint`, change bit depth to 1,2, or 4 bit * @miniswhite: `gboolean`, write 1-bit images as MINISWHITE * @resunit: [enum@ForeignTiffResunit] 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: [enum@RegionShrink] How to shrink each 2x2 region. * @level: `gint`, Zstd or Deflate (zlib) compression level * @lossless: `gboolean`, WebP lossless mode * @depth: [enum@ForeignDzDepth] how deep to make the pyramid * @subifd: `gboolean`, write pyr layers as sub-ifds * @premultiply: `gboolean`, write premultiplied alpha ::: seealso [ctor@Image.tiffload], [method@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 [method@Image.tiffsave], but save to a memory buffer. The address of the buffer is returned in @buf, the length of the buffer in @len. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "Optional arguments" * @compression: [enum@ForeignTiffCompression], write with this compression * @Q: `gint`, quality factor * @predictor: [enum@ForeignTiffPredictor], use this predictor * @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: `gint`, change bit depth to 1,2, or 4 bit * @miniswhite: `gboolean`, write 1-bit images as MINISWHITE * @resunit: [enum@ForeignTiffResunit] 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: [enum@RegionShrink] How to shrink each 2x2 region. * @level: `gint`, Zstd or Deflate (zlib) compression level * @lossless: `gboolean`, WebP lossless mode * @depth: [enum@ForeignDzDepth] how deep to make the pyramid * @subifd: `gboolean`, write pyr layers as sub-ifds * @premultiply: `gboolean`, write premultiplied alpha ::: seealso [method@Image.tiffsave], [method@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 [method@Image.tiffsave], but save to a target. ::: tip "Optional arguments" * @compression: [enum@ForeignTiffCompression], write with this compression * @Q: `gint`, quality factor * @predictor: [enum@ForeignTiffPredictor], use this predictor * @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: `gint`, change bit depth to 1,2, or 4 bit * @miniswhite: `gboolean`, write 1-bit images as MINISWHITE * @resunit: [enum@ForeignTiffResunit] 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: [enum@RegionShrink] How to shrink each 2x2 region. * @level: `gint`, Zstd or Deflate (zlib) compression level * @lossless: `gboolean`, WebP lossless mode * @depth: [enum@ForeignDzDepth] how deep to make the pyramid * @subifd: `gboolean`, write pyr layers as sub-ifds * @premultiply: `gboolean`, write premultiplied alpha ::: seealso [method@Image.tiffsave], [method@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 This operation behaves rather like [method@Image.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 [method@Region.prepare]. When the cache fills, a tile is chosen for reuse. If @access is [enum@Vips.Access.RANDOM], then the least-recently-used tile is reused. If @access is [enum@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 [enum@Vips.Access.RANDOM]. Normally, only a single thread at once is allowed to calculate tiles. If you set @threaded to `TRUE`, [method@Image.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. ::: tip "Optional arguments" * @tile_width: `gint`, width of tiles in cache * @tile_height: `gint`, height of tiles in cache * @max_tiles: `gint`, maximum number of tiles to cache * @access: [enum@Access], hint expected access pattern * @threaded: `gboolean`, allow many threads * @persistent: `gboolean`, don't drop cache at end of computation ::: seealso [method@Image.linecache]. 0 on success, -1 on error. input image output image `NULL`-terminated list of optional named arguments Transpose a volumetric image. Volumetric images are very tall, thin images, with the metadata item [const@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 [const@META_PAGE_HEIGHT] metadata item with the optional @page_height parameter. [const@META_PAGE_HEIGHT] in the output image is the number of pages in the input image. ::: tip "Optional arguments" * @page_height: `gint`, size of each input page ::: seealso [method@Image.grid]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Transform a uhdr image (three band sRGB with an attached gainmap) to scRGB. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Save an image as UltraHDR. If an image is sRGB and has a gainmap, it will be saved as UltraHDR with no gainmap recomputation. If the image is scRGB and has a gainmap, a base image will be computed and it will be saved as UltraHDR. If the image is scRGB and has no gainmap, one will be computed at a @gainmap_scale_factor of the base image. This is slow and takes a lot of memory. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @gainmap_scale_factor: `gint`, scale factor of base image to gainmap ::: seealso [method@Image.write_to_file], [ctor@Image.uhdrload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.uhdrsave], but save to a memory buffer. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @gainmap_scale_factor: `gint`, scale factor of base image to gainmap ::: seealso [method@Image.uhdrsave], [method@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 [method@Image.uhdrsave], but save to a target. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @gainmap_scale_factor: `gint`, scale factor of base image to gainmap ::: seealso [method@Image.uhdrsave], [method@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 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 [enum@Vips.BandFormat.FLOAT] unless the input format is [enum@Vips.BandFormat.DOUBLE], in which case the output is double as well. @max_alpha has the default value 255, or 65535 for images tagged as [enum@Vips.Interpretation.RGB16] or [enum@Vips.Interpretation.GREY16], and 1.0 for images tagged as [enum@Vips.Interpretation.scRGB. Non-complex images only. ::: tip "Optional arguments" * @max_alpha: `gdouble`, maximum value for alpha * @alpha_band: `gint`, band containing alpha data ::: seealso [method@Image.premultiply], [method@Image.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. ::: seealso [ctor@Image.vipsload]. 0 on success, -1 on error. image to save file to write to `NULL`-terminated list of optional named arguments As [method@Image.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 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 [enum@Vips.ForeignWebpPreset.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%. Set @exact to preserve the color data in transparent pixels. This can reduce compression efficiency, but is generally required when working with images as data. 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. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @exact: `gboolean`, preserves color values from transparent pixels * @preset: [enum@ForeignWebpPreset], 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 ::: seealso [ctor@Image.webpload], [method@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 [method@Image.webpsave], but save to a memory buffer. The address of the buffer is returned in @buf, the length of the buffer in @len. You are responsible for freeing the buffer with [func@GLib.free] when you are done with it. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @preset: [enum@ForeignWebpPreset], choose lossy compression preset * @exact: `gboolean`, preserves color values from transparent pixels * @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 ::: seealso [method@Image.webpsave]. 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 [method@Image.webpsave], but save as a mime webp on stdout. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @exact: `gboolean`, preserves color values from transparent pixels * @preset: [enum@ForeignWebpPreset], 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 ::: seealso [method@Image.webpsave], [method@Image.write_to_file]. 0 on success, -1 on error. image to save `NULL`-terminated list of optional named arguments As [method@Image.webpsave], but save to a target. ::: tip "Optional arguments" * @Q: `gint`, quality factor * @lossless: `gboolean`, enables lossless compression * @preset: [enum@ForeignWebpPreset], 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 ::: seealso [method@Image.webpsave]. 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 [func@IMAGE_ADDR] macro, that is, that the entire image is in memory and all pixels can be read with [func@IMAGE_ADDR]. If it isn't, try to transform it so that [func@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 [method@Image.copy_memory] instead. ::: seealso [method@Image.copy_memory], [method@Image.pio_input], [method@Image.inplace], [func@IMAGE_ADDR]. 0 on success, or -1 on error. image to transform Perform [enum@Vips.OperationMath2.WOP] on a pair of images. See [method@Image.math2]. 0 on success, -1 on error left-hand input [class@Image] right-hand input [class@Image] output [class@Image] `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.WOP] on an image and a constant. See [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] array of constants number of constants in @c `NULL`-terminated list of optional named arguments Perform [enum@Vips.OperationMath2.WOP] on an image and a constant. See [method@Image.math2_const]. 0 on success, -1 on error left-hand input [class@Image] output [class@Image] constant `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @x: `gint`, horizontal displacement * @y: `gint`, vertical displacement ::: seealso [method@Image.embed], [method@Image.replicate]. 0 on success, -1 on error input image output image `NULL`-terminated list of optional named arguments Write @image to @out. Use [ctor@Image.new] and friends to create the [class@Image] you want to write to. ::: seealso [ctor@Image.new], [method@Image.copy], [method@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 [property@Image:height]. @linebuffer must be [func@IMAGE_SIZEOF_LINE] bytes long. ::: seealso [method@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 [method@Image.generate] or [method@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 [method@Image.jpegsave_buffer], for example. ::: seealso [method@Image.write_to_memory], [ctor@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 [func@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. ::: seealso [ctor@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 [func@GLib.free]. ::: seealso [method@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 [method@Image.jpegsave_target], for example. ::: seealso [method@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. ::: seealso [method@Image.affine], [method@Image.subsample]. 0 on success, -1 on error. input image output image horizontal scale factor vertical scale factor `NULL`-terminated list of optional named arguments This 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 [method@Image.set_progress] to turn on progress reporting for an image. [struct@Progress] for this image This signal is emitted when an image or one of it's upstream data sources has been destructively modified. See [method@Image.invalidate_all]. This signal is emitted when an image has been asked to minimise memory usage. All non-essential caches are dropped. See [method@Image.minimise_all]. This signal is emitted once at the end of the computation of @image. It's a good place to shut down evaluation feedback. Use [method@Image.set_progress] to turn on progress reporting for an image. [struct@Progress] for this image This signal is emitted once before computation of @image starts. It's a good place to set up evaluation feedback. Use [method@Image.set_progress] to turn on progress reporting for an image. [struct@Progress] for this image This 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. [enum@Vips.Intent.ABSOLUTE] is best for scientific work, [enum@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 the rendering intent that the profile suggests Pick the algorithm vips uses to decide image "interestingness". This is used by [method@Image.smartcrop], for example, to decide what parts of the image to keep. [enum@Vips.Interesting.NONE] and [enum@Vips.Interesting.LOW] mean the same -- the crop is positioned at the top or left. [enum@Vips.Interesting.HIGH] positions at the bottom or right. ::: seealso [method@Image.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 An abstract base class for the various interpolation functions. Use `vips --list VipsInterpolate` to see all the interpolators available. An interpolator consists of a function to perform the interpolation, plus some extra data fields which tells libvips how to call the function and what data it needs. Look up an interpolator from a nickname and make one. You need to free the result with [method@GObject.Object.unref] when you're done with it. ::: seealso [func@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 [method@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 [func@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 @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 an @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 [property@Object:nickname] and [property@Object:description] in [class@Object]. ::: seealso [callback@InterpolateMethod], [class@Object] or [func@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 [func@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. ::: seealso [struct@InterpolateClass]. 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 [enum@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 [enum@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 pixels are in Oklab colourspace pixels are in Oklch colourspace The number of "real" bands we expect for this interpretation. If we've no idea (eg. MULTIBAND), return 0. the number of bands implied by this interpretation, or 0. image to check the maximum alpha value for an interpretation. image interpretation The resampling kernels vips supports. See [method@Image.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 convolve with Magic Kernel Sharp 2013 convolve with Magic Kernel Sharp 2021 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 [enum@Vips.BandFormat.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. ::: seealso [method@Image.wio_input], [method@Image.inplace], [func@check_matrix]. a [class@Image] 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 [method@Image.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 [method@Image.sequential] have this int field defined. Some operations (eg. [method@Image.shrinkv]) add extra caches if they see it on their input. If set, the height of the tiles for this image. If set, the width of the tiles for this image. 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 [func@tracked_malloc] if you are allocating large amounts of memory. ::: seealso [func@malloc]. allocate memory local to @OBJ, or `NULL` for no auto-free type of thing to allocate An abstract base class for all objects in libvips. It has the following major features: - **Functional class creation**: libvips objects have a very regular lifecycle: initialise, build, use, destroy. They behave rather like function calls and are free of side-effects. - **Run-time introspection**: libvips objects can be fully introspected at run-time. There is no need for separate source-code analysis. - **Command-line interface**: Any vips object can be run from the command-line with the `vips` driver program. ## The [class@Object] lifecycle [class@Object]'s have a strictly defined lifecycle, split broadly as construct and then use. In detail, the stages are: 1. [ctor@GObject.Object.new]. The [class@Object] is created with [ctor@GObject.Object.new]. Objects in this state are blank slates and need to have their various parameters set. 2. [method@GObject.Object.set]. You loop over the [struct@Argument] that the object has defined with [func@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. [method@Object.build]. Call this to construct the object and get it ready for use. Building an object happens in four stages, see below. 4. [method@GObject.Object.get]. The object has now been built. You can read out any computed values. 5. [method@GObject.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 [class@Object] uses. When the last ref to an object is released, the object is closed. Objects close in three stages, see below. The stages inside [method@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 [class@Object] 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. [method@Object.build] finishes the process by checking that all output objects have been set, and then triggering the [signal@Object::postbuild] signal. [signal@Object::postbuild] only runs if the object has constructed successfully. [class@Operation] has a cache of recent operation objects, see that class for an explanation of [func@cache_operation_build]. Finally, the stages inside close are: 1. [signal@Object::preclose]. This is emitted at the start of the [class@Object] dispose. The object is still functioning. 2. [signal@Object::close]. This runs just after all [struct@Argument] held by the object have been released. 3. [signal@Object::postclose]. This runs right at the end. The object pointer is still valid, but nothing else is. ## The [class@Object] reference counting convention [class@Object] has a set of conventions to simplify reference counting. 1. All input [class@GObject.Object] have a ref added to them, owned by the object. When a [class@Object] is unreffed, all of these refs to input objects are automatically dropped. 2. All output [class@GObject.Object] hold a ref to the object. When a [class@GObject.Object] which is an output of a [class@Object] is disposed, it must drop this reference. [class@Object] which are outputs of other [class@Object]'s will do this automatically. See [class@Operation] for an example of [class@Object] reference counting. [ctor@GObject.Object.new] the object, set any arguments with @set, call [method@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 [ctor@Object.new_from_string]: turn @object into eg. `"bicubic"`. 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 [class@GObject.ParamSpec] names and [flags@ArgumentFlags] for an object. This is handy for language bindings. From C, it's usually more convenient to use [func@Argument.map]. 0 on success, -1 on error object whose args should be retrieved output array of [class@GObject.ParamSpec] names output array of [flags@ArgumentFlags] 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 [flags@ArgumentFlags] 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. [property@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` [class@Object] 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: ```c 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; ``` 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: ```c 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. ::: seealso [method@Object.set_valist], [method@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. ::: seealso [method@Object.set], [method@Object.build], [func@cache_operation_buildp]. 0 on success, -1 on error object to set arguments on arguments as a string See [method@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 [ctor@Object.new_from_string]: turn @object into eg. `"bicubic"`. 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. ::: seealso [func@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 An abstract base class for all operations in libvips. It builds on [class@Object] to provide the introspection and command-line interface to libvips. It also maintains a cache of recent operations. See below. [func@call], [func@call_split] and [func@call_split_option_string] are used by vips to implement the C API. They can execute any [class@Operation], 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, [method@Image.embed] is defined as: ```c 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 [func@call_argv] to run any libvips operation from a command-line style argc/argv array. This is the thing used by the `vips` main program to implement the command-line interface. ## [class@Operation] and reference counting After calling a [class@Operation] you are responsible for unreffing any output objects. For example, consider: ```c VipsImage *im = ...; VipsImage *t1; if (vips_invert(im, &t1, NULL)) error .. ``` This will invert `im` and return a new [class@Image], `t1`. As the caller of [method@Image.invert], you are responsible for `t1` and must unref it when you no longer need it. If [method@Image.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`, [method@Image.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: ```c 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: ```c 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. [method@Object.local_array] makes an array of [class@Object] (or [class@Image], in this case) where when `parent` is freed, all non-`NULL` [class@Object] in the array are also unreffed. ## The [class@Operation] cache Because all [class@Object] are immutable, they can be cached. The cache is very simple to use: instead of calling [method@Object.build], call [func@cache_operation_build]. This function calculates a hash from the operations' 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 [func@cache_set_max] and friends. Return a new [class@Operation] 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 [func@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: ```c 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. ::: seealso [func@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: [method@Image.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: [method@Image.complex]. convert to polar coordinates convert to rectangular coordinates complex conjugate See also: [method@Image.complex2]. convert to polar coordinates See also: [method@Image.complexget]. get real component get imaginary component Flags we associate with an operation. [flags@Vips.OperationFlags.SEQUENTIAL] means that the operation works like [method@Image.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 [flags@Vips.OperationFlags.NOCACHE] means that the operation must not be cached by vips. [flags@Vips.OperationFlags.DEPRECATED] means this is an old operation kept in vips for compatibility only and should be hidden from users. [flags@Vips.OperationFlags.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 [func@block_untrusted_set] to block all untrusted operations. [flags@Vips.OperationFlags.BLOCKED] means the operation is prevented from executing. Use [func@Operation.block_set] to enable and disable groups of operations. [flags@Vips.OperationFlags.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 deprecated, use [flags@Vips.OperationFlags.SEQUENTIAL] instead must not be cached a compatibility thing not hardened for untrusted input prevent this operation from running force the operation to run See also: [method@Image.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: [method@Image.math]. `pow(left, right)` `pow(right, left)` `atan2(left, right)` More like hit-miss, really. ::: seealso [method@Image.morph]. true if all set true if one set See also: [method@Image.relational]. `==` `!=` `<` `<=` `>` `>=` See also: [method@Image.round]. round to nearest the smallest integral value not less than largest integral value not greater than Pick a Profile Connection Space for [method@Image.icc_import] and [method@Image.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 [signal@Image::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 [struct@Rect] (@R->valid). If DEBUG is defined, you get a version that checks bounds for you. ::: seealso [method@Region.prepare]. a [class@Region] x coordinate y coordinate This macro returns a pointer to the top-left pixel in the [class@Region], that is, the pixel at (@R->valid.left, @R->valid.top). ::: seealso [method@Region.prepare]. a [class@Region] a [class@Region] a [class@Region] a [class@Region] A [struct@Rect] 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 [func@GLib.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. ::: seealso [method@Area.unref]. the new [struct@RefString], or `NULL` on error. string to store Get a pointer to the private string inside a refstr. Handy for language bindings. ::: seealso [func@value_get_ref_string]. The C string held by @refstr. the [struct@RefString] to fetch from return length here, optionally A [class@Region] represents a small, rectangular 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. libvips sanity-checks region ownership in various places, so you are likely to see [func@GLib.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 libvips, so we don't expose it. Create a region. [class@Region] start out empty, you need to call [method@Region.prepare] to fill them with pixels. ::: seealso [method@Region.prepare]. image to create this region on Paints 0 into the valid part of @reg. ::: seealso [method@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 [struct@Rect] 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. ::: seealso [method@Region.paint]. source region destination region [struct@Rect] 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. ```c 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 region to test Generate an area of pixels and return a copy. The result must be freed with [func@GLib.free]. The requested area must be completely inside the image. This is equivalent to [method@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 [struct@Rect] of pixels you need to be able to address Mark a region as containing invalid pixels. Calling this function means that the next time [method@Region.prepare] is called, the region will be recalculated. This is faster than calling [method@Image.invalidate_all], but obviously only affects a single region. ::: seealso [method@Image.invalidate_all], [method@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()`](man:memset(3)), 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. ::: seealso [method@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. ::: seealso [method@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 [method@Region.prepare] fills @reg with pixels. After calling, you can address at least the area @r with [func@REGION_ADDR] and get valid pixels. [method@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 [method@Image.sink_screen] to calculate an area of pixels in the background. ::: seealso [method@Image.sink_screen], [method@Region.prepare_to]. 0 on success, or -1 on error. region to prepare [struct@Rect] of pixels you need to be able to address Like [method@Region.prepare]: fill @reg with the pixels in area @r. Unlike [method@Region.prepare], rather than writing the result to @reg, the pixels are written into @dest at offset @x, @y. Also unlike [method@Region.prepare], @dest is not set up for writing for you with [method@Region.buffer]. You can point @dest at anything, and pixels really will be written there. This makes [method@Region.prepare_to] useful for making the ends of pipelines. ::: seealso [method@Region.prepare], [method@Image.sink_disc]. 0 on success, or -1 on error region to prepare region to write to [struct@Rect] of pixels you need to be able to address position of @r in @dest position of @r in @dest Make [func@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 [struct@Rect] 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 [method@Image.hasalpha]) shrink with pixels scaled by alpha to avoid fringing. This is a compatibility stub that just calls [method@Region.shrink_method]. ::: seealso [method@Region.shrink_method]. source region destination region [struct@Rect] 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. @method selects the method used to do the 2x2 shrink. ::: seealso [method@Region.copy]. source region destination region [struct@Rect] of pixels you need to copy method to use when generating target pixels Width of the pixels held in region. fetch width from this How to calculate the output pixels when shrinking a 2x2 region. Images with alpha (see [method@Image.hasalpha]) always shrink with [enum@Vips.RegionShrink.MEAN] and pixels scaled by alpha to avoid fringing. Set the image interpretation to [enum@Vips.Interpretation.MULTIBAND] to treat all bands equally. use the average use the median use the mode use the maximum use the minimum use the top-left pixel The function should write the pixels in @area from @region. @a is the value passed into [method@Image.sink_disc]. ::: seealso [method@Image.sink_disc]. 0 on success, -1 on error. get pixels from here area to write client data After a successful [func@SBUF_REQUIRE], you can use this require times to fetch characters of input. Fetch the next character from the source. After a successful [func@SBUF_REQUIRE], you can index this to get require characters of input. Make sure at least @require characters are available for [func@SBUF_PEEK] and [func@SBUF_FETCH]. The opposite of [method@Sbuf.getc]: undo the previous getc. unget more than one character is undefined. Unget at the start of the file does nothing. A [class@Sbuf] provides a buffered reading interface for a [class@Source]. You can fetch lines of text, skip whitespace, and so on. It is useful for implementing things like CSV readers, for example. Create a [class@Sbuf] wrapping a source. a new [class@Sbuf] source to operate on Fetch the next line of text from @sbuf and return it. The end of line character (or characters, for DOS files) are removed, and the string is terminated with a null (`\0` character). Returns `NULL` on end of file or read error. If the line is longer than some arbitrary (but large) limit, it is truncated. If you need to be able to read very long lines, use the slower [method@Sbuf.get_line_copy]. The return value is owned by @sbuf and must not be freed. It is valid until the next get call to @sbuf. the next line of text, or `NULL` on EOF or read error. source to operate on Fetch the next line of text from @sbuf and return it. The end of line character (or characters, for DOS files) are removed, and the string is terminated with a null (`\0` character). The return result must be freed with [func@GLib.free]. This is slower than [method@Sbuf.get_line], but can work with lines of any length. the next line of text, or `NULL` on EOF or read error. source to operate on Fetch the next chunk of non-whitespace text from the source, and null-terminate it. After this, the next getc will be the first char of the next block of whitespace (or EOF). If the first getc is whitespace, stop instantly and return the empty string. If the item is longer than some arbitrary (but large) limit, it is truncated. The return value is owned by @sbuf and must not be freed. It is valid until the next get call to @sbuf. the next block of non-whitespace, or `NULL` on EOF or read error. source to operate on Fetch the next character from the source. If you can, use the macro [func@SBUF_GETC] instead for speed. the next char from @sbuf, -1 on read error or EOF. source to operate on Make sure there are at least @require bytes of readahead available. 0 on success, -1 on error or EOF. source to operate on make sure we have at least this many chars available After this, the next getc will be the first char of the next block of non-whitespace (or EOF). Also skip comments, ie. from any '#' character to the end of the line. 0 on success, or -1 on EOF. source to operate on Discard the input buffer and reset the read point. You must call this before using read or seek on the underlying [class@Source] class. source to operate on The opposite of [method@Sbuf.getc]: undo the previous getc. unget more than one character is undefined. Unget at the start of the file does nothing. If you can, use the macro [func@SBUF_UNGETC] instead for speed. source to operate on The SDF to generate, ::: seealso [ctor@Image.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. ::: seealso [ctor@Image.thumbnail]. size both up and down only upsize only downsize force size, that is, break aspect ratio A [class@Source] provides a unified interface for reading, seeking, and mapping data, regardless of the underlying source type. This source can originate from something like a socket, file or memory area. During the header phase, we save data from unseekable sources in a buffer so readers can rewind and read again. We don't buffer data during the decode stage. Create a source attached to an area of memory. a new source. memory area to load Create an source attached to a file descriptor. @descriptor is closed with [`close()`](man:close(2)) when source is finalized. a new source. read from this file descriptor Create a source attached to a file. If this descriptor does not support mmap and the source is used with a loader that can only work from memory, then the data will be automatically read into memory to EOF before the loader starts. This can produce high memory use if the descriptor represents a large object. Use [func@pipe_read_limit_set] to limit the size of object that will be read in this way. The default is 1GB. a new source. read from this filename Create a source attached to an area of memory. You must not free @data while the source is active. a new source. memory area to load size of memory area Create a source from an option string. a new source. option string Create a source from a temp target that has been written to. a new source. build the source from this target Read up to @length bytes from @source and store the bytes in @buffer. Return the number of bytes actually read. If all bytes have been read from the file, return 0. Arguments exactly as [`read()`](man:read(2)). the number of bytes read, 0 on end of file, -1 on error. source to operate on store bytes here length of @buffer in bytes Move the file read position. You can't call this after pixel decode starts. The arguments are exactly as [`lseek()`](man:lseek(2)). the new file position, or -1 on error. source to operate on seek by this offset seek relative to this point Signal the end of header read and the start of the pixel decode phase. After this, you can no longer seek on this source. Loaders should call this at the end of header read. ::: seealso [method@Source.unminimise]. 0 on success, -1 on error. source to operate on Test if this source is a simple file with support for seek. Named pipes, for example, will fail this test. If `TRUE`, you can use [method@Connection.filename] to find the filename. Use this to add basic source support for older loaders which can only work on files. `TRUE` if the source is a simple file. source to operate on Some sources can be efficiently mapped into memory. You can still use [method@Source.map] if this function returns `FALSE`, but it will be slow. `TRUE` if the source can be efficiently mapped into memory. source to operate on Return the length in bytes of the source. Unseekable sources, for example pipes, will have to be read entirely into memory before the length can be found, so this operation can take a long time. number of bytes in source, or -1 on error. source to operate on Map the source entirely into memory and return a pointer to the start. If @length is non-NULL, the source size is written to it. This operation can take a long time. Use [method@Source.is_mappable] to check if a source can be mapped efficiently. The pointer is valid for as long as @source is alive. a pointer to the start of the file contents, or `NULL` on error. source to operate on return the file length here, or `NULL` Just like [method@Source.map], but return a [struct@Blob] containing the pointer. @source will stay alive as long as the result is alive. a new [struct@Blob] containing the data, or `NULL` on error. source to operate on Minimise the source. As many resources as can be safely removed are removed. Use [method@Source.unminimise] to restore the source if you wish to use it again. Loaders should call this in response to the minimise signal on their output image. source to operate on Read up to @length bytes from @source and store the bytes in @buffer. Return the number of bytes actually read. If all bytes have been read from the file, return 0. Arguments exactly as [`read()`](man:read(2)). the number of bytes read, 0 on end of file, -1 on error. source to operate on store bytes here length of @buffer in bytes Rewind the source to the start. You can't always do this after the pixel decode phase starts -- for example, pipe-like sources can't be rewound. 0 on success, or -1 on error. source to operate on Move the file read position. You can't call this after pixel decode starts. The arguments are exactly as [`lseek()`](man:lseek(2)). the new file position, or -1 on error. source to operate on seek by this offset seek relative to this point Return a pointer to the first few bytes of the file. If the file is too short, return `NULL`. a pointer to the bytes at the start of the file, or `NULL` on error. sniff this source number of bytes to sniff Attempt to sniff at most @length bytes from the start of the source. A pointer to the bytes is returned in @data. The number of bytes actually read is returned -- it may be less than @length if the file is shorter than @length. A negative number indicates a read error. Do not use it if @length is greater than `UINT_MAX`. [struct@GLib.ByteArray] stores the length of its data in `guint`, which may be shorter than `size_t`. number of bytes read, or -1 on error. peek this source return a pointer to the bytes read here max number of bytes to read Restore the source after minimisation. This is called at the start of every source method, so loaders should not usually need this. ::: seealso [method@Source.minimise]. 0 on success, or -1 on error. source to operate on the number of bytes read, 0 on end of file, -1 on error. source to operate on store bytes here length of @buffer in bytes the new file position, or -1 on error. source to operate on seek by this offset seek relative to this point Subclass of [class@Source] with action signals for handlers. This is supposed to be useful for language bindings. Create a [class@SourceCustom]. Attach signals to implement read and seek. a new [class@SourceCustom] This signal is emitted to read bytes from the source into @buffer. the number of bytes read. Return 0 for EOF. `gpointer`, buffer to fill `gint64`, size of buffer This signal is emitted to seek the source. The handler should change the source position appropriately. The handler for an unseekable source should always return -1. the new seek position. `gint64`, seek offset `gint`, seek origin Create a [class@SourceGInputStream] which wraps @stream. ::: seealso [ctor@GInputStream.new_from_source] the new source. read from this stream Start a new processing sequence for this generate function. This allocates per-thread state, such as an input region. ::: seealso [func@start_one], [func@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. ::: seealso [func@stop_one], [func@stop_many]. 0 on success, -1 on error. sequence value user data user data [const@TRANSFORM_SHIFT] as a multiplicative constant. Many of the libvips interpolators use fixed-point arithmetic for coordinate calculation. This is how many bits of precision they use. A [class@Target] provides a unified interface for writing data to various output destinations. This target could be a socket, file, memory area, or any other destination that accepts byte data. Create a temporary target -- either a temporary file on disc, or an area in memory, depending on what sort of target @based_on is. ::: seealso [ctor@Target.new_to_file]. a new target. base the temporary target on this target Create a target attached to a file descriptor. @descriptor is kept open until the target is finalized. ::: seealso [ctor@Target.new_to_file]. a new target. write to this file descriptor Create a target attached to a file. a new target. write to this file Create a target which will write to a memory area. Read from @blob to get memory. ::: seealso [ctor@Target.new_to_file]. a new target. Call this at the end of write to make the target do any cleaning up. You can call it many times. After a target has been ended, further writes will do nothing. 0 on success, -1 on error. target to operate on Read up to @length bytes from @target and store the bytes in @buffer. Return the number of bytes actually read. If all bytes have been read from the file, return 0. Arguments exactly as [`read()`](man:read(2)). Reading from a target sounds weird, but libtiff needs this for multi-page writes. This method will fail for targets like pipes. the number of bytes read, 0 on end of file, -1 on error. target to operate on store bytes here length of @buffer in bytes Seek the target. This behaves exactly as [`lseek()`](man:lseek(2)). Seeking a target sounds weird, but libtiff needs this. This method will fail for targets like pipes. the new offset, -1 on error. target to operate on offset to seek to seek relative to beginning, offset, or end Call this at the end of write to make the target do any cleaning up. You can call it many times. After a target has been ended, further writes will do nothing. 0 on success, -1 on error. target to operate on Write a single character @ch to @target. See the macro [func@TARGET_PUTC] for a faster way to do this. 0 on success, -1 on error. target to operate on character to write Read up to @length bytes from @target and store the bytes in @buffer. Return the number of bytes actually read. If all bytes have been read from the file, return 0. Arguments exactly as [`read()`](man:read(2)). Reading from a target sounds weird, but libtiff needs this for multi-page writes. This method will fail for targets like pipes. the number of bytes read, 0 on end of file, -1 on error. target to operate on store bytes here length of @buffer in bytes Seek the target. This behaves exactly as [`lseek()`](man:lseek(2)). Seeking a target sounds weird, but libtiff needs this. This method will fail for targets like pipes. the new offset, -1 on error. target to operate on offset to seek to seek relative to beginning, offset, or end Memory targets only (see [ctor@Target.new_to_memory]). Steal all data written to the target so far, and call [method@Target.end]. You must free the returned pointer with [func@GLib.free]. The data is NOT automatically null-terminated. Use [method@Target.putc] with a '\0' before calling this to get a null-terminated string. You can't call this after [method@Target.end], since that moves the data to a blob, and we can't steal from that in case the pointer has been shared. You can't call this function more than once. the data target to operate on return number of bytes of data As [method@Target.steal], but return a null-terminated string. target contents as a null-terminated string. target to operate on Write @length bytes from @data to the output. 0 on success, -1 on error. target to operate on data to write length of @data in bytes Write @str to @target, but escape stuff that xml hates in text. Our argument string is utf-8. XML rules: - We must escape &<> - Don't escape \n, \t, \r - Do escape the other ASCII codes. 0 on success, -1 on error. target to operate on string to write Format the string and write to @target. 0 on success, and -1 on error. target to operate on `printf()`-style format string arguments to format string Write a null-terminated string to @target. 0 on success, and -1 on error. target to operate on string to write the number of bytes read, 0 on end of file, -1 on error. target to operate on store bytes here length of @buffer in bytes the new offset, -1 on error. target to operate on offset to seek to seek relative to beginning, offset, or end 0 on success, -1 on error. target to operate on Subclass of [class@Target] with action signals for handlers. This is supposed to be useful for language bindings. Create a [class@TargetCustom]. Attach signals to implement write and finish. a new [class@TargetCustom] This signal is emitted at the end of write. The target should do any finishing necessary. 0 on success, -1 on error. Deprecated for [signal@TargetCustom::end]. This signal is emitted to read bytes from the target into @buffer. The handler for an unreadable target should always return -1. the number of bytes read. Return 0 for EOF. `gpointer`, buffer to fill `gint64`, size of buffer This signal is emitted to seek the target. The handler should change the target position appropriately. The handler for an unseekable target should always return -1. the new seek position. `gint64`, seek offset `gint`, seek origin This signal is emitted to write bytes to the target. the number of bytes written. `gpointer`, bytes to write `gint64`, number of bytes Sets the word wrapping style for [ctor@Image.text] when used with a maximum width. ::: seealso [ctor@Image.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 [class@ThreadState] represents a per-thread state. [callback@ThreadpoolAllocateFn] functions can use these members to communicate with [callback@ThreadpoolWorkFn] functions. ::: seealso [func@threadpool_run]. This function is called to allocate a new work unit for the thread. It is always single-threaded, so it can modify per-pool state (such as a counter). It should set @stop to `TRUE` to indicate that no work could be allocated because the job is done. ::: seealso [func@threadpool_run]. 0 on success, or -1 on error per-thread state client data set this to signal end of computation This function is called by the main thread once for every work unit processed. It can be used to give the user progress feedback. ::: seealso [func@threadpool_run]. 0 on success, or -1 on error client data This function is called to process a work unit. Many copies of this can run at once, so it should not write to the per-pool state. It can write to per-thread state. ::: seealso [func@threadpool_run]. 0 on success, or -1 on error per-thread state client data Tokens returned by the vips lexical analyzer, see vips__token_get(). This is used to parse option strings for arguments. Left and right brackets can be any of (, {, [, <. Strings may be in double quotes, and may contain escaped quote characters, for example string, "string" and "str\"ing". left bracket right bracket string constant equals sign comma Add the standard vips [struct@GLib.OptionEntry] to a [struct@GLib.OptionGroup]. ::: seealso [ctor@GLib.OptionGroup.new]. group to add to Convenience function -- make a `NULL`-terminated array of input images. Use with [func@start_many]. ::: seealso [method@Image.generate], [func@start_many]. `NULL`-terminated array of images. Do not free the result. free array when this image closes `NULL`-terminated list of input images 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. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments And loop over a class. Same as ^^, but with no VipsArgumentInstance. Allocate a new property id. See [method@GObject.ObjectClass.install_property]. a new property id > 0 Loop over the [struct@Argument] of 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 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 [arithmetic](libvips-arithmetic.html)). [method@Image.colourspace] can be useful for moving the images to a common colourspace for compositing. ::: tip "Optional arguments" * @across: `gint`, number of images per row * @shim: `gint`, space between images, in pixels * @background: [struct@ArrayDouble], background ink colour * @halign: [enum@Align], low, centre or high alignment * @valign: [enum@Align], low, centre or high alignment * @hspacing: `gint`, horizontal distance between images * @vspacing: `gint`, vertical distance between images ::: seealso [method@Image.join], [method@Image.insert], [method@Image.colourspace]. 0 on success, -1 on error array of input images output image number of input images `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 [arithmetic](libvips-arithmetic.html)). ::: seealso [method@Image.insert]. 0 on success, -1 on error array of input images output image number of input images `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @index: `gint`, pick this index from list of sorted values ::: seealso [method@Image.rank]. 0 on success, -1 on error array of input images output image number of input images `NULL`-terminated list of optional named arguments Make a black unsigned char image of a specified size. ::: tip "Optional arguments" * @bands: `gint`, output bands ::: seealso [ctor@Image.xyz], [ctor@Image.text], [ctor@Image.gaussnoise]. 0 on success, -1 on error output image output width output height `NULL`-terminated list of optional named arguments Like [ctor@Blob.new], but take a copy of the data. Useful for bindings which struggle with callbacks. ::: seealso [ctor@Blob.new]. the new [struct@Blob]. data to store number of bytes in @data Set the block state on all untrusted operations. ```c 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 [func@init]. the block state to set Drop the whole operation cache, handy for leak tracking. Also called automatically on [func@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 [func@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 [ctor@Image.magickload], most of the descriptors it uses won't be included. ::: seealso [func@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 [func@tracked_get_mem]. ::: seealso [func@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 [func@cache_operation_buildp]. After calling this, @operation has the same ref count as when it went in, and the result must be freed with [method@Object.unref_outputs] and [method@GObject.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 [signal@Image::invalidate] are removed from cache. Operators with the [flags@Vips.OperationFlags.BLOCKED] flag are never executed. Operators with the [flags@Vips.OperationFlags.REVALIDATE] flag are always executed and any old cache value is replaced. Operators with the [flags@Vips.OperationFlags.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. ::: seealso [func@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 [func@tracked_get_files]. ::: seealso [func@tracked_get_files]. max open files we allow Set the maximum amount of tracked memory we allow before we start dropping cached operations. See [func@tracked_get_mem]. libvips only tracks memory it allocates, it can't track memory allocated by external libraries. If you use an operation like [ctor@Image.magickload], most of the memory it uses won't be included. ::: seealso [func@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`. ::: seealso [func@cache_set_dump]. if `TRUE`, trace the operation cache [func@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, [method@Image.embed] takes six required arguments, @in, @out, @x, @y, @width, @height, and has two optional arguments, @extend and @background. You can run it with [func@call] like this: ```c 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 [method@Image.embed] wrapper function and get type-safety for the required arguments. ::: seealso [func@call_split], [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. [func@check_bands_1orn]. If not, set an error message and return non-zero. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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 [func@MATRIX] to address values in @out. You must unref @out when you are done with it. ::: seealso [func@MATRIX]. 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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@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 [func@col_make_tables_CMC] at least once before using this function. C. 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 [func@col_make_tables_CMC] at least once before using this function. h. Chroma Hue cmc (degrees) Calculate Lcmc from L. Lcmc CIE L* Calculate XYZ from Lab, D65. ::: seealso [method@Image.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 [func@col_make_tables_CMC] at least once before using this function. L* L cmc Calculate XYZ from Lab, D65. ::: seealso [method@Image.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. ::: seealso [method@Image.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. ::: seealso [method@Image.scRGB2XYZ]. Input scRGB value Input scRGB value Input scRGB value Return XYZ colour Return XYZ colour Return XYZ colour 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 [enum@BlendMode] in @mode. Images are transformed to a compositing space before processing. This is [enum@Vips.Interpretation.sRGB], [enum@Vips.Interpretation.B_W], [enum@Vips.Interpretation.RGB16], or [enum@Vips.Interpretation.GREY16] by default, depending on how many bands and bits the input images have. You can select any other space, such as [enum@Vips.Interpretation.LAB] or [enum@Vips.Interpretation.scRGB]. The output image is in the compositing space. It will always be [enum@Vips.BandFormat.FLOAT] unless one of the inputs is [enum@Vips.BandFormat.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 [method@Image.premultiply], set @premultiplied. ::: tip "Optional arguments" * @compositing_space: [enum@Interpretation] to composite in * @premultiplied: `gboolean`, images are already premultiplied * @x: [struct@ArrayInt], array of (@n - 1) x coordinates * @y: [struct@ArrayInt], array of (@n - 1) y coordinates ::: seealso [method@Image.insert]. 0 on success, -1 on error array of input images output image number of input images array of (@n - 1) [enum@BlendMode] `NULL`-terminated list of optional named arguments Returns the number of worker threads that vips should use when running [func@threadpool_run]. vips gets this values from these sources in turn: If [func@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 [func@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. ::: seealso [func@concurrency_get]. number of worker threads to use. Sets the number of worker threads that vips should use when running [func@threadpool_run]. 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. ::: seealso [func@concurrency_get]. number of threads to run Load a CSV (comma-separated values) file. The output image is always 1 band (monochrome), [enum@Vips.BandFormat.DOUBLE]. Use [method@Image.bandfold] to turn RGBRGBRGB mono images into colour images. Items in lines can be either floating point numbers in the C locale, or strings enclosed in double-quotes ("), or empty. You can use a backslash (\) within the quotes to escape special characters, such as quote marks. @skip sets the number of lines to skip at the start of the file. Default zero. @lines sets the number of lines to read from the file. Default -1, meaning read all lines to end of file. @whitespace sets the skippable whitespace characters. Default *space*. Whitespace characters are always run together. @separator sets the characters that separate fields. Default ;,*tab*. Separators are never run together. Use @fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, [enum@Vips.FailOn.NONE]. ::: tip "Optional arguments" * @skip: `gint`, skip this many lines at start of file * @lines: `gint`, read this many lines from file * @whitespace: `gchararray`, set of whitespace characters * @separator: `gchararray`, set of separator characters * @fail_on: [enum@FailOn], types of read error to fail on ::: seealso [ctor@Image.new_from_file], [method@Image.bandfold]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.csvload], but read from a source. ::: tip "Optional arguments" * @skip: `gint`, skip this many lines at start of file * @lines: `gint`, read this many lines from file * @whitespace: `gchararray`, set of whitespace characters * @separator: `gchararray`, set of separator characters * @fail_on: [enum@FailOn], types of read error to fail on ::: seealso [ctor@Image.csvload]. 0 on success, -1 on error. source to load output image `NULL`-terminated list of optional named arguments Read a RAW camera file using LibRaw. This loader supports the most RAW formats, including ARW, CR2, CR3, CRW, DNG, NEF, NRW, ORF, PEF, RAF, RAW, RW2, SRW, X3F, and many others. The loader applies demosaicing and basic processing to produce an RGB or grayscale image suitable for further processing. It attaches XMP and ICC metadata, if present. ::: tip "Optional arguments" * @bitdepth: `gint`, load as 8 or 16 bit data 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.dcrawload], but read from a buffer. ::: tip "Optional arguments" * @bitdepth: `gint`, load as 8 or 16 bit data ::: seealso [ctor@Image.dcrawload]. 0 on success, -1 on error. memory area to load size of memory area output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.dcrawload], but read from a source. ::: tip "Optional arguments" * @bitdepth: `gint`, load as 8 or 16 bit data ::: seealso [ctor@Image.dcrawload]. 0 on success, -1 on error. source to load from image to write `NULL`-terminated list of optional named arguments Format the string in the style of [`printf()`](man:printf(3)) and append to the error buffer. ::: seealso [func@error_system], [func@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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [func@error]. `printf()`-style format string for the message arguments to the format string Stop errors being logged. Use [func@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 [func@g_error] for the inverse operation. ::: seealso [func@GLib.set_error], [func@g_error]. Format the string in the style of [`printf()`](man:printf(3)) and append to the error buffer. Then create and append a localised message based on the system error code, usually the value of errno. ::: seealso [func@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. 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. ::: tip "Optional arguments" * @factor: `gdouble`, maximum spatial frequency * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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. ::: seealso [func@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. ::: seealso [func@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. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.fitsload], but read from a source. 0 on success, -1 on error. source to load from decompressed image `NULL`-terminated list of optional named arguments 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 [func@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. ::: seealso [ctor@Image.gaussnoise], [ctor@Image.mask_fractal]. 0 on success, -1 on error output image output width output height fractal dimension `NULL`-terminated list of optional named arguments This function adds the [struct@GLib.Error] to the vips error buffer and clears it. It's the opposite of [func@error_g]. ::: seealso [func@error_g]. Wrapper for [ctor@GLib.Thread.try_new]. the new [struct@GLib.Thread], or `NULL` if an error occurred an (optional) name for the new thread a function to execute in the new thread an argument to supply to the new thread 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 [enum@Vips.Precision.INTEGER]. If @separable is set, only the centre horizontal is generated. This is useful for separable convolutions. If @precision is [enum@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. ::: tip "Optional arguments" * @separable: `gboolean`, generate a separable gaussian * @precision: [enum@Precision] for @out ::: seealso [ctor@Image.logmat], [method@Image.conv]. 0 on success, -1 on error output image standard deviation of mask minimum amplitude `NULL`-terminated list of optional named arguments Make a one band float image of gaussian noise with the specified distribution. The gaussian distribution is created by averaging 12 random numbers from a linear generator, then weighting appropriately with @mean and @sigma. ::: tip "Optional arguments" * @mean: `gdouble`, mean of generated pixels * @sigma: `gdouble`, standard deviation of generated pixels ::: seealso [ctor@Image.black], [ctor@Image.xyz], [ctor@Image.text]. 0 on success, -1 on error output image output width output height `NULL`-terminated list of optional named arguments ::: seealso [func@INIT]. a pointer to an internal copy of the argv0 string passed to [func@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 [ctor@Image.new_from_file]. disc threshold in bytes. Return the program name. ::: seealso [func@INIT]. a pointer to an internal copy of the program name. Do not free this value 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 [method@Image.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, [enum@Vips.FailOn.NONE]. The output image is RGBA for GIFs containing transparent elements, RGB otherwise. ::: tip "Optional arguments" * @page: `gint`, page (frame) to read * @n: `gint`, load this many pages * @fail_on: [enum@FailOn], types of read error to fail on ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.gifload], but read from a memory buffer. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @page: `gint`, page (frame) to read * @n: `gint`, load this many pages * @fail_on: [enum@FailOn], types of read error to fail on ::: seealso [ctor@Image.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 Exactly as [ctor@Image.gifload], but read from a source. ::: tip "Optional arguments" * @page: `gint`, page (frame) to read * @n: `gint`, load this many pages * @fail_on: [enum@FailOn], types of read error to fail on ::: seealso [ctor@Image.gifload]. 0 on success, -1 on error. source to load image to write `NULL`-terminated list of optional named arguments 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. ::: tip "Optional arguments" * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.xyz], [ctor@Image.identity]. 0 on success, -1 on error output image image size image size `NULL`-terminated list of optional named arguments [func@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, [func@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! ::: seealso [func@guess_prefix]. the libdir as a static string, do not free. program name (typically argv[0]) save prefix in this environment variable [func@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, [func@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! ::: seealso [func@guess_libdir]. the install prefix as a static string, do not free. program name (typically argv[0]) save prefix in this environment variable Like slist map, but for a hash table. `NULL` if @fn returns `NULL` for all arguments, otherwise the first non-`NULL` value from @fn. a [struct@GLib.HashTable] function to apply to each hash value user data user data 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 [method@Image.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`. ::: tip "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 ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Read a HEIF image file into a VIPS image. Exactly as [ctor@Image.heifload], but read from a memory buffer. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "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 ::: seealso [ctor@Image.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 Exactly as [ctor@Image.heifload], but read from a source. ::: tip "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 ::: seealso [ctor@Image.heifload]. 0 on success, -1 on error. source to load from image to write `NULL`-terminated list of optional named arguments 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. Creates an identity lookup table, ie. one which will leave an image unchanged when applied with [method@Image.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. ::: tip "Optional arguments" * @bands: `gint`, number of bands to create * @ushort: `gboolean`, `TRUE` for an unsigned short identity * @size: `gint`, number of LUT elements for a ushort image ::: seealso [ctor@Image.xyz], [method@Image.maplut]. 0 on success, -1 on error output image `NULL`-terminated list of optional named arguments This function starts up libvips, see [func@INIT]. This function is for bindings which need to start up vips. C programs should use the [func@INIT] macro, which does some extra checks. ::: seealso [func@INIT]. 0 on success, -1 otherwise name of application Look up the @interpolate method in the class and call it. Use [method@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 The number of "real" bands we expect for this interpretation. If we've no idea (eg. MULTIBAND), return 0. the number of bands implied by this interpretation, or 0. image to check the maximum alpha value for an interpretation. image interpretation 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. Some versions of openjpeg can fail to decode some tiled images correctly. Setting @oneshot will force the loader to decode tiled images in a single operation and can improve compatibility. Use @fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, [enum@Vips.FailOn.NONE]. ::: tip "Optional arguments" * @page: `gint`, load this page * @oneshot: `gboolean`, load pages in one-shot mode * @fail_on: [enum@FailOn], types of read error to fail on ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.jp2kload], but read from a buffer. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @page: `gint`, load this page * @oneshot: `gboolean`, load pages in one-shot mode * @fail_on: [enum@FailOn], types of read error to fail on 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 [ctor@Image.jp2kload], but read from a source. ::: tip "Optional arguments" * @page: `gint`, load this page * @oneshot: `gboolean`, load pages in one-shot mode * @fail_on: [enum@FailOn], types of read error to fail on 0 on success, -1 on error. source to load from decompressed image `NULL`-terminated list of optional named arguments Read a JPEG file into a VIPS image. It can read most 8-bit JPEG images, including CMYK and YCbCr. @shrink means shrink by this integer factor during load. Possible 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, [enum@Vips.FailOn.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 [const@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 [method@Image.autorot]. Save operations will use [const@META_ORIENTATION], if present, to set the orientation of output images. Example: ```c 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 [const@META_ICC_NAME]. You need to use something like [method@Image.icc_import] to get CIE values from the file. EXIF metadata is attached as [const@META_EXIF_NAME], IPTC as [const@META_IPTC_NAME], and XMP as [const@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 [method@Image.get_blob]. ::: tip "Optional arguments" * @shrink: `gint`, shrink by this much on load * @fail_on: [enum@FailOn], types of read error to fail on * @autorotate: `gboolean`, use exif Orientation tag to rotate the image during load ::: seealso [ctor@Image.jpegload_buffer], [method@Image.autorot]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Read a JPEG-formatted memory block into a VIPS image. Exactly as [ctor@Image.jpegload], but read from a memory buffer. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @shrink: `gint`, shrink by this much on load * @fail_on: [enum@FailOn], types of read error to fail on * @autorotate: `gboolean`, use exif Orientation tag to rotate the image during load ::: seealso [ctor@Image.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 Read a JPEG-formatted memory block into a VIPS image. Exactly as [ctor@Image.jpegload], but read from a source. ::: tip "Optional arguments" * @shrink: `gint`, shrink by this much on load * @fail_on: [enum@FailOn], types of read error to fail on * @autorotate: `gboolean`, use exif Orientation tag to rotate the image during load ::: seealso [ctor@Image.jpegload]. 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. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.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 [ctor@Image.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`, [func@add_option_entries] and the `VIPS_LEAK` environment variable. You should call this very early in your program. turn leak checking on or off Create 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: ``` 2 = @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 [enum@Vips.Precision.INTEGER]. If @separable is set, only the centre horizontal is generated. This is useful for separable convolutions. If @precision is [enum@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. ::: tip "Optional arguments" * @separable: `gboolean`, generate a separable mask * @precision: [enum@Precision] for @out ::: seealso [ctor@Image.gaussmat], [method@Image.conv]. 0 on success, -1 on error output image standard deviation of mask minimum amplitude `NULL`-terminated list of optional named arguments Read in an image using libMagick, the ImageMagick library. This library can read more than 80 file formats, including 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 `-Dmagick-package` 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. ::: tip "Optional arguments" * @page: `gint`, load from this page * @n: `gint`, load this many pages * @density: `gchararray`, canvas resolution for rendering vector formats like SVG ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Read an image memory block using libMagick into a VIPS image. Exactly as [ctor@Image.magickload], but read from a memory source. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @page: `gint`, load from this page * @n: `gint`, load this many pages * @density: `gchararray`, canvas resolution for rendering vector formats like SVG ::: seealso [ctor@Image.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 Exactly as [ctor@Image.magickload], but read from a source. ::: tip "Optional arguments" * @page: `gint`, load from this page * @n: `gint`, load this many pages * @density: `gchararray`, canvas resolution for rendering vector formats like SVG ::: seealso [ctor@Image.magickload]. 0 on success, -1 on error. source to load image to write `NULL`-terminated list of optional named arguments [func@GLib.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 [func@GLib.free]. This function cannot fail. See [func@tracked_malloc] if you are allocating large amounts of memory. ::: seealso [func@tracked_malloc]. a pointer to the allocated memory. allocate memory local to this [class@Object], or `NULL` number of bytes to allocate 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. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 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. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 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. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 This operation should be used to create fractal images by filtering the power spectrum of Gaussian white noise. See [ctor@Image.gaussnoise]. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.mask_ideal]. 0 on success, -1 on error output image image size image size fractal dimension `NULL`-terminated list of optional named arguments Make a gaussian high- or low-pass filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 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. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 Make a gaussian ring-pass or ring-reject filter, that is, one with a variable, smooth transition positioned at @frequency_cutoff of width @ringwidth. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 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 [method@Image.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]. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.mask_ideal], [ctor@Image.mask_ideal_ring], [ctor@Image.mask_ideal_band], [ctor@Image.mask_butterworth], [ctor@Image.mask_butterworth_ring], [ctor@Image.mask_butterworth_band], [ctor@Image.mask_gaussian], [ctor@Image.mask_gaussian_ring], [ctor@Image.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 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. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 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. ::: tip "Optional arguments" * @nodc: `gboolean`, don't set the DC pixel * @reject: `gboolean`, invert the filter sense * @optical: `gboolean`, coordinates in optical space * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.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 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. ::: seealso [ctor@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. ::: seealso [ctor@Image.matrixload]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.matrixload], but read from a source. ::: seealso [ctor@Image.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. Return the VIPS nickname for a [alias@GObject.Type]. Handy for language bindings. the class nickname. [alias@GObject.Type] to search for Read a NIFTI image file into a VIPS image. NIFTI metadata is attached with the "nifti-" prefix. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.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 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++. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Read a virtual slide supported by the OpenSlide library into a VIPS image. OpenSlide supports images in Aperio, Hamamatsu, MIRAX, Sakura, Trestle, and Ventana formats. To facilitate zooming, virtual slide formats include multiple scaled-down versions of the high-resolution image. These are typically called "levels". By default, [ctor@Image.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 [method@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. ::: tip "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 ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.openslideload], but read from a source. ::: tip "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 0 on success, -1 on error. source to load from decompressed image `NULL`-terminated list of optional named arguments 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 [ctor@Image.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 [method@Image.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. When using pdfium, the region of a page to render can be selected with @page_box, defaulting to the crop box. 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. ::: tip "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: [struct@ArrayDouble], background colour * @page_box: [enum@ForeignPdfPageBox], use this page box (pdfium only) ::: seealso [ctor@Image.new_from_file], [ctor@Image.magickload]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Read a PDF-formatted memory buffer into a VIPS image. Exactly as [ctor@Image.pdfload], but read from memory. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "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: [struct@ArrayDouble], background colour * @page_box: [enum@ForeignPdfPageBox], use this page box (pdfium only) ::: seealso [ctor@Image.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 Exactly as [ctor@Image.pdfload], but read from a source. ::: tip "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: [struct@ArrayDouble], background colour * @page_box: [enum@ForeignPdfPageBox], use this page box (pdfium only) ::: seealso [ctor@Image.pdfload] 0 on success, -1 on error. source to load from image to write `NULL`-terminated list of optional named arguments Create a one-band float image of [Perlin noise](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 [enum@Vips.BandFormat.FLOAT] in the range [-1, +1]. Set @uchar to output a uchar image with pixels in [0, 255]. ::: tip "Optional arguments" * @cell_size: `gint`, size of Perlin cells * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.worley], [ctor@Image.fractsurf], [ctor@Image.gaussnoise]. 0 on success, -1 on error output image horizontal size vertical size `NULL`-terminated list of optional named arguments If a source does not support mmap or seek and the source is used with a loader that can only work from memory, then the data will be automatically read into memory to EOF before the loader starts. This can produce high memory use if the descriptor represents a large object. Use [func@pipe_read_limit_set] to limit the size of object that will be read in this way. The default is 1GB. Set a value of -1 to mean no limit. ::: seealso `--vips-pipe-read-limit` and the environment variable `VIPS_PIPE_READ_LIMIT`. maximum number of bytes to buffer from a pipe 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, [enum@Vips.FailOn.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. ::: tip "Optional arguments" * @fail_on: [enum@FailOn], types of read error to fail on * @unlimited: `gboolean`, Remove all denial of service limits ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.pngload], but read from a PNG-formatted memory block. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @fail_on: [enum@FailOn], types of read error to fail on * @unlimited: `gboolean`, Remove all denial of service limits ::: seealso [ctor@Image.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 Exactly as [ctor@Image.pngload], but read from a source. ::: tip "Optional arguments" * @fail_on: [enum@FailOn], types of read error to fail on * @unlimited: `gboolean`, Remove all denial of service limits ::: seealso [ctor@Image.pngload]. 0 on success, -1 on error. source to load from image to write `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. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.ppmload], but read from a memory source. ::: seealso [ctor@Image.ppmload]. 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 [ctor@Image.ppmload], but read from a source. ::: seealso [ctor@Image.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 record profiling information, and dump it on program exit. These profiles can be analysed with the `vipsprofile` program. `TRUE` to enable profile recording 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 [enum@Vips.Coding.RAD]. They have one byte for each of red, green and blue, and one byte of shared exponent. Some operations (like [method@Image.extract_area]) can work directly with images in this format, but mmany (all the arithmetic operations, for example) will not. Unpack [enum@Vips.Coding.RAD] images to 3 band float with [method@Image.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. ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.radload], but read from a HDR-formatted memory block. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: seealso [ctor@Image.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 [ctor@Image.radload], but read from a source. ::: seealso [ctor@Image.radload]. 0 on success, -1 on error. source to load from output image `NULL`-terminated list of optional named arguments This operation mmaps the file, setting up @out so that access to that image will read from the file. By default, it assumes uchar pixels. Use @format to select something else. The image will be tagged as [enum@Vips.Interpretation.MULTIBAND]. Use @interpretation to select something else. Use [method@Image.byteswap] to reverse the byte ordering if necessary. ::: tip "Optional arguments" * @offset: `guint64`, offset in bytes from start of file * @format: [enum@BandFormat], set image format * @interpretation: [enum@Interpretation], set image interpretation ::: seealso [ctor@Image.new_from_file], [method@Image.copy], [method@Image.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 Create a signed distance field (SDF) image of the given @shape. Different shapes use different combinations of the optional arguments, see below. @shape [enum@Vips.SdfShape.CIRCLE]: create a circle centred on @a, radius @r. @shape [enum@Vips.SdfShape.BOX]: create a box with top-left corner @a and bottom-right corner @b. @shape [enum@Vips.SdfShape.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 [enum@Vips.SdfShape.LINE]: draw a line from @a to @b. ::: tip "Optional arguments" * @a: [struct@ArrayDouble], first point * @b: [struct@ArrayDouble], second point * @r: `gdouble`, radius * @corners: [struct@ArrayDouble], corner radii ::: seealso [ctor@Image.grey], [method@Image.grid], [ctor@Image.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. [func@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 [func@INIT] many times and [func@shutdown] many times, but you must not call [func@INIT] after [func@shutdown]. In other words, you cannot stop and restart libvips. ::: seealso [func@profile_set], [func@leak_set]. 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]. ::: tip "Optional arguments" * @hfreq: `gdouble`, horizontal frequency * @vreq: `gdouble`, vertical frequency * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.grey], [ctor@Image.xyz]. 0 on success, -1 on error output image image size image size `NULL`-terminated list of optional named arguments Loops over @im, generating it to a memory buffer attached to @im. It is used by vips to implement writing to a memory buffer. ::: seealso [method@Image.sink], [method@Image.get_tile_size], [ctor@Image.new_memory]. 0 on success, or -1 on error. generate this image to memory Test two lists for equality. `TRUE` if @l1 is equal to @l2. `FALSE` otherwise. a [struct@GLib.SList] another [struct@GLib.SList] Remove all occurrences of an item from a list. Returns the new head of the list. new head of @list a [struct@GLib.SList] function to call for each element. user data user data Fold over a slist, applying @fn to each element. `NULL` if @fn returns `NULL` for all arguments, otherwise the first non-`NULL` value from @fn. a [struct@GLib.SList] initial value for the accumulator function to apply to each list element user data user data Free a [struct@GLib.SList] of things which need [func@GLib.free]ing. a [struct@GLib.SList] Map over a slist. _copy() the list in case the callback changes it. `NULL` if @fn returns `NULL` for all arguments, otherwise the first non-`NULL` value from @fn. a [struct@GLib.SList] function to apply to each list element user data user data Map backwards. We _reverse() rather than recurse and unwind to save stack. `NULL` if @fn returns `NULL` for all arguments, otherwise the first non-`NULL` value from @fn. a [struct@GLib.SList] function to apply to each list element user data user data Map over a slist. _copy() the list in case the callback changes it. `NULL` if @fn returns `NULL` for all arguments, otherwise the first non-`NULL` value from @fn. a [struct@GLib.SList] function to apply to each list element user data user data user data user data Start function for many images in. @a is a pointer to a `NULL`-terminated array of input images. ::: seealso [method@Image.generate], [func@allocate_input_array] image to generate user data user data Start function for one image in. Input image is @a. ::: seealso [method@Image.generate]. image to generate user data user data Stop function for many images in. @a is a pointer to a `NULL`-terminated array of input images. ::: seealso [method@Image.generate]. sequence value user data user data Stop function for one image in. Input image is @a. ::: seealso [method@Image.generate]. sequence value user data user data [func@GLib.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 [func@GLib.free]. This function cannot fail. ::: seealso [func@malloc]. a pointer to the allocated memory allocate memory local to this [class@Object], or `NULL` string to copy 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 [arithmetic](libvips-arithmetic.html)), then the following table is used to determine the output type: ## [func@Image.sum] type promotion | input type | output type | |----------------|----------------| | uchar | uint | | char | int | | ushort | uint | | short | int | | uint | uint | | int | int | | float | float | | double | double | | complex | complex | | double complex | double complex | In other words, the output type is just large enough to hold the whole range of possible values. ::: seealso [method@Image.add]. 0 on success, -1 on error array of input images output image number of input images `NULL`-terminated list of optional named arguments 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. Additionally, you can scale by setting @scale. If you set both, they combine. 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. A UTF-8 string containing custom CSS can be provided via @stylesheet. During the CSS cascade, the specified stylesheet will be applied with a User Origin. This feature requires librsvg 2.48.0 or later. If @high_bitdepth is set and the version of cairo supports it (e.g. cairo >= 1.17.2), enable 128-bit scRGB output (32-bit per channel). ::: tip "Optional arguments" * @dpi: `gdouble`, render at this DPI * @scale: `gdouble`, scale render by this factor * @unlimited: `gboolean`, allow SVGs of any size * @stylesheet: `gchararray`, custom CSS * @high_bitdepth: `gboolean`, enable scRGB 128-bit output ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load output image `NULL`-terminated list of optional named arguments Read a SVG-formatted memory block into a VIPS image. Exactly as [ctor@Image.svgload], but read from a memory buffer. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @dpi: `gdouble`, render at this DPI * @scale: `gdouble`, scale render by this factor * @unlimited: `gboolean`, allow SVGs of any size * @stylesheet: `gchararray`, custom CSS * @high_bitdepth: `gboolean`, enable scRGB 128-bit output ::: seealso [ctor@Image.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 [ctor@Image.svgload], but read from a source. ::: seealso [ctor@Image.svgload]. 0 on success, -1 on error. source to load from image to write `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.svgload], but read from a string. This function takes a copy of the string. ::: tip "Optional arguments" * @dpi: `gdouble`, render at this DPI * @scale: `gdouble`, scale render by this factor * @unlimited: `gboolean`, allow SVGs of any size * @stylesheet: `gchararray`, custom CSS * @high_bitdepth: `gboolean`, enable scRGB 128-bit output ::: seealso [ctor@Image.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 [method@Image.case] to make an efficient multi-way [method@Image.ifthenelse]. ::: seealso [method@Image.maplut], [method@Image.case], [method@Image.ifthenelse]. 0 on success, -1 on error test these images output index image number of input images `NULL`-terminated list of optional named arguments [ctor@Image.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 [ctor@Image.new_temp_file] to see how temporary files are created. If @in_format is something like `%s.png`, the file will be written in PNG format. By default, @in_format is `%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 `%s` in @cmd_format for the names of the input files, if @in is set, and then the next `%s` for the output filename, if @out_format is set. You can put a number between the `%` and the `s` to change the order in which the substitution occurs. The command is executed with [`popen()`](man:popen(3)) 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. If @cache is set, this call will be added to the libvips operation cache and reused if possible. 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. ```c 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", "cache", TRUE, "log", &log, NULL)) error ... ``` ::: tip "Optional arguments" * @in: [struct@ArrayImage], array of input images * @out: [class@Image], output, image * @in_format: `gchararray`, write input files like this * @out_format: `gchararray`, write output filename like this * @cache: `gboolean`, cache this call * @log: `gchararray`, output, stdout of command is returned here 0 on success, -1 on failure. command to run `NULL`-terminated list of optional named arguments 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, [ctor@Image.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 [ctor@Image.text]. ::: tip "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: [enum@Align], set justification alignment * @justify: `gboolean`, justify lines * @dpi: `gint`, render at this resolution * @autofit_dpi: `gint`, output, auto-fitted DPI * @rgba: `gboolean`, enable RGBA output * @spacing: `gint`, space lines by this in points * @wrap: [enum@TextWrap], wrap lines on characters or words ::: seealso [func@Image.bandjoin], [func@Image.composite]. 0 on success, -1 on error output image utf-8 text string to render `NULL`-terminated list of optional named arguments A newly created or reused thread will execute @func with the argument @data. 0 on success, -1 on error. a name for the thread (useful for debugging) a function to execute in the libvips threadset an argument to supply to @func 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 [func@shutdown] and for any threads created within the thread pool. 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. This function runs a set of threads over an image. Each thread first calls @start to create new per-thread state, then runs @allocate to set up a new work unit (perhaps the next tile in an image, for example), then @work to process that work unit. After each unit is processed, @progress is called, so that the operation can give progress feedback. @progress may be `NULL`. The object returned by @start must be an instance of a subclass of [class@ThreadState]. Use this to communicate between @allocate and @work. @allocate and @start are always single-threaded (so they can write to the per-pool state), whereas @work can be executed concurrently. @progress is always called by the main thread (ie. the thread which called [func@threadpool_run]). ::: seealso [func@concurrency_set]. 0 on success, or -1 on error. image to loop over allocate per-thread state allocate a work unit process a work unit give progress feedback about a work unit, or `NULL` client data Make a thumbnail from a file. Shrinking is done in three stages: using any shrink-on-load features available in the image load 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 [ctor@Image.thumbnail_buffer] to thumbnail from a memory buffer, or [ctor@Image.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 [method@Image.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 [enum@Vips.Size.UP], the operation will only upsize and will just copy if asked to downsize. If @size is set to [enum@Vips.Size.DOWN], the operation will only downsize and will just copy if asked to upsize. If @size is [enum@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 @output_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 @input_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 [enum@Vips.Intent.RELATIVE]. Use @fail_on to control the types of error that will cause loading to fail. The default is [enum@Vips.FailOn.NONE], ie. thumbnail is permissive. ::: tip "Optional arguments" * @height: `gint`, target height in pixels * @size: [enum@Size], upsize, downsize, both or force * @no_rotate: `gboolean`, don't rotate upright using orientation tag * @crop: [enum@Interesting], shrink and crop to fill target * @linear: `gboolean`, perform shrink in linear light * @input_profile: `gchararray`, fallback input ICC profile * @output_profile: `gchararray`, output ICC profile * @intent: [enum@Intent], rendering intent * @fail_on: [enum@FailOn], load error types to fail on ::: seealso [ctor@Image.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 Exactly as [ctor@Image.thumbnail], but read from a memory buffer. One extra optional argument, @option_string, lets you pass options to the underlying loader. ::: tip "Optional arguments" * @height: `gint`, target height in pixels * @size: [enum@Size], upsize, downsize, both or force * @no_rotate: `gboolean`, don't rotate upright using orientation tag * @crop: [enum@Interesting], shrink and crop to fill target * @linear: `gboolean`, perform shrink in linear light * @input_profile: `gchararray`, fallback input ICC profile * @output_profile: `gchararray`, output ICC profile * @intent: [enum@Intent], rendering intent * @fail_on: [enum@FailOn], load error types to fail on * @option_string: `gchararray`, extra loader options ::: seealso [ctor@Image.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 Exactly as [ctor@Image.thumbnail], but read from a source. One extra optional argument, @option_string, lets you pass options to the underlying loader. ::: tip "Optional arguments" * @height: `gint`, target height in pixels * @size: [enum@Size], upsize, downsize, both or force * @no_rotate: `gboolean`, don't rotate upright using orientation tag * @crop: [enum@Interesting], shrink and crop to fill target * @linear: `gboolean`, perform shrink in linear light * @input_profile: `gchararray`, fallback input ICC profile * @output_profile: `gchararray`, output ICC profile * @intent: [enum@Intent], rendering intent * @fail_on: [enum@FailOn], load error types to fail on * @option_string: `gchararray`, extra loader options ::: seealso [ctor@Image.thumbnail]. 0 on success, -1 on error. source to thumbnail output image target width in pixels `NULL`-terminated list of optional named arguments Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader, with extensions for tiled images, multipage images, XYZ and LAB 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 [const@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 [const@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 [method@Image.autorot]. Save operations will use [const@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. Use @fail_on to set the type of error that will cause load to fail. By default, loaders are permissive, that is, [enum@Vips.FailOn.NONE]. When using libtiff 4.7.0+, the TIFF loader will limit memory allocation for decoding each input file to 50MB to prevent denial of service attacks. Set @unlimited to remove this limit. Any ICC profile is read and attached to the VIPS image as [const@META_ICC_NAME]. Any XMP metadata is read and attached to the image as [const@META_XMP_NAME]. Any IPTC is attached as [const@META_IPTC_NAME]. The image description is attached as [const@META_IMAGEDESCRIPTION]. Data in the photoshop tag is attached as [const@META_PHOTOSHOP_NAME]. ::: tip "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 * @fail_on: [enum@FailOn], types of read error to fail on * @unlimited: `gboolean`, remove all denial of service limits ::: seealso [ctor@Image.new_from_file], [method@Image.autorot]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Read a TIFF-formatted memory block into a VIPS image. Exactly as [ctor@Image.tiffload], but read from a memory source. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "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 * @fail_on: [enum@FailOn], types of read error to fail on * @unlimited: `gboolean`, remove all denial of service limits ::: seealso [ctor@Image.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 Exactly as [ctor@Image.tiffload], but read from a source. ::: tip "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 * @fail_on: [enum@FailOn], types of read error to fail on * @unlimited: `gboolean`, remove all denial of service limits ::: seealso [ctor@Image.tiffload]. 0 on success, -1 on error. source to load image to write `NULL`-terminated list of optional named arguments [ctor@Image.tonelut] generates a tone curve for the adjustment of image levels. This 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. ::: tip "Optional arguments" * @in_max: `gint`, input range * @out_max: `gint`, output range * @Lb: `gdouble`, black-point [0-100] * @Lw: `gdouble`, white-point [0-100] * @Ps: `gdouble`, shadow point (eg. 0.2) * @Pm: `gdouble`, mid-tone point (eg. 0.5) * @Ph: `gdouble`, highlight point (eg. 0.8) * @S: `gdouble`, shadow adjustment (+/- 30) * @M: `gdouble`, mid-tone adjustment (+/- 30) * @H: `gdouble`, highlight adjustment (+/- 30) 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 [func@tracked_get_mem] and friends. If allocation fails, [func@tracked_aligned_alloc] returns `NULL` and sets an error message. You must only free the memory returned with [func@tracked_aligned_free]. ::: seealso [func@tracked_malloc], [func@tracked_aligned_free], [func@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 [func@tracked_aligned_alloc] with a `NULL` first argument. ::: seealso [func@tracked_aligned_alloc]. memory to free Exactly as [`close()`](man:close(2)), but update the number of files currently open via [func@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 [func@tracked_open]. ::: seealso [func@tracked_open], [func@tracked_get_files]. a file descriptor, or -1 on error. file to `close()` Only use it to free memory that was previously allocated with [func@tracked_malloc] with a `NULL` first argument. ::: seealso [func@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 [func@malloc] and friends. vips uses this figure to decide when to start dropping cache, see [class@Operation]. the number of currently allocated bytes Returns the largest number of bytes simultaneously allocated via [func@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 [func@tracked_get_mem] and friends. If allocation fails, [func@tracked_malloc] returns `NULL` and sets an error message. You must only free the memory returned with [func@tracked_free]. ::: seealso [func@tracked_free], [func@malloc]. a pointer to the allocated memory, or `NULL` on error. number of bytes to allocate Exactly as [`open()`](man:open(2)), but the number of files currently open via [func@tracked_open] is available via [func@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 [func@tracked_close]. @pathname should be utf8. ::: seealso [func@tracked_close], [func@tracked_get_files]. a file descriptor, or -1 on error. name of file to open flags for `open()` open mode Search below @basename, return the [alias@GObject.Type] of the class whose name or @nickname matches, or 0 for not found. If @basename is `NULL`, the whole of [class@Object] is searched. This function uses a cache, so it should be quick. ::: seealso [func@class_find] the [alias@GObject.Type] 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 Read an UltraHDR image. The UltraHDR image is decoded as a tone-mapped SDR base image plus a gainmap attached as image metadata. Either process the SDR image and update the gainmap if necessary, or use [method@Image.uhdr2scRGB] to convert the SDR + gainmap image to full scRGB HDR. [method@Image.uhdrsave] can write both scRGB HDR and SDR plus gainmap images. Set @shrink to shrink the returned image by an integer factor during load. ::: tip "Optional arguments" * @shrink: `gint`, shrink by this factor on load ::: seealso [ctor@Image.new_from_file], [method@Image.uhdr2scRGB]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.uhdrload], but read from a buffer. ::: tip "Optional arguments" * @shrink: `gint`, shrink by this factor on load 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 [ctor@Image.uhdrload], but read from a source. ::: tip "Optional arguments" * @shrink: `gint`, shrink by this factor on load 0 on success, -1 on error. source to load from decompressed image `NULL`-terminated list of optional named arguments 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. ::: seealso [func@value_set_array]. The array address. [struct@GObject.Value] 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. ::: seealso [ctor@ArrayDouble.new]. The array address. [struct@GObject.Value] 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. ::: seealso [func@value_set_array_image]. The array address. [struct@GObject.Value] 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. ::: seealso [ctor@ArrayInt.new]. The array address. [struct@GObject.Value] to get from return the number of elements here, optionally Return the start of the array of [class@GObject.Object] held by @value. Optionally return the number of elements in @n. ::: seealso [ctor@Area.new_array_object]. The array address. [struct@GObject.Value] 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. ::: seealso [func@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 [struct@GObject.Value]. The C string held by @value. [struct@GObject.Value] 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. [struct@GObject.Value] 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. ::: seealso [method@ArrayDouble.get]. [struct@GObject.Value] 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. ::: seealso [method@ArrayImage.get]. [struct@GObject.Value] to get from the number of elements Set @value to hold a copy of @array. Pass in the array length in @n. ::: seealso [method@ArrayInt.get]. [struct@GObject.Value] to get from array of ints the number of elements Set @value to hold an array of [class@GObject.Object]. Pass in the array length in @n. ::: seealso [func@value_get_array_object]. [struct@GObject.Value] 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. ::: seealso [func@value_get_blob] GValue to set free function for @data pointer to area of memory length of memory area Just like [func@value_set_blob], but when @value is freed, @data will be freed with [func@GLib.free]. This can be easier to call for language bindings. ::: seealso [func@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 [struct@GObject.Value] strings. @str should be a valid utf-8 string. [struct@GObject.Value] 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 Takes a bitfield of targets to disable on the runtime platform. Handy for testing and benchmarking purposes. This can also be set using the `VIPS_VECTOR` environment variable. A bitfield of targets to disable at runtime. Gets a bitfield of builtin targets that libvips was built with. a bitfield of builtin targets. Gets a bitfield of builtin targets that are supported on this CPU. The targets returned may change after calling [func@vector_disable_targets]. a bitfield of supported CPU targets. Generates a human-readable ASCII string descriptor for a specific target. a string describing the target. A specific target to describe. Append a message to the error buffer. ::: seealso [func@error]. the source of the error `printf()`-style format string for the error arguments to the format string Format the string in the style of [`printf()`](man:printf(3)) and append to the error buffer. Then create and append a localised message based on the system error code, usually the value of errno. ::: seealso [func@error_system]. 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 in a vips image. ::: seealso [method@Image.vipssave]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Exactly as [ctor@Image.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 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 [method@Image.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. ::: tip "Optional arguments" * @page: `gint`, page (frame) to read * @n: `gint`, load this many pages * @scale: `gdouble`, scale by this much on load ::: seealso [ctor@Image.new_from_file]. 0 on success, -1 on error. file to load decompressed image `NULL`-terminated list of optional named arguments Read a WebP-formatted memory block into a VIPS image. Exactly as [ctor@Image.webpload], but read from a memory buffer. You must not free the buffer while @out is active. The [signal@Object::postclose] signal on @out is a good place to free. ::: tip "Optional arguments" * @page: `gint`, page (frame) to read * @n: `gint`, load this many pages * @scale: `gdouble`, scale by this much on load ::: seealso [ctor@Image.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 Exactly as [ctor@Image.webpload], but read from a source. ::: tip "Optional arguments" * @page: `gint`, page (frame) to read * @n: `gint`, load this many pages * @scale: `gdouble`, scale by this much on load ::: seealso [ctor@Image.webpload] 0 on success, -1 on error. source to load from image to write `NULL`-terminated list of optional named arguments Create a one-band float image of [Worley noise](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. ::: tip "Optional arguments" * @cell_size: `gint`, size of Worley cells ::: seealso [ctor@Image.perlin], [ctor@Image.fractsurf], [ctor@Image.gaussnoise]. 0 on success, -1 on error output image horizontal size vertical size `NULL`-terminated list of optional named arguments 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 [method@Image.grid] to change the layout. ::: tip "Optional arguments" * @csize: `gint`, size for third dimension * @dsize: `gint`, size for fourth dimension * @esize: `gint`, size for fifth dimension ::: seealso [ctor@Image.grey], [method@Image.grid], [ctor@Image.identity]. 0 on success, -1 on error output image horizontal size vertical size `NULL`-terminated list of optional named arguments Create a one-band image of a zone plate. Pixels are normally in [-1, +1], set @uchar to output [0, 255]. ::: tip "Optional arguments" * @uchar: `gboolean`, output a uchar image ::: seealso [ctor@Image.eye], [ctor@Image.xyz]. 0 on success, -1 on error output image image size image size `NULL`-terminated list of optional named arguments