Vips.Image

Subclasses:

None

Methods

Inherited:

Vips.Object (27), GObject.Object (37)

Structs:

Vips.ObjectClass (1), GObject.ObjectClass (5)

class	get_format_max (format)
class	memory ()
class	new ()
class	new_from_file_RW (filename)
class	new_from_file_raw (filename, xsize, ysize, bands, offset)
class	new_from_image (image, c)
class	new_from_image1 (image, c)
class	new_from_memory (data, width, height, bands, format)
class	new_from_memory_copy (data, width, height, bands, format)
class	new_matrix (width, height)
class	new_matrix_from_array (width, height, array)
class	new_temp_file (format)
	autorot_remove_angle ()
	colourspace_issupported ()
	copy_memory ()
	decode ()
	decode_predict ()
	encode (coding)
	foreign_load_invalidate ()
	free_buffer (buffer)
	get (name)
	get_area (name)
	get_array_double (name)
	get_array_int (name)
	get_as_string (name)
	get_bands ()
	get_blob (name)
	get_coding ()
	get_concurrency (default_concurrency)
	get_data ()
	get_double (name)
	get_fields ()
	get_filename ()
	get_format ()
	get_height ()
	get_history ()
	get_image (name)
	get_int (name)
	get_interpretation ()
	get_mode ()
	get_n_pages ()
	get_n_subifds ()
	get_offset ()
	get_orientation ()
	get_orientation_swap ()
	get_page_height ()
	get_scale ()
	get_string (name)
	get_typeof (name)
	get_width ()
	get_xoffset ()
	get_xres ()
	get_yoffset ()
	get_yres ()
	guess_format ()
	guess_interpretation ()
	hasalpha ()
	history_args (name, argv)
	icc_ac2rc (profile_filename)
	init_fields (xsize, ysize, bands, format, coding, interpretation, xres, yres)
	inplace ()
	invalidate_all ()
	isMSBfirst ()
	is_sequential ()
	isfile ()
	iskilled ()
	ispartial ()
	map (fn, a)
	minimise_all ()
	pio_input ()
	pio_output ()
	print_field (name)
	remove (name)
	reorder_margin_hint (margin)
	reorder_prepare_many (regions, r)
	set (name, value)
	set_area (name, free_fn, *data)
	set_array_double (name, array)
	set_array_int (name, array)
	set_blob (name, free_fn, data)
	set_blob_copy (name, data)
	set_delete_on_close (delete_on_close)
	set_double (name, d)
	set_image (name, im)
	set_int (name, i)
	set_kill (kill)
	set_progress (progress)
	set_string (name, str)
	wio_input ()
	write ()
	write_line (ypos, linebuffer)
	write_prepare ()
	write_to_memory ()

Virtual Methods

Inherited:

Vips.Object (9), GObject.Object (7)

	do_eval (progress, data)
	do_invalidate (data)
	do_minimise (data)
	do_posteval (progress, data)
	do_preeval (progress, data)
	do_written (result, data)

Properties

Inherited:

Vips.Object (2)

Name	Type	Flags	Short Description
bands	int	r/w	Number of bands in image
coding	Vips.Coding	r/w	Pixel coding
demand	Vips.DemandStyle	r/w	Preferred demand style for this image
filename	str	r/w	Image filename
foreign-buffer	int	r/w	Pointer to foreign pixels
format	Vips.BandFormat	r/w	Pixel format in image
height	int	r/w	Image height in pixels
interpretation	Vips.Interpretation	r/w	Pixel interpretation
kill	bool	r/w	Block evaluation on this image
mode	str	r/w	Open mode
sizeof-header	int	r/w	Offset in bytes from start of file
width	int	r/w	Image width in pixels
xoffset	int	r/w	Horizontal offset of origin
xres	float	r/w	Horizontal resolution in pixels/mm
yoffset	int	r/w	Vertical offset of origin
yres	float	r/w	Vertical resolution in pixels/mm

Signals

Inherited:

Vips.Object (4), GObject.Object (1)

Name	Short Description
eval	The ::eval signal is emitted once per work unit (typically a 128 x 128 area of pixels) during image computation.
invalidate	The ::invalidate signal is emitted when an image or one of it’s upstream data sources has been destructively modified.
minimise	The ::minimise signal is emitted when an image has been asked to minimise memory usage.
posteval	The ::posteval signal is emitted once at the end of the computation of image.
preeval	The ::preeval signal is emitted once before computation of image starts.
written	The ::written signal is emitted just after an image has been written to.

