# Numpy support¶

Numpy stands for “numeric Python” and is a very famous data processing library for scientists.
Since gmic-py 2.9.1, you can convert a `GmicImage`

from and to a `numpy.ndarray`

for simpler manipulation.
The numpy.ndarray type is used in turn by many graphics processing toolkits.

Numpy input/output support for gmic-py is broken down into 4 methods:

simplified input/output:

full-control, also used for PIL and Scikit-image support:

All those methods are fully documented in the API Reference. If you want to implement new gmic-py conversion methods for some library that uses numpy.ndarray`s a lot, you might just want to import and call the `*_numpy_helper methods with your own very parameters.

## Must-know¶

G’MIC works in 1D, 2D, 3D, or 4D. Numpy can work from 0D (scalar) to N dimensions (>4D).

G’MIC has the following array shapes’ dimension order:

`(width, height, depth, spectrum)`

. The`spectrum`

(or channels) dimension represents the number of values per pixel (eg. for RGB images,`spectrum=3`

). Numpy is shape-agnostic.G’MIC works in float32 (ie. 4-bytes float pixel values). Casts from and to numpy.ndarray will be done for you using numpy.ndarray.astype(). This can be tuned by parameter

`GmicImage().to_numpy_helper(astype=...)`

.G’MIC can store a few billions of values per pixel (eg. not just R,G,B,A).

G’MIC is not made for real-time image processing but is quite fast though :).

G’MIC stores pixel values internally in a non-interleaved format, eg.

`R,R,R,G,G,G,B,B,B`

for`(3,1,3)`

image shape.For now the shape is not altered between within input/output methods provided by G’MIC. To alter those, you can use either the permute= parameter or pre- or post-process you numpy array with a numpy transpose() call containing several axes.

`numpy`

is not a requirement for the G’MIC’s Python binding to install, start and work. But is must be installed if you happen to call the to_/from_/numpy_* methods.

```
pip install numpy
```

Use numpy.expand_dims and numpy.atleast_2d, numpy.atleast_3d, numpy.squeeze to fix your numpy arrays’s dimensions.

Advanced note: the compile flag for enabling or disabling numpy support in gmic-py is gmic_py_numpy (see setup.py).

## How-to¶

The usual way to convert a Numpy array to G’MIC is as follows:

```
pip install numpy
pip install gmic
```

```
import gmic
import numpy.random
arr = numpy.random.rand(512,256,3)
gmic_image_from_numpy = gmic.GmicImage.from_numpy(arr)
# You might have identically called gmic.GmicImage.from_numpy_helper(arr, deinterleave=True)
print(gmic_image_from_numpy)
gmic.run("display", gmic_image_from_numpy)
```

The usual way to convert a G’MIC Image to Numpy is as follows:

```
pip install numpy
pip install gmic
pip install matplotlib
```

```
import gmic
import numpy
from matplotlib import pyplot as plt
gmic_images = []
gmic.run("sp apples", gmic_images) # store apples image into our list
numpy_image_from_gmic = gmic_images[0].to_numpy()
# You might have identically called gmic.GmicImage.to_numpy_helper(arr, interleave=True)
print(numpy_image_from_gmic)
plt.imshow(numpy_image_from_gmic)
plt.show()
```