Image

Main methods

class pyvips.Image(pointer)[source]

Wrap a VipsImage object.

Methods

__init__(pointer)[source]

Wrap around a pointer.

Wraps a GObject instance around an underlying pointer. When the instance is garbage-collected, the underlying object is unreferenced.

static new_from_file(vips_filename, **kwargs)[source]

Load an image from a file.

This method can load images in any format supported by vips. The filename can include load options, for example:

image = pyvips.Image.new_from_file('fred.jpg[shrink=2]')

You can also supply options as keyword arguments, for example:

image = pyvips.Image.new_from_file('fred.jpg', shrink=2)

The full set of options available depend upon the load operation that will be executed. Try something like:

$ vips jpegload

at the command-line to see a summary of the available options for the JPEG loader.

Loading is fast: only enough of the image is loaded to be able to fill out the header. Pixels will only be decompressed when they are needed.

Parameters

vips_filename (str) – The disc file to load the image from, with optional appended arguments.

All loaders support at least the following options:

Keyword Arguments
  • memory (bool) – If set True, load the image via memory rather than via a temporary disc file. See new_temp_file() for notes on where temporary files are created. Small images are loaded via memory by default, use VIPS_DISC_THRESHOLD to set the definition of small.

  • access (Access) – Hint the expected access pattern for the image.

  • fail (bool) – If set True, the loader will fail with an error on the first serious error in the file. By default, libvips will attempt to read everything it can from a damaged image.

Returns

A new Image.

Raises

.Error

static new_from_buffer(data, options, **kwargs)[source]

Load a formatted image from memory.

This behaves exactly as new_from_file(), but the image is loaded from the memory object rather than from a file. The memory object can be anything that supports the Python buffer protocol.

Parameters
  • data (array, bytearray, bytes, buffer) – The memory object to load the image from.

  • options (str) – Load options as a string. Use "" for no options.

All loaders support at least the following options:

Keyword Arguments
  • access (Access) – Hint the expected access pattern for the image.

  • fail (bool) – If set True, the loader will fail with an error on the first serious error in the image. By default, libvips will attempt to read everything it can from a damaged image.

Returns

A new Image.

Raises

.Error

static new_from_list(array, scale=1.0, offset=0.0)[source]

Create an image from a list or list of lists.

A new one-band image with BandFormat 'double' pixels is created from the array. These image are useful with the libvips convolution operator Image.conv().

Parameters
  • array (list[list[float]]) – Create the image from these values. 1D arrays become a single row of pixels.

  • scale (float) – Default to 1.0. What to divide each pixel by after convolution. Useful for integer convolution masks.

  • offset (float) – Default to 0.0. What to subtract from each pixel after convolution. Useful for integer convolution masks.

Returns

A new Image.

Raises

.Error

classmethod new_from_array(obj, scale=1.0, offset=0.0, interpretation=None)[source]

Create a new Image from a list or an array-like object.

Array-like objects are those which define __array_interface__ or __array__. For details about the array interface, see The Array Interface.

If __array_interface__ is not available, __array__ is used as a fallback.

The behavior for input objects with different dimensions is summarized as:

| array ndim | array shape | Image w | Image h | Image bands |
|------------|-------------|---------|---------|-------------|
| 0          | ()          | 1       | 1       | 1           |
| 1          | (W,)        | W       | 1       | 1           |
| 2          | (H, W)      | W       | H       | 1           |
| 3          | (H, W, C)   | W       | H       | C           |
Parameters
  • obj (list or object width __array_interface__ or __array__) –

    The object to convert to an image.

    If the input object is a list, Image.new_from_list is used with the given scale and offset

    If the input object is an array-like object, a new image is created from the object’s data and shape. The memory is shared except in the following cases:

    • The object’s memory is not contiguous. In this case, a copy is made by attempting to call the object’s tobytes() method or its tostring() method.

    • The object is an array of bools, in which case it is converted to a pyvips uchar image with True values becoming 255 and False values becoming 0.

  • scale (float) – Default to 1.0. Ignored for non-list inputs. What to divide each pixel by after convolution. Useful for integer convolution masks.

  • offset (float) – Default to 0.0. Ignored for non-list inputs. What to subtract from each pixel after convolution. Useful for integer convolution masks.

  • interpretation (str, optional) –

    Ignored for list inputs The libvips interpretation of the array. If None, the interpretation defaults to the pyvips one for Image.new_from_memory.

    If ‘auto’, a heuristic is used to determine a best-guess interpretation as defined in the _guess_interpretation function.

    Must be one of None, ‘auto’, ‘error’, ‘multiband’, ‘b-w’, ‘histogram’, ‘xyz’, ‘lab’, ‘cmyk’, ‘labq’, ‘rgb’, ‘cmc’, ‘lch’, ‘labs’, ‘srgb’, ‘yxy’, ‘fourier’, ‘rgb16’, ‘grey16’, ‘matrix’, ‘scrgb’, or ‘hsv’

Returns

The new image.

See also

_guess_interpretation()

static new_from_memory(data, width, height, bands, format)[source]

Wrap an image around a memory array.

Wraps an Image around an area of memory containing a C-style array. For example, if the data memory array contains four bytes with the values 1, 2, 3, 4, you can make a one-band, 2x2 uchar image from it like this:

image = Image.new_from_memory(data, 2, 2, 1, 'uchar')

A reference is kept to the data object, so it will not be garbage-collected until the returned image is garbage-collected.

This method is useful for efficiently transferring images from PIL or NumPy into libvips.

See write_to_memory() for the opposite operation.

Use copy() to set other image attributes.

Parameters
  • data (bytes) – A memoryview or buffer object.

  • width (int) – Image width in pixels.

  • height (int) – Image height in pixels.

  • bands (int) – Number of bands.

  • format (BandFormat) – Band format.

Returns

A new Image.

Raises

.Error

static new_from_source(source, options, **kwargs)[source]

Load a formatted image from a source.

This behaves exactly as new_from_file(), but the image is loaded from the source rather than from a file.

Parameters
  • source (Source) – The source to load the image from.

  • options (str) – Load options as a string. Use "" for no options.

All loaders support at least the following options:

Keyword Arguments
  • access (Access) – Hint the expected access pattern for the image.

  • fail (bool) – If set True, the loader will fail with an error on the first serious error in the image. By default, libvips will attempt to read everything it can from a damaged image.

Returns

A new Image.

Raises

.Error

static new_temp_file(format)[source]

Make a new temporary image.

Returns an image backed by a temporary file. When written to with Image.write(), a temporary file will be created on disc in the specified format. When the image is closed, the file will be deleted automatically.

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.

vips uses g_mkstemp() to make the temporary filename. They generally look something like "vips-12-EJKJFGH.v".

Parameters

format (str) – The format for the temp file, for example "%s.v" for a vips format file. The %s is substituted by the file path.

Returns

A new Image.

Raises

.Error

new_from_image(value)[source]

Make a new image from an existing one.

A new image is created which has the same size, format, interpretation and resolution as self, but with every pixel set to value.

Parameters

value (float, list[float]) – The value for the pixels. Use a single number to make a one-band image; use an array constant to make a many-band image.

Returns

A new Image.

Raises

.Error

copy_memory()[source]

Copy an image to memory.

A large area of memory is allocated, the image is rendered to that memory area, and a new image is returned which wraps that large memory area.

Returns

A new Image.

Raises

.Error

write_to_file(vips_filename, **kwargs)[source]

Write an image to a file on disc.

This method can save images in any format supported by vips. The format is selected from the filename suffix. The filename can include embedded save options, see Image.new_from_file().

For example:

image.write_to_file('fred.jpg[Q=95]')

You can also supply options as keyword arguments, for example:

image.write_to_file('fred.jpg', Q=95)

The full set of options available depend upon the load operation that will be executed. Try something like:

$ vips jpegsave

at the command-line to see a summary of the available options for the JPEG saver.

Parameters

vips_filename (str) – The disc file to save the image to, with optional appended arguments.

Other arguments depend upon the save operation.

Returns

None

Raises

.Error

write_to_buffer(format_string, **kwargs)[source]

Write an image to memory.

This method can save images in any format supported by vips. The format is selected from the suffix in the format string. This can include embedded save options, see Image.write_to_file().

For example:

data = image.write_to_buffer('.jpg[Q=95]')

You can also supply options as keyword arguments, for example:

data = image.write_to_buffer('.jpg', Q=95)

The full set of options available depend upon the load operation that will be executed. Try something like:

$ vips jpegsave_buffer

at the command-line to see a summary of the available options for the JPEG saver.

Parameters

format_string (str) – The suffix, plus any string-form arguments.

Other arguments depend upon the save operation.

Returns

A byte string.

Raises

.Error

write_to_target(target, format_string, **kwargs)[source]

Write an image to a target.

This method will write the image to the target in the format specified in the suffix in the format string. This can include embedded save options, see Image.write_to_file().

For example:

image.write_to_target(target, '.jpg[Q=95]')

You can also supply options as keyword arguments, for example:

image.write_to_target(target, '.jpg', Q=95)

The full set of options available depend upon the save operation that will be executed. Try something like:

$ vips jpegsave_target

at the command-line to see a summary of the available options for the JPEG saver.

Parameters
  • target (Target) – The target to write the image to

  • format_string (str) – The suffix, plus any string-form arguments.

Other arguments depend upon the save operation.

Returns

None

Raises

.Error

write_to_memory()[source]

Write the image to a large memory array.

A large area of memory is allocated, the image is rendered to that memory array, and the array is returned as a buffer.

For example, if you have a 2x2 uchar image containing the bytes 1, 2, 3, 4, read left-to-right, top-to-bottom, then:

buf = image.write_to_memory()

will return a four byte buffer containing the values 1, 2, 3, 4.

Returns

buffer

Raises

.Error

write(other)[source]

Write an image to another image.

This function writes self to another image. Use something like Image.new_temp_file() to make an image that can be written to.

Parameters

other (Image) – The Image to write to,

Returns

None

Raises

.Error

invalidate()[source]

Drop caches on an image, and any downstream images.

This method drops all pixel caches on an image and on all downstream images. Any operations which depend on this image, directly or indirectly, are also dropped from the libvips operation cache.

This method can be useful if you wrap a libvips image around an area of memory with new_from_memory() and then change some bytes without libvips knowing.

Returns

None

set_progress(progress)[source]

Enable progress reporting on an image.

When progress reporting is enabled, evaluation of the most downstream image from this image will report progress using the ::preeval, ::eval, and ::posteval signals.

set_kill(kill)[source]

Kill processing of an image.

Use this to kill evaluation of an image. You can call it from one of the progress signals, for example. See set_progress().

get_typeof(name)[source]

Get the GType of an item of metadata.

Fetch the GType of a piece of metadata, or 0 if the named item does not exist. See GValue.

Parameters

name (str) – The name of the piece of metadata to get the type of.

Returns

The GType, or 0.

Raises

None

get(name)[source]

Get an item of metadata.

Fetches an item of metadata as a Python value. For example:

orientation = image.get('orientation')

would fetch the image orientation.

Parameters

name (str) – The name of the piece of metadata to get.

Returns

The metadata item as a Python value.

Raises

.Error

get_fields()[source]

Get a list of all the metadata fields on an image.

Returns

[string]

set_type(gtype, name, value)[source]

Set the type and value of an item of metadata.

Sets the type and value of an item of metadata. Any old item of the same name is removed. See GValue for types.

Parameters
  • gtype (int) – The GType of the metadata item to create.

  • name (str) – The name of the piece of metadata to create.

  • value (mixed) – The value to set as a Python value. It is converted to the gtype, if possible.

Returns

None

Raises

None

set(name, value)[source]

Set the value of an item of metadata.

Sets the value of an item of metadata. The metadata item must already exist.

Parameters
  • name (str) – The name of the piece of metadata to set the value of.

  • value (mixed) – The value to set as a Python value. It is converted to the type of the metadata item, if possible.

Returns

None

Raises

.Error

remove(name)[source]

Remove an item of metadata.

The named metadata item is removed.

Parameters

name (str) – The name of the piece of metadata to remove.

Returns

None

Raises

None

tolist()[source]

Return a single-band image as a list of lists.

Returns

list of lists of values

__array__(dtype=None)[source]

Conversion to a NumPy array.

Parameters

dtype (str or numpy dtype, optional) – numpy array. If None, the default dtype of the image is used as defined the global FORMAT_TO_TYPESTR dictionary.

Returns

The array representation of the image.
  • Single-band images lose their channel axis.

  • Single-pixel single-band images are converted to a 0D array.

Return type

numpy.ndarray

See https://numpy.org/devdocs/user/basics.dispatch.html for more details.

This enables a Image to be used where a numpy array is expected, including in plotting and conversion to other array container types (pytorch, JAX, dask, etc.), for example.

numpy is a runtime dependency of this function.

See Also Image.new_from_array for the inverse operation. #TODO

numpy(dtype=None)[source]

Convenience function to allow numpy conversion to be at the end of a method chain.

This mimics the behavior of pytorch: arr = im.op1().op2().numpy()

numpy is a runtime dependency of this function.

Parameters

dtype (str or numpy dtype) – The dtype to use for the numpy array. If None, the default dtype of the image is used.

Returns

The image as a numpy array.

Return type

numpy.ndarray

See also

  • __array__()

  • FORMAT_TO_TYPESTR: Global dictionary mapping libvips format strings to numpy dtype strings.

__repr__()[source]

Return repr(self).

__getattr__(name)[source]

Divert unknown names to libvips.

Unknown attributes are first looked up in the image properties as accessors, for example:

width = image.width

and then in the libvips operation table, where they become method calls, for example:

new_image = image.invert()

Use get() to fetch image metadata.

A __getattr__ on the metatype lets you call static members in the same way.

Parameters

name (str) – The name of the piece of metadata to get.

Returns

Mixed.

Raises

.Error

__getitem__(arg)[source]

Overload [] to pull out band elements from an image.

The following arguments types are accepted:

  • int:

    green = rgb_image[1]
    

    Will make a new one-band image from band 1 (the middle band).

  • slice:

    last_two = rgb_image[1:]
    last_band = rgb_image[-1]
    middle_few = multiband[1:-2]
    reversed  = multiband[::-1]
    every_other = multiband[::2]
    other_every_other = multiband[1::2]
    
  • list of int:

    # list of integers
    desired_bands = [1, 2, 2, -1]
    four_band = multiband[desired_bands]
    
  • list of bool:

    wanted_bands = [True, False, True, True, False]
    three_band = five_band[wanted_bands]
    

In the case of integer or slice arguments, the semantics of slicing exactly match those of slicing range(self.bands).

In the case of list arguments, the semantics match those of numpy’s extended slicing syntax. Thus, lists of booleans must have as many elements as there are bands in the image.

__call__(x, y)[source]

Fetch a pixel value.

Parameters
  • x (int) – The x coordinate to fetch.

  • y (int) – The y coordinate to fetch.

Returns

Pixel as an array of floating point numbers.

Raises

.Error

__or__(other)[source]

Return self|value.

__ror__(other)[source]

Return value|self.

__gt__(other)[source]

Return self>value.

__ge__(other)[source]

Return self>=value.

__lt__(other)[source]

Return self<value.

__le__(other)[source]

Return self<=value.

__eq__(other)[source]

Return self==value.

__ne__(other)[source]

Return self!=value.

floor()[source]

Return the largest integral value not greater than the argument.

ceil()[source]

Return the smallest integral value not less than the argument.

rint()[source]

Return the nearest integral value.

bandand()[source]

AND image bands together.

bandor()[source]

OR image bands together.

bandeor()[source]

EOR image bands together.

bandsplit()[source]

Split an n-band image into n separate images.

bandjoin(other)[source]

Append a set of images or constants bandwise.

get_n_pages()[source]

Get the number of pages in an image file, or 1.

This is the number of pages in the file the image was loaded from, not the number of pages in the image.

To get the number of pages in an image, divide the image height by the page height.

get_page_height()[source]

Get the page height in a many-page image, or height.

pagesplit()[source]

Split an N-page image into a list of N separate images.

pagejoin(other)[source]

Join a set of pages vertically to make a multipage image.

Also sets the page-height property on the result.

composite(other, mode, **kwargs)[source]

Composite a set of images with a set of modes.

bandrank(other, **kwargs)[source]

Band-wise rank filter a set of images.

maxpos()[source]

Return the coordinates of the image maximum.

minpos()[source]

Return the coordinates of the image minimum.

real()[source]

Return the real part of a complex image.

imag()[source]

Return the imaginary part of a complex image.

polar()[source]

Return an image converted to polar coordinates.

rect()[source]

Return an image converted to rectangular coordinates.

conj()[source]

Return the complex conjugate of an image.

sin()[source]

Return the sine of an image in degrees.

cos()[source]

Return the cosine of an image in degrees.

tan()[source]

Return the tangent of an image in degrees.

asin()[source]

Return the inverse sine of an image in degrees.

acos()[source]

Return the inverse cosine of an image in degrees.

atan()[source]

Return the inverse tangent of an image in degrees.

sinh()[source]

Return the hyperbolic sine of an image in radians.

cosh()[source]

Return the hyperbolic cosine of an image in radians.

tanh()[source]

Return the hyperbolic tangent of an image in radians.

asinh()[source]

Return the inverse hyperbolic sine of an image in radians.

acosh()[source]

Return the inverse hyperbolic cosine of an image in radians.

