Functions ¶

Vips.argument_map(object, fn, a, b)¶

Parameters:

object (Vips.Object) – object whose args should be enumerated
fn (Vips.ArgumentMapFn) – call this function for every argument
a (object or None) – client data
b (object or None) – client data

Returns:

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

Return type:

Loop over the [struct`Argument`] of an object. Stop when fn returns non-NULL and return that value.

Vips.band_format_is8bit(format)¶

Parameters:: format (Vips.BandFormat) – format to test
Return type:: bool

Return TRUE if format is uchar or schar.

Vips.band_format_iscomplex(format)¶

Parameters:: format (Vips.BandFormat) – format to test
Return type:: bool

Return TRUE if fmt is one of the complex types.

Vips.band_format_isfloat(format)¶

Parameters:: format (Vips.BandFormat) – format to test
Return type:: bool

Return TRUE if format is one of the float types.

Vips.band_format_isint(format)¶

Parameters:: format (Vips.BandFormat) – format to test
Return type:: bool

Return TRUE if format is one of the integer types.

Vips.band_format_isuint(format)¶

Parameters:: format (Vips.BandFormat) – format to test
Return type:: bool

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

Vips.blob_copy(data)¶

Parameters:: data (bytes) – data to store
Returns:: the new [struct`Blob`].
Return type:: Vips.Blob

Like [ctor`Blob`.new], but take a copy of the data. Useful for bindings which struggle with callbacks.

::: seealso [ctor`Blob`.new].

Vips.block_untrusted_set(state)¶

Parameters:: state (bool) – the block state to set

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

Vips.break_token(str, brk)¶

Parameters:

str (str) –
brk (str) –

Return type:

Vips.cache_drop_all()¶: Drop the whole operation cache, handy for leak tracking. Also called automatically on [func`shutdown`].

Vips.cache_get_max()¶

Returns:: the maximum number of operations we keep in cache
Return type:: int

Get the maximum number of operations we keep in cache.

Vips.cache_get_max_files()¶

Returns:: the maximum number of tracked files we allow
Return type:: int

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

Vips.cache_get_max_mem()¶

Returns:: the maximum amount of tracked memory we allow
Return type:: int

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

Vips.cache_get_size()¶

Returns:: get the current number of operations in cache.
Return type:: int

Get the current number of operations in cache.

Vips.cache_operation_build(operation)¶

Parameters:: operation (Vips.Operation) – operation to lookup
Returns:: The built operation.
Return type:: Vips.Operation

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

Vips.cache_print()¶: Print the whole operation cache to stdout. Handy for debugging.

Vips.cache_set_dump(dump)¶

Parameters:: dump (bool) – if TRUE, dump the operation cache on exit

Handy for debugging. Print the operation cache to stdout just before exit.

::: seealso [func`cache_set_trace`].

Vips.cache_set_max(max)¶

Parameters:: max (int) – maximum number of operation to cache

Set the maximum number of operations we keep in cache.

Vips.cache_set_max_files(max_files)¶

Parameters:: max_files (int) – max open files we allow

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

Vips.cache_set_max_mem(max_mem)¶

Parameters:: max_mem (int) – maximum amount of tracked memory we use

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

Vips.cache_set_trace(trace)¶

Parameters:: trace (bool) – if TRUE, trace the operation cache

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

Vips.call_argv(operation, argc, argv)¶

Parameters:

operation (Vips.Operation) –
argc (int) –
argv (str) –

Return type:

Vips.call_options(group, operation)¶

Parameters:

group (GLib.OptionGroup) –
operation (Vips.Operation) –

Vips.check_8or16(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_bandno(domain, im, bandno)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check
bandno (int) – band number

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_bands(domain, im, bands)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check
bands (int) – must have this many bands

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image has bands bands. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_bands_1or3(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image has either one or three bands. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_bands_1orn(domain, im1, im2)¶

Parameters:

domain (str) – the originating domain for the error message
im1 (Vips.Image) – first image to check
im2 (Vips.Image) – second image to check

Returns:

0 on OK, or -1 on error.

Return type:

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

Vips.check_bands_1orn_unary(domain, im, n)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check
n (int) – number of bands, or 1

Returns:

0 on OK, or -1 on error.

Return type:

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

Vips.check_bands_atleast(domain, im, bands)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check
bands (int) – at least this many bands

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image has at least bands bands. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_bands_same(domain, im1, im2)¶

Parameters:

domain (str) – the originating domain for the error message
im1 (Vips.Image) – first image to check
im2 (Vips.Image) – second image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the images have the same number of bands. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_coding(domain, im, coding)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check
coding (Vips.Coding) – required coding

Returns:

0 on OK, or -1 on error.

Return type:

Check that the image has the required coding. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_coding_known(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 on OK, or -1 on error.

Return type:

Check that the image is uncoded, LABQ coded or RAD coded. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_coding_noneorlabq(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 on OK, or -1 on error.

Return type:

Check that the image is uncoded or LABQ coded. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_coding_same(domain, im1, im2)¶

Parameters:

domain (str) – the originating domain for the error message
im1 (Vips.Image) – first image to check
im2 (Vips.Image) – second image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the images have the same coding. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_complex(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image is complex. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_format(domain, im, fmt)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check
fmt (Vips.BandFormat) – format to test for

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image has the specified format. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_format_same(domain, im1, im2)¶

Parameters:

domain (str) – the originating domain for the error message
im1 (Vips.Image) – first image to check
im2 (Vips.Image) – second image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the images have the same format. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_hist(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_int(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image is in one of the integer formats. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_matrix(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

out:: put image as in-memory doubles here

Return type:

(int, out: Vips.Image)

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 [funcMATRIX] to address values in out.

You must unref out when you are done with it.

::: seealso [funcMATRIX].

Vips.check_mono(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image has exactly one band. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_noncomplex(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image is not complex. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_oddsquare(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_precision_intfloat(domain, precision)¶

Parameters:

domain (str) – the originating domain for the error message
precision (Vips.Precision) – precision to check

Returns:

0 on OK, or -1 on error.

Return type:

Check that prec image is either float or int. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_separable(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_size_same(domain, im1, im2)¶

Parameters:

domain (str) – the originating domain for the error message
im1 (Vips.Image) – first image to check
im2 (Vips.Image) – second image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the images have the same size. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_twocomponents(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_u8or16(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image is 8 or 16-bit unsigned integer. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_u8or16orf(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_uint(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image is in one of the unsigned integer formats. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_uintorf(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 if OK, -1 otherwise.

Return type:

Check that the image is unsigned int or float. Otherwise set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_uncoded(domain, im)¶

Parameters:

domain (str) – the originating domain for the error message
im (Vips.Image) – image to check

Returns:

0 on OK, or -1 on error.

Return type:

Check that the image is not coded. If not, set an error message and return non-zero.

::: seealso [func`error`].

Vips.check_vector(domain, n, im)¶

Parameters:

domain (str) – the originating domain for the error message
n (int) – number of elements in vector
im (Vips.Image) – image to check against

Returns:

0 if OK, -1 otherwise.

Return type:

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

Vips.check_vector_length(domain, n, len)¶

Parameters:

domain (str) – the originating domain for the error message
n (int) – number of elements in vector
len (int) – number of elements vector should have

Returns:

0 if OK, -1 otherwise.

Return type:

Check that n == len.

::: seealso [func`error`].

Vips.class_find(basename, nickname)¶

Parameters:

basename (str) – name of base class
nickname (str) – search for a class with this nickname

Returns:

the found class.

Return type:

Vips.ObjectClass

Search below basename, return the first class whose name or nickname matches.

::: seealso [func`type_find`]

Vips.col_C2Ccmc(C)¶

Parameters:: C (float) – Chroma
Returns:: Ccmc.
Return type:: float

Calculate Ccmc from C.

Vips.col_Ccmc2C(Ccmc)¶

Parameters:

Ccmc (float) – Ccmc

Returns:

Return type:

Calculate C from Ccmc using a table. Call [func`col_make_tables_CMC`] at least once before using this function.

Vips.col_Ch2ab(C, h, a, b)¶

Parameters:

C (float) – Chroma
h (float) – Hue angle (degrees)
a (float) – return CIE a* value
b (float) – return CIE b* value

Calculate ab from Ch, h in degrees.

Vips.col_Ch2hcmc(C, h)¶

Parameters:

C (float) – Chroma
h (float) – Hue (degrees)

Returns:

hcmc.

Return type:

Calculate hcmc from C and h.

Vips.col_Chcmc2h(C, hcmc)¶

Parameters:

C (float) – Chroma
hcmc (float) – Hue cmc (degrees)

Returns:

Return type:

Calculate h from C and hcmc, using a table. Call [func`col_make_tables_CMC`] at least once before using this function.

Vips.col_L2Lcmc(L)¶

Parameters:: L (float) – CIE L*
Returns:: Lcmc
Return type:: float

Calculate Lcmc from L.

Vips.col_Lab2XYZ(L, a, b)¶

Parameters:

L (float) – Input CIE Lab value
a (float) – Input CIE Lab value
b (float) – Input CIE Lab value

Returns:

X:: Return CIE XYZ colour
Y:: Return CIE XYZ colour
Z:: Return CIE XYZ colour

Return type:

(X: float, Y: float, Z: float)

Calculate XYZ from Lab, D65.

::: seealso [method`Image`.Lab2XYZ].

Vips.col_Lcmc2L(Lcmc)¶

Parameters:: Lcmc (float) – L cmc
Returns:: L*
Return type:: float

Calculate L from Lcmc using a table. Call [func`col_make_tables_CMC`] at least once before using this function.

Vips.col_XYZ2Lab(X, Y, Z)¶

Parameters:

X (float) – Input CIE XYZ colour
Y (float) – Input CIE XYZ colour
Z (float) – Input CIE XYZ colour

Returns:

L:: Return CIE Lab value
a:: Return CIE Lab value
b:: Return CIE Lab value

Return type:

(L: float, a: float, b: float)

Calculate XYZ from Lab, D65.

::: seealso [method`Image`.XYZ2Lab].

Vips.col_XYZ2scRGB(X, Y, Z)¶

Parameters:

X (float) – Input XYZ value
Y (float) – Input XYZ value
Z (float) – Input XYZ value

Returns:

R:: Return scRGB colour
G:: Return scRGB colour
B:: Return scRGB colour

Return type:

(int, R: float, G: float, B: float)

Turn XYZ into scRGB.

::: seealso [method`Image`.XYZ2scRGB].

Vips.col_ab2Ch(a, b, C, h)¶

Parameters:

a (float) –
b (float) –
C (float) –
h (float) –

Vips.col_ab2h(a, b)¶

Parameters:

a (float) – CIE a
b (float) – CIE b

Returns:

Hue (degrees)

Return type:

Vips.col_dE00(L1, a1, b1, L2, a2, b2)¶

Parameters:

L1 (float) – Input coordinate 1
a1 (float) – Input coordinate 1
b1 (float) – Input coordinate 1
L2 (float) – Input coordinate 2
a2 (float) – Input coordinate 2
b2 (float) – Input coordinate 2

Returns:

CIE dE2000 colour difference.

Return type:

CIEDE2000, from:

Luo, Cui, Rigg, “The Development of the CIE 2000 Colour-Difference Formula: CIEDE2000”, COLOR research and application, pp 340

Vips.col_make_tables_CMC()¶: Make the lookup tables for cmc.

Vips.col_sRGB2scRGB_16(r, g, b, R, G, B)¶

Parameters:

r (int) –
g (int) –
b (int) –
R (float) –
G (float) –
B (float) –

Return type:

Vips.col_sRGB2scRGB_16_noclip(r, g, b, R, G, B)¶

Parameters:

r (int) –
g (int) –
b (int) –
R (float) –
G (float) –
B (float) –

Return type:

Vips.col_sRGB2scRGB_8(r, g, b, R, G, B)¶

Parameters:

r (int) –
g (int) –
b (int) –
R (float) –
G (float) –
B (float) –

Return type:

Vips.col_sRGB2scRGB_8_noclip(r, g, b, R, G, B)¶

Parameters:

r (int) –
g (int) –
b (int) –
R (float) –
G (float) –
B (float) –

Return type:

Vips.col_scRGB2BW_16(R, G, B, g, og)¶

Parameters:

R (float) –
G (float) –
B (float) –
g (int) –
og (int) –

Return type:

Vips.col_scRGB2BW_8(R, G, B, g, og)¶

Parameters:

R (float) –
G (float) –
B (float) –
g (int) –
og (int) –

Return type:

Vips.col_scRGB2XYZ(R, G, B)¶

Parameters:

R (float) – Input scRGB value
G (float) – Input scRGB value
B (float) – Input scRGB value

Returns:

X:: Return XYZ colour
Y:: Return XYZ colour
Z:: Return XYZ colour

Return type:

(int, X: float, Y: float, Z: float)

Turn scRGB into XYZ.

::: seealso [method`Image`.scRGB2XYZ].

Vips.col_scRGB2sRGB_16(R, G, B, r, g, b, og)¶

Parameters:

R (float) –
G (float) –
B (float) –
r (int) –
g (int) –
b (int) –
og (int) –

Return type:

Vips.col_scRGB2sRGB_8(R, G, B, r, g, b, og)¶

Parameters:

R (float) –
G (float) –
B (float) –
r (int) –
g (int) –
b (int) –
og (int) –

Return type:

Vips.concurrency_get()¶

Returns:: number of worker threads to use.
Return type:: int

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

Vips.concurrency_set(concurrency)¶

Parameters:: concurrency (int) – number of threads to run

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

Vips.enum_from_nick(domain, type, str)¶

Parameters:

domain (str) –
type (GObject.GType) –
str (str) –

Return type:

Vips.enum_nick(enm, value)¶

Parameters:

enm (GObject.GType) –
value (int) –

Return type:

Vips.enum_string(enm, value)¶

Parameters:

enm (GObject.GType) –
value (int) –

Return type:

Vips.error_buffer()¶

Returns:: the error buffer as a C string which must not be freed
Return type:: str

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

Vips.error_buffer_copy()¶

Returns:: a copy of the libvips error buffer
Return type:: str

Return a copy of the vips error buffer, and clear it.

Vips.error_clear()¶

Clear and reset the error buffer. This is typically called after presenting an error to the user.

::: seealso [func`error_buffer`].

Vips.error_freeze()¶: Stop errors being logged. Use [func`error_thaw`] to unfreeze. You can nest freeze/thaw pairs.

Vips.error_g()¶

Raises:: GLib.Error

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

Vips.error_thaw()¶: Re-enable error logging.

Vips.file_length(fd)¶

Parameters:: fd (int) –
Return type:: int

Vips.filename_get_filename(vips_filename)¶

Parameters:: vips_filename (str) – a filename including a set of options
Returns:: transfer full: just the filename component.
Return type:: str

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

Vips.filename_get_options(vips_filename)¶

Parameters:: vips_filename (str) – a filename including a set of options
Returns:: transfer full: just the options component.
Return type:: str

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

Vips.filename_suffix_match(path, suffixes)¶

Parameters:

path (str) –
suffixes (str) –

Return type:

Vips.flags_from_nick(domain, type, nick)¶

Parameters:

domain (str) –
type (GObject.GType) –
nick (str) –

Return type:

Vips.foreign_flags(loader, filename)¶

Parameters:

loader (str) – name of loader to use for test
filename (str) – file to test

Returns:

the flags for filename.

Return type:

Vips.ForeignFlags

Return the flags for filename using loader. loader is something like “tiffload” or “VipsForeignLoadTiff”.

Vips.format_sizeof(format)¶

Parameters:: format (Vips.BandFormat) – format type
Returns:: number of bytes for a band format.
Return type:: int

Vips.g_error()¶

Raises:: GLib.Error

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

Vips.g_thread_new(domain, func, *data)¶

Parameters:

domain (str or None) – an (optional) name for the new thread
func (GLib.ThreadFunc) – a function to execute in the new thread
data (object or None) – an argument to supply to the new thread

Returns:

the new [struct`GLib`.Thread], or NULL if an error occurred

Return type:

GLib.Thread

Wrapper for [ctor`GLib`.Thread.try_new].

Vips.get_argv0()¶

Returns:: a pointer to an internal copy of the argv0 string passed to [funcINIT]. Do not free this value
Return type:: str

::: seealso [funcINIT].

Vips.get_disc_threshold()¶

Returns:: disc threshold in bytes.
Return type:: int

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

Vips.get_prgname()¶

Returns:: a pointer to an internal copy of the program name. Do not free this value
Return type:: str

Return the program name.

::: seealso [funcINIT].

Vips.guess_libdir(argv0, env_name)¶

Parameters:

argv0 (str) – program name (typically argv[0])
env_name (str) – save prefix in this environment variable

Returns:

the libdir as a static string, do not free.

Return type:

[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`].

Vips.guess_prefix(argv0, env_name)¶

Parameters:

argv0 (str) – program name (typically argv[0])
env_name (str) – save prefix in this environment variable

Returns:

the install prefix as a static string, do not free.

Return type:

[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`].

Vips.hash_table_map(hash, fn, a, b)¶

Parameters:

hash ({object: object}) – a [struct`GLib`.HashTable]
fn (Vips.SListMap2Fn) – function to apply to each hash value
a (object or None) – user data
b (object or None) – user data

Returns:

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

Return type:

Like slist map, but for a hash table.

Vips.icc_is_compatible_profile(image, data, data_length)¶

Parameters:

image (Vips.Image) –
data (object or None) –
data_length (int) –

Return type:

Vips.icc_present()¶

Returns:: non-zero if the ICC library is present.
Return type:: int

VIPS can optionally be built without the ICC library. Use this function to test for its availability.

Vips.init(argv0)¶

Parameters:: argv0 (str) – name of application
Returns:: 0 on success, -1 otherwise
Return type:: int

This function starts up libvips, see [funcINIT].

This function is for bindings which need to start up vips. C programs should use the [funcINIT] macro, which does some extra checks.

::: seealso [funcINIT].

Vips.interpretation_bands(interpretation)¶

Parameters:: interpretation (Vips.Interpretation) – image to check
Returns:: the number of bands implied by this interpretation, or 0.
Return type:: int

The number of “real” bands we expect for this interpretation. If we’ve no idea (eg. MULTIBAND), return 0.

Vips.interpretation_max_alpha(interpretation)¶

Parameters:: interpretation (Vips.Interpretation) – image interpretation
Returns:: the maximum alpha value for an interpretation.
Return type:: float

Vips.iscasepostfix(a, b)¶

Parameters:

a (str) –
b (str) –

Return type:

Vips.ispoweroftwo(p)¶

Parameters:: p (int) –
Return type:: int

Vips.isprefix(a, b)¶

Parameters:

a (str) –
b (str) –

Return type:

Vips.leak_set(leak)¶

Parameters:: leak (bool) – turn leak checking on or off

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.

Vips.malloc(object, size)¶

Parameters:

object (Vips.Object or None) – allocate memory local to this [class`Object`], or NULL
size (int) – number of bytes to allocate

Returns:

a pointer to the allocated memory.

Return type:

[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`].

Vips.map_equal(a, b)¶

Parameters:

a (object or None) –
b (object or None) –

Return type:

Vips.max_coord_get()¶

Returns:: The maximum value a coordinate, or image dimension, can have.
Return type:: int

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.

Vips.nickname_find(type)¶

Parameters:: type (GObject.GType) – [alias`GObject`.Type] to search for
Returns:: the class nickname.
Return type:: str

Return the VIPS nickname for a [alias`GObject`.Type]. Handy for language bindings.

Vips.pipe_read_limit_set(limit)¶

Parameters:: limit (int) – maximum number of bytes to buffer from a pipe

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.

Vips.profile_set(profile)¶

Parameters:: profile (bool) – TRUE to enable profile recording

If set, vips will record profiling information, and dump it on program exit. These profiles can be analysed with the vipsprofile program.

Vips.progress_set(progress)¶

Parameters:: progress (bool) – TRUE to enable progress messages

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.

Vips.pythagoras(L1, a1, b1, L2, a2, b2)¶

Parameters:

L1 (float) – Input coordinate 1
a1 (float) – Input coordinate 1
b1 (float) – Input coordinate 1
L2 (float) – Input coordinate 2
a2 (float) – Input coordinate 2
b2 (float) – Input coordinate 2

Return type:

Pythagorean distance between two points in colour space. Lab/XYZ/CMC etc.

Vips.realpath(path)¶

Parameters:: path (str) –
Return type:: str

Vips.rename(old_name, new_name)¶

Parameters:

old_name (str) –
new_name (str) –

Return type:

Vips.shutdown()¶

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 [funcINIT] many times and [func`shutdown`] many times, but you must not call [funcINIT] after [func`shutdown`]. In other words, you cannot stop and restart libvips.

::: seealso [func`profile_set`], [func`leak_set`].

Vips.sink_memory(im)¶

Parameters:: im (Vips.Image) – generate this image to memory
Returns:: 0 on success, or -1 on error.
Return type:: int

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

Vips.slist_equal(l1, l2)¶

Parameters:

l1 ([int]) – a [struct`GLib`.SList]
l2 ([int]) – another [struct`GLib`.SList]

Returns:

TRUE if l1 is equal to l2. FALSE otherwise.

Return type:

Test two lists for equality.

Vips.slist_filter(list, fn, a, b)¶

Parameters:

list ([int]) – a [struct`GLib`.SList]
fn (Vips.SListMap2Fn) – function to call for each element.
a (object or None) – user data
b (object or None) – user data

Returns:

new head of list

Return type:

[int]

Remove all occurrences of an item from a list. Returns the new head of the list.

Vips.slist_fold2(list, start, fn, a, b)¶

Parameters:

list ([int]) – a [struct`GLib`.SList]
start (object or None) – initial value for the accumulator
fn (Vips.SListFold2Fn) – function to apply to each list element
a (object or None) – user data
b (object or None) – user data

Returns:

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

Return type:

Fold over a slist, applying fn to each element.

Vips.slist_free_all(list)¶

Parameters:: list ([int]) – a [struct`GLib`.SList]

Free a [struct`GLib`.SList] of things which need [func`GLib`.free]ing.

Vips.slist_map2(list, fn, a, b)¶

Parameters:

list ([int]) – a [struct`GLib`.SList]
fn (Vips.SListMap2Fn) – function to apply to each list element
a (object or None) – user data
b (object or None) – user data

Returns:

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

Return type:

Map over a slist. _copy() the list in case the callback changes it.

Vips.slist_map2_rev(list, fn, a, b)¶

Parameters:

list ([int]) – a [struct`GLib`.SList]
fn (Vips.SListMap2Fn) – function to apply to each list element
a (object or None) – user data
b (object or None) – user data

Returns:

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

Return type:

Map backwards. We _reverse() rather than recurse and unwind to save stack.

Vips.slist_map4(list, fn, a, b, c, d)¶

Parameters:

list ([int]) – a [struct`GLib`.SList]
fn (Vips.SListMap4Fn) – function to apply to each list element
a (object or None) – user data
b (object or None) – user data
c (object or None) – user data
d (object or None) – user data

Returns:

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

Return type:

Map over a slist. _copy() the list in case the callback changes it.

Vips.start_many(out, a, b)¶

Parameters:

out (Vips.Image) – image to generate
a (object or None) – user data
b (object or None) – user data

Return type:

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

Vips.start_one(out, a, b)¶

Parameters:

out (Vips.Image) – image to generate
a (object or None) – user data
b (object or None) – user data

Return type:

Start function for one image in. Input image is a.

::: seealso [method`Image`.generate].

Vips.stop_many(seq, a, b)¶

Parameters:

seq (object or None) – sequence value
a (object or None) – user data
b (object or None) – user data

Return type:

Stop function for many images in. a is a pointer to a NULL-terminated array of input images.

::: seealso [method`Image`.generate].

Vips.stop_one(seq, a, b)¶

Parameters:

seq (object or None) – sequence value
a (object or None) – user data
b (object or None) – user data

Return type:

Stop function for one image in. Input image is a.

::: seealso [method`Image`.generate].

Vips.strdup(object, str)¶

Parameters:

object (Vips.Object or None) – allocate memory local to this [class`Object`], or NULL
str (str) – string to copy

Returns:

a pointer to the allocated memory

Return type:

[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`].

Vips.strtod(str, out)¶

Parameters:

str (str) –
out (float) –

Return type:

Vips.thread_execute(domain, func, *data)¶

Parameters:

domain (str) – a name for the thread (useful for debugging)
func (GLib.Func) – a function to execute in the libvips threadset
data (object or None) – an argument to supply to func

Returns:

0 on success, -1 on error.

Return type:

A newly created or reused thread will execute func with the argument data.

Vips.thread_isvips()¶

Return type:: bool

Vips.thread_shutdown()¶

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.

Vips.tracked_aligned_alloc(size, align)¶

Parameters:

size (int) – number of bytes to allocate
align (int) – specifies the alignment

Returns:

a pointer to the allocated memory, or NULL on error.

Return type:

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

Vips.tracked_aligned_free(s)¶

Parameters:: s (object or None) – memory to free

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

Vips.tracked_close(fd)¶

Parameters:: fd (int) – file to close()
Returns:: a file descriptor, or -1 on error.
Return type:: int

Exactly as close()), 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`].

Vips.tracked_free(s)¶

Parameters:: s (object or None) – memory to free

Only use it to free memory that was previously allocated with [func`tracked_malloc`] with a NULL first argument.

::: seealso [func`tracked_malloc`].

Vips.tracked_get_allocs()¶

Returns:: the number of active allocations
Return type:: int

Returns the number of active allocations.

Vips.tracked_get_files()¶

Returns:: the number of open files
Return type:: int

Returns the number of open files.

Vips.tracked_get_mem()¶

Returns:: the number of currently allocated bytes
Return type:: int

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

Vips.tracked_get_mem_highwater()¶

Returns:: the largest number of currently allocated bytes
Return type:: int

Returns the largest number of bytes simultaneously allocated via [func`tracked_malloc`]. Handy for estimating max memory requirements for a program.

Vips.tracked_malloc(size)¶

Parameters:: size (int) – number of bytes to allocate
Returns:: a pointer to the allocated memory, or NULL on error.
Return type:: object or None

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

Vips.tracked_open(pathname, flags, mode)¶

Parameters:

pathname (str) – name of file to open
flags (int) – flags for open()
mode (int) – open mode

Returns:

a file descriptor, or -1 on error.

Return type:

Exactly as open()), 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`].

Vips.type_depth(type)¶

Parameters:: type (GObject.GType) –
Return type:: int

Vips.type_find(basename, nickname)¶

Parameters:

basename (str) – name of base class
nickname (str) – search for a class with this nickname

Returns:

the [alias`GObject`.Type] of the class, or 0 if the class is not found.

Return type:

GObject.GType

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

Vips.value_get_area(value)¶

Parameters:

value (GObject.Value) – get from this value

Returns:

The pointer held by value.

length:: optionally return length here

Return type:

(object or None, length: int)

Get the pointer from an area. Don’t touch count (area is static).

Vips.value_get_array(value)¶

Parameters:

value (GObject.Value) – [struct`GObject`.Value] to get from

Returns:

The array address.

n:: return the number of elements here, optionally
type:: return the type of each element here, optionally
sizeof_type:: return the sizeof each element here, optionally

Return type:

(object or None, n: int, type: GObject.GType, sizeof_type: int)

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

Vips.value_get_array_double(value)¶

Parameters:: value (GObject.Value) – [struct`GObject`.Value] to get from
Returns:: The array address.
Return type:: [float]

Return the start of the array of doubles held by value. optionally return the number of elements in n.

::: seealso [ctor`ArrayDouble`.new].

Vips.value_get_array_image(value)¶

Parameters:: value (GObject.Value) – [struct`GObject`.Value] to get from
Returns:: The array address.
Return type:: [Vips.Image]

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

Vips.value_get_array_int(value)¶

Parameters:: value (GObject.Value) – [struct`GObject`.Value] to get from
Returns:: The array address.
Return type:: [int]

Return the start of the array of ints held by value. optionally return the number of elements in n.

::: seealso [ctor`ArrayInt`.new].

Vips.value_get_blob(value)¶

Parameters:: value (GObject.Value) – GObject.Value to set
Returns:: The pointer held by value.
Return type:: bytes

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

Vips.value_get_ref_string(value)¶

Parameters:

value (GObject.Value) – [struct`GObject`.Value] to get from

Returns:

The C string held by value.

length:: return length here, optionally

Return type:

(str, length: int)

Get the C string held internally by the [struct`GObject`.Value].

Vips.value_get_save_string(value)¶

Parameters:: value (GObject.Value) – GObject.Value to get from
Returns:: The C string held by value.
Return type:: str

Get the C string held internally by the GObject.Value.

Vips.value_is_null(psoec, value)¶

Parameters:

psoec (GObject.ParamSpec) –
value (GObject.Value) –

Return type: