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 (26), GObject.Object (37)
Structs:Vips.ObjectClass (1), GObject.ObjectClass (5)
class matrix_from_array (width, height, array)
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_memory ()
class new_temp_file (format)
  autorot_remove_angle ()
  foreign_load_invalidate ()
  icc_ac2rc (profile_filename)
  image_copy_memory ()
  image_decode ()
  image_decode_predict ()
  image_encode (coding)
  image_get (name)
  image_get_area (name)
  image_get_array_int (name, out, n)
  image_get_as_string (name, out)
  image_get_bands ()
  image_get_blob (name, data, length)
  image_get_coding ()
  image_get_data ()
  image_get_double (name, out)
  image_get_fields ()
  image_get_filename ()
  image_get_format ()
  image_get_height ()
  image_get_history ()
  image_get_image (name, out)
  image_get_int (name)
  image_get_interpretation ()
  image_get_mode ()
  image_get_n_pages ()
  image_get_n_subifds ()
  image_get_offset ()
  image_get_orientation ()
  image_get_orientation_swap ()
  image_get_page_height ()
  image_get_scale ()
  image_get_string (name, out)
  image_get_typeof (name)
  image_get_width ()
  image_get_xoffset ()
  image_get_xres ()
  image_get_yoffset ()
  image_get_yres ()
  image_guess_format ()
  image_guess_interpretation ()
  image_hasalpha ()
  image_history_args (name, argv)
  image_init_fields (xsize, ysize, bands, format, coding, interpretation, xres, yres)
  image_inplace ()
  image_invalidate_all ()
  image_isMSBfirst ()
  image_is_sequential ()
  image_isfile ()
  image_iskilled ()
  image_ispartial ()
  image_map (fn, a)
  image_minimise_all ()
  image_pio_input ()
  image_pio_output ()
  image_print_field (field)
  image_remove (name)
  image_set (name, value)
  image_set_area (name, free_fn, *data)
  image_set_array_int (name, array)
  image_set_blob (name, free_fn, data, length)
  image_set_blob_copy (name, data, length)
  image_set_delete_on_close (delete_on_close)
  image_set_double (name, d)
  image_set_image (name, im)
  image_set_int (name, i)
  image_set_kill (kill)
  image_set_progress (progress)
  image_set_string (name, str)
  image_wio_input ()
  image_write ()
  image_write_line (ypos, linebuffer)
  image_write_prepare ()
  image_write_to_memory ()
  reorder_margin_hint (margin)
  reorder_prepare_many (regions, r)

Virtual Methods

Inherited:Vips.Object (7), 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 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 renamed Vips.Image.new_matrix_from_array(). Some gobject bindings do not like more than one _new method.

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.image_write_line(). Write a whole image to another image with Vips.Image.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:
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:
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.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.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_memory()
Returns:the new Vips.Image, or None on error.
Return type:Vips.Image

Vips.Image.new_memory() creates a new Vips.Image which, when written to, will create a memory image.

See also: Vips.Image.new().

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.

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.

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

image_copy_memory()
Returns:the new Vips.Image, or None on error.
Return type:Vips.Image

Make an image which is an area of memory.

If self is already a memory buffer, just ref and return. If it’s a file on disc or a partial, allocate memory and copy the image to it.

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

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

See also: Vips.Image.image_wio_input().

image_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.image_encode(), vips_LabQ2Lab(), vips_rad2float().

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

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

See also: Vips.Image.image_decode().

image_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.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.image_get_double() in practice):

GValue value = { 0 };
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.image_get_typeof(), Vips.Image.image_get_double().

image_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.image_get(). Use Vips.Image.image_get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.image_set_area(), Vips.Image.image_get(), Vips.Image.image_get_typeof()

image_get_array_int(name, out, n)
Parameters:
  • name (str) – metadata name
  • out (int) – return pointer to array
  • n (int or None) – return the number of elements here, optionally
Returns:

0 on success, -1 otherwise.

Return type:

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.image_get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.image_get(), Vips.Image.image_set_image()

image_get_as_string(name, out)
Parameters:
  • name (str) – field name
  • out (str) – return field value as string
Returns:

0 on success, -1 otherwise.

Return type:

int

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.image_get(), Vips.Image.image_get_typeof(), vips_buf_appendgv().

image_get_bands()
Returns:the number of bands (channels) in the image.
Return type:int
image_get_blob(name, data, length)
Parameters:
  • name (str) – metadata name
  • data (object or None) – pointer to area of memory
  • length (int) – return the blob length here, optionally
Returns:

0 on success, -1 otherwise.

Return type:

int

Gets blob from self under the name name, optionally returns its length in length. A convenience function over Vips.Image.image_get(). Use Vips.Image.image_get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.image_get(), Vips.Image.image_get_typeof(), Vips.Blob.get(),

image_get_coding()
Returns:the image coding
Return type:Vips.Coding
image_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.image_wio_input(), Vips.Image.image_copy_memory().

image_get_double(name, out)
Parameters:
  • name (str) – field name
  • out (float) – return field value
Returns:

0 on success, -1 otherwise.

Return type:

int

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

See also: Vips.Image.image_get(), Vips.Image.image_get_typeof()

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

