https://github.com/mthiboust/array2image
Converts a Numpy array to a PIL image.
https://github.com/mthiboust/array2image
array data-visualization image numpy pillow plotting python
Last synced: about 1 month ago
JSON representation
Converts a Numpy array to a PIL image.
- Host: GitHub
- URL: https://github.com/mthiboust/array2image
- Owner: mthiboust
- License: apache-2.0
- Created: 2023-11-16T14:39:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-11-22T08:57:46.000Z (over 2 years ago)
- Last Synced: 2025-09-25T08:24:31.275Z (9 months ago)
- Topics: array, data-visualization, image, numpy, pillow, plotting, python
- Language: Python
- Homepage:
- Size: 993 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
pip install array2image
```
Requires python 3.10+.
# Documentation
### Function signature
```python
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:
```python
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
```python
from array2image import array_to_image
# Represent only a 4D array
image = array_to_image(array)
```
```python
from array2image import array_to_image
# Force 0 pixel for all grid levels
image = array_to_image(
array,
grid_thickness=(0, 0)
)
```
```python
from array2image import array_to_image
# Invert colors
image = array_to_image(
array,
inverted_colors=True
)
```
```python
from array2image import array_to_image
import matplotlib
# Use an external colormap
image = array_to_image(
array,
cmap=matplotlib.cm.viridis
)
```
```python
from array2image import array_to_image
import matplotlib
# Represent only a 2D array
image = array_to_image(
array[0, 0],
cmap=matplotlib.cm.viridis
)
```
```python
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
)
```
```python
from array2image import array_to_image
# Fix the bin size
image = array_to_image(
array[0, 0],
bin_size=4
)
```
```python
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:
```python
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
```python
from array2image import array_to_image
# Default Hue/Saturation colormap
image = array_to_image(array)
```
```python
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:
```python
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
```python
from array2image import array_to_image
# Default RGB colormap
image = array_to_image(array)
```
```python
from array2image import array_to_image
import matplotlib
# External 3D colormap
array_to_image(
array,
cmap=matplotlib.colors.hsv_to_rgb
)
```