Fields

Inherited:

Vips.Object (4), GObject.Object (1)

Name	Type	Access	Description
BandFmt	Vips.BandFormat	r
Bands	int	r
Bbits	int	r
Coding	Vips.Coding	r
Compression	int	r
Hist	str	r
Length	int	r
Level	int	r
Type	Vips.Interpretation	r
Xoffset	int	r
Xres	float	r
Xres_float	float	r
Xsize	int	r
Yoffset	int	r
Yres	float	r
Yres_float	float	r
Ysize	int	r
baseaddr	object	r
client1	object	r
client2	object	r
data	int	r
delete_on_close	bool	r
delete_on_close_filename	str	r
dhint	Vips.DemandStyle	r
downstream	[object]	r
dtype	Vips.ImageType	r
fd	int	r
file_length	int	r
filename	str	r
generate_fn	Vips.GenerateFn	r
hint_set	bool	r
history_list	[object]	r
kill	int	r
length	int	r
magic	int	r
meta	{object: object}	r
meta_traverse	[object]	r
mode	str	r
parent_instance	Vips.Object	r
progress_signal	Vips.Image	r
regions	[object]	r
serial	int	r
sizeof_header	int	r
sslock	GLib.Mutex	r
start_fn	Vips.StartFn	r
stop_fn	Vips.StopFn	r
time	Vips.Progress	r
upstream	[object]	r
windows	[object]	r

Class Details

class Vips.Image(**kwargs)

Bases:

Vips.Object

Abstract:

No

Structure:

Vips.ImageClass

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

classmethod get_format_max(format)

Parameters:

format (Vips.BandFormat) – the format

Returns:

the maximum numeric value possible for this format.

Return type:

float

classmethod memory()

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

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

See also: vips_image_new_memory().

classmethod new()

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

Vips.Image.new() creates a new, empty Vips.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 vips_image_generate() or Vips.Image.write_line(). Write a whole image to another image with Vips.Image.write().

classmethod new_from_file_RW(filename)

Parameters:

filename (str) – filename to open

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

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

See also: vips_draw_circle().

classmethod new_from_file_raw(filename, xsize, ysize, bands, offset)

Parameters:

• filename (str) – filename to open

• xsize (int) – image width

• ysize (int) – image height

• bands (int) – image bands (or bytes per pixel)

• offset (int) – bytes to skip at start of file

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

This function maps the named file and returns a Vips.Image you can use to read it.

It returns an 8-bit image with bands bands. If the image is not 8-bit, use vips_copy() to transform the descriptor after loading it.

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

classmethod new_from_image(image, c)

Parameters:

• image (Vips.Image) – image to copy

• c ([float]) – array of constants

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

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

See also: Vips.Image.new_from_image1()

classmethod new_from_image1(image, c)

Parameters:

• image (Vips.Image) – image to copy

• c (float) – constants

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

Creates a new image with width, height, format, interpretation, resolution and offset taken from image, but with one band and each pixel having the value c.

See also: Vips.Image.new_from_image()

classmethod new_from_memory(data, width, height, bands, format)

Parameters:

• data (bytes) – start of memory area

• width (int) – image width

• height (int) – image height

• bands (int) – image bands (or bytes per pixel)

• format (Vips.BandFormat) – image format

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

This function wraps a Vips.Image around a memory area. The memory area must be a simple array, for example RGBRGBRGB, left-to-right, top-to-bottom. Use vips_image_new_from_buffer() to load an area of memory containing an image in a format.

VIPS does not take responsibility for the area of memory, it’s up to you to make sure it’s freed when the image is closed. See for example Vips.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 Vips.Image.new_from_memory_copy() instead if you are at all unsure.

Use vips_copy() to set other image properties.

See also: Vips.Image.new(), Vips.Image.write_to_memory(), Vips.Image.new_from_memory_copy().

classmethod new_from_memory_copy(data, width, height, bands, format)

Parameters:

• data (bytes) – start of memory area

• width (int) – image width

• height (int) – image height

• bands (int) – image bands (or bytes per pixel)

• format (Vips.BandFormat) – image format

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

Like Vips.Image.new_from_memory(), but VIPS will make a copy of the memory area. This means more memory use and an extra copy operation, but is much simpler and safer.

See also: Vips.Image.new_from_memory().

classmethod new_matrix(width, height)

Parameters:

• width (int) – image width

• height (int) – image height

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

This convenience function makes an image which is a matrix: a one-band Vips.BandFormat.DOUBLE image held in memory.

Use VIPS_IMAGE_ADDR(), or VIPS_MATRIX() to address pixels in the image.

Use Vips.Image.set_double() to set “scale” and “offset”, if required.

See also: vips_image_new_matrixv()

classmethod new_matrix_from_array(width, height, array)

Parameters:

• width (int) – image width

• height (int) – image height

• array ([float]) – array of elements

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

A binding-friendly version of vips_image_new_matrixv().

classmethod new_temp_file(format)

Parameters:

format (str) – format of file

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

Make a Vips.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 “%s.v” for a vips file.

The file is created in the temporary directory. This is set with the environment variable TMPDIR. If this is not set, then on Unix systems, vips will default to /tmp. On Windows, vips uses GetTempPath() to find the temporary directory.

See also: Vips.Image.new().

autorot_remove_angle()

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

colourspace_issupported()

Returns:

True if self is in a supported colourspace.

Return type:

bool

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

copy_memory()

Returns:

the new Vips.Image, or None on error.

Return type:

Vips.Image

This function allocates memory, renders self 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 self and returns it.

Call this before using the draw operations to make sure you have a memory image that can be modified.

vips_copy() adds a null “copy” node to a pipeline. Use that instead if you want to change metadata and not pixels.

This operation is thread-safe, unlike Vips.Image.wio_input().

If you are sure that self is not shared with another thread (perhaps you have made it yourself), use Vips.Image.wio_input() instead.

See also: Vips.Image.wio_input().

decode()

Returns:

0 on success, or -1 on error.

out:

write to this image

Return type:

(int, out: Vips.Image)

A convenience function to unpack to a format that we can compute with. out.coding is always Vips.Coding.NONE.

This unpacks LABQ to plain LAB. Use vips_LabQ2LabS() for a bit more speed if you need it.

See also: Vips.Image.encode(), vips_LabQ2Lab(), vips_rad2float().

decode_predict()

Returns:

bands:

predict bands here

format:

predict format here

Return type:

(int, bands: int, format: Vips.BandFormat)

We often need to know what an image will decode to without actually decoding it, for example, in arg checking.

See also: Vips.Image.decode().

encode(coding)

Parameters:

coding (Vips.Coding) – coding to apply

Returns:

0 on success, or -1 on error.

out:

write to this image

Return type:

(int, out: Vips.Image)

A convenience function to pack to a coding. The inverse of Vips.Image.decode().

See also: Vips.Image.decode().

foreign_load_invalidate()

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.

free_buffer(buffer)

Parameters:

buffer (object or None) – the original buffer that was stolen

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

get(name)

Parameters:

name (str) – the name to fetch

Returns:

0 on success, -1 otherwise.

value_copy:

the GObject.Value is copied into this

Return type:

(int, value_copy: GObject.Value)

Fill value_copy with a copy of the header field. value_copy must be zeroed but uninitialised.

This will return -1 and add a message to the error buffer if the field does not exist. Use Vips.Image.get_typeof() to test for the existence of a field first if you are not certain it will be there.

For example, to read a double from an image (though of course you would use Vips.Image.get_double() in practice):

GValue value = G_VALUE_INIT;
double d;

if (vips_image_get(image, name, &value))
    return -1;

if (G_VALUE_TYPE(&value) != G_TYPE_DOUBLE) {
    vips_error("mydomain",
        _("field \"%s\" is of type %s, not double"),
        name,
        g_type_name(G_VALUE_TYPE(&value)));
    g_value_unset(&value);
    return -1;
}

d = g_value_get_double(&value);
g_value_unset(&value);

See also: Vips.Image.get_typeof(), Vips.Image.get_double().

get_area(name)

Parameters:

name (str) – metadata name

Returns:

0 on success, -1 otherwise.

data:

return metadata value

Return type:

(int, data: object)

Gets data from self under the name name. A convenience function over Vips.Image.get(). Use Vips.Image.get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.set_area(), Vips.Image.get(), Vips.Image.get_typeof()

get_array_double(name)

Parameters:

name (str) – metadata name

