Image input/output operations

A set of functions to read, write, and display images represented as NumPy arrays.

machinevisiontoolbox.base.imageio.idisp(im, colororder='RGB', matplotlib=True, block=None, fps=None, fig=None, ax=None, reuse=False, colormap=None, ncolors=None, black=0, darken=None, powernorm=False, gamma=None, vrange=None, badcolor=None, undercolor=None, overcolor=None, title=None, grid=False, axes=True, gui=True, frame=True, plain=False, colorbar=False, square=True, width=None, height=None, flatten=False, ynormal=False, extent=None, coordformat=None, savefigname=None, **kwargs)[source]

Interactive image display tool

Parameters:

  • im (ndarray(H,W), ndarray(H,W,3)) – image to display

  • colororder (str) – color order, defaults to “RGB”

  • matplotlib (bool, optional) – plot using Matplotlib (True) or OpenCV (False), defaults to True

  • block (bool, float, optional) – after display, Matplotlib blocks until window closed or for the specified time period, defaults to False

  • fps (float, optional) – frames per second, Matplotlib blocks for 1/fps seconds after display, defaults to None

  • fig (int, optional) – Matplotlib figure handle to display image on, defaults to new figure

  • ax (axis object, optional) – Matplotlib axis object to plot on, defaults to new axis

  • reuse (bool, optional) – plot into current figure, skips setup overhead, defaults to False

  • colormap (str or matplotlib.colors.Colormap) – colormap name or Matplotlib colormap object

  • ncolors (int, optional) – number of colors in colormap

  • black (int or float) – set black (zero) pixels to this value, default 0

  • darken (float, bool, optional) – darken the image by scaling pixel values by this amount, if darken is True then darken by 0.5

  • powernorm (array_like(2), optional) – Matplotlib power-law normalization

  • gamma (float, optional) – gamma correction applied before display

  • vrange (array_like(2), optional) – minimum and maximum values for colormap, defaults to minimum and maximum values from image data.

  • badcolor (str, optional) – name of color to display when value is NaN

  • undercolor (str, optional) – name of color to display when value is less than colormap minimum

  • overcolor (str, optional) – name of color to display when value is less than colormap maximum

  • title (str, optional) – title of figure in figure window

  • grid – display grid lines over image, default False

  • axes (bool, optional) – display axes on the image, default True

  • gui (bool, optional) – display GUI/interactive buttons, default True

  • frame (bool, optional) – display frame around the image, default True

  • plain (bool, optional) – don’t display axes, frame or GUI

  • colorbar (bool, optional) – add colorbar to image, default False

  • width (float, optional) – figure width in millimetres, defaults to Matplotlib default

  • height (float, optional) – figure height in millimetres, defaults to Matplotlib default

  • square (bool, optional) – set aspect ratio so that pixels are square, default True

  • ynormal (bool, optional) – y-axis increases upward, default False

  • extent (array_like(4), optional) – extent of the image in user units [xmin, xmax, ymin, ymax]

  • coordformat (callable returning string) – format coordinates and pixel values for the figure window toolbar

  • savefigname (str, optional) – if not None, save figure as savefigname (default eps)

  • kwargs – additional options passed through to matplotlib.pyplot.imshow.

Returns:

Matplotlib figure handle and axes handle

Return type:

figure handle, axes handle

Display a greyscale or color image using Matplotlib (if matplotlib is True) or OpenCV. The Matplotlib display is interactive allowing zooming and pixel value picking.

Greyscale images are displayed in indexed mode: the image pixel value is mapped through the color map to determine the display pixel value. The colormap is specified by a string or else a Colormap subclass object. Valid strings are any valid matplotlib colormap names or

Colormap

Meaning

grey

zero is black, maximum value is white

inverted

zero is white, maximum value is black

signed

negative is red, 0 is white, positive is blue

invsigned

negative is red, 0 is black, positive is blue

random

random values

The argument block has the following functions

block

Action after display

False (default)

Call plt.show(block=False), don’t block

True

Call plt.show(block=True), block

None

Don’t call plt.show(), don’t block, in Jupyter subsequents plots will be added

t:float

Block for set time, calls plt.pause(t)

The coordformat function is called with (u, v) coordinates and the image is in the variable im which is in scope, but not passed, and is an ndarray(H,W) or ndarray(H,W,P).

Example:

>>> from machinevisiontoolbox import iread, idisp
>>> im, file = iread('monalisa.png')
>>> idisp(im)

Note

  • For grey scale images the minimum and maximum image values are mapped to the first and last element of the color map, which by default (‘grey’) is the range black to white. To set your own scaling between displayed grey level and pixel value use the vrange option.

References:

  • Robotics, Vision & Control for Python, Section 10.1, P. Corke, Springer 2023.

Seealso:

matplotlib.imshow cv2.imshow

machinevisiontoolbox.base.imageio.iread(filename, *args, **kwargs)[source]

Read image from file or URL

Parameters:

  • filename (str) – file name or URL

  • kwargs – key word arguments passed to convert

Returns:

image and filename

