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

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