Returns:

0 on success, -1 otherwise.

out:

return pointer to array

Return type:

(int, out: [float])

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 self is valid.

Use Vips.Image.get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.get(), Vips.Image.set_image()

get_array_int(name)

Parameters:

name (str) – metadata name

Returns:

0 on success, -1 otherwise.

out:

return pointer to array

Return type:

(int, out: [int])

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 self is valid.

Use Vips.Image.get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.get(), Vips.Image.set_image()

get_as_string(name)

Parameters:

name (str) – field name

Returns:

0 on success, -1 otherwise.

out:

return field value as string

Return type:

(int, out: str)

Returns name from self in out. This function will read any field, returning it as a printable string. You need to free the string with GLib.free() when you are done with it.

This will base64-encode BLOBs, for example. Use vips_buf_appendgv() to make a string that’s for humans.

See also: Vips.Image.get(), Vips.Image.get_typeof(), vips_buf_appendgv().

get_bands()

Returns:

the number of bands (channels) in the image.

Return type:

int

get_blob(name)

Parameters:

name (str) – metadata name

Returns:

0 on success, -1 otherwise.

data:

pointer to area of memory

Return type:

(int, data: bytes)

Gets data from self under the name name, optionally returns its length in length. Use Vips.Image.get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.get(), Vips.Image.get_typeof(), Vips.Blob.get(),

get_coding()

Returns:

the image coding

Return type:

Vips.Coding

get_concurrency(default_concurrency)

Parameters:

default_concurrency (int) –

Returns:

the suggested concurrency for this image

Return type:

int

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

get_data()

Returns:

a pointer to pixel data, if possible.

Return type:

object or None

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 self, it is not threadsafe. Only call it on images which you are sure have not been shared with another thread.

See also: Vips.Image.wio_input(), Vips.Image.copy_memory().

get_double(name)

Parameters:

name (str) – field name

Returns:

0 on success, -1 otherwise.

out:

return field value

Return type:

(int, out: float)

Gets out from im under the name name. The value will be transformed into a double, if possible.

See also: Vips.Image.get(), Vips.Image.get_typeof()

get_fields()

Returns:

metadata fields in image, as a None-terminated array.

Return type:

[str]

Get a None-terminated array listing all the metadata field names on self. Free the return result with GLib.strfreev().

This is handy for language bindings. From C, it’s usually more convenient to use Vips.Image.map().

get_filename()

Returns:

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

Return type:

str

get_format()

Returns:

the format of each band element.

Return type:

Vips.BandFormat

get_height()

Returns:

the number of pixels down the image.

Return type:

int

get_history()

Returns:

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

Return type:

str

This function reads the image history as a C string. The string is owned by VIPS and must not be freed.

VIPS tracks the history of each image, that is, the sequence of operations that generated that image. Applications built on VIPS need to call vips_image_history_printf() for each action they perform, setting the command-line equivalent for the action.

See also: vips_image_history_printf().

get_image(name)

Parameters:

name (str) – metadata name

Returns:

0 on success, -1 otherwise.

out:

return metadata value

Return type:

(int, out: Vips.Image)

Gets out from im under the name name. The field must be of type #VIPS_TYPE_IMAGE. You must unref out with GObject.Object.unref().

Use Vips.Image.get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.get(), Vips.Image.set_image()

get_int(name)

Parameters:

name (str) – field name

Returns:

0 on success, -1 otherwise.

out:

return field value

Return type:

(int, out: int)

Gets out from im under the name name. The value will be transformed into an int, if possible.

See also: Vips.Image.get(), Vips.Image.get_typeof()

get_interpretation()

Returns:

the Vips.Interpretation from the image header.

Return type:

Vips.Interpretation

Return the Vips.Interpretation set in the image header. Use Vips.Image.guess_interpretation() if you want a sanity-checked value.

get_mode()

Returns:

the image mode.

Return type:

str

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

get_n_pages()

Returns:

the number of pages in the image file

Return type:

int

Fetch and sanity-check Vips.META_N_PAGES. Default to 1 if not present or crazy.

This is the number of pages in the image file, not the number of pages that have been loaded into self.

get_n_subifds()

Returns:

the number of subifds in the image file

Return type:

int

Fetch and sanity-check Vips.META_N_SUBIFDS. Default to 0 if not present or crazy.

get_offset()

Returns:

the offset.

