Skip to content

Commit

Permalink
#43 refreshing README and its badges
Browse files Browse the repository at this point in the history
  • Loading branch information
@myselfhimself
myselfhimself committed Aug 27, 2020
1 parent 958e4cc commit c3b9e8e
Showing 1 changed file with 32 additions and 76 deletions.
108 changes: 32 additions & 76 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,80 +8,53 @@
---------------------------

# gmic-py
[![PyPI download total](https://img.shields.io/pypi/dt/gmic.svg)](https://pypi.python.org/pypi/gmic/)
[![PyPI version shields.io](https://img.shields.io/pypi/v/gmic.svg)](https://pypi.python.org/pypi/gmic/)
[![PyPI license](https://img.shields.io/pypi/l/gmic.svg)](https://pypi.python.org/pypi/gmic/)
[![PyPI format](https://img.shields.io/pypi/format/gmic.svg)](https://pypi.python.org/pypi/gmic/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/gmic.svg)](https://pypi.python.org/pypi/gmic/)
[![PyPI implementation](https://img.shields.io/pypi/implementation/gmic.svg)](https://pypi.python.org/pypi/gmic/)
[![PyPI status](https://img.shields.io/pypi/status/gmic.svg)](https://pypi.python.org/pypi/gmic/)

![](https://github.com/myselfhimself/gmic-py/workflows/CPython%20GMIC%20Manylinux%202010%20%26%202014%20i686%20%26%20x86_64/badge.svg)
![](https://github.com/myselfhimself/gmic-py/workflows/CPython%20GMIC%20MacOS%20build/badge.svg)
![](https://github.com/dtschump/gmic-py/workflows/CPython%20GMIC%20Python%20package%20(Source%20and%20Debian/Ubuntu%20OS%20compilation)/badge.svg)
![CPython GMIC Optimized Python package (Source and Debian/Ubuntu OS compilation)](https://github.com/myselfhimself/gmic-py/workflows/CPython%20GMIC%20Optimized%20Python%20package%20(Source%20and%20Debian/Ubuntu%20OS%20compilation)/badge.svg)
![CPython GMIC Manylinux 2010 & 2014 x86_64 Optimized No-release](https://github.com/myselfhimself/gmic-py/workflows/CPython%20GMIC%20Manylinux%202010%20&%202014%20x86_64%20Optimized%20No-release/badge.svg)
![CPython GMIC Debug Python package (Source and Debian/Ubuntu OS compilation)](https://github.com/myselfhimself/gmic-py/workflows/CPython%20GMIC%20Debug%20Python%20package%20(Source%20and%20Debian/Ubuntu%20OS%20compilation)/badge.svg)
![CPython GMIC MacOS Optimized Build](https://github.com/myselfhimself/gmic-py/workflows/CPython%20GMIC%20MacOS%20Optimized%20Build/badge.svg)

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.
`gmic-py` is the official Python 3 binding for the [G'MIC C++ image processing library](https://gmic.eu) purely written with Python's C API.
Its Python package name on [pypi.org](https://pypi.org/project/gmic/) is just `gmic`.
This project lives under the CeCILL license (similar to GNU Public License).

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

## Documentation
Full documentation is being written at [https://gmic-py.readthedocs.io/](https://gmic-py.readthedocs.io/).
You can use the `gmic` Python module for projects related to desktop or server-side graphics software, numpy, video-games, image procesing.

[gmic-blender](https://github.com/myselfhimself/gmic-blender) is a Blender3d add-on bundling `gmic-py` and allowing you use a new `gmic` module from there without installing anything more.

## Quickstart
You need Python 3.x and `pip` installed.
Things work best with the last development version for now :)
First install the G'MIC Python module in your (virtual) environment.

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

G'MIC is a language processing framework, interpreter and image-processing scripting language.
Here is how to load `gmic`, and evaluate some G'MIC commands with an interpreter.
```python
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).
gmic.run("sp earth blur 4") # On Linux a window shall open-up with a blurred earth
gmic.run("sp rose fx_bokeh 3,8,0,30,8,4,0.3,0.2,210,210,80,160,0.7,30,20,20,1,2,170,130,20,110,0.15,0 output rose_with_bokeh.png") # Save a rose with bokeh effect to file
```

## 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](https://pypi.org/project/gmic/), 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-py<sup>0</sup> | ppm/bmp I/O | libpng I/O | OpenMP | libcURL | OpenCV |
| ----------- | ------------------------- | ----------- | ---------- |------- | ------- |-------- |
| Build from source<sup>1</sup> | ✓ | ✓ | ✓ <sup>2</sup> | ✓ | ✓ <sup>2</sup> | ✓ <sup>2</sup> |
| Github CI Ubuntu Linux 64bit <sup>1</sup> | ✓ | ✓ | ✓ <sup>2</sup> | ✓ | ✓ <sup>2</sup> | ✓ <sup>2</sup> |
| Pre-compiled Linux x86\_64 py3.6-3.9 (gcc)<sup>m</sup>| ✓ | ✓ | ✓ | ✓ | ✓ <sup>3</sup> | ✗ |
| Pre-compiled MacOS 64 py3.6-3.9 (clang) | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
| Windows (planned)<sup>w</sup> | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |

<sup>0</sup> ie. `gmic.GmicImage(bytes, w, h, d, s)`, `gmic.run(..., "commands")`

<sup>1</sup> 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.
Longer tutorials are available in the [documentation](https://gmic-py.readthedocs.io/).

<sup>2</sup> enabled if related library is found at compile time, using found `pkg-config` executable.

<sup>3</sup> useful for samples retrieval and getting the latest filters collection updated; libcurl is embedded in the wheel package. If failing, any runtime-findable `curl` executable will be used, see [this issue](https://github.com/myselfhimself/gmic-py/issues/9); at anytime, use the `network 0` G'MIC command to disable internet access
## Documentation
Full documentation is being written at [https://gmic-py.readthedocs.io/](https://gmic-py.readthedocs.io/).

<sup>m</sup> those are actually manylinux2010 and manylinux2014 targets. Manylinux1 has been dropped
## Supported platforms
`gmic-py` works for Linux and Mac OS x 64bits architecture x Python >= 3.6. Windows support is planned for Q4 2020.

<sup>w</sup> Until it is ready, you can try building you own gmic-py builds on Windows using [MSYS2](https://www.msys2.org/)
In case your environment is a type of Unix, but compiling from source is needed, note that the `pip` installer will download `gmic-py`'s source and most possibly compile it very well.
See the `CONTRIBUTING.md` file and the [documentation](https://gmic-py.readthedocs.io/) for tips on building `gmic-py` for your own OS.

## Examples

Expand All @@ -92,20 +65,3 @@ If your machine has `libopencv` installed and your gmic-py was compiled from sou

![Live example](examples/opencv-camera/gmic-py-opencv-camera.gif)

## 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](https://python-packaging-tutorial.readthedocs.io/en/latest/binaries_dependencies.html).
1. Through `Ctypes` dynamic binding on an Ubuntu docker image using Python 2-3. DONE in [ctypes\_archive branch](https://github.com/dtschump/gmic-py/tree/ctypes_archive).
1. Through custom Python/C++ binding (see `gmicpy.cpp` and `setup.py`) DONE
1. Create documented examples for various application domains. WIP

### Q1-Q3 2020
1. Move the package to official Python package repositories. DONE
1. Add numpy nparray I/O support with automatic values (de-)interlacing WIP
1. Add Windows support

### Q2-Q3 2020
1. In a separate repository, create a Blender Plugin, leveraging the Python library and exposing: DONE
1. a single Blender GMIC 2D node with a text field or linkable script to add a GMIC expression WIP
1. as many 2D nodes as there are types of GMIC filters and commands (500+)

0 comments on commit c3b9e8e

Please sign in to comment.