atanh()[source]

Return the inverse hyperbolic tangent of an image in radians.

log()[source]

Return the natural log of an image.

log10()[source]

Return the log base 10 of an image.

exp()[source]

Return e ** pixel.

exp10()[source]

Return 10 ** pixel.

erode(mask)[source]

Erode with a structuring element.

dilate(mask)[source]

Dilate with a structuring element.

median(size)[source]

size x size median filter.

fliphor()[source]

Flip horizontally.

flipver()[source]

Flip vertically.

rot90()[source]

Rotate 90 degrees clockwise.

rot180()[source]

Rotate 180 degrees.

rot270()[source]

Rotate 270 degrees clockwise.

hasalpha()[source]

True if the image has an alpha channel.

addalpha()[source]

Add an alpha channel.

ifthenelse(in1, in2, **kwargs)[source]

Ifthenelse an image.

Example

out = cond.ifthenelse(in1, in2, blend=bool)

Returns

Output image

Return type

out (Image)

Parameters
  • cond (Image) – Condition input image

  • in1 (Image) – Source for TRUE pixels

  • in2 (Image) – Source for FALSE pixels

Keyword Arguments

blend (bool) – Blend smoothly between then and else parts

Raises

.Error

scaleimage(**kwargs)[source]

Scale an image to 0 - 255.

This is the libvips scale operation, renamed to avoid a clash with the scale for convolution masks.

Keyword Arguments
  • exp (float) – Exponent for log scale.

  • log (bool) – Switch to turn on log scaling.

Returns

A new Image.

Raises

.Error

__hash__ = None

Attributes

scale

Scale an image to uchar.

class pyvips.Image
width

int, read-only: Image width in pixels.

height

int, read-only: Image height in pixels.

bands

int, read-only: Number of bands in image.

format

BandFormat, read-only: Image format.

interpretation

Interpretation, read-only: Suggested interpretation of image pixel values.

coding

Coding, read-only: Pixel coding.

filename

str, read-only: Filename image was loaded from, or None.

xoffset

int, read-only: Image X offset.

yoffset

int, read-only: Image Y offset.

xres

float, read-only: Image X resolution, in pixels / mm

yres

float, read-only: Image Y resolution, in pixels / mm.

scale

float, read-only: Image scale.

offset

float, read-only: Image offset.

Autogenerated methods

class pyvips.Image

Methods

CMC2LCh

Transform LCh to CMC.

CMYK2XYZ

Transform CMYK to XYZ.

HSV2sRGB

Transform HSV to sRGB.

LCh2CMC

Transform LCh to CMC.

LCh2Lab

Transform LCh to Lab.

Lab2LCh

Transform Lab to LCh.

Lab2LabQ

Transform float Lab to LabQ coding.

Lab2LabS

Transform float Lab to signed short.

Lab2XYZ

Transform CIELAB to XYZ.

LabQ2Lab

Unpack a LabQ image to float Lab.

LabQ2LabS

Unpack a LabQ image to short Lab.

LabQ2sRGB

Convert a LabQ image to sRGB.

LabS2Lab

Transform signed short Lab to float.

LabS2LabQ

Transform short Lab to LabQ coding.

XYZ2CMYK

Transform XYZ to CMYK.

XYZ2Lab

Transform XYZ to Lab.

XYZ2Yxy

Transform XYZ to Yxy.

XYZ2scRGB

Transform XYZ to scRGB.

Yxy2XYZ

Transform Yxy to XYZ.

abs

Absolute value of an image.

add

Add two images.

affine

Affine transform of an image.

analyzeload

Load an Analyze6 image.

arrayjoin

Join an array of images.

autorot

Autorotate image by exif tag.

avg

Find image average.

bandbool

Boolean operation across image bands.

bandfold

Fold up x axis into bands.

bandjoin_const

Append a constant band to an image.

bandmean

Band-wise average.

bandunfold

Unfold image bands into x axis.

black

Make a black image.

boolean

Boolean operation on two images.

boolean_const

Boolean operations against a constant.

buildlut

Build a look-up table.

byteswap

Byteswap an image.

cache

Cache an image.

canny

Canny edge detector.

case

Use pixel values to pick cases from an array of images.

cast

Cast an image.

colourspace

Convert to a new colourspace.

compass

Convolve with rotating mask.

complex

Perform a complex operation on an image.

complex2

Complex binary operations on two images.

complexform

Form a complex image from two real images.

complexget

Get a component from a complex image.

composite

Composite a set of images with a set of modes.

composite2

Blend a pair of images with a blend mode.

conv

Convolution operation.

conva

Approximate integer convolution.

convasep

Approximate separable integer convolution.

convf

Float convolution operation.

convi

Int convolution operation.

convsep

Seperable convolution operation.

copy

Copy an image.

countlines

Count lines in an image.

crop

Extract an area from an image.

csvload

Load csv.

csvload_source

Load csv.

csvsave

Save image to csv.

csvsave_target

Save image to csv.

dE00

Calculate dE00.

dE76

Calculate dE76.

dECMC

Calculate dECMC.

deviate

Find image standard deviation.

divide

Divide two images.

draw_circle

Draw a circle on an image.

draw_flood

Flood-fill an area.

draw_image

Paint an image into another image.

draw_line

Draw a line on an image.

draw_mask

Draw a mask on an image.

draw_rect

Paint a rectangle on an image.

draw_smudge

Blur a rectangle on an image.

dzsave

Save image to deepzoom file.

dzsave_buffer

Save image to dz buffer.

dzsave_target

Save image to deepzoom target.

embed

Embed an image in a larger image.

extract_area

Extract an area from an image.

extract_band

Extract band from an image.

eye

Make an image showing the eye's spatial response.

falsecolour

False-colour an image.

fastcor

Fast correlation.

fill_nearest

Fill image zeros with nearest non-zero pixel.

find_trim

Search an image for non-edge areas.

fitsload

Load a FITS image.

fitsload_source

Load FITS from a source.

fitssave

Save image to fits file.

flatten

Flatten alpha out of an image.

flip

Flip an image.

float2rad

Transform float RGB to Radiance coding.

fractsurf

Make a fractal surface.

freqmult

Frequency-domain filtering.

fwfft

Forward FFT.

gamma

Gamma an image.

gaussblur

Gaussian blur.

gaussmat

Make a gaussian image.

gaussnoise

Make a gaussnoise image.

getpoint

Read a point from an image.

gifload

Load GIF with libnsgif.

gifload_buffer

Load GIF with libnsgif.

gifload_source

Load gif from source.

gifsave

Save as gif.

gifsave_buffer

Save as gif.

gifsave_target

Save as gif.

globalbalance

Global balance an image mosaic.

gravity

Place an image within a larger image with a certain gravity.

grey

Make a grey ramp image.

grid

Grid an image.

heifload

Load a HEIF image.

heifload_buffer

Load a HEIF image.

heifload_source

Load a HEIF image.

heifsave

Save image in HEIF format.

heifsave_buffer

Save image in HEIF format.

heifsave_target

Save image in HEIF format.

hist_cum

Form cumulative histogram.

hist_entropy

Estimate image entropy.

hist_equal

Histogram equalisation.

hist_find

Find image histogram.

hist_find_indexed

Find indexed image histogram.

hist_find_ndim

Find n-dimensional image histogram.

hist_ismonotonic

Test for monotonicity.

hist_local

Local histogram equalisation.

hist_match

Match two histograms.

hist_norm

Normalise histogram.

hist_plot

Plot histogram.

hough_circle

Find hough circle transform.

hough_line

Find hough line transform.

icc_export

Output to device with ICC profile.

icc_import

Import from device with ICC profile.

icc_transform

Transform between devices with ICC profiles.

identity

Make a 1D image where pixel values are indexes.

insert

Insert image @sub into @main at @x, @y.

invert

Invert an image.

invertlut

Build an inverted look-up table.

invfft

Inverse FFT.

join

Join a pair of images.

jp2kload

Load JPEG2000 image.

jp2kload_buffer

Load JPEG2000 image.

jp2kload_source

Load JPEG2000 image.

jp2ksave

Save image in JPEG2000 format.

jp2ksave_buffer

Save image in JPEG2000 format.

jp2ksave_target

Save image in JPEG2000 format.

jpegload

Load jpeg from file.

jpegload_buffer

Load jpeg from buffer.

jpegload_source

Load image from jpeg source.

jpegsave

Save image to jpeg file.

jpegsave_buffer

Save image to jpeg buffer.

jpegsave_mime

Save image to jpeg mime.

jpegsave_target

Save image to jpeg target.

jxlload

Load JPEG-XL image.

jxlload_buffer

Load JPEG-XL image.

jxlload_source

Load JPEG-XL image.

jxlsave

Save image in JPEG-XL format.

jxlsave_buffer

Save image in JPEG-XL format.

jxlsave_target

Save image in JPEG-XL format.

labelregions

Label regions in an image.

linear

Calculate (a * in + b).

linecache

Cache an image as a set of lines.

logmat

Make a Laplacian of Gaussian image.

magickload

Load file with ImageMagick.

magickload_buffer

Load buffer with ImageMagick.

magicksave

Save file with ImageMagick.

magicksave_buffer

Save image to magick buffer.

mapim

Resample with a map image.

maplut

Map an image though a lut.

mask_butterworth

Make a butterworth filter.

mask_butterworth_band

Make a butterworth_band filter.

mask_butterworth_ring

Make a butterworth ring filter.

mask_fractal

Make fractal filter.

mask_gaussian

Make a gaussian filter.

mask_gaussian_band

Make a gaussian filter.

mask_gaussian_ring

Make a gaussian ring filter.

mask_ideal

Make an ideal filter.

mask_ideal_band

Make an ideal band filter.

mask_ideal_ring

Make an ideal ring filter.

match

First-order match of two images.

math

Apply a math operation to an image.

math2

Binary math operations.

math2_const

Binary math operations with a constant.

matload

Load mat from file.

matrixinvert

Invert an matrix.

matrixload

Load matrix.

matrixload_source

Load matrix.

matrixprint

Print matrix.

matrixsave

Save image to matrix.

matrixsave_target

Save image to matrix.

max

Find image maximum.

measure

Measure a set of patches on a colour chart.

merge

Merge two images.

min

Find image minimum.

morph

Morphology operation.

mosaic

Mosaic two images.

mosaic1

First-order mosaic of two images.

msb

Pick most-significant byte from an image.

multiply

Multiply two images.

niftiload

Load NIfTI volume.

niftiload_source

Load NIfTI volumes.

niftisave

Save image to nifti file.

openexrload

Load an OpenEXR image.

openslideload

Load file with OpenSlide.

openslideload_source

Load source with OpenSlide.

pdfload

Load PDF from file.

pdfload_buffer

Load PDF from buffer.

pdfload_source

Load PDF from source.

percent

Find threshold for percent of pixels.

perlin

Make a perlin noise image.

phasecor

Calculate phase correlation.

pngload

Load png from file.

pngload_buffer

Load png from buffer.

pngload_source

Load png from source.

pngsave

Save image to file as PNG.

pngsave_buffer

Save image to buffer as PNG.

pngsave_target

Save image to target as PNG.

ppmload

Load ppm from file.

ppmload_source

Load ppm base class.

ppmsave

Save image to ppm file.

ppmsave_target

Save to ppm.

premultiply

Premultiply image alpha.

profile

Find image profiles.

profile_load

Load named ICC profile.

project

Find image projections.

quadratic

Resample an image with a quadratic transform.

rad2float

Unpack Radiance coding to float RGB.

radload

Load a Radiance image from a file.

radload_buffer

Load rad from buffer.

radload_source

Load rad from source.

radsave

Save image to Radiance file.

radsave_buffer

Save image to Radiance buffer.

radsave_target

Save image to Radiance target.

rank

Rank filter.

rawload

Load raw data from a file.

rawsave

Save image to raw file.

rawsave_fd

Write raw image to file descriptor.

recomb

Linear recombination with matrix.

reduce

Reduce an image.

reduceh

Shrink an image horizontally.

reducev

Shrink an image vertically.

relational

Relational operation on two images.

relational_const

Relational operations against a constant.

remainder

Remainder after integer division of two images.

remainder_const

Remainder after integer division of an image and a constant.

replicate

Replicate an image.

resize

Resize an image.

rot

Rotate an image.

rot45

Rotate an image.

rotate

Rotate an image by a number of degrees.

round

Perform a round function on an image.

sRGB2HSV

Transform sRGB to HSV.

sRGB2scRGB

Convert an sRGB image to scRGB.

scRGB2BW

Convert scRGB to BW.

scRGB2XYZ

Transform scRGB to XYZ.

scRGB2sRGB

Convert an scRGB image to sRGB.

sequential

Check sequential access.

sharpen

Unsharp masking for print.

shrink

Shrink an image.

shrinkh

Shrink an image horizontally.

shrinkv

Shrink an image vertically.

sign

Unit vector of pixel.

similarity

Similarity transform of an image.

sines

Make a 2D sine wave.

smartcrop

Extract an area from an image.

sobel

Sobel edge detector.

spcor

Spatial correlation.

spectrum

Make displayable power spectrum.

stats

Find many image stats.

stdif

Statistical difference.

subsample

Subsample an image.

subtract

Subtract two images.

sum

Sum an array of images.

svgload

Load SVG with rsvg.

svgload_buffer

Load SVG with rsvg.

svgload_source

Load svg from source.

switch

Find the index of the first non-zero pixel in tests.

system

Run an external command.

text

Make a text image.

thumbnail

Generate thumbnail from file.

thumbnail_buffer

Generate thumbnail from buffer.

thumbnail_image

Generate thumbnail from image.

thumbnail_source

Generate thumbnail from source.

tiffload

Load tiff from file.

tiffload_buffer

Load tiff from buffer.

tiffload_source

Load tiff from source.

tiffsave

Save image to tiff file.

tiffsave_buffer

Save image to tiff buffer.

tiffsave_target

Save image to tiff target.

tilecache

Cache an image as a set of tiles.

tonelut

Build a look-up table.

transpose3d

Transpose3d an image.

unpremultiply

Unpremultiply image alpha.

vipsload

Load vips from file.

vipsload_source

Load vips from source.

vipssave

Save image to file in vips format.

vipssave_target

Save image to target in vips format.

webpload

Load webp from file.

webpload_buffer

Load webp from buffer.

webpload_source

Load webp from source.

webpsave

Save image to webp file.

webpsave_buffer

Save image to webp buffer.

webpsave_target

Save image to webp target.

worley

Make a worley noise image.

wrap

Wrap image origin.

xyz

Make an image where pixel values are coordinates.

zone

Make a zone plate.

zoom

Zoom an image.

CMC2LCh()

Transform LCh to CMC.

Example:

out = in.CMC2LCh()

Return type

Image

Raises

Error

CMYK2XYZ()

Transform CMYK to XYZ.

Example:

out = in.CMYK2XYZ()

Return type

Image

Raises

Error

HSV2sRGB()

Transform HSV to sRGB.

Example:

out = in.HSV2sRGB()

Return type

Image

Raises

Error

LCh2CMC()

Transform LCh to CMC.

Example:

out = in.LCh2CMC()

Return type

Image

Raises

Error

LCh2Lab()

Transform LCh to Lab.

Example:

out = in.LCh2Lab()

Return type

Image

Raises

Error

Lab2LCh()

Transform Lab to LCh.

Example:

out = in.Lab2LCh()

Return type

Image

Raises

Error

Lab2LabQ()

Transform float Lab to LabQ coding.

Example:

out = in.Lab2LabQ()

Return type

Image

Raises

Error

Lab2LabS()

Transform float Lab to signed short.

Example:

out = in.Lab2LabS()

Return type

Image

Raises

Error

Lab2XYZ(temp=list[float])

Transform CIELAB to XYZ.

Example:

out = in.Lab2XYZ(temp=list[float])

Parameters

temp (list[float]) – Color temperature

Return type

Image

Raises

Error

LabQ2Lab()

Unpack a LabQ image to float Lab.

Example:

out = in.LabQ2Lab()

Return type

Image

Raises

Error

LabQ2LabS()

Unpack a LabQ image to short Lab.

Example:

out = in.LabQ2LabS()

Return type

Image

Raises

Error

LabQ2sRGB()

Convert a LabQ image to sRGB.

Example:

out = in.LabQ2sRGB()

Return type

Image

Raises

Error

LabS2Lab()

Transform signed short Lab to float.

Example:

out = in.LabS2Lab()

Return type

Image

Raises

Error

LabS2LabQ()

Transform short Lab to LabQ coding.

Example:

out = in.LabS2LabQ()

Return type

Image

Raises

Error

XYZ2CMYK()

Transform XYZ to CMYK.

Example:

out = in.XYZ2CMYK()

Return type

Image

Raises

Error

XYZ2Lab(temp=list[float])

Transform XYZ to Lab.

Example:

out = in.XYZ2Lab(temp=list[float])

Parameters

temp (list[float]) – Colour temperature

Return type

Image

Raises

Error

XYZ2Yxy()

Transform XYZ to Yxy.

Example:

out = in.XYZ2Yxy()

Return type

Image

Raises

Error

XYZ2scRGB()

Transform XYZ to scRGB.

Example:

out = in.XYZ2scRGB()

Return type

Image

Raises

Error

Yxy2XYZ()

Transform Yxy to XYZ.

Example:

out = in.Yxy2XYZ()

