Skip to content

image_matrix

image_matrix(
    image_data_array: ndarray,
    cmap: str | list[str] | None = None,
    *,
    norm: bool | None = None,
    vmin: float | None = None,
    vmax: float | None = None,
    scale: float = 1,
    spacer: float = 1,
) -> PlotSpec

Show a grid of images, one per cell of a 2D object array.

Each cell holds a 2D (greyscale) or 3D (RGB or RGBA) image array, as geom_imshow takes, or None for an empty cell. Every column is as wide as its widest image and every row as tall as its tallest one.

Parameters:

  • image_data_array (ndarray) –

    2D numpy array of dtype=object whose cells are images.

  • cmap (str or list of str, default: None ) –

    Greyscale only: a color map name or a list of colors (see geom_imshow).

  • norm (bool, default: True ) –

    Greyscale only: stretch vmin..vmax to the full luminance range.

  • vmin (float, default: None ) –

    Greyscale only: the value range norm stretches.

  • vmax (float, default: None ) –

    Greyscale only: the value range norm stretches.

  • scale (float, default: 1 ) –

    Image size magnification; each cell is at least 50 x 50 px.

  • spacer (float, default: 1 ) –

    Pixels between images.

Returns:

  • PlotSpec –

    An empty plot of the grid's size with one inset per image (lets_plot returns a SupPlotsSpec built with ggbunch).

Raises:

  • SpecError –

    When image_data_array is not a 2D array or is empty, the grid is over 10000 px on a side, a cell is not a 2D or 3D array, or scale or spacer is not a finite number in range.

Examples:

>>> import numpy as np
>>> from ggrust.bistro import image_matrix
>>> rng = np.random.default_rng(42)
>>> matrix = np.empty((2, 3), dtype=object)
>>> for row in range(2):
...     for column in range(3):
...         matrix[row, column] = rng.integers(256, size=(32, 32, 3))
>>> plot = image_matrix(matrix, scale=2)

Greyscale images in a color map, over a fixed value range:

>>> grey = np.empty((1, 3), dtype=object)
>>> for column in range(3):
...     grey[0, column] = rng.random((32, 32)) * (column + 1) / 3
>>> plot = image_matrix(grey, cmap="magma", vmin=0, vmax=1, scale=3, spacer=6)

Greyscale images in a color map, over a fixed value range