Return type:

float

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

get_orientation()

Returns:

the image orientation.

Return type:

int

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

get_orientation_swap()

Returns:

if width/height will swap

Return type:

bool

Return True if applying the orientation would swap width and height.

get_page_height()

Returns:

the page height.

Return type:

int

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.

get_scale()

Returns:

the scale.

Return type:

float

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

get_string(name)

Parameters:

name (str) – field name

Returns:

0 on success, -1 otherwise.

out:

return field value

Return type:

(int, out: str)

Gets out from im under the name name. The field must be of type GObject.TYPE_STRING, VIPS_TYPE_REF_STRING.

Do not free out.

Use Vips.Image.get_as_string() to fetch any field as a string.

See also: Vips.Image.get(), Vips.Image.get_typeof()

get_typeof(name)

Parameters:

name (str) – the name to search for

Returns:

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

Return type:

GObject.GType

Read the GObject.GType for a header field. Returns zero if there is no field of that name.

See also: Vips.Image.get().

get_width()

Returns:

the number of pixels across the image.

Return type:

int

get_xoffset()

Returns:

the horizontal position of the image origin, in pixels.

Return type:

int

get_xres()

Returns:

the horizontal image resolution in pixels per millimeter.

Return type:

float

get_yoffset()

Returns:

the vertical position of the image origin, in pixels.

Return type:

int

get_yres()

Returns:

the vertical image resolution in pixels per millimeter.

Return type:

float

guess_format()

Returns:

a sensible Vips.BandFormat for the image.

Return type:

Vips.BandFormat

Return the Vips.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.

guess_interpretation()

Returns:

a sensible Vips.Interpretation for the image.

Return type:

Vips.Interpretation

Return the Vips.Interpretation for an image, guessing a sane value if the set value looks crazy.

hasalpha()

Return type:

bool

Look at an image’s interpretation and see if it has extra alpha bands. For example, a 4-band #VIPS_INTERPRETATION_sRGB would, but a six-band Vips.Interpretation.MULTIBAND would not.

Return True if self has an alpha channel.

history_args(name, argv)

Parameters:

• name (str) – program name

• argv ([str]) – program arguments

Returns:

0 on success, -1 on error.

Return type:

int

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

See also: Vips.Image.get_history().

icc_ac2rc(profile_filename)

Parameters:

profile_filename (str) – use this profile

Returns:

0 on success, -1 on error.

out:

output image

Return type:

(int, out: Vips.Image)

Transform an image from absolute to relative colorimetry using the MediaWhitePoint stored in the ICC profile.

See also: vips_icc_transform(), vips_icc_import().

init_fields(xsize, ysize, bands, format, coding, interpretation, xres, yres)

Parameters:

• xsize (int) – image width

• ysize (int) – image height

• bands (int) – image bands

• format (Vips.BandFormat) – band format

• coding (Vips.Coding) – image coding

• interpretation (Vips.Interpretation) – image type

• xres (float) – horizontal resolution, pixels per millimetre

• yres (float) – vertical resolution, pixels per millimetre

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

See also: vips_image_pipelinev().

inplace()

Returns:

0 on success, or -1 on error.

Return type:

int

Gets self ready for an in-place operation, such as vips_draw_circle(). After calling this function you can both read and write the image with VIPS_IMAGE_ADDR().

This method is called for you by the base class of the draw operations, there’s no need to call it yourself.

Since this function modifies self, it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. All in-place operations are inherently not thread-safe, so you need to take great care in any case.

See also: vips_draw_circle(), Vips.Image.wio_input().

invalidate_all()

Invalidate all pixel caches on self and any downstream images, that is, images which depend on this image. Additionally, all operations which depend upon this image are dropped from the VIPS operation cache.

You should call this function after destructively modifying an image with something like vips_draw_circle().

The Vips.Image ::invalidate signal is emitted for all invalidated images.

See also: Vips.Region.invalidate().

isMSBfirst()

Return type:

bool

Return True if self is in most-significant- byte first form. This is the byte order used on the SPARC architecture and others.

is_sequential()

Returns:

True if self is in sequential mode.

Return type:

bool

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

isfile()

Return type:

bool

Return True if self represents a file on disc in some way.

iskilled()

Returns:

True if self has been killed.

Return type:

bool

If self has been killed (see Vips.Image.set_kill()), set an error message, clear the Vips.Image.kill flag and return True. Otherwise return False.

