Vips.Image

g GObject.Object GObject.Object Vips.Object Vips.Object GObject.Object->Vips.Object Vips.Image Vips.Image Vips.Object->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)

class

pipeline_array (hint, in_)

autorot_remove_angle ()

colourspace_issupported ()

copy_memory ()

decode ()

decode_predict ()

encode (coding)

eval (processed)

foreign_load_invalidate ()

free_buffer (buffer)

generate (start_fn, generate_fn, stop_fn, a, b)

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

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

get_tile_size ()

get_tile_width ()

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

posteval ()

preeval ()

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)

sink (start_fn, generate_fn, stop_fn, a, b)

sink_disc (write_fn, *a)

sink_screen (mask, tile_width, tile_height, max_tiles, priority, notify_fn, *a)

sink_tile (tile_width, tile_height, start_fn, generate_fn, stop_fn, a, b)

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

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

invalidate

This signal is emitted when an image or one of it’s upstream data sources has been destructively modified.

minimise

This signal is emitted when an image has been asked to minimise memory usage.

posteval

This signal is emitted once at the end of the computation of image.

preeval

This signal is emitted once before computation of image starts.

written

This 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

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 for getting and setting image metadata. See [class`Object`] for a discussion of the lower levels.

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 [class`Image`], or NULL on error.

Return type:

Vips.Image

A renamed [ctor`Image`.new_memory] … Some gobject binding systems do not like more than one _new() method.

::: seealso [ctor`Image`.new_memory].

classmethod new()
Returns:

the new [class`Image`], or NULL on error.

Return type:

Vips.Image

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

classmethod new_from_file_RW(filename)
Parameters:

filename (str) – filename to open

Returns:

the new [class`Image`], or NULL 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.

