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:

G’MIC-Py <-> Python world: the vision // Q4 2020

Here is a short post to share our team’s vision for the G’MIC Python binding till end of December 2020.

The G’MIC C++ library offers nice things for 2020:

  • a domain-specific language (DSL) for image processing, it is used mostly for calling simple G’MIC commands or defining new filters. Its learning curve is not a fast one though.
  • a sound pixel storage capacity (32-bits, 3D-4D) and OpenMP parallelization.
  • state-of-the-art filters, non-machine-learning-based style transfer, many interesting noise and denoise filters… for many field applications (arts, medical, science, engineering)…
  • a community-contributed filters database, which can be updated locally thanks to the “update” command, without reinstall needed.

Those are enough strengths for various Pythonists to be jealous of G’MIC!! So, what we want is Python developers from many sectors, likely already using other image processing libraries, video games or GUI toolkits, to dare integrating G’MIC within their workflows, as simply as possible, without forcing them to quit their usual tools and habits.

Foretaste of gmic-py 2.9.2
For this we have been developing lastly input and output conversion functions for the GmicImage type towards:

  • Numpy’s ndarray: gmic.GmicImage.to_numpy(), gmic.GmicImage.from_numpy(), gmic.GmicImage.to_numpy_helper(), gmic.GmicImage.from_numpy_helper(). Docs here.
  • PIL (or Pillow)'s Image type: gmic.GmicImage.to_PIL(), gmic.GmicImage.from_PIL(). Docs here.
  • Scikit-Image (aka skimage) numpy.ndarray using special matrix shaping: gmic.GmicImage.to_skimage(), gmic.GmicImage.from_skimage(). Docs here.

Additionally Jupyter/IPython/Google Colab shells now have support for G’MIC text output and image display redirections.

All this is on the verge of being finally stabilized and part of a 2.9.2 release. Though, we miss users for now. Thanks already go to two Twitter users (a french man and columbian woman) for testing out PIL <-> gmic-py conversion functions for style transfer, and for inspiring feature details for the skimage I/O functions.

For now the above converter functions are available from gmic-py 2.9.1-alpha5 for Linux platforms only.

Installing an gmic-py 2.9.1 alpha version for giving feedback
You can install that early release with:
pip install gmic==2.9.1-a5
and give feedback:

November-december 2020 gmic-py plan
After releasing a stable gmic-py version with the above changes this or next week, we will keep you posted with simple examples and tutorials, till the end of december 2020!
After then… public funding to have me full-time on gmic-py will 99 percent sure reach its end :slight_smile:

Thanks for reading and using G’MIC and gmic-py!!
Keep you updated!!!

1 Like

Google Colab (currently based on Ubuntu 18.04 LTS) can install this with !pip install gmic and thus use 2.9.2 version.

Convenient for testing whilst on the go.


It’s been a while since we’ve seen jayprich — their last post was 5 years ago.

James, welcome back in the business :slight_smile:
So good to have you here !

1 Like

YAY thank you for testing!!!

1 Like

you can actually skip the display.Image step by appending display at the end of your gmic command string in“your command display”) like so.

Aha yes, ; ) interactive! Here on Google Colab it runs headless in the cloud and renders on my phone’s browser.

1 Like

Thank you … I do always come back to browse PIXLS & use G’MIC.

Neat! Reminds of how I made Github Actions to compile the gmic-py module from a smartphone while travelling in Prague. Lazy is clever.

Windows support is on the way

some news about this gmic-py Python binding: I am currently working on the Windows support. That is to say that I am trying to build precompiled gmic-py wheel files, which allow anyone to run pip install gmic on Windows, without needing to compile anything. For now the target version is Python 3.8 I think, and possibly next week I will extend to versions 3.6-3.9.
Right now I am facing issues with bundling required .dll files into the .whl file, so that Windows Python users do not have to install any extra libraries.
The official recently updated G’MIC Windows compiling instructions using the MSYS2 environment have been very useful in that regard, as well as @PHartsuyker on Twitter for helping to pave the first steps.

If you want to track what is happening technically, here is the related Github pull request and the related issue.

Thanks early Linux testers!

I would like also to express how thankful I am to early Linux testers of gmic-py, namely @ginimod, @jayprich, @lesolorzanov ! Feel free to ask for precise example ideas and tutorials! I have noticed a certain struggle to build proper style transfer G’MIC commands.

1 Like

Windows wheels WIP

Windows Python wheels building is still on the way… chances are they will be built partly by hand or by running several scripts in chain for a first release. This pain stems from the fact that there is no simple auditwheel repair or delocate tool for Windows on or as a standalone script. (Unless I am mistaken).

Here is the related [cibuildwheel]( windows support issue), as well as a hopefully promising wheel repair pull request before moving to an independent Git project.

@PHartsuyker has been nice in testing things so far.

On avoiding G’MIC GUI-dedicated commands for non-GUI or stability-needing software applications or artistic pipelines

After a chat with @David_Tschumperle I wrote this tiny Gist article on why fx_ and _ prefixed commands should be avoided in your G’MIC production scripts, where parameters stability is required.

If the idea of it were already stated on the Internet, it is not bad to have it expressed twice, in a different manner :slight_smile:

If you lack time, you may just linger a few seconds on the short TL;DR paragraph :slight_smile:

First tutorial preview - for G’MIC or Python beginners

A first tutorial for ultra-beginners with the G’MIC language, coming from a Python background or the opposite, has just been written here:

I will write the markdown counterpart for our website soon. Though that Python file is probably very easy to read and ready to be run on Linux after a pip install gmic.

Your early feedback is much appreciated!!
Related Github issue:

Just one little note: Some people like myself prefer gui instead of fx since I find that it’s more direct.