Handy for loops which need to run sets of threads which can fail.

See also: Vips.Image.set_kill().

ispartial()

Return type:

bool

Return True if im represents a partial image (a delayed calculation).

map(fn, a)

Parameters:

• fn (Vips.ImageMapFn or None) – function to call for each header field

• a (object or None) – user data for function

Returns:

None on success, the failing pointer otherwise.

Return type:

object or None

This function calls fn for every header field, including every item of metadata.

Like all _map functions, the user function should return None to continue iteration, or a non-None pointer to indicate early termination.

See also: Vips.Image.get_typeof(), Vips.Image.get().

minimise_all()

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 Vips.Image ::minimise signal is emitted for all minimised images.

pio_input()

Returns:

0 on success, or -1 on error.

Return type:

int

Check that an image is readable with Vips.Region.prepare() and friends. If it isn’t, try to transform the image so that Vips.Region.prepare() can work.

See also: Vips.Image.pio_output(), Vips.Region.prepare().

pio_output()

Returns:

0 on success, or -1 on error.

Return type:

int

Check that an image is writeable with vips_image_generate(). If it isn’t, try to transform the image so that vips_image_generate() can work.

See also: Vips.Image.pio_input().

print_field(name)

Parameters:

name (str) – field name

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

remove(name)

Parameters:

name (str) – the name to search for

Returns:

True if an item of metadata of that name was found and removed

Return type:

bool

Find and remove an item of metadata. Return False if no metadata of that name was found.

See also: Vips.Image.set(), Vips.Image.get_typeof().

reorder_margin_hint(margin)

Parameters:

margin (int) – the size of the margin this operation has added

Vips.Image.reorder_margin_hint() sets a hint that self contains a margin, that is, that each Vips.Region.prepare() on self will request a slightly larger region from it’s inputs. A good value for margin is (width * height) for the window the operation uses.

This information is used by vips_image_prepare_many() to attempt to reorder computations to minimise recomputation.

See also: vips_image_prepare_many().

reorder_prepare_many(regions, r)

Parameters:

• regions ([Vips.Region]) – the set of regions to prepare

• r (Vips.Rect) – the Vips.Rect to prepare on each region

Returns:

0 on success, or -1 on error.

Return type:

int

Vips.Image.reorder_prepare_many() runs Vips.Region.prepare() on each region in regions, requesting the pixels in r.

It tries to request the regions in the order which will cause least recomputation. This can give a large speedup, in some cases.

See also: Vips.Region.prepare(), Vips.Image.reorder_margin_hint().

set(name, value)

Parameters:

• name (str) – the name to give the metadata

• value (GObject.Value) – the GObject.Value to copy into the image

Set a piece of metadata on self. Any old metadata with that name is destroyed. The 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 Vips.Image.set_int() in practice), you would do:

GValue value = G_VALUE_INIT;

g_value_init(&value, G_TYPE_INT);
g_value_set_int(&value, 42);
vips_image_set(image, name, &value);
g_value_unset(&value);

See also: Vips.Image.get().

set_area(name, free_fn, *data)

Parameters:

• name (str) – metadata name

• free_fn (Vips.CallbackFn or None) – free function for data

• data (object or None) – pointer to area of memory

Attaches data as a metadata item on self under the name name. When VIPS no longer needs the metadata, it will be freed with free_fn.

See also: Vips.Image.get_double(), Vips.Image.set()

set_array_double(name, array)

Parameters:

• name (str) – metadata name

• array ([float] or None) – array of doubles

Attaches array as a metadata item on self as name. A convenience function over Vips.Image.set().

See also: Vips.Image.get_image(), Vips.Image.set().

set_array_int(name, array)

Parameters:

• name (str) – metadata name

• array ([int] or None) – array of ints

Attaches array as a metadata item on self as name. A convenience function over Vips.Image.set().

See also: Vips.Image.get_image(), Vips.Image.set().

set_blob(name, free_fn, data)

Parameters:

• name (str) – metadata name

• free_fn (Vips.CallbackFn or None) – free function for data

• data (bytes) – pointer to area of memory

Attaches data as a metadata item on self under the name name.

See also: Vips.Image.get_blob(), Vips.Image.set().

set_blob_copy(name, data)

Parameters:

• name (str) – metadata name

• data (bytes) – pointer to area of memory

