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:

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.


  • 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


  • 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)"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 = []"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)