image_get_filename()
Returns:the name of the file the image was loaded from, or None if there is no filename.
Return type:str
image_get_format()
Returns:the format of each band element.
Return type:Vips.BandFormat
image_get_height()
Returns:the number of pixels down the image.
Return type:int
image_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().

image_get_image(name, out)
Parameters:
  • name (str) – metadata name
  • out (Vips.Image) – return metadata value
Returns:

0 on success, -1 otherwise.

Return type:

int

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.image_get_typeof() to test for the existence of a piece of metadata.

See also: Vips.Image.image_get(), Vips.Image.image_set_image()

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.image_get(), Vips.Image.image_get_typeof()

image_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.image_guess_interpretation() if you want a sanity-checked value.

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

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

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

image_get_offset()
Returns:the offset.
Return type:float

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

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

image_get_orientation_swap()
Returns:if width/height will swap
Return type:bool

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

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

image_get_scale()
Returns:the scale.
Return type:float

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

image_get_string(name, out)
Parameters:
  • name (str) – field name
  • out (str) – return field value
Returns:

0 on success, -1 otherwise.

Return type:

int

Gets out from im under the name name. The field must be of type G_STRING, VIPS_TYPE_REFSTRING.

Do not free out.

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

See also: Vips.Image.image_get(), Vips.Image.image_get_typeof()

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

image_get_width()
Returns:the number of pixels across the image.
Return type:int
image_get_xoffset()
Returns:the horizontal position of the image origin, in pixels.
Return type:int
image_get_xres()
Returns:the horizontal image resolution in pixels per millimeter.
Return type:float
image_get_yoffset()
Returns:the vertical position of the image origin, in pixels.
Return type:int
image_get_yres()
Returns:the vertical image resolution in pixels per millimeter.
Return type:float
image_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.

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

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

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

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

image_inplace()
Returns:0 on succeess, 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.image_wio_input().

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

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

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

image_isfile()
Return type:bool

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

image_iskilled()
Returns:True if self has been killed.
Return type:bool

If self has been killed (see Vips.Image.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.image_set_kill().

image_ispartial()
Return type:bool

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

image_map(fn, a)
Parameters:
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.image_get_typeof(), Vips.Image.image_get().

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

image_pio_input()
Returns:0 on succeess, or -1 on error.
Return type:int

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

See also: Vips.Image.image_pio_output(), Vips.Region.region_prepare().

image_pio_output()
Returns:0 on succeess, 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.image_pio_input().

image_print_field(field)
Parameters:field (str) –

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

image_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.image_set(), Vips.Image.image_get_typeof().

image_set(name, value)
Parameters:

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.image_set_int() in practice), you would do:

GValue value = { 0 };

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

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

See also: Vips.Image.image_get_double(), Vips.Image.image_set()

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

See also: Vips.Image.image_get_image(), Vips.Image.image_set().

image_set_blob(name, free_fn, data, length)
Parameters:
  • name (str) – metadata name
  • free_fn (Vips.CallbackFn) – free function for data
  • data (object or None) – pointer to area of memory
  • length (int) – length of memory area

Attaches blob as a metadata item on self under the name name. A convenience function over Vips.Image.image_set() using a vips_blob.

See also: Vips.Image.image_get_blob(), Vips.Image.image_set().

image_set_blob_copy(name, data, length)
Parameters:
  • name (str) – metadata name
  • data (object or None) – pointer to area of memory
  • length (int) – length of memory area

Attaches blob as a metadata item on self under the name name, taking a copy of the memory area. A convenience function over Vips.Image.image_set_blob().

See also: Vips.Image.image_get_blob(), Vips.Image.image_set().

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

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

See also: Vips.Image.image_get_double(), Vips.Image.image_set()

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

See also: Vips.Image.image_get_image(), Vips.Image.image_set().

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

See also: Vips.Image.image_get_int(), Vips.Image.image_set()

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

image_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.image_set_progress() was called.

image_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.image_set() using #VIPS_TYPE_REF_STRING.

See also: Vips.Image.image_get_double(), Vips.Image.image_set().

image_wio_input()
Returns:0 on succeess, 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.image_copy_memory() instead.

See also: Vips.Image.image_copy_memory(), Vips.Image.image_pio_input(), Vips.Image.image_inplace(), VIPS_IMAGE_ADDR().

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

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

image_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.image_write_line(). You will need to call it yourself if you plan to write directly to the ->data member of a memory image.

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

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.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:
Returns:

0 on success, or -1 on error.

Return type:

int

Vips.Image.reorder_prepare_many() runs Vips.Region.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.region_prepare(), Vips.Image.reorder_margin_hint().

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:

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

Vips.Image.signals.posteval(image, progress)
Signal Name:

posteval

Flags:

RUN_LAST

Parameters:

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.image_set_progress() to turn on progress reporting for an image.

Vips.Image.signals.preeval(image, progress)
Signal Name:

preeval

Flags:

RUN_LAST

Parameters:

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

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

Vips.Image.signals.written(image, result)
Signal Name:

written

Flags:

RUN_LAST, ACTION

Parameters:
  • image (Vips.Image) – The object which received the signal
  • result (object or None) – set to non-zero to indicate error

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