Attaches data as a metadata item on self under the name name, taking a copy of the memory area.

See also: Vips.Image.get_blob(), Vips.Image.set().

set_delete_on_close(delete_on_close)

Parameters:

delete_on_close (bool) – format of file

Sets the delete_on_close flag for the image. If this flag is set, when self is finalized, the filename held in self->filename at the time of this call is deleted.

This function is clearly extremely dangerous, use with great caution.

See also: Vips.Image.new_temp_file().

set_double(name, d)

Parameters:

• name (str) – metadata name

• d (float) – metadata value

Attaches d as a metadata item on self as name. A convenience function over Vips.Image.set().

See also: Vips.Image.get_double(), Vips.Image.set()

set_image(name, im)

Parameters:

• name (str) – metadata name

• im (Vips.Image) – metadata value

Attaches im as a metadata item on self as name. A convenience function over Vips.Image.set().

See also: Vips.Image.get_image(), Vips.Image.set().

set_int(name, i)

Parameters:

• name (str) – metadata name

• i (int) – metadata value

Attaches i as a metadata item on self under the name name. A convenience function over Vips.Image.set().

See also: Vips.Image.get_int(), Vips.Image.set()

set_kill(kill)

Parameters:

kill (bool) – the kill state

Set the Vips.Image.kill flag on an image. Handy for stopping sets of threads.

See also: Vips.Image.iskilled().

set_progress(progress)

Parameters:

progress (bool) – turn progress reporting on or off

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

set_string(name, str)

Parameters:

• name (str) – metadata name

• str (str) – metadata value

Attaches str as a metadata item on self as name. A convenience function over Vips.Image.set() using #VIPS_TYPE_REF_STRING.

See also: Vips.Image.get_double(), Vips.Image.set().

wio_input()

Returns:

0 on success, or -1 on error.

Return type:

int

Check that an image is readable via the VIPS_IMAGE_ADDR() macro, that is, that the entire image is in memory and all pixels can be read with VIPS_IMAGE_ADDR(). If it isn’t, try to transform it so that VIPS_IMAGE_ADDR() can work.

Since this function modifies self, it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. If the image might have been shared, use the less efficient Vips.Image.copy_memory() instead.

See also: Vips.Image.copy_memory(), Vips.Image.pio_input(), Vips.Image.inplace(), VIPS_IMAGE_ADDR().

write()

Returns:

0 on success, or -1 on error.

out:

write to this image

Return type:

(int, out: Vips.Image)

Write self to out. Use Vips.Image.new() and friends to create the Vips.Image you want to write to.

See also: Vips.Image.new(), vips_copy(), vips_image_write_to_file().

write_line(ypos, linebuffer)

Parameters:

• ypos (int) – vertical position of scan-line to write

• linebuffer (int) – scanline of pixels

Returns:

0 on success, or -1 on error.

Return type:

int

Write a line of pixels to an image. This function must be called repeatedly with ypos increasing from 0 to Vips.Image ::height . linebuffer must be VIPS_IMAGE_SIZEOF_LINE() bytes long.

See also: vips_image_generate().

write_prepare()

Returns:

0 on success, or -1 on error.

Return type:

int

Call this after setting header fields (width, height, and so on) to allocate resources ready for writing.

Normally this function is called for you by vips_image_generate() or Vips.Image.write_line(). You will need to call it yourself if you plan to write directly to the ->data member of a memory image.

write_to_memory()

Returns:

return buffer start here

Return type:

bytes

Writes self to memory as a simple, unformatted C-style array.

The caller is responsible for freeing this memory with GLib.free().

See also: vips_image_write_to_buffer().

do_eval(progress, data) virtual

Parameters:

• progress (Vips.Progress) –

• data (object or None) –

do_invalidate(data) virtual

Parameters:

data (object or None) –

do_minimise(data) virtual

Parameters:

data (object or None) –

do_posteval(progress, data) virtual

Parameters:

• progress (Vips.Progress) –

• data (object or None) –

do_preeval(progress, data) virtual

Parameters:

• progress (Vips.Progress) –

• data (object or None) –

do_written(result, data) virtual

Parameters:

• result (int) –

• data (object or None) –

Signal Details

Vips.Image.signals.eval(image, progress)

Signal Name:

eval

Flags:

RUN_LAST

Parameters:

• image (Vips.Image) – The object which received the signal

