Image input/output operations#

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

Low-level image reading from files, URLs, and byte buffers.

convert(image: ndarray, mono: bool = False, gray: bool = False, grey: bool = False, rgb: bool = True, dtype: str | type | None = None, gamma: float | str | None = None, alpha: bool = False, reduce: int | None = None, roi: tuple[int, int, int, int] | list[int] | None = None, maxintval: int | None = None, copy: bool = False) → ndarray[source]#

Convert image

Parameters:

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

  • mono (bool, optional) – convert to grey scale, synonym for grey

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

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

idisp(im: ndarray, colororder: str = 'RGB', matplotlib: bool = True, block: bool | float | None = None, fps: float | None = None, fig: Any = None, ax: Any = None, reuse: bool = False, colormap: str | Any = None, ncolors: int | None = None, black: int | float = 0, darken: float | bool | None = None, powernorm: bool = False, gamma: float | None = None, vrange: tuple[float, float] | list[float] | None = None, badcolor: str | None = None, undercolor: str | None = None, overcolor: str | None = None, title: str | None = None, grid: bool = False, axes: bool = True, axlabels: tuple[str, str] | list[str] = ('u (pixels)', 'v (pixels)'), gui: bool = True, frame: bool = True, plain: bool = False, colorbar: bool | dict[str, Any] = False, square: bool = True, width: float | None = None, height: float | None = None, flatten: bool = False, ynormal: bool = False, extent: tuple[float, float, float, float] | list[float] | None = None, coordformat: Callable[[float, float], str] | None = None, savefigname: str | None = None, **kwargs: Any) → Any[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 or dict, optional) – add colorbar to image, default False

  • axlabels (array_like(2), optional) – labels for axes, default “u (pixels)” and “v (pixels)”

  • 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

  • flatten (bool, optional) – flatten singleton dimensions before display, defaults to False

  • 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 interactively using OpenCV or Matplotlib (if matplotlib is True, default).

OpenCV

OpenCV is used to display the mage if matplotlib is False. The display is provided by the “HighGUI” module, and is not interactive. Overlay graphics cannot be displayed, but the draw_xxx() functions can be used to draw on the image prior to display.

Example:

from machinevisiontoolbox import iread, idisp
im, file = iread("monalisa.png", matplotlib=False)
idisp(im)

Most of the options apply to the Matplotlib case.

Matplotlib

The Matplotlib display is interactive allowing zooming and pixel value picking. Other graphics can be superimposed on the image using the Matplotlib plotting functions plot_xxx().

Example:

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

(Source code, png, hires.png, pdf)

_images/imageio-1.png

Color map

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, useful for seeing fine details

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.

Colorbar

Setting colorbar=True adds a colorbar to the image, which is a key for interpreting the colors in the image.

Alternatively, a dictionary of options can be passed to the colorbar function, eg. colorbar={'ticks': range(10)} which is passed through to Matplotlib’s colorbar method. The option xtick is not an actual colorbar option but it invokes colorbar.set_ticks to set custom tick labels for the colorbar. The value is a tuple of two lists, the first is the list of tick values, and the second is the list of tick labels. The lists must be the same length, and the tick values must be in the range of the color map.

Blocking behaviour

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 subsequent plots will be added

t (numeric)

Block for set time, calls plt.pause(t). See also fps option.

The coordformat function is called with (u, v) float 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). The function should return a string which is displayed in the figure window toolbar when the mouse is over the image. This allows you to display pixel values in any format you want.

Certain keys can be pressed while the image is displayed:

  • q will close the window

If pyclip is installed, the following clipboard keys are available:

  • c will copy the current pixel coordinates to the paste buffer as U,V

  • C will append the current pixel coordinates to the paste buffer, with a newline separator

  • v will copy the current pixel coordinates to the paste buffer as U,V,X

  • V will append the current pixel coordinates and pixel value to the paste buffer as U,V,X, with a newline separator

  • x will clear the paste buffer

Animation behaviour

Setting fps to a numeric value will cause the display to block for 1/fps seconds after each call to idisp, which allows for simple animations by calling idisp repeatedly in a loop. Note that by default a new figure is created each time, which is slow, so for animations you should set reuse=True to reuse the same figure and axes.

Note

  • The displayed pixel value is a scalar (int or float), or a tuple of scalars for multiplane/color images.

  • The string never ends with a newline, newlines only separate values, eg. U1,V1nU2,V2

  • The clipboard keys require that pyclip is installed.

References:
Seealso:

matplotlib.imshow cv2.imshow

iread(filename: str | Path, *args: Any, **kwargs: Any) → tuple[ndarray, str] | tuple[list[ndarray], list[str]][source]#

Read image from file or URL

Parameters:

  • filename (str) – file name or URL

  • args (tuple) – reserved positional arguments

  • kwargs (dict) – 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.

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 passed 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.12.13/x64/lib/python3.12/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.12.13/x64/lib/python3.12/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.

  • For wildcards this is an “eager” function, all images are read and returned in a list. If you want to read images one at a time, use the lazy companion function iread_iter.

  • Wildcard lookup is done using pathlib Path.glob() and supports recursive globbing with the ** pattern, as well as the usual *, ? and [abc] patterns, and includes hidden files (those starting with a dot) in the search results.

  • For URL input, the image is read directly from the URL without saving to a local file. The URL must start with “http://” or “https://”. Wildcard patterns are not supported for URLs.

References:
Seealso:

iread_iter convert cv2.imread

iread_iter(filename: str | Path, *args: Any, **kwargs: Any) → Iterator[tuple[ndarray, str]][source]#

Lazily read image(s) from local files.

Parameters:

  • filename (str or Path) – file name or wildcard path

  • args (tuple) – reserved positional arguments

  • kwargs (dict) – key word arguments passed to convert

Returns:

iterator yielding (image, path) tuples

Return type:

iterator of tuple(ndarray, str)

This function is the lazy companion to iread for local file input, and is useful when a wildcard matches many files. Images are decoded one-at-a-time as the iterator is consumed.

For wildcard patterns, file paths are sorted before iteration to preserve deterministic order compatible with iread.

Seealso:

iread convert cv2.imread

iwrite(im: ndarray, filename: str, colororder: str = 'RGB', **kwargs: Any) → bool[source]#

Write NumPy array to an image file

Parameters:

  • im (ndarray(H,W), ndarray(H,W,P)) – image to write

  • 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 cv2.imwrite(), passing any keyword arguments 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

pickpoints(self: Any, n: int | None = None, matplotlib: bool = True) → ndarray | None[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

safe_plt_show(block: bool | None = False) → None[source]#

Call matplotlib.pyplot.show while ignoring benign headless warnings.

In documentation builds and other headless contexts Matplotlib can use a non-interactive canvas such as Agg. Calling plt.show() there emits a user warning of the form FigureCanvas... is non-interactive, and thus cannot be shown. That warning is harmless for MVTB because the figure has already been rendered; it only becomes a problem when tooling promotes warnings to errors.

Parameters:

block (bool or None) – Matplotlib blocking flag; if None then show() is not called