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’s imshow method.

Note

This submodule was introduced in v1.3.0.

Conversions

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

Convert a numpy array to a vtkImageData.

Parameters:
  • arr (np.ndarray with dtype np.uint8) – Array of colors.
  • image_data (vtkImageData, optional) – An image data to write into, a new one is created if not specified, defaults to None.
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)

Convert a vtkImageData to numpy array.

See also

vtkimagedata_from_array() for the reverse.

as_vtkimagedata

vtkplotlib.image_io.as_vtkimagedata(x, ndim=None)

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 Pillow (Python image library) which does the same thing. But these methods are included anyway just incase you don’t want to use Pillow.

read

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

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, optional) – Image compressed binary data, defaults to None.
  • format (str, optional) – Image format extension (e.g. jpg), not needed if format can be determined from path, defaults to None.
  • convert_to_array (bool, optional) – If true, convert to numpy, otherwise leave as vtkImageData, defaults to True.
Returns:

Read image.
Return type:

np.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 ‘.’s 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 you're 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 :meth:`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.

write

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

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

Parameters:
  • arr (np.ndarray) – arr can be a vtkImageData or a numpy array.
  • path (str, os.Pathlike, io.BytesIO,) – File path to write to.
  • format (str, optional) – Image format extension (e.g. jpg), not needed if format can be determined from path, defaults to None.
  • quality (int from 0 to 100, optional) – Lossy compression quality, only applicable to JPEGs, defaults to 95.
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 summerises which are allowed. This table is accessable 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)

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

Parameters:
  • arr (3D np.ndarray) – An image array.
  • background_color (Strictly an (r, g, b) 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:

Smaller image array.
Return type:

3D np.ndarray

If you don’t want your files smaller you can instead use vtkplotlib.zoom().