• progress (Vips.Progress) – Vips.Progress for this image

The ::eval signal is emitted once per work unit (typically a 128 x 128 area of pixels) during image computation.

You can use this signal to update user-interfaces with progress feedback. Beware of updating too frequently: you will usually need some throttling mechanism.

Use Vips.Image.set_progress() to turn on progress reporting for an image.

Vips.Image.signals.invalidate(image)

Signal Name:

invalidate

Flags:

RUN_LAST, ACTION

Parameters:

image (Vips.Image) – The object which received the signal

The ::invalidate signal is emitted when an image or one of it’s upstream data sources has been destructively modified. See Vips.Image.invalidate_all().

Vips.Image.signals.minimise(image)

Signal Name:

minimise

Flags:

RUN_LAST, ACTION

Parameters:

image (Vips.Image) – The object which received the signal

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

Vips.Image.signals.posteval(image, progress)

Signal Name:

posteval

Flags:

RUN_LAST

Parameters:

• image (Vips.Image) – The object which received the signal

• progress (Vips.Progress) – Vips.Progress for this image

The ::posteval signal is emitted once at the end of the computation of image. It’s a good place to shut down evaluation feedback.

Use Vips.Image.set_progress() to turn on progress reporting for an image.

Vips.Image.signals.preeval(image, progress)

Signal Name:

preeval

Flags:

RUN_LAST

Parameters:

• image (Vips.Image) – The object which received the signal

• progress (Vips.Progress) – Vips.Progress for this image

The ::preeval signal is emitted once before computation of image starts. It’s a good place to set up evaluation feedback.

Use Vips.Image.set_progress() to turn on progress reporting for an image.

Vips.Image.signals.written(image)

Signal Name:

written

Flags:

RUN_LAST, ACTION

Parameters:

image (Vips.Image) – The object which received the signal

Returns:

set to non-zero to indicate error

Return type:

result: int

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

Property Details

Vips.Image.props.bands

Name:

bands

Type:

int

Default Value:

1

Flags:

READABLE, WRITABLE

Number of bands in image

Vips.Image.props.coding

Name:

coding

Type:

Vips.Coding

Default Value:

Vips.Coding.NONE

Flags:

READABLE, WRITABLE

Pixel coding

Vips.Image.props.demand

Name:

demand

Type:

Vips.DemandStyle

Default Value:

Vips.DemandStyle.SMALLTILE

Flags:

READABLE, WRITABLE

Preferred demand style for this image

Vips.Image.props.filename

Name:

filename

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

Image filename

Vips.Image.props.foreign_buffer

Name:

foreign-buffer

Type:

int

Default Value:

None

Flags:

READABLE, WRITABLE

Pointer to foreign pixels

Vips.Image.props.format

Name:

format

Type:

Vips.BandFormat

Default Value:

Vips.BandFormat.UCHAR

Flags:

READABLE, WRITABLE

Pixel format in image

Vips.Image.props.height

Name:

height

Type:

int

Default Value:

1

Flags:

READABLE, WRITABLE

Image height in pixels

Vips.Image.props.interpretation

Name:

interpretation

Type:

Vips.Interpretation

Default Value:

Vips.Interpretation.MULTIBAND

Flags:

READABLE, WRITABLE

Pixel interpretation

Vips.Image.props.kill

Name:

kill

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE

Block evaluation on this image

Vips.Image.props.mode

Name:

mode

Type:

str

Default Value:

'p'

Flags:

READABLE, WRITABLE

Open mode

Vips.Image.props.sizeof_header

Name:

sizeof-header

Type:

int

Default Value:

64

Flags:

READABLE, WRITABLE

Offset in bytes from start of file

Vips.Image.props.width

Name:

width

Type:

int

Default Value:

1

Flags:

READABLE, WRITABLE

Image width in pixels

Vips.Image.props.xoffset

Name:

xoffset

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE

Horizontal offset of origin

Vips.Image.props.xres

Name:

xres

Type:

float

Default Value:

0.0

Flags:

READABLE, WRITABLE

Horizontal resolution in pixels/mm

Vips.Image.props.yoffset

Name:

yoffset

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE

Vertical offset of origin

Vips.Image.props.yres

Name:

yres

Type:

float

Default Value:

0.0

Flags:

READABLE, WRITABLE

Vertical resolution in pixels/mm