mthiboust/array2image

Converts a Numpy array to a PIL image.

Array2image

Array2image helps you convert Numpy arrays to PIL images. It comes with a single function array_to_image().

When given an array, it automatically guesses its spatial and channel dimensions. Spatial dimensions greater than 2 are considered as images of images. The resulting image is then represented differently depending on the channel dimension:

• 1D channel: greyscale image.
• 2D channel: image with varying hue and saturation.
• 3D channel: RGB image.

If specified, custom colormap functions can be used instead. For instance:

• matplotlib.cm.* functions for 1D channel arrays (like matplotlib.cm.viridis)
• colormap2d.* functions for 2D channel arrays (like colormap2d.pinwheel)
• The matplotlib.colors.hsv_to_rgb function for 3D channel arrays.`

It assumes that values are floats between 0 and 1 or integers between 0 and 255 (values are clipped anyway). If specified, it automatically normalizes the values.

Why not directly use matplotlib.plt.imshow instead? If you have 2D array with 1 or 3-channel data and don't care about the size nor the incrusted axis in the returned image, matplotlib.plt.imshow is great. The Array2image library makes the focus on simplicity by guessing an appropriate way of rendering non-generic arrays.

Installation

pip install array2image

Requires python 3.10+.

Documentation

Function signature

def array_to_image(
    arr,
    spatial_dims: tuple[int, ...] | None = None,
    channel_dim: int | None = None,
    cmap: Callable | None = None,
    inverted_colors: bool = False,
    bin_size: int | tuple[int, int] | None = None,
    target_total_size: int = 200,
    grid_thickness: int | tuple[int, ...] = 0,
    norm: bool = False,
) -> PIL.Image

Argument description

• arr: Array-like to be converted.
• spatial_dims: Spatial dimensions of the array. If None, spatial dimensions are automatically guessed.
• channel_dim: Channel dimension of the array. Only 1, 2 or 3 channel dimension arrays can be converted to an image. If None, the channel dimension is automatically guessed.
• cmap: Colormap function to be used if provided. If None, default built-in functions are used.
• inverted_colors: If True, inverts the color of the image.
• bin_size: Number of pixels for each array spatial element. target_total_size: Target size of the image. Used to automatically choose bin_size if the latter is None.
• grid_thickness: Tuple of grid thickness for each level of 2D spatial dimensions. By default, it is 0 for the last 2D dimensions and 2 pixels for the others.
• norm: If True, normalize values between 0 and 1 with a min-max normalization.

Examples

1-channel arrays

Data for the following examples:

import numpy as np

# Random data: A 2x4x10x8 Numpy array with random values between 0 and 1
np.random.seed(0)
array = np.random.uniform(0, 1, (2, 4, 10, 8))

# MNIST data: The first 48 MNIST digits organized in a 6x8 grid.
mnist_data = ...
array = mnist_data[:48].reshape(6, 8, 28, 28)

	Random	MNIST
from array2image import array_to_image # Represent only a 4D array image = array_to_image(array)
from array2image import array_to_image # Force 0 pixel for all grid levels image = array_to_image( array, grid_thickness=(0, 0) )
from array2image import array_to_image # Invert colors image = array_to_image( array, inverted_colors=True )
from array2image import array_to_image import matplotlib # Use an external colormap image = array_to_image( array, cmap=matplotlib.cm.viridis )
from array2image import array_to_image import matplotlib # Represent only a 2D array image = array_to_image( array[0, 0], cmap=matplotlib.cm.viridis )
from array2image import array_to_image import matplotlib # Show a grid image = array_to_image( array[0, 0], cmap=matplotlib.cm.viridis, grid_thickness=1 )
from array2image import array_to_image # Fix the bin size image = array_to_image( array[0, 0], bin_size=4 )
from array2image import array_to_image # Fix a specific asymetric bin size image = array_to_image( array[0, 0], bin_size=(4,8) )

2-channel arrays

Data for the following examples:

import numpy as np

# Random data: A 10x10x2 Numpy array with random values between 0 and 1
np.random.seed(0)
array = np.random.uniform(0, 1, (10, 10, 2))

# Dummy fourier data: linearly varying phase and magnitude over a 2D grid
phase, amplitude = np.meshgrid(np.linspace(0,1,10), np.meshgrid(np.linspace(0,1,10)))
array = np.stack((phase, amplitude), axis=-1)

	Random	Fourier
from array2image import array_to_image # Default Hue/Saturation colormap image = array_to_image(array)
from array2image import array_to_image import colormap2d # External 2D colormap array_to_image( array, cmap=colormap2d.pinwheel )

3-channel arrays

Data for the following examples:

import numpy as np

# Random data: A 10x10x3 Numpy array with random values between 0 and 1
np.random.seed(0)
array = np.random.uniform(0, 1, (10, 10, 3))

# The Lena RGB image
image = Image.open("lena.png")
array = np.asarray(image)

	Random	Lena
from array2image import array_to_image # Default RGB colormap image = array_to_image(array)
from array2image import array_to_image import matplotlib # External 3D colormap array_to_image( array, cmap=matplotlib.colors.hsv_to_rgb )