diff --git a/README.md b/README.md index 84f478cc..7496b0cf 100644 --- a/README.md +++ b/README.md @@ -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.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-py0 | ppm/bmp I/O | libpng I/O | OpenMP | libcURL | OpenCV | -| ----------- | ------------------------- | ----------- | ---------- |------- | ------- |-------- | -| Build from source1 | ✓ | ✓ | ✓ 2 | ✓ | ✓ 2 | ✓ 2 | -| Github CI Ubuntu Linux 64bit 1 | ✓ | ✓ | ✓ 2 | ✓ | ✓ 2 | ✓ 2 | -| Pre-compiled Linux x86\_64 py3.6-3.9 (gcc)m| ✓ | ✓ | ✓ | ✓ | ✓ 3 | ✗ | -| Pre-compiled MacOS 64 py3.6-3.9 (clang) | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | -| Windows (planned)w | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | - -0 ie. `gmic.GmicImage(bytes, w, h, d, s)`, `gmic.run(..., "commands")` - -1 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/). -2 enabled if related library is found at compile time, using found `pkg-config` executable. - -3 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/). -m 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. -w 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 @@ -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+)