Return type

Image

Raises

Error

abs()

Absolute value of an image.

Example:

out = in.abs()

Return type

Image

Raises

Error

add(right)

Add two images.

Example:

out = left.add(right)

Parameters

right (Image) – Right-hand image argument

Return type

Image

Raises

Error

affine(matrix, interpolate=GObject, oarea=list[int], odx=float, ody=float, idx=float, idy=float, background=list[float], premultiplied=bool, extend=Union[str, Extend])

Affine transform of an image.

Example:

out = in.affine(matrix, interpolate=GObject, oarea=list[int], odx=float, ody=float, idx=float, idy=float, background=list[float], premultiplied=bool, extend=Union[str, Extend])

Parameters
  • matrix (list[float]) – Transformation matrix

  • interpolate (GObject) – Interpolate pixels with this

  • oarea (list[int]) – Area of output to generate

  • odx (float) – Horizontal output displacement

  • ody (float) – Vertical output displacement

  • idx (float) – Horizontal input displacement

  • idy (float) – Vertical input displacement

  • background (list[float]) – Background value

  • premultiplied (bool) – Images have premultiplied alpha

  • extend (Union[str, Extend]) – How to generate the extra pixels

Return type

Image

Raises

Error

static analyzeload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load an Analyze6 image.

Example:

out = pyvips.Image.analyzeload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static arrayjoin(in, across=int, shim=int, background=list[float], halign=Union[str, Align], valign=Union[str, Align], hspacing=int, vspacing=int)

Join an array of images.

Example:

out = pyvips.Image.arrayjoin(in, across=int, shim=int, background=list[float], halign=Union[str, Align], valign=Union[str, Align], hspacing=int, vspacing=int)

Parameters
  • in (list[Image]) – Array of input images

  • across (int) – Number of images across grid

  • shim (int) – Pixels between images

  • background (list[float]) – Colour for new pixels

  • halign (Union[str, Align]) – Align on the left, centre or right

  • valign (Union[str, Align]) – Align on the top, centre or bottom

  • hspacing (int) – Horizontal spacing between images

  • vspacing (int) – Vertical spacing between images

Return type

Image

Raises

Error

autorot(angle=bool, flip=bool)

Autorotate image by exif tag.

Example:

out = in.autorot()

Parameters
  • angle (bool) – enable output: Angle image was rotated by

  • flip (bool) – enable output: Whether the image was flipped or not

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

avg()

Find image average.

Example:

out = in.avg()

Return type

float

Raises

Error

bandbool(boolean)

Boolean operation across image bands.

Example:

out = in.bandbool(boolean)

Parameters

boolean (Union[str, OperationBoolean]) – Boolean to perform

Return type

Image

Raises

Error

bandfold(factor=int)

Fold up x axis into bands.

Example:

out = in.bandfold(factor=int)

Parameters

factor (int) – Fold by this factor

Return type

Image

Raises

Error

bandjoin_const(c)

Append a constant band to an image.

Example:

out = in.bandjoin_const(c)

Parameters

c (list[float]) – Array of constants to add

Return type

Image

Raises

Error

bandmean()

Band-wise average.

Example:

out = in.bandmean()

Return type

Image

Raises

Error

bandunfold(factor=int)

Unfold image bands into x axis.

Example:

out = in.bandunfold(factor=int)

Parameters

factor (int) – Unfold by this factor

Return type

Image

Raises

Error

static black(width, height, bands=int)

Make a black image.

Example:

out = pyvips.Image.black(width, height, bands=int)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • bands (int) – Number of bands in image

Return type

Image

Raises

Error

boolean(right, boolean)

Boolean operation on two images.

Example:

out = left.boolean(right, boolean)

Parameters
  • right (Image) – Right-hand image argument

  • boolean (Union[str, OperationBoolean]) – Boolean to perform

Return type

Image

Raises

Error

boolean_const(boolean, c)

Boolean operations against a constant.

Example:

out = in.boolean_const(boolean, c)

Parameters
  • boolean (Union[str, OperationBoolean]) – Boolean to perform

  • c (list[float]) – Array of constants

Return type

Image

Raises

Error

buildlut()

Build a look-up table.

Example:

out = in.buildlut()

Return type

Image

Raises

Error

byteswap()

Byteswap an image.

Example:

out = in.byteswap()

Return type

Image

Raises

Error

cache(max_tiles=int, tile_height=int, tile_width=int)

Cache an image.

Example:

out = in.cache(max_tiles=int, tile_height=int, tile_width=int)

Parameters
  • max_tiles (int) – Maximum number of tiles to cache

  • tile_height (int) – Tile height in pixels

  • tile_width (int) – Tile width in pixels

Return type

Image

Raises

Error

canny(sigma=float, precision=Union[str, Precision])

Canny edge detector.

Example:

out = in.canny(sigma=float, precision=Union[str, Precision])

Parameters
  • sigma (float) – Sigma of Gaussian

  • precision (Union[str, Precision]) – Convolve with this precision

Return type

Image

Raises

Error

case(cases)

Use pixel values to pick cases from an array of images.

Example:

out = index.case(cases)

Parameters

cases (list[Image]) – Array of case images

Return type

Image

Raises

Error

cast(format, shift=bool)

Cast an image.

Example:

out = in.cast(format, shift=bool)

Parameters
  • format (Union[str, BandFormat]) – Format to cast to

  • shift (bool) – Shift integer values up and down

Return type

Image

Raises

Error

colourspace(space, source_space=Union[str, Interpretation])

Convert to a new colorspace.

Example:

out = in.colourspace(space, source_space=Union[str, Interpretation])

Parameters
Return type

Image

Raises

Error

compass(mask, times=int, angle=Union[str, Angle45], combine=Union[str, Combine], precision=Union[str, Precision], layers=int, cluster=int)

Convolve with rotating mask.

Example:

out = in.compass(mask, times=int, angle=Union[str, Angle45], combine=Union[str, Combine], precision=Union[str, Precision], layers=int, cluster=int)

Parameters
  • mask (Image) – Input matrix image

  • times (int) – Rotate and convolve this many times

  • angle (Union[str, Angle45]) – Rotate mask by this much between convolutions

  • combine (Union[str, Combine]) – Combine convolution results like this

  • precision (Union[str, Precision]) – Convolve with this precision

  • layers (int) – Use this many layers in approximation

  • cluster (int) – Cluster lines closer than this in approximation

Return type

Image

Raises

Error

complex(cmplx)

Perform a complex operation on an image.

Example:

out = in.complex(cmplx)

Parameters

cmplx (Union[str, OperationComplex]) – Complex to perform

Return type

Image

Raises

Error

complex2(right, cmplx)

Complex binary operations on two images.

Example:

out = left.complex2(right, cmplx)

Parameters
  • right (Image) – Right-hand image argument

  • cmplx (Union[str, OperationComplex2]) – Binary complex operation to perform

Return type

Image

Raises

Error

complexform(right)

Form a complex image from two real images.

Example:

out = left.complexform(right)

Parameters

right (Image) – Right-hand image argument

Return type

Image

Raises

Error

complexget(get)

Get a component from a complex image.

Example:

out = in.complexget(get)

Parameters

get (Union[str, OperationComplexget]) – Complex to perform

Return type

Image

Raises

Error

static composite(in, mode, x=list[int], y=list[int], compositing_space=Union[str, Interpretation], premultiplied=bool)

Blend an array of images with an array of blend modes.

Example:

out = pyvips.Image.composite(in, mode, x=list[int], y=list[int], compositing_space=Union[str, Interpretation], premultiplied=bool)

Parameters
  • in (list[Image]) – Array of input images

  • mode (list[int]) – Array of VipsBlendMode to join with

  • x (list[int]) – Array of x coordinates to join at

  • y (list[int]) – Array of y coordinates to join at

  • compositing_space (Union[str, Interpretation]) – Composite images in this colour space

  • premultiplied (bool) – Images have premultiplied alpha

Return type

Image

Raises

Error

composite2(overlay, mode, x=int, y=int, compositing_space=Union[str, Interpretation], premultiplied=bool)

Blend a pair of images with a blend mode.

Example:

out = base.composite2(overlay, mode, x=int, y=int, compositing_space=Union[str, Interpretation], premultiplied=bool)

Parameters
  • overlay (Image) – Overlay image

  • mode (Union[str, BlendMode]) – VipsBlendMode to join with

  • x (int) – x position of overlay

  • y (int) – y position of overlay

  • compositing_space (Union[str, Interpretation]) – Composite images in this colour space

  • premultiplied (bool) – Images have premultiplied alpha

Return type

Image

Raises

Error

conv(mask, precision=Union[str, Precision], layers=int, cluster=int)

Convolution operation.

Example:

out = in.conv(mask, precision=Union[str, Precision], layers=int, cluster=int)

Parameters
  • mask (Image) – Input matrix image

  • precision (Union[str, Precision]) – Convolve with this precision

  • layers (int) – Use this many layers in approximation

  • cluster (int) – Cluster lines closer than this in approximation

Return type

Image

Raises

Error

conva(mask, layers=int, cluster=int)

Approximate integer convolution.

Example:

out = in.conva(mask, layers=int, cluster=int)

Parameters
  • mask (Image) – Input matrix image

  • layers (int) – Use this many layers in approximation

  • cluster (int) – Cluster lines closer than this in approximation

Return type

Image

Raises

Error

convasep(mask, layers=int)

Approximate separable integer convolution.

Example:

out = in.convasep(mask, layers=int)

Parameters
  • mask (Image) – Input matrix image

  • layers (int) – Use this many layers in approximation

Return type

Image

Raises

Error

convf(mask)

Float convolution operation.

Example:

out = in.convf(mask)

Parameters

mask (Image) – Input matrix image

Return type

Image

Raises

Error

convi(mask)

Int convolution operation.

Example:

out = in.convi(mask)

Parameters

mask (Image) – Input matrix image

Return type

Image

Raises

Error

convsep(mask, precision=Union[str, Precision], layers=int, cluster=int)

Seperable convolution operation.

Example:

out = in.convsep(mask, precision=Union[str, Precision], layers=int, cluster=int)

Parameters
  • mask (Image) – Input matrix image

  • precision (Union[str, Precision]) – Convolve with this precision

  • layers (int) – Use this many layers in approximation

  • cluster (int) – Cluster lines closer than this in approximation

Return type

Image

Raises

Error

copy(width=int, height=int, bands=int, format=Union[str, BandFormat], coding=Union[str, Coding], interpretation=Union[str, Interpretation], xres=float, yres=float, xoffset=int, yoffset=int)

Copy an image.

Example:

out = in.copy(width=int, height=int, bands=int, format=Union[str, BandFormat], coding=Union[str, Coding], interpretation=Union[str, Interpretation], xres=float, yres=float, xoffset=int, yoffset=int)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • bands (int) – Number of bands in image

  • format (Union[str, BandFormat]) – Pixel format in image

  • coding (Union[str, Coding]) – Pixel coding

  • interpretation (Union[str, Interpretation]) – Pixel interpretation

  • xres (float) – Horizontal resolution in pixels/mm

  • yres (float) – Vertical resolution in pixels/mm

  • xoffset (int) – Horizontal offset of origin

  • yoffset (int) – Vertical offset of origin

Return type

Image

Raises

Error

countlines(direction)

Count lines in an image.

Example:

nolines = in.countlines(direction)

Parameters

direction (Union[str, Direction]) – Countlines left-right or up-down

Return type

float

Raises

Error

crop(left, top, width, height)

Extract an area from an image.

Example:

out = input.crop(left, top, width, height)

Parameters
  • left (int) – Left edge of extract area

  • top (int) – Top edge of extract area

  • width (int) – Width of extract area

  • height (int) – Height of extract area

Return type

Image

Raises

Error