::: seealso [method`Image`.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 [class`Image`], or NULL on error.

Return type:

Vips.Image

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

classmethod new_from_image(image, c)
Parameters:
Returns:

the new [class`Image`], or NULL 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.

::: seealso [ctor`Image`.new_from_image1]

classmethod new_from_image1(image, c)
Parameters:
Returns:

the new [class`Image`], or NULL 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.

::: seealso [ctor`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 [class`Image`], or NULL on error.

Return type:

Vips.Image

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`:py:func:::close<Vips.Image.signals.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].

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 [class`Image`], or NULL on error.

Return type:

Vips.Image

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

classmethod new_matrix(width, height)
Parameters:

  • width (int) – image width

  • height (int) – image height

Returns:

the new [class`Image`], or NULL on error.

Return type:

Vips.Image

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

Use [funcIMAGE_ADDR], or [funcMATRIX] to address pixels in the image.

Use [method`Image`.set_double] to set “scale” and “offset”, if required.

::: seealso [ctor`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 [class`Image`], or NULL on error.

Return type:

Vips.Image

A binding-friendly version of [ctor`Image`.new_matrixv].

classmethod new_temp_file(format)
Parameters:

format (str) – format of file

Returns:

the new [class`Image`], or NULL on error.

Return type:

Vips.Image

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

classmethod pipeline_array(hint, in_)
Parameters:
Returns:

0 on success, -1 on error.

image:

output image

Return type:

(int, image: Vips.Image)

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

autorot_remove_angle()

Remove the orientation tag on self. Also remove any exif orientation tags. You must [method`Image`.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 [method`Image`.colourspace] can process.

copy_memory()
Returns:

the new [class`Image`], or NULL 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.

[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 self is not shared with another thread (perhaps you have made it yourself), use [method`Image`.wio_input] instead.

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

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.

::: seealso [method`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 [method`Image`.decode].

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

eval(processed)
Parameters:

processed (int) –

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.

generate(start_fn, generate_fn, stop_fn, a, b)
Parameters:
Returns:

0 on success, or -1 on error.

Return type:

int

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

get(name)
Parameters:

name (str) – the name to fetch

Returns:

0 on success, -1 otherwise.

value_copy:

the [struct`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 [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 GObject.Value value = G_VALUE_INIT; double d;

if (Vips.Image.get(image, name, &value)) return -1;

if (G_VALUE_TYPE(&value) != GObject.TYPE_DOUBLE) { vips_error(“mydomain”, _(“field \”%s\” is of type %s, not double”), name, GObject.type_name(G_VALUE_TYPE(&value))); GObject.Value.unset(&value); return -1; }

d = GObject.Value.get_double(&value); GObject.Value.unset(&value); ```

::: seealso [method`Image`.get_typeof], [method`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 [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].

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 [method`Image`.get_typeof] to test for the existence of a piece of metadata.

::: seealso [method`Image`.get], [method`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 [method`Image`.get_typeof] to test for the existence of a piece of metadata.

::: seealso [method`Image`.get], [method`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 [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].

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

get_coding()
Returns:

the [enum`Coding`] from the image header.

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 [constMETA_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.

::: seealso [method`Image`.wio_input], [method`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.

::: seealso [method`Image`.get], [method`Image`.get_typeof].

get_fields()
Returns:

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

Return type:

[str]

Get a NULL-terminated array listing all the metadata field names on self. 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].

get_filename()
Returns:

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

Return type:

str

get_format()
Returns:

the format of each band element.

Return type:

Vips.BandFormat

get_gainmap()
Returns:

the gainmap image, if present, or None.

Return type:

Vips.Image or None

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.

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 [method`Image`.history_printf] for each action they perform, setting the command-line equivalent for the action.

::: seealso [method`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 [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]

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.

::: seealso [method`Image`.get], [method`Image`.get_typeof].

get_interpretation()
Returns:

the [enum`Interpretation`] from the image header.

Return type:

Vips.Interpretation

Return the [enum`Interpretation`] set in the image header. Use [method`Image`.guess_format] 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 [constMETA_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 [constMETA_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 [constMETA_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 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].

get_tile_height()
Returns:

the height of the tiles encoded in the image.

Return type:

int

Fetch and sanity-check [constMETA_TILE_HEIGHT]. Default to -1 (no tiling) if not present or crazy.

get_tile_size()
Returns:

tile_width:

return selected tile width

tile_height:

return selected tile height

n_lines:

return buffer height in scanlines

Return type:

(tile_width: int, tile_height: int, n_lines: int)

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.

get_tile_width()
Returns:

the width of the tiles encoded in the image.

Return type:

int

Fetch and sanity-check [constMETA_TILE_WIDTH]. Default to -1 (no tiling) if not present or crazy.

get_typeof(name)
Parameters:

name (str) – the name to search for

Returns:

the [alias`GObject`.Type] of the field, or zero if there is no field of that name.

Return type:

GObject.GType

Read the [alias`GObject`.Type] for a header field. Returns zero if there is no field of that name.

::: seealso [method`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 [enum`BandFormat`] for the image.

Return type:

Vips.BandFormat

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.

guess_interpretation()
Returns:

a sensible [enum`Interpretation`] for the image.

Return type:

Vips.Interpretation

Return the [enum`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 [enum`Vips`.Interpretation.sRGB] would, but a six-band [enum`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 [method`Image`.history_printf]. A convenience function for command-line programs.

::: seealso [method`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.

::: seealso [method`Image`.icc_transform], [method`Image`.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 [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].

inplace()
Returns:

0 on success, or -1 on error.

Return type:

int

Gets self 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 [funcIMAGE_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.

::: seealso [method`Image`.draw_circle], [method`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 [method`Image`.draw_circle].

The [signal`Image`:py:func:::invalidate<Vips.Image.signals.invalidate>] signal is emitted for all invalidated images.

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

ispartial()
Return type:

bool

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

map(fn, *a)
Parameters:
Returns:

NULL 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 NULL to continue iteration, or a non-NULL pointer to indicate early termination.

::: seealso [method`Image`.get_typeof], [method`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 [signal`Image`:py:func:::minimise<Vips.Image.signals.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 [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].

pio_output()
Returns:

0 on success, or -1 on error.

Return type:

int

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

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

::: seealso [method`Image`.set], [method`Image`.get_typeof].

reorder_margin_hint(margin)
Parameters:

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

[method`Image`.reorder_margin_hint] sets a hint that self contains a margin, that is, that each [method`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 [method`Image`.reorder_prepare_many] to attempt to reorder computations to minimise recomputation.

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

reorder_prepare_many(regions, r)
Parameters:

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

  • r (Vips.Rect) – the [struct`Rect`] to prepare on each region

Returns:

0 on success, or -1 on error.

Return type:

int

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

set(name, value)
Parameters:

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

  • value (GObject.Value) – the [struct`GObject`.Value] to copy into the image

Set a piece of metadata on self. 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 GObject.Value value = G_VALUE_INIT;

GObject.Value.init(&value, GObject.TYPE_INT); GObject.Value.set_int(&value, 42); Vips.Image.set(image, name, &value); GObject.Value.unset(&value); ```

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

set_area(name, free_fn, *data)
Parameters:

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.

::: seealso [method`Image`.get_double], [method`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 [method`Image`.set].

::: seealso [method`Image`.get_image], [method`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 [method`Image`.set].

::: seealso [method`Image`.get_image], [method`Image`.set].

set_blob(name, free_fn, data)
Parameters:

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

::: seealso [method`Image`.get_blob], [method`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.

::: seealso [method`Image`.get_blob], [method`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.

::: seealso [ctor`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 [method`Image`.set].

::: seealso [method`Image`.get_double], [method`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 [method`Image`.set].

::: seealso [method`Image`.get_image], [method`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 [method`Image`.set].

::: seealso [method`Image`.get_int], [method`Image`.set].

set_kill(kill)
Parameters:

kill (bool) – the kill state

Set the [class`Image`].kill flag on an image. Handy for stopping sets of threads.

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

set_progress(progress)
Parameters:

progress (bool) – turn progress reporting on or off

vips signals evaluation progress via the [signal`Image`:py:func:::preeval<Vips.Image.signals.preeval>], [signal`Image`:py:func:::eval<Vips.Image.signals.eval>] and [signal`Image`:py:func:::posteval<Vips.Image.signals.posteval>] signals. Progress is signalled on the most-downstream image for which [method`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 [method`Image`.set] using VIPS_TYPE_REF_STRING.

::: seealso [method`Image`.get_double], [method`Image`.set].

sink(start_fn, generate_fn, stop_fn, a, b)
Parameters:
Returns:

0 on success, or -1 on error.

Return type:

int

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

::: seealso [method`Image`.generate], [ctor`Image`.new].

sink_disc(write_fn, *a)
Parameters:
Returns:

0 on success, -1 on error.

Return type:

int

[method`Image`.sink_disc] loops over self, 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`].

sink_screen(mask, tile_width, tile_height, max_tiles, priority, notify_fn, *a)
Parameters:

  • mask (Vips.Image) – mask image indicating valid pixels

  • tile_width (int) – tile width

  • tile_height (int) – tile height

  • max_tiles (int) – maximum tiles to cache

  • priority (int) – rendering priority

  • notify_fn (Vips.SinkNotify or None) – pixels are ready notification callback

  • a (object or None) – client data for callback

Returns:

0 on success, -1 on error.

out:

output image

Return type:

(int, out: Vips.Image)

This operation renders self 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].

sink_tile(tile_width, tile_height, start_fn, generate_fn, stop_fn, a, b)
Parameters:

  • tile_width (int) – tile width

  • tile_height (int) – tile height

  • start_fn (Vips.StartFn) – start sequences with this function

  • generate_fn (Vips.GenerateFn) – generate pixels with this function

  • stop_fn (Vips.StopFn) – stop sequences with this function

  • a (object or None) – user data

  • b (object or None) – user data

Returns:

0 on success, or -1 on error.

Return type:

int

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

wio_input()
Returns:

0 on success, or -1 on error.

Return type:

int

Check that an image is readable via the [funcIMAGE_ADDR] macro, that is, that the entire image is in memory and all pixels can be read with [funcIMAGE_ADDR]. If it isn’t, try to transform it so that [funcIMAGE_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 [method`Image`.copy_memory] instead.

::: seealso [method`Image`.copy_memory], [method`Image`.pio_input], [method`Image`.inplace], [funcIMAGE_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 [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].

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 [property`Image`:py:data::height<Vips.Image.props.height>]. linebuffer must be [funcIMAGE_SIZEOF_LINE] bytes long.

::: seealso [method`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 [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.

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

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

do_eval(progress, data) virtual
Parameters:
do_invalidate(data) virtual
Parameters:

data (object or None) –

do_minimise(data) virtual
Parameters:

data (object or None) –

do_posteval(progress, data) virtual
Parameters:
do_preeval(progress, data) virtual
Parameters:
do_written(result, data) virtual
Parameters:

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) – [struct`Progress`] for this image

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.

Vips.Image.signals.invalidate(image)
Signal Name:

invalidate

Flags:

RUN_LAST, ACTION

Parameters:

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

This signal is emitted when an image or one of it’s upstream data sources has been destructively modified. See [method`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

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

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) – [struct`Progress`] for this image

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.

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) – [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.

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

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.

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