Developing and Fiddling with the G'MIC Python Binding

The official G’MIC Python binding also named gmic-py has been in development since November 2019. Here are some inside news and creations. Come, try, suggest, discuss!


Here is a hello world in G’MIC Python !

First, install the gmic-py package inside your virtual environment. Available packages are also listed here on This shall work for Linux and MacOS only for now. Windows support will come before the end of the year 2020.

pip install gmic

At this time, it will get gmic-2.9.0 without OpenCV support (for lighter packages).

Then just use<my command>) instead of the usual "gmic " command-line tool which may already know."200,200,1,3 text \"HELLO WORLD\",50%,50%,13,1,255,147,23 display")

is equivalent to the command-line tool call:
gmic 200,200,1,3 text \"HELLO WORLD\",50%,50%,13,1,255,147,23 display

The display might be necessary if you see no window popping up. Indeed, display any result outright is a feature of the command-line tool, while the G’MIC Python binding is a thin wrapper around the libgmic C++ library, shared by both pieces of software.

The result is this window:

And your Python shell will also output this message (if you are using an IPython/Jupyter, note that image display and messages output is being worked on on Github (here and there) and should land in gmic-py 2.9.1):

[gmic]-1./ Display image [0] = '[unnamed]', from point (100,100,0).
[0] = '[unnamed]':
  size = (200,200,1,3) [468 Kio of floats].
  data = (0,0,0,0,0,0,0,0,0,0,0,0,(...),0,0,0,0,0,0,0,0,0,0,0,0).
  min = 0, max = 255, mean = 0.626875, std = 11.3214, coords_min = (0,0,0,0), coords_max = (100,103,0,0).

That’s it for a hello world!! Congratulations !!!

Here is something more Pythonic example… What about making a nice frame out of an online random image placeholder service?

Internally, G’MIC uses libcurl to download data from the internet… You may also know that putting a URL or a file path within a G’MIC command equates to asking G’MIC to use it as a media input file.

Local file input example:
myfile.png (or myfile.png display) will open the file directly
Web address input example:
gmic (ie. the command-line version; for Python G’MIC use instead, remove the gmic word and possibly append display).

Now, G’MIC by default does not download with HTTP redirect support - it seems so. So let use a super robust Python library instead for this (something similar to libcurl), named requests:
pip install requests is a nice placeholder service. Random images can be generated at anytime from there (although G’MIC has its own samples as well, using the sample or sp command).
Visiting will yield a random placeholder image with a width of 200 and height of 300.

Unfortunately for a simple downloading robot, there is a redirection that will lead such a URL to At this G’MIC’s cURL settings seemed not 100% reliable for me today… But no problem, Python :snake: can help!!

What we want is to make a frame out of random height and width images thanks to this Picsum photos online API!

Here is a typical Python script for that, using both requests for file download with HTTP redirection support and our most famous gmic module.

import gmic # do not forget to `pip install gmic` first!
import random
import requests

output_filename = "myframe.png"
max_images = 70
filenames = []
for a in range(max_images):
    url = "{}/{}".format(random.randint(50, 200), random.randint(50,200))
    filename = "picsum{}.png".format(a)
    myfile = requests.get(url, allow_redirects=True)
    with open(filename, 'wb') as f:

gmic_command = "{} frame 3,3,0 frame 3,3,255 montage A display output {}".format(" ".join(filenames), output_filename)

Here you are, a beautiful frame out of 70 random images with random sizes!!!
Print it and hang it in your kitchen if you like it!!

Congratulations and see you another time for another G’MIC Python tutorial!! :tiger: :sweat_smile:

Code files for the above 2 mini-tutorials are now on Github in the master branch:

The G’MIC Python binding is intended for two kind of users: scientists and artists.

Here is ongoing work on tuning gmic-py for scientists: the bindings now displays images and console output in a Jupyter / IPython notebook even with no operating system display available - for Linux only for now or probably MacOS as well. This should be released as part of gmic-py 2.9.1 (1 version number behind G’MIC 2.9.2 today). Image that before your gmic-py commands in such environments were not displaying any text or visual output…

Below is gmic-py within a Jupyter (local) notebook, using the Javascript Matplotlib notebook (otherwise gmic will use a non-interactive Matplotlib plot or IPython image)

Here is how it looks like in a Jupyter Qt Console (with the G’MIC window display by default):

And without a DISPLAY enabled (a bit nonsense for a Qt window, I agree), leveraging the Matplotlib renderer:

The related Github issues are number 63 and 64.

The other big milestone is numpy.ndarray <=> gmic.GmicImage input and output support. This is a work in progress and will be showcased in a different post :tiger:

That’s it for a little preview !

Hey! gmic-py 2.9.1 the Python binding for G’MIC has been released undercover today for Linux with many non-passing unit tests, to ensure that remote IPython web interfaces do accept to install the package and have this double feature working of a) G’MIC output redirection and b) G’MIC Display transformation. This version is in alpha1 quality…

The result today is YES, output and display do work on online Python notepad services.

See on Google Colab and Jupyter Lab (the new name for Jupyter Notebook) below:

You can actually test it as well on your computer within a web browser or some desktop IPython/Jupyter etc application, with this exact install command:
pip install gmic==2.9.1-alpha1
(Python >=3.6 <=3.8)

Happy testing!
If you at least manage to pip install gmic on your OS (a Linux or Mac OS), feel free to give little feedback!! We do not know who uses or would like to use G’MIC for Python more or less often for now.

Coming up next
The next step is to make the tests suite green and stabilize the GmicImage to/from_numpy_array() methods’ presets for input/output with various Numpy-based scientifical packages (Numpy raw, Scikit image, PIL).
:tiger: + :snake: = :slightly_smiling_face:

1 Like

Cool, this opens up many possibilities. :+1: