Images

The image_io subpackage provides tools for working 2D images. It includes methods for:

For the most part, vtkplotlib converts implicitly to/from its preferred format, which is just a numpy array of RGB values, using methods from here. But if you are venturing into a region of VTK that vtkplotlib doesn’t cover then these may be useful.

vtkplotlib’s default image format is the same as matplotlib’s. i.e an (m, n, 3) numpy array with dtype np.uint8. The most convenient way to visualise is using matplotlib.pyplot.imshow method.

import matplotlib.pylab as plt
plt.imshow(image_array)
plt.show()

New in version v1.3.0.

Conversions

Converting numpy to vtkImageData and back is ugly. These methods do this for you.

vtkimagedata_from_array

vtkplotlib.image_io.vtkimagedata_from_array(arr, image_data=None)[source]

Convert a numpy array to a vtkImageData.

Parameters

  • arr (numpy.ndarray) – An uint8 array of colors.

  • image_data (vtkImageData) – An image data to write into, a new one is created if not specified.

Returns

A VTK image.

Return type

vtkImageData

Grayscale images are allowed. arr.shape can be any of (m, n) or (m, n, 1) for greyscale, (m, n, 3) for RGB, or (m, n, 4) for RGBA.

See also

vtkimagedata_to_array for the reverse.

See also

as_vtkimagedata for converting from other types.

vtkimagedata_to_array

vtkplotlib.image_io.vtkimagedata_to_array(image_data)[source]

Convert a vtkImageData to numpy array.

See also

vtkimagedata_from_array for the reverse.

as_vtkimagedata

vtkplotlib.image_io.as_vtkimagedata(x, ndim=None)[source]

Convert x to a vtkImageData.

x can be any of the following:

  • A vtkImageData.

  • A 2D or 3D numpy array.

  • A file or filename to be read.

  • A Pillow image.

Some VTK methods require a greyscale image. Using ndim=2 will convert to greyscale.

Read and Write

VTK provides classes for reading and writing images to disk. These are somewhat superseded by PIL (the Python Image Library) which does the same thing. But these methods are here anyway whether you need them or not.

read

vtkplotlib.image_io.read(path, raw_bytes=None, format=None, convert_to_array=True)[source]

Read an image from a file using one of VTK’s vtkFormatReader classes where Format is replaced by JPEG, PNG, BMP or TIFF.

Parameters

  • path (str, os.PathLike, io.BytesIO) – Filename or file handle or None if using the raw_bytes argument.

  • raw_bytes (bytes) – Image compressed binary data.

  • format (str) – Image format extension (e.g. jpg). This should never be needed.

  • convert_to_array (bool) – If true, convert to numpy.ndarray, otherwise leave as vtkImageData.

Returns

Read image.

Return type

numpy.ndarray or vtkImageData

The file format can be determined automatically from the path suffix or the beginning of raw_bytes. format can be any of JPEG, PNG, TIFF, BMP. It is case insensitive, tolerant to preceding '.' e.g. format=".jpg" and understands the aliases JPG ⇔ JPEG and TIF ⇔ TIFF.

The following demonstrates how to use pseudo file objects to avoid temporary files when reading an image from the web.

import vtkplotlib as vpl

# Link your image url here
url = "https://raw.githubusercontent.com/bwoodsend/vtkplotlib/master/vtkplotlib/data/icons/Right.jpg"

# You can make the url request with either:
from urllib import request
raw_bytes = request.urlopen(url).read()

# Or if you have the more modern requests library installed:
# import requests
# raw_bytes = requests.get(url).content

# Pass the bytes to `read()` using:
image = vpl.image_io.read(path=None, raw_bytes=raw_bytes)

# Visualize using matplotlib.
from matplotlib import pyplot
pyplot.imshow(image)
pyplot.show()

Warning

Some formats only support reading from disk. See vtkplotlib.image_io.BUFFERABLE_FORMAT_MODES or for which these are.

Note

BytesIO and raw bytes functionality is new in vtkplotlib >= 1.3.0. Older versions are hardcoded to write to disk and therefore path must be a filename and not a BytesIO or similar pseudo file object.

Note

There is a bug in VTK==9.0.0

write

vtkplotlib.image_io.write(arr, path, format=None, quality=95)[source]

Write an image from a file using one of VTK’s vtkFormatWriter classes where Format is replaced by JPEG or PNG.

Parameters

  • arr (numpy.ndarray or vtkImageData) – An image array.

  • path (str or os.PathLike or io.BytesIO) – File path to write to.

  • format (str) – Image format extension (e.g. jpg), not needed if format can be determined from path.

  • quality (int) – Lossy compression quality (only applicable to JPEGs) between 0 to 100.

Returns

The raw image binary if path is None, NotImplemented if the filetype is unknown. Otherwise no return value.

Return type

bytes

See read for more information.

Note

BytesIO and raw bytes functionality is new in vtkplotlib >= 1.3.0. Older versions are hardcoded to write to disk and therefore path must be a filename and not a BytesIO or similar pseudo file object.

Formats allowing pseudo files

Some formats allow reading and writing from RAM whereas others must use the disk. The following table summarises which are allowed. This table is accessible via vtkplotlib.image_io.BUFFERABLE_FORMAT_MODES.

Name

Allowed modes

JPEG

Read and Write

PNG

Write

TIFF

BMP

Write

Misc

trim_image

vtkplotlib.image_io.trim_image(arr, background_color, crop_padding)[source]

Crop an image to its contents so that there aren’t large amounts of empty background.

Parameters

  • arr (numpy.ndarray) – An image array.

  • background_color (tuple) – The color of the portions to crop away.

  • crop_padding (int or float) – Space to leave, in pixels if int, or relative to image size if float.

Returns

A smaller image array.

Return type

numpy.ndarray

If you don’t want your files smaller you can instead use vtkplotlib.zoom_to_contents.