Return type:

tuple (ndarray, str) or list of tuples, image is a 2D or 3D NumPy ndarray

Loads an image from a file or URL, and returns the image as a NumPy array, as well as the absolute path name.

If the path is not absolute it is first searched for relative to the current directory, and if not found, it is searched for in the images folder of the `mvtb_data package <https://github.com/petercorke/machinevision-toolbox-python/tree/master/mvtb-data>`_.

If file is a list or contains a wildcard, the result will be a list of (image, path) tuples. They will be sorted by path.

The image can by greyscale or color in any of the wide range of formats supported by the OpenCV imread function. Extra options can be passsed to perform datatype conversion, color to grey scale conversion, gamma correction, image decimation or region of interest windowing. Details are given at convert.

Example:

>>> from machinevisiontoolbox import iread
>>> im, file = iread('flowers1.png')
>>> im.shape
(426, 640, 3)
>>> file[27:]
'/3.9.20/x64/lib/python3.9/site-packages/mvtbdata/images/flowers1.png'
>>> imdata = iread('campus/*.png')
>>> len(imdata)
2
>>> imdata[0][0].shape
(426, 640, 3)
>>> imdata[1][0][27:]
'/3.9.20/x64/lib/python3.9/site-packages/mvtbdata/images/campus/P1070491.png'

Note

  • A greyscale image is returned as an \(H \times W\) array

  • A color image is returned as an \(H \times W \times P\) array, typically \(P=3\) for an RGB or BGR image or \(P=4\) if there is an alpha plane, eg. RGBA.

  • wildcard lookup is done using pathlib Path.glob() and supports recursive globbing with the ** pattern.

References:

  • Robotics, Vision & Control for Python, Section 10.1, P. Corke, Springer 2023.

Seealso:

convert cv2.imread

machinevisiontoolbox.base.imageio.convert(image, mono=False, gray=False, grey=False, rgb=True, dtype=None, gamma=None, alpha=False, reduce=None, roi=None, maxintval=None, copy=False)[source]

Convert image

Parameters:

  • image (ndarray(H,W), ndarray(H,W,P)) – input image

  • grey (bool or 'ITU601' [default] or 'ITU709') – convert to grey scale, default False

  • gray – synonym for grey

  • dtype (str) – a NumPy dtype string such as "uint8", "int16", "float32" or a NumPy type like np.uint8.

  • rgb (bool, optional) – force color image to RGB order, otherwise BGR

  • gamma (float or str) – gamma decoding, either the exponent of “sRGB”

  • alpha (bool) – allow alpha plane, default False

  • reduce (int) – subsample image by this amount in u- and v-dimensions

  • roi (array_like(4)) – region of interest: [umin, umax, vmin, vmax]

  • maxintval (int) – maximum integer value to be used for scaling

  • copy (bool) – guarantee that returned image is a copy of the input image, defaults to False

Returns:

converted image

Return type:

ndarray(H,W) or ndarray(H,W,N)

Peform common image conversion and transformations for NumPy images.

dtype controls the resulting pixel data type. If the image is a floating type the pixels are assumed to be in the range [0, 1] and are scaled into the range [0, maxintval]. If maxintval is not given it is taken as the maximum value of dtype.

Gamma decoding specified by gamma can be applied to float or int type images.

The grey/gray option converts a color image to greyscale and is ignored if the image is already greyscale. Note that this conversions requires knowledge of the color plane order specified by colororder. The planes are inverted by invertplanes before this step.

machinevisiontoolbox.base.imageio.iwrite(im, filename, colororder='RGB', **kwargs)[source]

Write NumPy array to an image file

Parameters:

  • filename (string) – filename to write to

  • colororder (str) – color order, defaults to “RGB”

  • kwargs – additional arguments, see ImwriteFlags

Returns:

successful write

Return type:

bool

Writes the image im to filename using cv.imwrite(), with **kwargs passed as options. The file type is taken from the extension in filename.

Example:

>>> from machinevisiontoolbox import iwrite
>>> import numpy as np
>>> image = np.zeros((20,20))  # 20x20 black image
>>> iwrite(image, "black.png")

Note

  • supports 8-bit greyscale and color images

  • supports uint16 for PNG, JPEG 2000, and TIFF formats

  • supports float32

  • image must be in BGR or RGB format

Seealso:

iread cv2.imwrite

machinevisiontoolbox.base.imageio.pickpoints(self, n=None, matplotlib=True)[source]

Pick points on image

Parameters:

  • n (int, optional) – number of points to input, defaults to infinite number

  • matplotlib (bool, optional) – plot using Matplotlib (True) or OpenCV (False), defaults to True

Returns:

Picked points, one per column

Return type:

ndarray(2,n)

Allow the user to select points on the displayed image.

For Matplotlib, a marker is displayed at each point selected with a left-click. Points can be removed by a right-click, like an undo function. middle-click or Enter-key will terminate the entry process. If n is given, the entry process terminates after n points are entered, but can terminated prematurely as above.

Note

Picked coordinates have floating point values.

Seealso:

idisp