gmic 2.8.3

Binary Python3 bindings for the G'MIC C++ image processing library

Python binding for G'MIC - A Full-Featured Open-Source Framework for Image Processing

https://gmic.eu

---

gmic-py

The aim of this project is to provide an official Python 3 package of the G'MIC image processing library, with its platform-specific binaries bundled or auto-compiled. When this matures, running pip install gmic-py should be all you need to get ready and use G'MIC within data-science, games, video editing, texture editing etc.. Python scripts.

This project is a work in progress and lives under the CeCILL license (similar to GNU Public License).

Quickstart

You need Python 3.x and pip installed. Things work best with the last development version for now :)

pip install gmic # Consider adding --only-binary if your machine makes you compile from source
python3

import gmic
import struct
import random

random_32x32_image = gmic.GmicImage(struct.pack('1024f', *[random.randint(0, 255) for i in range(1024)]), 32, 32) 
random_32x32_image
# Output: <gmic.GmicImage object at 0x7f1084c41c90 with _data address at 0x2772010, w=32 h=32 d=1 s=1 shared=0>

gmic.run("print", images=random_32x32_image)
# Output:
# [gmic]-1./ Print image [0] = '[unnamed]'.
# [0] = '[unnamed]':
#   size = (32,32,1,1) [4096 b of floats].
#   data = (152,88,134,92,50,179,33,248,18,81,84,187,(...),54,42,179,121,125,74,67,171,224,240,174,96).
#   min = 0, max = 255, mean = 127.504, std = 75.1126, coords_min = (22,1,0,0), coords_max = (8,2,0,0).

# Reuse the same interpreter for better performance
reusable_gmic_instance = gmic.Gmic()
for a in range(10):
    reusable_gmic_instance.run("blur 2 print", images=random_32x32_image, image_names="my random blurred picture") # add "display" after "print" for a preview on Linux
# Output (first iteration only):
# [gmic]-1./ Print image [0] = 'my random blurred picture'.
# [0] = 'my random blurred picture':
#   size = (32,32,1,1) [4096 b of floats].
#   data = (146.317,134.651,125.137,117.714,115.019,118.531,121.125,123.81,121.736,120.603,123.06,130.212,(...),116.879,114.402,117.773,119.173,117.546,117.341,122.487,133.949,143.605,145.584,137.652,125.728).
#   min = 85.2638, max = 186.79, mean = 127.961, std = 11.9581, coords_min = (0,31,0,0), coords_max = (31,0,0,0).

Official platform support

You can build your own Gmic python binding on possibly any platform with a C/C++ compiler. Here is what we have managed to build and ship to Gmic PyPI page, allowing you to pip install gmic and use pre-built binaries or build gmic-py on the fly. Note that gmic-py's package installer links to your machine's existing libpng, OpenMP and libcURL if found.

Build target	Basic gmic-py0	libpng I/O	OpenMP	libcURL	OpenCV
Build from source1	✓	✓ 2	✓	✓ 2	✓ 2
DIY Linux 32&64bit 1	✓	✓ 2	✓	✓ 2	✓ 2
Pre-compiled Linux i686 & x86_64 py3.4-3.8 (gcc)m	✓	✓	✓	✗ 3	✗
Pre-compiled MacOS 64 py3.5-3.8 (clang)	✓	✓	✓	✓	✗
Windows (planned)w	✗	✗	✗	✗	✗

⁰ ie. gmic.GmicImage(bytes, w, h, d, s), gmic.run(..., "commands")

¹ ie. from this project's tarball or using pip install gmic with the (possibly default) "from source" option. Hack the setup.py if needed, should work well with just libz installed, preferably with libfftw3 too to support all sizes of images. Compiling with gcc or clang should work well.

² enabled if related library is found at compile time, using found pkg-config executable.

³ useful for samples retrieval and getting the latest filters collection updated; instead of linking against libcURL, any runtime-findable curl executable will be used, see this issue; at anytime, use the network 0 G'MIC command to disable internet access

^m those are actually manylinux2010 and manylinux2014 targets. Manylinux1 has been dropped

^w Until it is ready, you can try building you own gmic-py builds on Windows using MSYS2

Examples

Using your camera with G'MIC's optional OpenCV linking

If your machine has libopencv installed and your gmic-py was compiled from source (ie. python setup.py build), it will be dynamically linked.

Example script

Roadmap

Q4 2019

1. Create a pip install -e GITHUB_URL installable Python package for GMIC, with an API very similar to the C++ library: gmic_instance.run(...), gmic(...) and matching exception types. Binary dependencies should be bundled as in this tutorial.
   1. Through Ctypes dynamic binding on an Ubuntu docker image using Python 2-3. DONE in ctypes_archive branch.
   2. Through custom Python/C++ binding (see gmicpy.cpp and setup.py) DONE
2. Create documented examples for various application domains. WIP

Q1-Q2 2020

1. Move the package to official Python package repositories. DONE
2. Add numpy nparray I/O support with automatic values (de-)interlacing
3. Add Windows support
4. In a separate repository, create a Blender Plugin, leveraging the Python library and exposing:
5. a single Blender GMIC 2D node with a text field or linkable script to add a GMIC expression
6. as many 2D nodes as there are types of GMIC 'operators'

Q3-Q4 2020

1. In a separate repository, create a GMIC Inkscape plugin, leveraging the Python library (possibly applying only to image objects, as the Trace bitmap tool does).

Binding blueprint

This is an overview of how we want the gmic binding inner working:

from gmic import Gmic, run, Image, GmicException
#we give up the Gmic native List

class GmicException:
   def __init__(self, command, message):
       self.command = command
       self.message = message
   def what(self):
       pass
   def command_help(self):
       pass

class Gmic:
    def __init__(self, images=[]|tuple|iterable[Image], image_names=[]|tuple|iterable, include_stdlib=True, progress=None, is_abort=None):
        self._status = None
        self.include_stdlib = include_stdlib
        # TODO V2 = progress, is_abort
        if all params were given:
           self.run(images, image_names, include_stdlib, progress, is_abort)

    @throws GmicException
    def run(self, images=[], images_names=[], progress=None, abort=None):
        ....
        self._status = ""
        return self

    def _build_lists(self):
        self._build_gmic_images_list(self.images)
        self._build_gmic_images_names_list(self.image_names)

    def _build_gmic_images_list(self):
        """Convert and store to Gmic builtin C++ type"""
        pass

    def _build_gmic_images_names_list(self):
        """Convert and store to Gmic builtin C++ type"""
        pass

    @property
    def status(self):
       """ string result of last operation, or exception text if was raised, or user-entered text through a gmic command. 
       This is a read-only attribute, starting with underscore. See https://stackoverflow.com/a/15812738/420684
       :return str
       """
       return self._status


def run(images=[]|tuple|iterable[Image], image_names=[]|tuple|iterable[Image], include_stdlib=True, progress=None, is_abort=None):
    return Gmic(images, images_names, include_stdlib, progress, is_abort).run()