static csvload(filename, skip=int, lines=int, whitespace=str, separator=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load csv.

Example:

out = pyvips.Image.csvload(filename, skip=int, lines=int, whitespace=str, separator=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • skip (int) – Skip this many lines at the start of the file

  • lines (int) – Read this many lines from the file

  • whitespace (str) – Set of whitespace characters

  • separator (str) – Set of separator characters

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static csvload_source(source, skip=int, lines=int, whitespace=str, separator=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load csv.

Example:

out = pyvips.Image.csvload_source(source, skip=int, lines=int, whitespace=str, separator=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • skip (int) – Skip this many lines at the start of the file

  • lines (int) – Read this many lines from the file

  • whitespace (str) – Set of whitespace characters

  • separator (str) – Set of separator characters

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

csvsave(filename, separator=str, strip=bool, background=list[float], page_height=int)

Save image to csv.

Example:

in.csvsave(filename, separator=str, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • separator (str) – Separator characters

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

csvsave_target(target, separator=str, strip=bool, background=list[float], page_height=int)

Save image to csv.

Example:

in.csvsave_target(target, separator=str, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • separator (str) – Separator characters

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

dE00(right)

Calculate dE00.

Example:

out = left.dE00(right)

Parameters

right (Image) – Right-hand input image

Return type

Image

Raises

Error

dE76(right)

Calculate dE76.

Example:

out = left.dE76(right)

Parameters

right (Image) – Right-hand input image

Return type

Image

Raises

Error

dECMC(right)

Calculate dECMC.

Example:

out = left.dECMC(right)

Parameters

right (Image) – Right-hand input image

Return type

Image

Raises

Error

deviate()

Find image standard deviation.

Example:

out = in.deviate()

Return type

float

Raises

Error

divide(right)

Divide two images.

Example:

out = left.divide(right)

Parameters

right (Image) – Right-hand image argument

Return type

Image

Raises

Error

draw_circle(ink, cx, cy, radius, fill=bool)

Draw a circle on an image.

Example:

image = image.draw_circle(ink, cx, cy, radius, fill=bool)

Parameters
  • ink (list[float]) – Color for pixels

  • cx (int) – Centre of draw_circle

  • cy (int) – Centre of draw_circle

  • radius (int) – Radius in pixels

  • fill (bool) – Draw a solid object

Return type

Image

Raises

Error

draw_flood(ink, x, y, test=Image, equal=bool, left=bool, top=bool, width=bool, height=bool)

Flood-fill an area.

Example:

image = image.draw_flood(ink, x, y, test=Image, equal=bool)

Parameters
  • ink (list[float]) – Color for pixels

  • x (int) – DrawFlood start point

  • y (int) – DrawFlood start point

  • test (Image) – Test pixels in this image

  • equal (bool) – DrawFlood while equal to edge

  • left (bool) – enable output: Left edge of modified area

  • top (bool) – enable output: Top edge of modified area

  • width (bool) – enable output: Width of modified area

  • height (bool) – enable output: Height of modified area

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

draw_image(sub, x, y, mode=Union[str, CombineMode])

Paint an image into another image.

Example:

image = image.draw_image(sub, x, y, mode=Union[str, CombineMode])

Parameters
  • sub (Image) – Sub-image to insert into main image

  • x (int) – Draw image here

  • y (int) – Draw image here

  • mode (Union[str, CombineMode]) – Combining mode

Return type

Image

Raises

Error

draw_line(ink, x1, y1, x2, y2)

Draw a line on an image.

Example:

image = image.draw_line(ink, x1, y1, x2, y2)

Parameters
  • ink (list[float]) – Color for pixels

  • x1 (int) – Start of draw_line

  • y1 (int) – Start of draw_line

  • x2 (int) – End of draw_line

  • y2 (int) – End of draw_line

Return type

Image

Raises

Error

draw_mask(ink, mask, x, y)

Draw a mask on an image.

Example:

image = image.draw_mask(ink, mask, x, y)

Parameters
  • ink (list[float]) – Color for pixels

  • mask (Image) – Mask of pixels to draw

  • x (int) – Draw mask here

  • y (int) – Draw mask here

Return type

Image

Raises

Error

draw_rect(ink, left, top, width, height, fill=bool)

Paint a rectangle on an image.

Example:

image = image.draw_rect(ink, left, top, width, height, fill=bool)

Parameters
  • ink (list[float]) – Color for pixels

  • left (int) – Rect to fill

  • top (int) – Rect to fill

  • width (int) – Rect to fill

  • height (int) – Rect to fill

  • fill (bool) – Draw a solid object

Return type

Image

Raises

Error

draw_smudge(left, top, width, height)

Blur a rectangle on an image.

Example:

image = image.draw_smudge(left, top, width, height)

Parameters
  • left (int) – Rect to fill

  • top (int) – Rect to fill

  • width (int) – Rect to fill

  • height (int) – Rect to fill

Return type

Image

Raises

Error

dzsave(filename, basename=str, layout=Union[str, ForeignDzLayout], suffix=str, overlap=int, tile_size=int, centre=bool, depth=Union[str, ForeignDzDepth], angle=Union[str, Angle], container=Union[str, ForeignDzContainer], compression=int, region_shrink=Union[str, RegionShrink], skip_blanks=int, no_strip=bool, id=str, strip=bool, background=list[float], page_height=int)

Save image to deepzoom file.

Example:

in.dzsave(filename, basename=str, layout=Union[str, ForeignDzLayout], suffix=str, overlap=int, tile_size=int, centre=bool, depth=Union[str, ForeignDzDepth], angle=Union[str, Angle], container=Union[str, ForeignDzContainer], compression=int, region_shrink=Union[str, RegionShrink], skip_blanks=int, no_strip=bool, id=str, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • basename (str) – Base name to save to

  • layout (Union[str, ForeignDzLayout]) – Directory layout

  • suffix (str) – Filename suffix for tiles

  • overlap (int) – Tile overlap in pixels

  • tile_size (int) – Tile size in pixels

  • centre (bool) – Center image in tile

  • depth (Union[str, ForeignDzDepth]) – Pyramid depth

  • angle (Union[str, Angle]) – Rotate image during save

  • container (Union[str, ForeignDzContainer]) – Pyramid container type

  • compression (int) – ZIP deflate compression level

  • region_shrink (Union[str, RegionShrink]) – Method to shrink regions

  • skip_blanks (int) – Skip tiles which are nearly equal to the background

  • no_strip (bool) – Don’t strip tile metadata

  • id (str) – Resource ID

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

dzsave_buffer(basename=str, layout=Union[str, ForeignDzLayout], suffix=str, overlap=int, tile_size=int, centre=bool, depth=Union[str, ForeignDzDepth], angle=Union[str, Angle], container=Union[str, ForeignDzContainer], compression=int, region_shrink=Union[str, RegionShrink], skip_blanks=int, no_strip=bool, id=str, strip=bool, background=list[float], page_height=int)

Save image to dz buffer.

Example:

buffer = in.dzsave_buffer(basename=str, layout=Union[str, ForeignDzLayout], suffix=str, overlap=int, tile_size=int, centre=bool, depth=Union[str, ForeignDzDepth], angle=Union[str, Angle], container=Union[str, ForeignDzContainer], compression=int, region_shrink=Union[str, RegionShrink], skip_blanks=int, no_strip=bool, id=str, strip=bool, background=list[float], page_height=int)

Parameters
  • basename (str) – Base name to save to

  • layout (Union[str, ForeignDzLayout]) – Directory layout

  • suffix (str) – Filename suffix for tiles

  • overlap (int) – Tile overlap in pixels

  • tile_size (int) – Tile size in pixels

  • centre (bool) – Center image in tile

  • depth (Union[str, ForeignDzDepth]) – Pyramid depth

  • angle (Union[str, Angle]) – Rotate image during save

  • container (Union[str, ForeignDzContainer]) – Pyramid container type

  • compression (int) – ZIP deflate compression level

  • region_shrink (Union[str, RegionShrink]) – Method to shrink regions

  • skip_blanks (int) – Skip tiles which are nearly equal to the background

  • no_strip (bool) – Don’t strip tile metadata

  • id (str) – Resource ID

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

dzsave_target(target, basename=str, layout=Union[str, ForeignDzLayout], suffix=str, overlap=int, tile_size=int, centre=bool, depth=Union[str, ForeignDzDepth], angle=Union[str, Angle], container=Union[str, ForeignDzContainer], compression=int, region_shrink=Union[str, RegionShrink], skip_blanks=int, no_strip=bool, id=str, strip=bool, background=list[float], page_height=int)

Save image to deepzoom target.

Example:

in.dzsave_target(target, basename=str, layout=Union[str, ForeignDzLayout], suffix=str, overlap=int, tile_size=int, centre=bool, depth=Union[str, ForeignDzDepth], angle=Union[str, Angle], container=Union[str, ForeignDzContainer], compression=int, region_shrink=Union[str, RegionShrink], skip_blanks=int, no_strip=bool, id=str, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • basename (str) – Base name to save to

  • layout (Union[str, ForeignDzLayout]) – Directory layout

  • suffix (str) – Filename suffix for tiles

  • overlap (int) – Tile overlap in pixels

  • tile_size (int) – Tile size in pixels

  • centre (bool) – Center image in tile

  • depth (Union[str, ForeignDzDepth]) – Pyramid depth

  • angle (Union[str, Angle]) – Rotate image during save

  • container (Union[str, ForeignDzContainer]) – Pyramid container type

  • compression (int) – ZIP deflate compression level

  • region_shrink (Union[str, RegionShrink]) – Method to shrink regions

  • skip_blanks (int) – Skip tiles which are nearly equal to the background

  • no_strip (bool) – Don’t strip tile metadata

  • id (str) – Resource ID

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

embed(x, y, width, height, extend=Union[str, Extend], background=list[float])

Embed an image in a larger image.

Example:

out = in.embed(x, y, width, height, extend=Union[str, Extend], background=list[float])

Parameters
  • x (int) – Left edge of input in output

  • y (int) – Top edge of input in output

  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • extend (Union[str, Extend]) – How to generate the extra pixels

  • background (list[float]) – Color for background pixels

Return type

Image

Raises

Error

extract_area(left, top, width, height)

Extract an area from an image.

Example:

out = input.extract_area(left, top, width, height)

Parameters
  • left (int) – Left edge of extract area

  • top (int) – Top edge of extract area

  • width (int) – Width of extract area

  • height (int) – Height of extract area

Return type

Image

Raises

Error

extract_band(band, n=int)

Extract band from an image.

Example:

out = in.extract_band(band, n=int)

Parameters
  • band (int) – Band to extract

  • n (int) – Number of bands to extract

Return type

Image

Raises

Error

static eye(width, height, uchar=bool, factor=float)

Make an image showing the eye’s spatial response.

Example:

out = pyvips.Image.eye(width, height, uchar=bool, factor=float)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • uchar (bool) – Output an unsigned char image

  • factor (float) – Maximum spatial frequency

Return type

Image

Raises

Error

falsecolour()

False-color an image.

Example:

out = in.falsecolour()

Return type

Image

Raises

Error

fastcor(ref)

Fast correlation.

Example:

out = in.fastcor(ref)

Parameters

ref (Image) – Input reference image

Return type

Image

Raises

Error

fill_nearest(distance=bool)

Fill image zeros with nearest non-zero pixel.

Example:

out = in.fill_nearest()

Parameters

distance (bool) – enable output: Distance to nearest non-zero pixel

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

find_trim(threshold=float, background=list[float])

Search an image for non-edge areas.

Example:

left, top, width, height = in.find_trim(threshold=float, background=list[float])

Parameters
  • threshold (float) – Object threshold

  • background (list[float]) – Color for background pixels

Return type

list[int, int, int, int]

Raises

Error

static fitsload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load a FITS image.

Example:

out = pyvips.Image.fitsload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static fitsload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load FITS from a source.

Example:

out = pyvips.Image.fitsload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

fitssave(filename, strip=bool, background=list[float], page_height=int)

Save image to fits file.

Example:

in.fitssave(filename, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

flatten(background=list[float], max_alpha=float)

Flatten alpha out of an image.

Example:

out = in.flatten(background=list[float], max_alpha=float)

Parameters
  • background (list[float]) – Background value

  • max_alpha (float) – Maximum value of alpha channel

Return type

Image

Raises

Error

flip(direction)

Flip an image.

Example:

out = in.flip(direction)

Parameters

direction (Union[str, Direction]) – Direction to flip image

Return type

Image

Raises

Error

float2rad()

Transform float RGB to Radiance coding.

Example:

out = in.float2rad()

Return type

Image

Raises

Error

static fractsurf(width, height, fractal_dimension)

Make a fractal surface.

Example:

out = pyvips.Image.fractsurf(width, height, fractal_dimension)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • fractal_dimension (float) – Fractal dimension

Return type

Image

Raises

Error

freqmult(mask)

Frequency-domain filtering.

Example:

out = in.freqmult(mask)

Parameters

mask (Image) – Input mask image

Return type

Image

Raises

Error

fwfft()

Forward FFT.

Example:

out = in.fwfft()

Return type

Image

Raises

Error

gamma(exponent=float)

Gamma an image.

Example:

out = in.gamma(exponent=float)

Parameters

exponent (float) – Gamma factor

Return type

Image

Raises

Error

gaussblur(sigma, min_ampl=float, precision=Union[str, Precision])

Gaussian blur.

Example:

out = in.gaussblur(sigma, min_ampl=float, precision=Union[str, Precision])

Parameters
  • sigma (float) – Sigma of Gaussian

  • min_ampl (float) – Minimum amplitude of Gaussian

  • precision (Union[str, Precision]) – Convolve with this precision

Return type

Image

Raises

Error

static gaussmat(sigma, min_ampl, separable=bool, precision=Union[str, Precision])

Make a gaussian image.

Example:

out = pyvips.Image.gaussmat(sigma, min_ampl, separable=bool, precision=Union[str, Precision])

Parameters
  • sigma (float) – Sigma of Gaussian

  • min_ampl (float) – Minimum amplitude of Gaussian

  • separable (bool) – Generate separable Gaussian

  • precision (Union[str, Precision]) – Generate with this precision

Return type

Image

Raises

Error

static gaussnoise(width, height, sigma=float, mean=float, seed=int)

Make a gaussnoise image.

Example:

out = pyvips.Image.gaussnoise(width, height, sigma=float, mean=float, seed=int)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • sigma (float) – Standard deviation of pixels in generated image

  • mean (float) – Mean of pixels in generated image

  • seed (int) – Random number seed

Return type

Image

Raises

Error

getpoint(x, y)

Read a point from an image.

Example:

out_array = in.getpoint(x, y)

Parameters
  • x (int) – Point to read

  • y (int) – Point to read

Return type

list[float]

Raises

Error

static gifload(filename, n=int, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load GIF with libnsgif.

Example:

out = pyvips.Image.gifload(filename, n=int, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • n (int) – Load this many pages

  • page (int) – Load this page from the file

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static gifload_buffer(buffer, n=int, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load GIF with libnsgif.

Example:

out = pyvips.Image.gifload_buffer(buffer, n=int, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • n (int) – Load this many pages

  • page (int) – Load this page from the file

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static gifload_source(source, n=int, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load gif from source.

Example:

out = pyvips.Image.gifload_source(source, n=int, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • n (int) – Load this many pages

  • page (int) – Load this page from the file

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

gifsave(filename, dither=float, effort=int, bitdepth=int, interframe_maxerror=float, reoptimise=bool, interpalette_maxerror=float, strip=bool, background=list[float], page_height=int)

Save as gif.

Example:

in.gifsave(filename, dither=float, effort=int, bitdepth=int, interframe_maxerror=float, reoptimise=bool, interpalette_maxerror=float, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • dither (float) – Amount of dithering

  • effort (int) – Quantisation effort

  • bitdepth (int) – Number of bits per pixel

  • interframe_maxerror (float) – Maximum inter-frame error for transparency

  • reoptimise (bool) – Reoptimise colour palettes

  • interpalette_maxerror (float) – Maximum inter-palette error for palette reusage

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

gifsave_buffer(dither=float, effort=int, bitdepth=int, interframe_maxerror=float, reoptimise=bool, interpalette_maxerror=float, strip=bool, background=list[float], page_height=int)

Save as gif.

Example:

buffer = in.gifsave_buffer(dither=float, effort=int, bitdepth=int, interframe_maxerror=float, reoptimise=bool, interpalette_maxerror=float, strip=bool, background=list[float], page_height=int)

Parameters
  • dither (float) – Amount of dithering

  • effort (int) – Quantisation effort

  • bitdepth (int) – Number of bits per pixel

  • interframe_maxerror (float) – Maximum inter-frame error for transparency

  • reoptimise (bool) – Reoptimise colour palettes

  • interpalette_maxerror (float) – Maximum inter-palette error for palette reusage

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

gifsave_target(target, dither=float, effort=int, bitdepth=int, interframe_maxerror=float, reoptimise=bool, interpalette_maxerror=float, strip=bool, background=list[float], page_height=int)

Save as gif.

Example:

in.gifsave_target(target, dither=float, effort=int, bitdepth=int, interframe_maxerror=float, reoptimise=bool, interpalette_maxerror=float, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • dither (float) – Amount of dithering

  • effort (int) – Quantisation effort

  • bitdepth (int) – Number of bits per pixel

  • interframe_maxerror (float) – Maximum inter-frame error for transparency

  • reoptimise (bool) – Reoptimise colour palettes

  • interpalette_maxerror (float) – Maximum inter-palette error for palette reusage

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

globalbalance(gamma=float, int_output=bool)

Global balance an image mosaic.

Example:

out = in.globalbalance(gamma=float, int_output=bool)

Parameters
  • gamma (float) – Image gamma

  • int_output (bool) – Integer output

Return type

Image

Raises

Error

gravity(direction, width, height, extend=Union[str, Extend], background=list[float])

Place an image within a larger image with a certain gravity.

Example:

out = in.gravity(direction, width, height, extend=Union[str, Extend], background=list[float])

Parameters
  • direction (Union[str, CompassDirection]) – Direction to place image within width/height

  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • extend (Union[str, Extend]) – How to generate the extra pixels

  • background (list[float]) – Color for background pixels

Return type

Image

Raises

Error

static grey(width, height, uchar=bool)

Make a grey ramp image.

Example:

out = pyvips.Image.grey(width, height, uchar=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • uchar (bool) – Output an unsigned char image

Return type

Image

Raises

Error

grid(tile_height, across, down)

Grid an image.

Example:

out = in.grid(tile_height, across, down)

Parameters
  • tile_height (int) – Chop into tiles this high

  • across (int) – Number of tiles across

  • down (int) – Number of tiles down

Return type

Image

Raises

Error

static heifload(filename, page=int, n=int, thumbnail=bool, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load a HEIF image.

Example:

out = pyvips.Image.heifload(filename, page=int, n=int, thumbnail=bool, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • thumbnail (bool) – Fetch thumbnail image

  • unlimited (bool) – Remove all denial of service limits

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static heifload_buffer(buffer, page=int, n=int, thumbnail=bool, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load a HEIF image.

Example:

out = pyvips.Image.heifload_buffer(buffer, page=int, n=int, thumbnail=bool, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • thumbnail (bool) – Fetch thumbnail image

  • unlimited (bool) – Remove all denial of service limits

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static heifload_source(source, page=int, n=int, thumbnail=bool, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load a HEIF image.

Example:

out = pyvips.Image.heifload_source(source, page=int, n=int, thumbnail=bool, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • thumbnail (bool) – Fetch thumbnail image

  • unlimited (bool) – Remove all denial of service limits

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

heifsave(filename, Q=int, bitdepth=int, lossless=bool, compression=Union[str, ForeignHeifCompression], effort=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Save image in HEIF format.

Example:

in.heifsave(filename, Q=int, bitdepth=int, lossless=bool, compression=Union[str, ForeignHeifCompression], effort=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • Q (int) – Q factor

  • bitdepth (int) – Number of bits per pixel

  • lossless (bool) – Enable lossless compression

  • compression (Union[str, ForeignHeifCompression]) – Compression format

  • effort (int) – CPU effort

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

heifsave_buffer(Q=int, bitdepth=int, lossless=bool, compression=Union[str, ForeignHeifCompression], effort=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Save image in HEIF format.

Example:

buffer = in.heifsave_buffer(Q=int, bitdepth=int, lossless=bool, compression=Union[str, ForeignHeifCompression], effort=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Parameters
  • Q (int) – Q factor

  • bitdepth (int) – Number of bits per pixel

  • lossless (bool) – Enable lossless compression

  • compression (Union[str, ForeignHeifCompression]) – Compression format

  • effort (int) – CPU effort

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

heifsave_target(target, Q=int, bitdepth=int, lossless=bool, compression=Union[str, ForeignHeifCompression], effort=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Save image in HEIF format.

Example:

in.heifsave_target(target, Q=int, bitdepth=int, lossless=bool, compression=Union[str, ForeignHeifCompression], effort=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • Q (int) – Q factor

  • bitdepth (int) – Number of bits per pixel

  • lossless (bool) – Enable lossless compression

  • compression (Union[str, ForeignHeifCompression]) – Compression format

  • effort (int) – CPU effort

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

hist_cum()

Form cumulative histogram.

Example:

out = in.hist_cum()

Return type

Image

Raises

Error

hist_entropy()

Estimate image entropy.

Example:

out = in.hist_entropy()

Return type

float

Raises

Error

hist_equal(band=int)

Histogram equalisation.

Example:

out = in.hist_equal(band=int)

Parameters

band (int) – Equalise with this band

Return type

Image

Raises

Error

hist_find(band=int)

Find image histogram.

Example:

out = in.hist_find(band=int)

Parameters

band (int) – Find histogram of band

Return type

Image

Raises

Error

hist_find_indexed(index, combine=Union[str, Combine])

Find indexed image histogram.

Example:

out = in.hist_find_indexed(index, combine=Union[str, Combine])

Parameters
  • index (Image) – Index image

  • combine (Union[str, Combine]) – Combine bins like this

Return type

Image

Raises

Error

hist_find_ndim(bins=int)

Find n-dimensional image histogram.

Example:

out = in.hist_find_ndim(bins=int)

Parameters

bins (int) – Number of bins in each dimension

Return type

Image

Raises

Error

hist_ismonotonic()

Test for monotonicity.

Example:

monotonic = in.hist_ismonotonic()

Return type

bool

Raises

Error

hist_local(width, height, max_slope=int)

Local histogram equalisation.

Example:

out = in.hist_local(width, height, max_slope=int)

Parameters
  • width (int) – Window width in pixels

  • height (int) – Window height in pixels

  • max_slope (int) – Maximum slope (CLAHE)

Return type

Image

Raises

Error

hist_match(ref)

Match two histograms.

Example:

out = in.hist_match(ref)

Parameters

ref (Image) – Reference histogram

Return type

Image

Raises

Error

hist_norm()

Normalise histogram.

Example:

out = in.hist_norm()

Return type

Image

Raises

Error

hist_plot()

Plot histogram.

Example:

out = in.hist_plot()

Return type

Image

Raises

Error

hough_circle(scale=int, min_radius=int, max_radius=int)

Find hough circle transform.

Example:

out = in.hough_circle(scale=int, min_radius=int, max_radius=int)

Parameters
  • scale (int) – Scale down dimensions by this factor

  • min_radius (int) – Smallest radius to search for

  • max_radius (int) – Largest radius to search for

Return type

Image

Raises

Error

hough_line(width=int, height=int)

Find hough line transform.

Example:

out = in.hough_line(width=int, height=int)

Parameters
  • width (int) – Horizontal size of parameter space

  • height (int) – Vertical size of parameter space

Return type

Image

Raises

Error

icc_export(pcs=Union[str, PCS], intent=Union[str, Intent], black_point_compensation=bool, output_profile=str, depth=int)

Output to device with ICC profile.

Example:

out = in.icc_export(pcs=Union[str, PCS], intent=Union[str, Intent], black_point_compensation=bool, output_profile=str, depth=int)

Parameters
  • pcs (Union[str, PCS]) – Set Profile Connection Space

  • intent (Union[str, Intent]) – Rendering intent

  • black_point_compensation (bool) – Enable black point compensation

  • output_profile (str) – Filename to load output profile from

  • depth (int) – Output device space depth in bits

Return type

Image

Raises

Error

icc_import(pcs=Union[str, PCS], intent=Union[str, Intent], black_point_compensation=bool, embedded=bool, input_profile=str)

Import from device with ICC profile.

Example:

out = in.icc_import(pcs=Union[str, PCS], intent=Union[str, Intent], black_point_compensation=bool, embedded=bool, input_profile=str)

Parameters
  • pcs (Union[str, PCS]) – Set Profile Connection Space

  • intent (Union[str, Intent]) – Rendering intent

  • black_point_compensation (bool) – Enable black point compensation

  • embedded (bool) – Use embedded input profile, if available

  • input_profile (str) – Filename to load input profile from

Return type

Image

Raises

Error

icc_transform(output_profile, pcs=Union[str, PCS], intent=Union[str, Intent], black_point_compensation=bool, embedded=bool, input_profile=str, depth=int)

Transform between devices with ICC profiles.

Example:

out = in.icc_transform(output_profile, pcs=Union[str, PCS], intent=Union[str, Intent], black_point_compensation=bool, embedded=bool, input_profile=str, depth=int)

Parameters
  • output_profile (str) – Filename to load output profile from

  • pcs (Union[str, PCS]) – Set Profile Connection Space

  • intent (Union[str, Intent]) – Rendering intent

  • black_point_compensation (bool) – Enable black point compensation

  • embedded (bool) – Use embedded input profile, if available

  • input_profile (str) – Filename to load input profile from

  • depth (int) – Output device space depth in bits

Return type

Image

Raises

Error

static identity(bands=int, ushort=bool, size=int)

Make a 1D image where pixel values are indexes.

Example:

out = pyvips.Image.identity(bands=int, ushort=bool, size=int)

Parameters
  • bands (int) – Number of bands in LUT

  • ushort (bool) – Create a 16-bit LUT

  • size (int) – Size of 16-bit LUT

Return type

Image

Raises

Error

insert(sub, x, y, expand=bool, background=list[float])

Insert image @sub into @main at @x, @y.

Example:

out = main.insert(sub, x, y, expand=bool, background=list[float])

Parameters
  • sub (Image) – Sub-image to insert into main image

  • x (int) – Left edge of sub in main

  • y (int) – Top edge of sub in main

  • expand (bool) – Expand output to hold all of both inputs

  • background (list[float]) – Color for new pixels

Return type

Image

Raises

Error

invert()

Invert an image.

Example:

out = in.invert()

Return type

Image

Raises

Error

invertlut(size=int)

Build an inverted look-up table.

Example:

out = in.invertlut(size=int)

Parameters

size (int) – LUT size to generate

Return type

Image

Raises

Error

invfft(real=bool)

Inverse FFT.

Example:

out = in.invfft(real=bool)

Parameters

real (bool) – Output only the real part of the transform

Return type

Image

Raises

Error

join(in2, direction, expand=bool, shim=int, background=list[float], align=Union[str, Align])

Join a pair of images.

Example:

out = in1.join(in2, direction, expand=bool, shim=int, background=list[float], align=Union[str, Align])

Parameters
  • in2 (Image) – Second input image

  • direction (Union[str, Direction]) – Join left-right or up-down

  • expand (bool) – Expand output to hold all of both inputs

  • shim (int) – Pixels between images

  • background (list[float]) – Colour for new pixels

  • align (Union[str, Align]) – Align on the low, centre or high coordinate edge

Return type

Image

Raises

Error

static jp2kload(filename, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load JPEG2000 image.

Example:

out = pyvips.Image.jp2kload(filename, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • page (int) – Load this page from the image

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static jp2kload_buffer(buffer, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load JPEG2000 image.

Example:

out = pyvips.Image.jp2kload_buffer(buffer, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • page (int) – Load this page from the image

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static jp2kload_source(source, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load JPEG2000 image.

Example:

out = pyvips.Image.jp2kload_source(source, page=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • page (int) – Load this page from the image

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

jp2ksave(filename, tile_width=int, tile_height=int, lossless=bool, Q=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Save image in JPEG2000 format.

Example:

in.jp2ksave(filename, tile_width=int, tile_height=int, lossless=bool, Q=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to load from

  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • lossless (bool) – Enable lossless compression

  • Q (int) – Q factor

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

jp2ksave_buffer(tile_width=int, tile_height=int, lossless=bool, Q=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Save image in JPEG2000 format.

Example:

buffer = in.jp2ksave_buffer(tile_width=int, tile_height=int, lossless=bool, Q=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Parameters
  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • lossless (bool) – Enable lossless compression

  • Q (int) – Q factor

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

jp2ksave_target(target, tile_width=int, tile_height=int, lossless=bool, Q=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Save image in JPEG2000 format.

Example:

in.jp2ksave_target(target, tile_width=int, tile_height=int, lossless=bool, Q=int, subsample_mode=Union[str, ForeignSubsample], strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • lossless (bool) – Enable lossless compression

  • Q (int) – Q factor

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

static jpegload(filename, shrink=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load jpeg from file.

Example:

out = pyvips.Image.jpegload(filename, shrink=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • shrink (int) – Shrink factor on load

  • autorotate (bool) – Rotate image using exif orientation

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static jpegload_buffer(buffer, shrink=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load jpeg from buffer.

Example:

out = pyvips.Image.jpegload_buffer(buffer, shrink=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • shrink (int) – Shrink factor on load

  • autorotate (bool) – Rotate image using exif orientation

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static jpegload_source(source, shrink=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load image from jpeg source.

Example:

out = pyvips.Image.jpegload_source(source, shrink=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • shrink (int) – Shrink factor on load

  • autorotate (bool) – Rotate image using exif orientation

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

jpegsave(filename, Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Save image to jpeg file.

Example:

in.jpegsave(filename, Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • Q (int) – Q factor

  • profile (str) – ICC profile to embed

  • optimize_coding (bool) – Compute optimal Huffman coding tables

  • interlace (bool) – Generate an interlaced (progressive) jpeg

  • trellis_quant (bool) – Apply trellis quantisation to each 8x8 block

  • overshoot_deringing (bool) – Apply overshooting to samples with extreme values

  • optimize_scans (bool) – Split spectrum of DCT coefficients into separate scans

  • quant_table (int) – Use predefined quantization table with given index

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • restart_interval (int) – Add restart markers every specified number of mcu

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

jpegsave_buffer(Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Save image to jpeg buffer.

Example:

buffer = in.jpegsave_buffer(Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Parameters
  • Q (int) – Q factor

  • profile (str) – ICC profile to embed

  • optimize_coding (bool) – Compute optimal Huffman coding tables

  • interlace (bool) – Generate an interlaced (progressive) jpeg

  • trellis_quant (bool) – Apply trellis quantisation to each 8x8 block

  • overshoot_deringing (bool) – Apply overshooting to samples with extreme values

  • optimize_scans (bool) – Split spectrum of DCT coefficients into separate scans

  • quant_table (int) – Use predefined quantization table with given index

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • restart_interval (int) – Add restart markers every specified number of mcu

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

jpegsave_mime(Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Save image to jpeg mime.

Example:

in.jpegsave_mime(Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Parameters
  • Q (int) – Q factor

  • profile (str) – ICC profile to embed

  • optimize_coding (bool) – Compute optimal Huffman coding tables

  • interlace (bool) – Generate an interlaced (progressive) jpeg

  • trellis_quant (bool) – Apply trellis quantisation to each 8x8 block

  • overshoot_deringing (bool) – Apply overshooting to samples with extreme values

  • optimize_scans (bool) – Split spectrum of DCT coefficients into separate scans

  • quant_table (int) – Use predefined quantization table with given index

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • restart_interval (int) – Add restart markers every specified number of mcu

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

jpegsave_target(target, Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Save image to jpeg target.

Example:

in.jpegsave_target(target, Q=int, profile=str, optimize_coding=bool, interlace=bool, trellis_quant=bool, overshoot_deringing=bool, optimize_scans=bool, quant_table=int, subsample_mode=Union[str, ForeignSubsample], restart_interval=int, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • Q (int) – Q factor

  • profile (str) – ICC profile to embed

  • optimize_coding (bool) – Compute optimal Huffman coding tables

  • interlace (bool) – Generate an interlaced (progressive) jpeg

  • trellis_quant (bool) – Apply trellis quantisation to each 8x8 block

  • overshoot_deringing (bool) – Apply overshooting to samples with extreme values

  • optimize_scans (bool) – Split spectrum of DCT coefficients into separate scans

  • quant_table (int) – Use predefined quantization table with given index

  • subsample_mode (Union[str, ForeignSubsample]) – Select chroma subsample operation mode

  • restart_interval (int) – Add restart markers every specified number of mcu

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

static jxlload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load JPEG-XL image.

Example:

out = pyvips.Image.jxlload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static jxlload_buffer(buffer, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load JPEG-XL image.

Example:

out = pyvips.Image.jxlload_buffer(buffer, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static jxlload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load JPEG-XL image.

Example:

out = pyvips.Image.jxlload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

jxlsave(filename, tier=int, distance=float, effort=int, lossless=bool, Q=int, strip=bool, background=list[float], page_height=int)

Save image in JPEG-XL format.

Example:

in.jxlsave(filename, tier=int, distance=float, effort=int, lossless=bool, Q=int, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to load from

  • tier (int) – Decode speed tier

  • distance (float) – Target butteraugli distance

  • effort (int) – Encoding effort

  • lossless (bool) – Enable lossless compression

  • Q (int) – Quality factor

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

jxlsave_buffer(tier=int, distance=float, effort=int, lossless=bool, Q=int, strip=bool, background=list[float], page_height=int)

Save image in JPEG-XL format.

Example:

buffer = in.jxlsave_buffer(tier=int, distance=float, effort=int, lossless=bool, Q=int, strip=bool, background=list[float], page_height=int)

Parameters
  • tier (int) – Decode speed tier

  • distance (float) – Target butteraugli distance

  • effort (int) – Encoding effort

  • lossless (bool) – Enable lossless compression

  • Q (int) – Quality factor

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

jxlsave_target(target, tier=int, distance=float, effort=int, lossless=bool, Q=int, strip=bool, background=list[float], page_height=int)

Save image in JPEG-XL format.

Example:

in.jxlsave_target(target, tier=int, distance=float, effort=int, lossless=bool, Q=int, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • tier (int) – Decode speed tier

  • distance (float) – Target butteraugli distance

  • effort (int) – Encoding effort

  • lossless (bool) – Enable lossless compression

  • Q (int) – Quality factor

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

labelregions(segments=bool)

Label regions in an image.

Example:

mask = in.labelregions()

Parameters

segments (bool) – enable output: Number of discrete contiguous regions

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

linear(a, b, uchar=bool)

Calculate (a * in + b).

Example:

out = in.linear(a, b, uchar=bool)

Parameters
  • a (list[float]) – Multiply by this

  • b (list[float]) – Add this

  • uchar (bool) – Output should be uchar

Return type

Image

Raises

Error

linecache(tile_height=int, access=Union[str, Access], threaded=bool, persistent=bool)

Cache an image as a set of lines.

Example:

out = in.linecache(tile_height=int, access=Union[str, Access], threaded=bool, persistent=bool)

Parameters
  • tile_height (int) – Tile height in pixels

  • access (Union[str, Access]) – Expected access pattern

  • threaded (bool) – Allow threaded access

  • persistent (bool) – Keep cache between evaluations

Return type

Image

Raises

Error

static logmat(sigma, min_ampl, separable=bool, precision=Union[str, Precision])

Make a Laplacian of Gaussian image.

Example:

out = pyvips.Image.logmat(sigma, min_ampl, separable=bool, precision=Union[str, Precision])

Parameters
  • sigma (float) – Radius of Gaussian

  • min_ampl (float) – Minimum amplitude of Gaussian

  • separable (bool) – Generate separable Gaussian

  • precision (Union[str, Precision]) – Generate with this precision

Return type

Image

Raises

Error

static magickload(filename, density=str, page=int, n=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load file with ImageMagick.

Example:

out = pyvips.Image.magickload(filename, density=str, page=int, n=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • density (str) – Canvas resolution for rendering vector formats like SVG

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static magickload_buffer(buffer, density=str, page=int, n=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load buffer with ImageMagick.

Example:

out = pyvips.Image.magickload_buffer(buffer, density=str, page=int, n=int, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • density (str) – Canvas resolution for rendering vector formats like SVG

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

magicksave(filename, format=str, quality=int, optimize_gif_frames=bool, optimize_gif_transparency=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Save file with ImageMagick.

Example:

in.magicksave(filename, format=str, quality=int, optimize_gif_frames=bool, optimize_gif_transparency=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • format (str) – Format to save in

  • quality (int) – Quality to use

  • optimize_gif_frames (bool) – Apply GIF frames optimization

  • optimize_gif_transparency (bool) – Apply GIF transparency optimization

  • bitdepth (int) – Number of bits per pixel

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

magicksave_buffer(format=str, quality=int, optimize_gif_frames=bool, optimize_gif_transparency=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Save image to magick buffer.

Example:

buffer = in.magicksave_buffer(format=str, quality=int, optimize_gif_frames=bool, optimize_gif_transparency=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Parameters
  • format (str) – Format to save in

  • quality (int) – Quality to use

  • optimize_gif_frames (bool) – Apply GIF frames optimization

  • optimize_gif_transparency (bool) – Apply GIF transparency optimization

  • bitdepth (int) – Number of bits per pixel

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

mapim(index, interpolate=GObject, background=list[float], premultiplied=bool, extend=Union[str, Extend])

Resample with a map image.

Example:

out = in.mapim(index, interpolate=GObject, background=list[float], premultiplied=bool, extend=Union[str, Extend])

Parameters
  • index (Image) – Index pixels with this

  • interpolate (GObject) – Interpolate pixels with this

  • background (list[float]) – Background value

  • premultiplied (bool) – Images have premultiplied alpha

  • extend (Union[str, Extend]) – How to generate the extra pixels

Return type

Image

Raises

Error

maplut(lut, band=int)

Map an image though a lut.

Example:

out = in.maplut(lut, band=int)

Parameters
  • lut (Image) – Look-up table image

  • band (int) – Apply one-band lut to this band of in

Return type

Image

Raises

Error

static mask_butterworth(width, height, order, frequency_cutoff, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make a butterworth filter.

Example:

out = pyvips.Image.mask_butterworth(width, height, order, frequency_cutoff, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • order (float) – Filter order

  • frequency_cutoff (float) – Frequency cutoff

  • amplitude_cutoff (float) – Amplitude cutoff

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_butterworth_band(width, height, order, frequency_cutoff_x, frequency_cutoff_y, radius, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make a butterworth_band filter.

Example:

out = pyvips.Image.mask_butterworth_band(width, height, order, frequency_cutoff_x, frequency_cutoff_y, radius, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • order (float) – Filter order

  • frequency_cutoff_x (float) – Frequency cutoff x

  • frequency_cutoff_y (float) – Frequency cutoff y

  • radius (float) – Radius of circle

  • amplitude_cutoff (float) – Amplitude cutoff

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_butterworth_ring(width, height, order, frequency_cutoff, amplitude_cutoff, ringwidth, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make a butterworth ring filter.

Example:

out = pyvips.Image.mask_butterworth_ring(width, height, order, frequency_cutoff, amplitude_cutoff, ringwidth, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • order (float) – Filter order

  • frequency_cutoff (float) – Frequency cutoff

  • amplitude_cutoff (float) – Amplitude cutoff

  • ringwidth (float) – Ringwidth

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_fractal(width, height, fractal_dimension, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make fractal filter.

Example:

out = pyvips.Image.mask_fractal(width, height, fractal_dimension, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • fractal_dimension (float) – Fractal dimension

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_gaussian(width, height, frequency_cutoff, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make a gaussian filter.

Example:

out = pyvips.Image.mask_gaussian(width, height, frequency_cutoff, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • frequency_cutoff (float) – Frequency cutoff

  • amplitude_cutoff (float) – Amplitude cutoff

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_gaussian_band(width, height, frequency_cutoff_x, frequency_cutoff_y, radius, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make a gaussian filter.

Example:

out = pyvips.Image.mask_gaussian_band(width, height, frequency_cutoff_x, frequency_cutoff_y, radius, amplitude_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • frequency_cutoff_x (float) – Frequency cutoff x

  • frequency_cutoff_y (float) – Frequency cutoff y

  • radius (float) – Radius of circle

  • amplitude_cutoff (float) – Amplitude cutoff

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_gaussian_ring(width, height, frequency_cutoff, amplitude_cutoff, ringwidth, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make a gaussian ring filter.

Example:

out = pyvips.Image.mask_gaussian_ring(width, height, frequency_cutoff, amplitude_cutoff, ringwidth, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • frequency_cutoff (float) – Frequency cutoff

  • amplitude_cutoff (float) – Amplitude cutoff

  • ringwidth (float) – Ringwidth

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_ideal(width, height, frequency_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make an ideal filter.

Example:

out = pyvips.Image.mask_ideal(width, height, frequency_cutoff, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • frequency_cutoff (float) – Frequency cutoff

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_ideal_band(width, height, frequency_cutoff_x, frequency_cutoff_y, radius, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make an ideal band filter.

Example:

out = pyvips.Image.mask_ideal_band(width, height, frequency_cutoff_x, frequency_cutoff_y, radius, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • frequency_cutoff_x (float) – Frequency cutoff x

  • frequency_cutoff_y (float) – Frequency cutoff y

  • radius (float) – Radius of circle

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

static mask_ideal_ring(width, height, frequency_cutoff, ringwidth, uchar=bool, nodc=bool, reject=bool, optical=bool)

Make an ideal ring filter.

Example:

out = pyvips.Image.mask_ideal_ring(width, height, frequency_cutoff, ringwidth, uchar=bool, nodc=bool, reject=bool, optical=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • frequency_cutoff (float) – Frequency cutoff

  • ringwidth (float) – Ringwidth

  • uchar (bool) – Output an unsigned char image

  • nodc (bool) – Remove DC component

  • reject (bool) – Invert the sense of the filter

  • optical (bool) – Rotate quadrants to optical space

Return type

Image

Raises

Error

match(sec, xr1, yr1, xs1, ys1, xr2, yr2, xs2, ys2, hwindow=int, harea=int, search=bool, interpolate=GObject)

First-order match of two images.

Example:

out = ref.match(sec, xr1, yr1, xs1, ys1, xr2, yr2, xs2, ys2, hwindow=int, harea=int, search=bool, interpolate=GObject)

Parameters
  • sec (Image) – Secondary image

  • xr1 (int) – Position of first reference tie-point

  • yr1 (int) – Position of first reference tie-point

  • xs1 (int) – Position of first secondary tie-point

  • ys1 (int) – Position of first secondary tie-point

  • xr2 (int) – Position of second reference tie-point

  • yr2 (int) – Position of second reference tie-point

  • xs2 (int) – Position of second secondary tie-point

  • ys2 (int) – Position of second secondary tie-point

  • hwindow (int) – Half window size

  • harea (int) – Half area size

  • search (bool) – Search to improve tie-points

  • interpolate (GObject) – Interpolate pixels with this

Return type

Image

Raises

Error

math(math)

Apply a math operation to an image.

Example:

out = in.math(math)

Parameters

math (Union[str, OperationMath]) – Math to perform

Return type

Image

Raises

Error

math2(right, math2)

Binary math operations.

Example:

out = left.math2(right, math2)

Parameters
  • right (Image) – Right-hand image argument

  • math2 (Union[str, OperationMath2]) – Math to perform

Return type

Image

Raises

Error

math2_const(math2, c)

Binary math operations with a constant.

Example:

out = in.math2_const(math2, c)

Parameters
  • math2 (Union[str, OperationMath2]) – Math to perform

  • c (list[float]) – Array of constants

Return type

Image

Raises

Error

static matload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load mat from file.

Example:

out = pyvips.Image.matload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

matrixinvert()

Invert an matrix.

Example:

out = in.matrixinvert()

Return type

Image

Raises

Error

static matrixload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load matrix.

Example:

out = pyvips.Image.matrixload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static matrixload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load matrix.

Example:

out = pyvips.Image.matrixload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

matrixprint(strip=bool, background=list[float], page_height=int)

Print matrix.

Example:

in.matrixprint(strip=bool, background=list[float], page_height=int)

Parameters
  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

matrixsave(filename, strip=bool, background=list[float], page_height=int)

Save image to matrix.

Example:

in.matrixsave(filename, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

matrixsave_target(target, strip=bool, background=list[float], page_height=int)

Save image to matrix.

Example:

in.matrixsave_target(target, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

max(size=int, x=bool, y=bool, out_array=bool, x_array=bool, y_array=bool)

Find image maximum.

Example:

out = in.max(size=int)

Parameters
  • size (int) – Number of maximum values to find

  • x (bool) – enable output: Horizontal position of maximum

  • y (bool) – enable output: Vertical position of maximum

  • out_array (bool) – enable output: Array of output values

  • x_array (bool) – enable output: Array of horizontal positions

  • y_array (bool) – enable output: Array of vertical positions

Return type

float or list[float, Dict[str, mixed]]

Raises

Error

measure(h, v, left=int, top=int, width=int, height=int)

Measure a set of patches on a color chart.

Example:

out = in.measure(h, v, left=int, top=int, width=int, height=int)

Parameters
  • h (int) – Number of patches across chart

  • v (int) – Number of patches down chart

  • left (int) – Left edge of extract area

  • top (int) – Top edge of extract area

  • width (int) – Width of extract area

  • height (int) – Height of extract area

Return type

Image

Raises

Error

merge(sec, direction, dx, dy, mblend=int)

Merge two images.

Example:

out = ref.merge(sec, direction, dx, dy, mblend=int)

Parameters
  • sec (Image) – Secondary image

  • direction (Union[str, Direction]) – Horizontal or vertical merge

  • dx (int) – Horizontal displacement from sec to ref

  • dy (int) – Vertical displacement from sec to ref

  • mblend (int) – Maximum blend size

Return type

Image

Raises

Error

min(size=int, x=bool, y=bool, out_array=bool, x_array=bool, y_array=bool)

Find image minimum.

Example:

out = in.min(size=int)

Parameters
  • size (int) – Number of minimum values to find

  • x (bool) – enable output: Horizontal position of minimum

  • y (bool) – enable output: Vertical position of minimum

  • out_array (bool) – enable output: Array of output values

  • x_array (bool) – enable output: Array of horizontal positions

  • y_array (bool) – enable output: Array of vertical positions

Return type

float or list[float, Dict[str, mixed]]

Raises

Error

morph(mask, morph)

Morphology operation.

Example:

out = in.morph(mask, morph)

Parameters
Return type

Image

Raises

Error

mosaic(sec, direction, xref, yref, xsec, ysec, hwindow=int, harea=int, mblend=int, bandno=int, dx0=bool, dy0=bool, scale1=bool, angle1=bool, dy1=bool, dx1=bool)

Mosaic two images.

Example:

out = ref.mosaic(sec, direction, xref, yref, xsec, ysec, hwindow=int, harea=int, mblend=int, bandno=int)

Parameters
  • sec (Image) – Secondary image

  • direction (Union[str, Direction]) – Horizontal or vertical mosaic

  • xref (int) – Position of reference tie-point

  • yref (int) – Position of reference tie-point

  • xsec (int) – Position of secondary tie-point

  • ysec (int) – Position of secondary tie-point

  • hwindow (int) – Half window size

  • harea (int) – Half area size

  • mblend (int) – Maximum blend size

  • bandno (int) – Band to search for features on

  • dx0 (bool) – enable output: Detected integer offset

  • dy0 (bool) – enable output: Detected integer offset

  • scale1 (bool) – enable output: Detected scale

  • angle1 (bool) – enable output: Detected rotation

  • dy1 (bool) – enable output: Detected first-order displacement

  • dx1 (bool) – enable output: Detected first-order displacement

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

mosaic1(sec, direction, xr1, yr1, xs1, ys1, xr2, yr2, xs2, ys2, hwindow=int, harea=int, search=bool, interpolate=GObject, mblend=int)

First-order mosaic of two images.

Example:

out = ref.mosaic1(sec, direction, xr1, yr1, xs1, ys1, xr2, yr2, xs2, ys2, hwindow=int, harea=int, search=bool, interpolate=GObject, mblend=int)

Parameters
  • sec (Image) – Secondary image

  • direction (Union[str, Direction]) – Horizontal or vertical mosaic

  • xr1 (int) – Position of first reference tie-point

  • yr1 (int) – Position of first reference tie-point

  • xs1 (int) – Position of first secondary tie-point

  • ys1 (int) – Position of first secondary tie-point

  • xr2 (int) – Position of second reference tie-point

  • yr2 (int) – Position of second reference tie-point

  • xs2 (int) – Position of second secondary tie-point

  • ys2 (int) – Position of second secondary tie-point

  • hwindow (int) – Half window size

  • harea (int) – Half area size

  • search (bool) – Search to improve tie-points

  • interpolate (GObject) – Interpolate pixels with this

  • mblend (int) – Maximum blend size

Return type

Image

Raises

Error

msb(band=int)

Pick most-significant byte from an image.

Example:

out = in.msb(band=int)

Parameters

band (int) – Band to msb

Return type

Image

Raises

Error

multiply(right)

Multiply two images.

Example:

out = left.multiply(right)

Parameters

right (Image) – Right-hand image argument

Return type

Image

Raises

Error

static niftiload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load NIfTI volume.

Example:

out = pyvips.Image.niftiload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static niftiload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load NIfTI volumes.

Example:

out = pyvips.Image.niftiload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

niftisave(filename, strip=bool, background=list[float], page_height=int)

Save image to nifti file.

Example:

in.niftisave(filename, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

static openexrload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load an OpenEXR image.

Example:

out = pyvips.Image.openexrload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static openslideload(filename, attach_associated=bool, level=int, autocrop=bool, associated=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load file with OpenSlide.

Example:

out = pyvips.Image.openslideload(filename, attach_associated=bool, level=int, autocrop=bool, associated=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • attach_associated (bool) – Attach all associated images

  • level (int) – Load this level from the file

  • autocrop (bool) – Crop to image bounds

  • associated (str) – Load this associated image

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static openslideload_source(source, attach_associated=bool, level=int, autocrop=bool, associated=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load source with OpenSlide.

Example:

out = pyvips.Image.openslideload_source(source, attach_associated=bool, level=int, autocrop=bool, associated=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • attach_associated (bool) – Attach all associated images

  • level (int) – Load this level from the file

  • autocrop (bool) – Crop to image bounds

  • associated (str) – Load this associated image

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static pdfload(filename, page=int, n=int, dpi=float, scale=float, background=list[float], password=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load PDF from file.

Example:

out = pyvips.Image.pdfload(filename, page=int, n=int, dpi=float, scale=float, background=list[float], password=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • dpi (float) – Render at this DPI

  • scale (float) – Scale output by this factor

  • background (list[float]) – Background value

  • password (str) – Decrypt with this password

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static pdfload_buffer(buffer, page=int, n=int, dpi=float, scale=float, background=list[float], password=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load PDF from buffer.

Example:

out = pyvips.Image.pdfload_buffer(buffer, page=int, n=int, dpi=float, scale=float, background=list[float], password=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • dpi (float) – Render at this DPI

  • scale (float) – Scale output by this factor

  • background (list[float]) – Background value

  • password (str) – Decrypt with this password

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static pdfload_source(source, page=int, n=int, dpi=float, scale=float, background=list[float], password=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load PDF from source.

Example:

out = pyvips.Image.pdfload_source(source, page=int, n=int, dpi=float, scale=float, background=list[float], password=str, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • dpi (float) – Render at this DPI

  • scale (float) – Scale output by this factor

  • background (list[float]) – Background value

  • password (str) – Decrypt with this password

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

percent(percent)

Find threshold for percent of pixels.

Example:

threshold = in.percent(percent)

Parameters

percent (float) – Percent of pixels

Return type

int

Raises

Error

static perlin(width, height, cell_size=int, uchar=bool, seed=int)

Make a perlin noise image.

Example:

out = pyvips.Image.perlin(width, height, cell_size=int, uchar=bool, seed=int)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • cell_size (int) – Size of Perlin cells

  • uchar (bool) – Output an unsigned char image

  • seed (int) – Random number seed

Return type

Image

Raises

Error

phasecor(in2)

Calculate phase correlation.

Example:

out = in.phasecor(in2)

Parameters

in2 (Image) – Second input image

Return type

Image

Raises

Error

static pngload(filename, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load png from file.

Example:

out = pyvips.Image.pngload(filename, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • unlimited (bool) – Remove all denial of service limits

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static pngload_buffer(buffer, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load png from buffer.

Example:

out = pyvips.Image.pngload_buffer(buffer, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • unlimited (bool) – Remove all denial of service limits

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static pngload_source(source, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load png from source.

Example:

out = pyvips.Image.pngload_source(source, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • unlimited (bool) – Remove all denial of service limits

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

pngsave(filename, compression=int, interlace=bool, profile=str, filter=int, palette=bool, Q=int, dither=float, bitdepth=int, effort=int, strip=bool, background=list[float], page_height=int)

Save image to file as PNG.

Example:

in.pngsave(filename, compression=int, interlace=bool, profile=str, filter=int, palette=bool, Q=int, dither=float, bitdepth=int, effort=int, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • compression (int) – Compression factor

  • interlace (bool) – Interlace image

  • profile (str) – ICC profile to embed

  • filter (int) – libspng row filter flag(s)

  • palette (bool) – Quantise to 8bpp palette

  • Q (int) – Quantisation quality

  • dither (float) – Amount of dithering

  • bitdepth (int) – Write as a 1, 2, 4, 8 or 16 bit image

  • effort (int) – Quantisation CPU effort

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

pngsave_buffer(compression=int, interlace=bool, profile=str, filter=int, palette=bool, Q=int, dither=float, bitdepth=int, effort=int, strip=bool, background=list[float], page_height=int)

Save image to buffer as PNG.

Example:

buffer = in.pngsave_buffer(compression=int, interlace=bool, profile=str, filter=int, palette=bool, Q=int, dither=float, bitdepth=int, effort=int, strip=bool, background=list[float], page_height=int)

Parameters
  • compression (int) – Compression factor

  • interlace (bool) – Interlace image

  • profile (str) – ICC profile to embed

  • filter (int) – libspng row filter flag(s)

  • palette (bool) – Quantise to 8bpp palette

  • Q (int) – Quantisation quality

  • dither (float) – Amount of dithering

  • bitdepth (int) – Write as a 1, 2, 4, 8 or 16 bit image

  • effort (int) – Quantisation CPU effort

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

pngsave_target(target, compression=int, interlace=bool, profile=str, filter=int, palette=bool, Q=int, dither=float, bitdepth=int, effort=int, strip=bool, background=list[float], page_height=int)

Save image to target as PNG.

Example:

in.pngsave_target(target, compression=int, interlace=bool, profile=str, filter=int, palette=bool, Q=int, dither=float, bitdepth=int, effort=int, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • compression (int) – Compression factor

  • interlace (bool) – Interlace image

  • profile (str) – ICC profile to embed

  • filter (int) – libspng row filter flag(s)

  • palette (bool) – Quantise to 8bpp palette

  • Q (int) – Quantisation quality

  • dither (float) – Amount of dithering

  • bitdepth (int) – Write as a 1, 2, 4, 8 or 16 bit image

  • effort (int) – Quantisation CPU effort

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

static ppmload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load ppm from file.

Example:

out = pyvips.Image.ppmload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static ppmload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load ppm base class.

Example:

out = pyvips.Image.ppmload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

ppmsave(filename, format=Union[str, ForeignPpmFormat], ascii=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Save image to ppm file.

Example:

in.ppmsave(filename, format=Union[str, ForeignPpmFormat], ascii=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • format (Union[str, ForeignPpmFormat]) – Format to save in

  • ascii (bool) – Save as ascii

  • bitdepth (int) – Set to 1 to write as a 1 bit image

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

ppmsave_target(target, format=Union[str, ForeignPpmFormat], ascii=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Save to ppm.

Example:

in.ppmsave_target(target, format=Union[str, ForeignPpmFormat], ascii=bool, bitdepth=int, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • format (Union[str, ForeignPpmFormat]) – Format to save in

  • ascii (bool) – Save as ascii

  • bitdepth (int) – Set to 1 to write as a 1 bit image

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

premultiply(max_alpha=float)

Premultiply image alpha.

Example:

out = in.premultiply(max_alpha=float)

Parameters

max_alpha (float) – Maximum value of alpha channel

Return type

Image

Raises

Error

profile()

Find image profiles.

Example:

columns, rows = in.profile()

Return type

list[Image, Image]

Raises

Error

static profile_load(name)

Load named ICC profile.

Example:

profile = pyvips.Image.profile_load(name)

Parameters

name (str) – Profile name

Return type

str

Raises

Error

project()

Find image projections.

Example:

columns, rows = in.project()

Return type

list[Image, Image]

Raises

Error

quadratic(coeff, interpolate=GObject)

Resample an image with a quadratic transform.

Example:

out = in.quadratic(coeff, interpolate=GObject)

Parameters
  • coeff (Image) – Coefficient matrix

  • interpolate (GObject) – Interpolate values with this

Return type

Image

Raises

Error

rad2float()

Unpack Radiance coding to float RGB.

Example:

out = in.rad2float()

Return type

Image

Raises

Error

static radload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load a Radiance image from a file.

Example:

out = pyvips.Image.radload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static radload_buffer(buffer, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load rad from buffer.

Example:

out = pyvips.Image.radload_buffer(buffer, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static radload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load rad from source.

Example:

out = pyvips.Image.radload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

radsave(filename, strip=bool, background=list[float], page_height=int)

Save image to Radiance file.

Example:

in.radsave(filename, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

radsave_buffer(strip=bool, background=list[float], page_height=int)

Save image to Radiance buffer.

Example:

buffer = in.radsave_buffer(strip=bool, background=list[float], page_height=int)

Parameters
  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

radsave_target(target, strip=bool, background=list[float], page_height=int)

Save image to Radiance target.

Example:

in.radsave_target(target, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

rank(width, height, index)

Rank filter.

Example:

out = in.rank(width, height, index)

Parameters
  • width (int) – Window width in pixels

  • height (int) – Window height in pixels

  • index (int) – Select pixel at index

Return type

Image

Raises

Error

static rawload(filename, width, height, bands, offset=long, format=Union[str, BandFormat], interpretation=Union[str, Interpretation], memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load raw data from a file.

Example:

out = pyvips.Image.rawload(filename, width, height, bands, offset=long, format=Union[str, BandFormat], interpretation=Union[str, Interpretation], memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • bands (int) – Number of bands in image

  • offset (long) – Offset in bytes from start of file

  • format (Union[str, BandFormat]) – Pixel format in image

  • interpretation (Union[str, Interpretation]) – Pixel interpretation

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

rawsave(filename, strip=bool, background=list[float], page_height=int)

Save image to raw file.

Example:

in.rawsave(filename, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

rawsave_fd(fd, strip=bool, background=list[float], page_height=int)

Write raw image to file descriptor.

Example:

in.rawsave_fd(fd, strip=bool, background=list[float], page_height=int)

Parameters
  • fd (int) – File descriptor to write to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

recomb(m)

Linear recombination with matrix.

Example:

out = in.recomb(m)

Parameters

m (Image) – Matrix of coefficients

Return type

Image

Raises

Error

reduce(hshrink, vshrink, kernel=Union[str, Kernel], gap=float)

Reduce an image.

Example:

out = in.reduce(hshrink, vshrink, kernel=Union[str, Kernel], gap=float)

Parameters
  • hshrink (float) – Horizontal shrink factor

  • vshrink (float) – Vertical shrink factor

  • kernel (Union[str, Kernel]) – Resampling kernel

  • gap (float) – Reducing gap

Return type

Image

Raises

Error

reduceh(hshrink, kernel=Union[str, Kernel], gap=float)

Shrink an image horizontally.

Example:

out = in.reduceh(hshrink, kernel=Union[str, Kernel], gap=float)

Parameters
  • hshrink (float) – Horizontal shrink factor

  • kernel (Union[str, Kernel]) – Resampling kernel

  • gap (float) – Reducing gap

Return type

Image

Raises

Error

reducev(vshrink, kernel=Union[str, Kernel], gap=float)

Shrink an image vertically.

Example:

out = in.reducev(vshrink, kernel=Union[str, Kernel], gap=float)

Parameters
  • vshrink (float) – Vertical shrink factor

  • kernel (Union[str, Kernel]) – Resampling kernel

  • gap (float) – Reducing gap

Return type

Image

Raises

Error

relational(right, relational)

Relational operation on two images.

Example:

out = left.relational(right, relational)

Parameters
Return type

Image

Raises

Error

relational_const(relational, c)

Relational operations against a constant.

Example:

out = in.relational_const(relational, c)

Parameters
  • relational (Union[str, OperationRelational]) – Relational to perform

  • c (list[float]) – Array of constants

Return type

Image

Raises

Error

remainder(right)

Remainder after integer division of two images.

Example:

out = left.remainder(right)

Parameters

right (Image) – Right-hand image argument

Return type

Image

Raises

Error

remainder_const(c)

Remainder after integer division of an image and a constant.

Example:

out = in.remainder_const(c)

Parameters

c (list[float]) – Array of constants

Return type

Image

Raises

Error

replicate(across, down)

Replicate an image.

Example:

out = in.replicate(across, down)

Parameters
  • across (int) – Repeat this many times horizontally

  • down (int) – Repeat this many times vertically

Return type

Image

Raises

Error

resize(scale, kernel=Union[str, Kernel], gap=float, vscale=float)

Resize an image.

Example:

out = in.resize(scale, kernel=Union[str, Kernel], gap=float, vscale=float)

Parameters
  • scale (float) – Scale image by this factor

  • kernel (Union[str, Kernel]) – Resampling kernel

  • gap (float) – Reducing gap

  • vscale (float) – Vertical scale image by this factor

Return type

Image

Raises

Error

rot(angle)

Rotate an image.

Example:

out = in.rot(angle)

Parameters

angle (Union[str, Angle]) – Angle to rotate image

Return type

Image

Raises

Error

rot45(angle=Union[str, Angle45])

Rotate an image.

Example:

out = in.rot45(angle=Union[str, Angle45])

Parameters

angle (Union[str, Angle45]) – Angle to rotate image

Return type

Image

Raises

Error

rotate(angle, interpolate=GObject, background=list[float], odx=float, ody=float, idx=float, idy=float)

Rotate an image by a number of degrees.

Example:

out = in.rotate(angle, interpolate=GObject, background=list[float], odx=float, ody=float, idx=float, idy=float)

Parameters
  • angle (float) – Rotate anticlockwise by this many degrees

  • interpolate (GObject) – Interpolate pixels with this

  • background (list[float]) – Background value

  • odx (float) – Horizontal output displacement

  • ody (float) – Vertical output displacement

  • idx (float) – Horizontal input displacement

  • idy (float) – Vertical input displacement

Return type

Image

Raises

Error

round(round)

Perform a round function on an image.

Example:

out = in.round(round)

Parameters

round (Union[str, OperationRound]) – Rounding operation to perform

Return type

Image

Raises

Error

sRGB2HSV()

Transform sRGB to HSV.

Example:

out = in.sRGB2HSV()

Return type

Image

Raises

Error

sRGB2scRGB()

Convert an sRGB image to scRGB.

Example:

out = in.sRGB2scRGB()

Return type

Image

Raises

Error

scRGB2BW(depth=int)

Convert scRGB to BW.

Example:

out = in.scRGB2BW(depth=int)

Parameters

depth (int) – Output device space depth in bits

Return type

Image

Raises

Error

scRGB2XYZ()

Transform scRGB to XYZ.

Example:

out = in.scRGB2XYZ()

Return type

Image

Raises

Error

scRGB2sRGB(depth=int)

Convert an scRGB image to sRGB.

Example:

out = in.scRGB2sRGB(depth=int)

Parameters

depth (int) – Output device space depth in bits

Return type

Image

Raises

Error

sequential(tile_height=int)

Check sequential access.

Example:

out = in.sequential(tile_height=int)

Parameters

tile_height (int) – Tile height in pixels

Return type

Image

Raises

Error

sharpen(sigma=float, x1=float, y2=float, y3=float, m1=float, m2=float)

Unsharp masking for print.

Example:

out = in.sharpen(sigma=float, x1=float, y2=float, y3=float, m1=float, m2=float)

Parameters
  • sigma (float) – Sigma of Gaussian

  • x1 (float) – Flat/jaggy threshold

  • y2 (float) – Maximum brightening

  • y3 (float) – Maximum darkening

  • m1 (float) – Slope for flat areas

  • m2 (float) – Slope for jaggy areas

Return type

Image

Raises

Error

shrink(hshrink, vshrink, ceil=bool)

Shrink an image.

Example:

out = in.shrink(hshrink, vshrink, ceil=bool)

Parameters
  • hshrink (float) – Horizontal shrink factor

  • vshrink (float) – Vertical shrink factor

  • ceil (bool) – Round-up output dimensions

Return type

Image

Raises

Error

shrinkh(hshrink, ceil=bool)

Shrink an image horizontally.

Example:

out = in.shrinkh(hshrink, ceil=bool)

Parameters
  • hshrink (int) – Horizontal shrink factor

  • ceil (bool) – Round-up output dimensions

Return type

Image

Raises

Error

shrinkv(vshrink, ceil=bool)

Shrink an image vertically.

Example:

out = in.shrinkv(vshrink, ceil=bool)

Parameters
  • vshrink (int) – Vertical shrink factor

  • ceil (bool) – Round-up output dimensions

Return type

Image

Raises

Error

sign()

Unit vector of pixel.

Example:

out = in.sign()

Return type

Image

Raises

Error

similarity(scale=float, angle=float, interpolate=GObject, background=list[float], odx=float, ody=float, idx=float, idy=float)

Similarity transform of an image.

Example:

out = in.similarity(scale=float, angle=float, interpolate=GObject, background=list[float], odx=float, ody=float, idx=float, idy=float)

Parameters
  • scale (float) – Scale by this factor

  • angle (float) – Rotate anticlockwise by this many degrees

  • interpolate (GObject) – Interpolate pixels with this

  • background (list[float]) – Background value

  • odx (float) – Horizontal output displacement

  • ody (float) – Vertical output displacement

  • idx (float) – Horizontal input displacement

  • idy (float) – Vertical input displacement

Return type

Image

Raises

Error

static sines(width, height, uchar=bool, hfreq=float, vfreq=float)

Make a 2D sine wave.

Example:

out = pyvips.Image.sines(width, height, uchar=bool, hfreq=float, vfreq=float)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • uchar (bool) – Output an unsigned char image

  • hfreq (float) – Horizontal spatial frequency

  • vfreq (float) – Vertical spatial frequency

Return type

Image

Raises

Error

smartcrop(width, height, interesting=Union[str, Interesting])

Extract an area from an image.

Example:

out = input.smartcrop(width, height, interesting=Union[str, Interesting])

Parameters
  • width (int) – Width of extract area

  • height (int) – Height of extract area

  • interesting (Union[str, Interesting]) – How to measure interestingness

Return type

Image

Raises

Error

sobel()

Sobel edge detector.

Example:

out = in.sobel()

Return type

Image

Raises

Error

spcor(ref)

Spatial correlation.

Example:

out = in.spcor(ref)

Parameters

ref (Image) – Input reference image

Return type

Image

Raises

Error

spectrum()

Make displayable power spectrum.

Example:

out = in.spectrum()

Return type

Image

Raises

Error

stats()

Find many image stats.

Example:

out = in.stats()

Return type

Image

Raises

Error

stdif(width, height, s0=float, b=float, m0=float, a=float)

Statistical difference.

Example:

out = in.stdif(width, height, s0=float, b=float, m0=float, a=float)

Parameters
  • width (int) – Window width in pixels

  • height (int) – Window height in pixels

  • s0 (float) – New deviation

  • b (float) – Weight of new deviation

  • m0 (float) – New mean

  • a (float) – Weight of new mean

Return type

Image

Raises

Error

subsample(xfac, yfac, point=bool)

Subsample an image.

Example:

out = input.subsample(xfac, yfac, point=bool)

Parameters
  • xfac (int) – Horizontal subsample factor

  • yfac (int) – Vertical subsample factor

  • point (bool) – Point sample

Return type

Image

Raises

Error

subtract(right)

Subtract two images.

Example:

out = left.subtract(right)

Parameters

right (Image) – Right-hand image argument

Return type

Image

Raises

Error

static sum(in)

Sum an array of images.

Example:

out = pyvips.Image.sum(in)

Parameters

in (list[Image]) – Array of input images

Return type

Image

Raises

Error

static svgload(filename, dpi=float, scale=float, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load SVG with rsvg.

Example:

out = pyvips.Image.svgload(filename, dpi=float, scale=float, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • dpi (float) – Render at this DPI

  • scale (float) – Scale output by this factor

  • unlimited (bool) – Allow SVG of any size

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static svgload_buffer(buffer, dpi=float, scale=float, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load SVG with rsvg.

Example:

out = pyvips.Image.svgload_buffer(buffer, dpi=float, scale=float, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • dpi (float) – Render at this DPI

  • scale (float) – Scale output by this factor

  • unlimited (bool) – Allow SVG of any size

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static svgload_source(source, dpi=float, scale=float, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load svg from source.

Example:

out = pyvips.Image.svgload_source(source, dpi=float, scale=float, unlimited=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • dpi (float) – Render at this DPI

  • scale (float) – Scale output by this factor

  • unlimited (bool) – Allow SVG of any size

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static switch(tests)

Find the index of the first non-zero pixel in tests.

Example:

out = pyvips.Image.switch(tests)

Parameters

tests (list[Image]) – Table of images to test

Return type

Image

Raises

Error

static system(cmd_format, in=list[Image], out_format=str, in_format=str, out=bool, log=bool)

Run an external command.

Example:

pyvips.Image.system(cmd_format, in=list[Image], out_format=str, in_format=str)

Parameters
  • cmd_format (str) – Command to run

  • in (list[Image]) – Array of input images

  • out_format (str) – Format for output filename

  • in_format (str) – Format for input filename

  • out (bool) – enable output: Output image

  • log (bool) – enable output: Command log

Return type

list[] or list[Dict[str, mixed]]

Raises

Error

static text(text, font=str, width=int, height=int, align=Union[str, Align], rgba=bool, dpi=int, justify=bool, spacing=int, fontfile=str, autofit_dpi=bool)

Make a text image.

Example:

out = pyvips.Image.text(text, font=str, width=int, height=int, align=Union[str, Align], rgba=bool, dpi=int, justify=bool, spacing=int, fontfile=str)

Parameters
  • text (str) – Text to render

  • font (str) – Font to render with

  • width (int) – Maximum image width in pixels

  • height (int) – Maximum image height in pixels

  • align (Union[str, Align]) – Align on the low, centre or high edge

  • rgba (bool) – Enable RGBA output

  • dpi (int) – DPI to render at

  • justify (bool) – Justify lines

  • spacing (int) – Line spacing

  • fontfile (str) – Load this font file

  • autofit_dpi (bool) – enable output: DPI selected by autofit

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static thumbnail(filename, width, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Generate thumbnail from file.

Example:

out = pyvips.Image.thumbnail(filename, width, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to read from

  • width (int) – Size to this width

  • height (int) – Size to this height

  • size (Union[str, Size]) – Only upsize, only downsize, or both

  • no_rotate (bool) – Don’t use orientation tags to rotate image upright

  • crop (Union[str, Interesting]) – Reduce to fill target rectangle, then crop

  • linear (bool) – Reduce in linear light

  • import_profile (str) – Fallback import profile

  • export_profile (str) – Fallback export profile

  • intent (Union[str, Intent]) – Rendering intent

  • fail_on (Union[str, FailOn]) – Error level to fail on

Return type

Image

Raises

Error

static thumbnail_buffer(buffer, width, option_string=str, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Generate thumbnail from buffer.

Example:

out = pyvips.Image.thumbnail_buffer(buffer, width, option_string=str, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • width (int) – Size to this width

  • option_string (str) – Options that are passed on to the underlying loader

  • height (int) – Size to this height

  • size (Union[str, Size]) – Only upsize, only downsize, or both

  • no_rotate (bool) – Don’t use orientation tags to rotate image upright

  • crop (Union[str, Interesting]) – Reduce to fill target rectangle, then crop

  • linear (bool) – Reduce in linear light

  • import_profile (str) – Fallback import profile

  • export_profile (str) – Fallback export profile

  • intent (Union[str, Intent]) – Rendering intent

  • fail_on (Union[str, FailOn]) – Error level to fail on

Return type

Image

Raises

Error

thumbnail_image(width, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Generate thumbnail from image.

Example:

out = in.thumbnail_image(width, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Parameters
  • width (int) – Size to this width

  • height (int) – Size to this height

  • size (Union[str, Size]) – Only upsize, only downsize, or both

  • no_rotate (bool) – Don’t use orientation tags to rotate image upright

  • crop (Union[str, Interesting]) – Reduce to fill target rectangle, then crop

  • linear (bool) – Reduce in linear light

  • import_profile (str) – Fallback import profile

  • export_profile (str) – Fallback export profile

  • intent (Union[str, Intent]) – Rendering intent

  • fail_on (Union[str, FailOn]) – Error level to fail on

Return type

Image

Raises

Error

static thumbnail_source(source, width, option_string=str, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Generate thumbnail from source.

Example:

out = pyvips.Image.thumbnail_source(source, width, option_string=str, height=int, size=Union[str, Size], no_rotate=bool, crop=Union[str, Interesting], linear=bool, import_profile=str, export_profile=str, intent=Union[str, Intent], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • width (int) – Size to this width

  • option_string (str) – Options that are passed on to the underlying loader

  • height (int) – Size to this height

  • size (Union[str, Size]) – Only upsize, only downsize, or both

  • no_rotate (bool) – Don’t use orientation tags to rotate image upright

  • crop (Union[str, Interesting]) – Reduce to fill target rectangle, then crop

  • linear (bool) – Reduce in linear light

  • import_profile (str) – Fallback import profile

  • export_profile (str) – Fallback export profile

  • intent (Union[str, Intent]) – Rendering intent

  • fail_on (Union[str, FailOn]) – Error level to fail on

Return type

Image

Raises

Error

static tiffload(filename, page=int, subifd=int, n=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load tiff from file.

Example:

out = pyvips.Image.tiffload(filename, page=int, subifd=int, n=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • page (int) – Load this page from the image

  • subifd (int) – Select subifd index

  • n (int) – Load this many pages

  • autorotate (bool) – Rotate image using orientation tag

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static tiffload_buffer(buffer, page=int, subifd=int, n=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load tiff from buffer.

Example:

out = pyvips.Image.tiffload_buffer(buffer, page=int, subifd=int, n=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • page (int) – Load this page from the image

  • subifd (int) – Select subifd index

  • n (int) – Load this many pages

  • autorotate (bool) – Rotate image using orientation tag

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static tiffload_source(source, page=int, subifd=int, n=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load tiff from source.

Example:

out = pyvips.Image.tiffload_source(source, page=int, subifd=int, n=int, autorotate=bool, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • page (int) – Load this page from the image

  • subifd (int) – Select subifd index

  • n (int) – Load this many pages

  • autorotate (bool) – Rotate image using orientation tag

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

tiffsave(filename, compression=Union[str, ForeignTiffCompression], Q=int, predictor=Union[str, ForeignTiffPredictor], profile=str, tile=bool, tile_width=int, tile_height=int, pyramid=bool, miniswhite=bool, bitdepth=int, resunit=Union[str, ForeignTiffResunit], xres=float, yres=float, bigtiff=bool, properties=bool, region_shrink=Union[str, RegionShrink], level=int, lossless=bool, depth=Union[str, ForeignDzDepth], subifd=bool, premultiply=bool, strip=bool, background=list[float], page_height=int)

Save image to tiff file.

Example:

in.tiffsave(filename, compression=Union[str, ForeignTiffCompression], Q=int, predictor=Union[str, ForeignTiffPredictor], profile=str, tile=bool, tile_width=int, tile_height=int, pyramid=bool, miniswhite=bool, bitdepth=int, resunit=Union[str, ForeignTiffResunit], xres=float, yres=float, bigtiff=bool, properties=bool, region_shrink=Union[str, RegionShrink], level=int, lossless=bool, depth=Union[str, ForeignDzDepth], subifd=bool, premultiply=bool, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • compression (Union[str, ForeignTiffCompression]) – Compression for this file

  • Q (int) – Q factor

  • predictor (Union[str, ForeignTiffPredictor]) – Compression prediction

  • profile (str) – ICC profile to embed

  • tile (bool) – Write a tiled tiff

  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • pyramid (bool) – Write a pyramidal tiff

  • miniswhite (bool) – Use 0 for white in 1-bit images

  • bitdepth (int) – Write as a 1, 2, 4 or 8 bit image

  • resunit (Union[str, ForeignTiffResunit]) – Resolution unit

  • xres (float) – Horizontal resolution in pixels/mm

  • yres (float) – Vertical resolution in pixels/mm

  • bigtiff (bool) – Write a bigtiff image

  • properties (bool) – Write a properties document to IMAGEDESCRIPTION

  • region_shrink (Union[str, RegionShrink]) – Method to shrink regions

  • level (int) – ZSTD compression level

  • lossless (bool) – Enable WEBP lossless mode

  • depth (Union[str, ForeignDzDepth]) – Pyramid depth

  • subifd (bool) – Save pyr layers as sub-IFDs

  • premultiply (bool) – Save with premultiplied alpha

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

tiffsave_buffer(compression=Union[str, ForeignTiffCompression], Q=int, predictor=Union[str, ForeignTiffPredictor], profile=str, tile=bool, tile_width=int, tile_height=int, pyramid=bool, miniswhite=bool, bitdepth=int, resunit=Union[str, ForeignTiffResunit], xres=float, yres=float, bigtiff=bool, properties=bool, region_shrink=Union[str, RegionShrink], level=int, lossless=bool, depth=Union[str, ForeignDzDepth], subifd=bool, premultiply=bool, strip=bool, background=list[float], page_height=int)

Save image to tiff buffer.

Example:

buffer = in.tiffsave_buffer(compression=Union[str, ForeignTiffCompression], Q=int, predictor=Union[str, ForeignTiffPredictor], profile=str, tile=bool, tile_width=int, tile_height=int, pyramid=bool, miniswhite=bool, bitdepth=int, resunit=Union[str, ForeignTiffResunit], xres=float, yres=float, bigtiff=bool, properties=bool, region_shrink=Union[str, RegionShrink], level=int, lossless=bool, depth=Union[str, ForeignDzDepth], subifd=bool, premultiply=bool, strip=bool, background=list[float], page_height=int)

Parameters
  • compression (Union[str, ForeignTiffCompression]) – Compression for this file

  • Q (int) – Q factor

  • predictor (Union[str, ForeignTiffPredictor]) – Compression prediction

  • profile (str) – ICC profile to embed

  • tile (bool) – Write a tiled tiff

  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • pyramid (bool) – Write a pyramidal tiff

  • miniswhite (bool) – Use 0 for white in 1-bit images

  • bitdepth (int) – Write as a 1, 2, 4 or 8 bit image

  • resunit (Union[str, ForeignTiffResunit]) – Resolution unit

  • xres (float) – Horizontal resolution in pixels/mm

  • yres (float) – Vertical resolution in pixels/mm

  • bigtiff (bool) – Write a bigtiff image

  • properties (bool) – Write a properties document to IMAGEDESCRIPTION

  • region_shrink (Union[str, RegionShrink]) – Method to shrink regions

  • level (int) – ZSTD compression level

  • lossless (bool) – Enable WEBP lossless mode

  • depth (Union[str, ForeignDzDepth]) – Pyramid depth

  • subifd (bool) – Save pyr layers as sub-IFDs

  • premultiply (bool) – Save with premultiplied alpha

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

tiffsave_target(target, compression=Union[str, ForeignTiffCompression], Q=int, predictor=Union[str, ForeignTiffPredictor], profile=str, tile=bool, tile_width=int, tile_height=int, pyramid=bool, miniswhite=bool, bitdepth=int, resunit=Union[str, ForeignTiffResunit], xres=float, yres=float, bigtiff=bool, properties=bool, region_shrink=Union[str, RegionShrink], level=int, lossless=bool, depth=Union[str, ForeignDzDepth], subifd=bool, premultiply=bool, strip=bool, background=list[float], page_height=int)

Save image to tiff target.

Example:

in.tiffsave_target(target, compression=Union[str, ForeignTiffCompression], Q=int, predictor=Union[str, ForeignTiffPredictor], profile=str, tile=bool, tile_width=int, tile_height=int, pyramid=bool, miniswhite=bool, bitdepth=int, resunit=Union[str, ForeignTiffResunit], xres=float, yres=float, bigtiff=bool, properties=bool, region_shrink=Union[str, RegionShrink], level=int, lossless=bool, depth=Union[str, ForeignDzDepth], subifd=bool, premultiply=bool, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • compression (Union[str, ForeignTiffCompression]) – Compression for this file

  • Q (int) – Q factor

  • predictor (Union[str, ForeignTiffPredictor]) – Compression prediction

  • profile (str) – ICC profile to embed

  • tile (bool) – Write a tiled tiff

  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • pyramid (bool) – Write a pyramidal tiff

  • miniswhite (bool) – Use 0 for white in 1-bit images

  • bitdepth (int) – Write as a 1, 2, 4 or 8 bit image

  • resunit (Union[str, ForeignTiffResunit]) – Resolution unit

  • xres (float) – Horizontal resolution in pixels/mm

  • yres (float) – Vertical resolution in pixels/mm

  • bigtiff (bool) – Write a bigtiff image

  • properties (bool) – Write a properties document to IMAGEDESCRIPTION

  • region_shrink (Union[str, RegionShrink]) – Method to shrink regions

  • level (int) – ZSTD compression level

  • lossless (bool) – Enable WEBP lossless mode

  • depth (Union[str, ForeignDzDepth]) – Pyramid depth

  • subifd (bool) – Save pyr layers as sub-IFDs

  • premultiply (bool) – Save with premultiplied alpha

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

tilecache(tile_width=int, tile_height=int, max_tiles=int, access=Union[str, Access], threaded=bool, persistent=bool)

Cache an image as a set of tiles.

Example:

out = in.tilecache(tile_width=int, tile_height=int, max_tiles=int, access=Union[str, Access], threaded=bool, persistent=bool)

Parameters
  • tile_width (int) – Tile width in pixels

  • tile_height (int) – Tile height in pixels

  • max_tiles (int) – Maximum number of tiles to cache

  • access (Union[str, Access]) – Expected access pattern

  • threaded (bool) – Allow threaded access

  • persistent (bool) – Keep cache between evaluations

Return type

Image

Raises

Error

static tonelut(in_max=int, out_max=int, Lb=float, Lw=float, Ps=float, Pm=float, Ph=float, S=float, M=float, H=float)

Build a look-up table.

Example:

out = pyvips.Image.tonelut(in_max=int, out_max=int, Lb=float, Lw=float, Ps=float, Pm=float, Ph=float, S=float, M=float, H=float)

Parameters
  • in_max (int) – Size of LUT to build

  • out_max (int) – Maximum value in output LUT

  • Lb (float) – Lowest value in output

  • Lw (float) – Highest value in output

  • Ps (float) – Position of shadow

  • Pm (float) – Position of mid-tones

  • Ph (float) – Position of highlights

  • S (float) – Adjust shadows by this much

  • M (float) – Adjust mid-tones by this much

  • H (float) – Adjust highlights by this much

Return type

Image

Raises

Error

transpose3d(page_height=int)

Transpose3d an image.

Example:

out = in.transpose3d(page_height=int)

Parameters

page_height (int) – Height of each input page

Return type

Image

Raises

Error

unpremultiply(max_alpha=float, alpha_band=int)

Unpremultiply image alpha.

Example:

out = in.unpremultiply(max_alpha=float, alpha_band=int)

Parameters
  • max_alpha (float) – Maximum value of alpha channel

  • alpha_band (int) – Unpremultiply with this alpha

Return type

Image

Raises

Error

static vipsload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load vips from file.

Example:

out = pyvips.Image.vipsload(filename, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static vipsload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load vips from source.

Example:

out = pyvips.Image.vipsload_source(source, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

vipssave(filename, strip=bool, background=list[float], page_height=int)

Save image to file in vips format.

Example:

in.vipssave(filename, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

vipssave_target(target, strip=bool, background=list[float], page_height=int)

Save image to target in vips format.

Example:

in.vipssave_target(target, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

static webpload(filename, page=int, n=int, scale=float, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load webp from file.

Example:

out = pyvips.Image.webpload(filename, page=int, n=int, scale=float, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • filename (str) – Filename to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • scale (float) – Scale factor on load

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static webpload_buffer(buffer, page=int, n=int, scale=float, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load webp from buffer.

Example:

out = pyvips.Image.webpload_buffer(buffer, page=int, n=int, scale=float, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • buffer (str) – Buffer to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • scale (float) – Scale factor on load

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

static webpload_source(source, page=int, n=int, scale=float, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn], flags=bool)

Load webp from source.

Example:

out = pyvips.Image.webpload_source(source, page=int, n=int, scale=float, memory=bool, access=Union[str, Access], fail_on=Union[str, FailOn])

Parameters
  • source (Source) – Source to load from

  • page (int) – Load this page from the file

  • n (int) – Load this many pages

  • scale (float) – Scale factor on load

  • memory (bool) – Force open via memory

  • access (Union[str, Access]) – Required access pattern for this file

  • fail_on (Union[str, FailOn]) – Error level to fail on

  • flags (bool) – enable output: Flags for this file

Return type

Image or list[Image, Dict[str, mixed]]

Raises

Error

webpsave(filename, Q=int, lossless=bool, preset=Union[str, ForeignWebpPreset], smart_subsample=bool, near_lossless=bool, alpha_q=int, min_size=bool, kmin=int, kmax=int, effort=int, profile=str, mixed=bool, strip=bool, background=list[float], page_height=int)

Save image to webp file.

Example:

in.webpsave(filename, Q=int, lossless=bool, preset=Union[str, ForeignWebpPreset], smart_subsample=bool, near_lossless=bool, alpha_q=int, min_size=bool, kmin=int, kmax=int, effort=int, profile=str, mixed=bool, strip=bool, background=list[float], page_height=int)

Parameters
  • filename (str) – Filename to save to

  • Q (int) – Q factor

  • lossless (bool) – Enable lossless compression

  • preset (Union[str, ForeignWebpPreset]) – Preset for lossy compression

  • smart_subsample (bool) – Enable high quality chroma subsampling

  • near_lossless (bool) – Enable preprocessing in lossless mode (uses Q)

  • alpha_q (int) – Change alpha plane fidelity for lossy compression

  • min_size (bool) – Optimise for minimum size

  • kmin (int) – Minimum number of frames between key frames

  • kmax (int) – Maximum number of frames between key frames

  • effort (int) – Level of CPU effort to reduce file size

  • profile (str) – ICC profile to embed

  • mixed (bool) – Allow mixed encoding (might reduce file size)

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

webpsave_buffer(Q=int, lossless=bool, preset=Union[str, ForeignWebpPreset], smart_subsample=bool, near_lossless=bool, alpha_q=int, min_size=bool, kmin=int, kmax=int, effort=int, profile=str, mixed=bool, strip=bool, background=list[float], page_height=int)

Save image to webp buffer.

Example:

buffer = in.webpsave_buffer(Q=int, lossless=bool, preset=Union[str, ForeignWebpPreset], smart_subsample=bool, near_lossless=bool, alpha_q=int, min_size=bool, kmin=int, kmax=int, effort=int, profile=str, mixed=bool, strip=bool, background=list[float], page_height=int)

Parameters
  • Q (int) – Q factor

  • lossless (bool) – Enable lossless compression

  • preset (Union[str, ForeignWebpPreset]) – Preset for lossy compression

  • smart_subsample (bool) – Enable high quality chroma subsampling

  • near_lossless (bool) – Enable preprocessing in lossless mode (uses Q)

  • alpha_q (int) – Change alpha plane fidelity for lossy compression

  • min_size (bool) – Optimise for minimum size

  • kmin (int) – Minimum number of frames between key frames

  • kmax (int) – Maximum number of frames between key frames

  • effort (int) – Level of CPU effort to reduce file size

  • profile (str) – ICC profile to embed

  • mixed (bool) – Allow mixed encoding (might reduce file size)

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

str

Raises

Error

webpsave_target(target, Q=int, lossless=bool, preset=Union[str, ForeignWebpPreset], smart_subsample=bool, near_lossless=bool, alpha_q=int, min_size=bool, kmin=int, kmax=int, effort=int, profile=str, mixed=bool, strip=bool, background=list[float], page_height=int)

Save image to webp target.

Example:

in.webpsave_target(target, Q=int, lossless=bool, preset=Union[str, ForeignWebpPreset], smart_subsample=bool, near_lossless=bool, alpha_q=int, min_size=bool, kmin=int, kmax=int, effort=int, profile=str, mixed=bool, strip=bool, background=list[float], page_height=int)

Parameters
  • target (Target) – Target to save to

  • Q (int) – Q factor

  • lossless (bool) – Enable lossless compression

  • preset (Union[str, ForeignWebpPreset]) – Preset for lossy compression

  • smart_subsample (bool) – Enable high quality chroma subsampling

  • near_lossless (bool) – Enable preprocessing in lossless mode (uses Q)

  • alpha_q (int) – Change alpha plane fidelity for lossy compression

  • min_size (bool) – Optimise for minimum size

  • kmin (int) – Minimum number of frames between key frames

  • kmax (int) – Maximum number of frames between key frames

  • effort (int) – Level of CPU effort to reduce file size

  • profile (str) – ICC profile to embed

  • mixed (bool) – Allow mixed encoding (might reduce file size)

  • strip (bool) – Strip all metadata from image

  • background (list[float]) – Background value

  • page_height (int) – Set page height for multipage save

Return type

list[]

Raises

Error

static worley(width, height, cell_size=int, seed=int)

Make a worley noise image.

Example:

out = pyvips.Image.worley(width, height, cell_size=int, seed=int)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • cell_size (int) – Size of Worley cells

  • seed (int) – Random number seed

Return type

Image

Raises

Error

wrap(x=int, y=int)

Wrap image origin.

Example:

out = in.wrap(x=int, y=int)

Parameters
  • x (int) – Left edge of input in output

  • y (int) – Top edge of input in output

Return type

Image

Raises

Error

static xyz(width, height, csize=int, dsize=int, esize=int)

Make an image where pixel values are coordinates.

Example:

out = pyvips.Image.xyz(width, height, csize=int, dsize=int, esize=int)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • csize (int) – Size of third dimension

  • dsize (int) – Size of fourth dimension

  • esize (int) – Size of fifth dimension

Return type

Image

Raises

Error

static zone(width, height, uchar=bool)

Make a zone plate.

Example:

out = pyvips.Image.zone(width, height, uchar=bool)

Parameters
  • width (int) – Image width in pixels

  • height (int) – Image height in pixels

  • uchar (bool) – Output an unsigned char image

Return type

Image

Raises

Error

zoom(xfac, yfac)

Zoom an image.

Example:

out = input.zoom(xfac, yfac)

Parameters
  • xfac (int) – Horizontal zoom factor

  • yfac (int) – Vertical zoom factor

Return type

Image

Raises

Error