0.0.2 release

CHANGES.md

@@ -1,5 +1,10 @@
 # Changes
 
+## 0.0.2 (2020-12-05)
+
+- FEATURE: `mplcairo` becomes an optional dependency. The `matplotlib` backend can fall back to its own `cairo` backend while also showing a warning.
+- DOCS: Package installation via `conda`
+
 ## 0.0.1 (2020-12-02)
 
 - Initial release.

README.md

@@ -1,11 +1,24 @@
 # BEWEGUNG
 
+*/bəˈveːɡʊŋ/ ([German, noun, feminine: motion/movement/animation](https://dict.leo.org/englisch-deutsch/bewegung))*
+
+[![docs_master](https://readthedocs.org/projects/bewegung/badge/?version=latest&style=flat-square "Documentation Status: master / release")](https://bewegung.readthedocs.io/en/latest/)
+[![license](https://img.shields.io/pypi/l/bewegung.svg?style=flat-square "LGPL 2.1")](https://github.com/pleiszenburg/bewegung/blob/master/LICENSE)
+[![status](https://img.shields.io/pypi/status/bewegung.svg?style=flat-square "Project Development Status")](https://github.com/pleiszenburg/bewegung/issues)
+[![pypi_version](https://img.shields.io/pypi/v/bewegung.svg?style=flat-square "pypi version")](https://pypi.python.org/pypi/bewegung)
+[![conda_version](https://anaconda.org/conda-forge/bewegung/badges/version.svg "conda version")](https://pypi.python.org/pypi/bewegung)
+[![pypi_versions](https://img.shields.io/pypi/pyversions/bewegung.svg?style=flat-square "Available on PyPi - the Python Package Index")](https://pypi.python.org/pypi/bewegung)
+
 ## Synopsis
 
-[`bewegung`](https://dict.leo.org/englisch-deutsch/bewegung) is a versatile video renderer, primarily targeting scientific visualizations of large quantities of data. Its core concepts are *sequences* and *layers*. Sequences describe a certain time span within a video and can overlap. Each sequence can hold multiple layers. Layers can be generated with [`cairo`](https://cairographics.org/), [`Pillow`](https://pillow.readthedocs.io), [`datashader`](https://datashader.org/), [`matplotlib`](https://matplotlib.org/) and `bewegung`'s internal drawing system [`DrawingBoard`](https://bewegung.readthedocs.io/en/latest/canvas.html). Final compositing of every video frame and video effects are implemented via `Pillow`. Video encoding is handled by `ffmpeg`. `bewegung` also includes a simple [vector algebra system](https://bewegung.readthedocs.io/en/latest/vectors.html) and a ["camera" for 3D to 2D projections](https://bewegung.readthedocs.io/en/latest/camera.html). `bewegung` is developed with ease of use, compute time and memory efficiency in mind.
+`bewegung` is a versatile video renderer, primarily targeting scientific visualizations of large quantities of data. Its core concepts are *sequences* and *layers*. Sequences describe a certain time span within a video and can overlap. Each sequence can hold multiple layers. Layers can be generated with [`cairo`](https://cairographics.org/), [`Pillow`](https://pillow.readthedocs.io), [`datashader`](https://datashader.org/), [`matplotlib`](https://matplotlib.org/) and `bewegung`'s internal drawing system [`DrawingBoard`](https://bewegung.readthedocs.io/en/latest/canvas.html). Final compositing of every video frame and video effects are implemented via `Pillow`. Video encoding is handled by `ffmpeg`. `bewegung` also includes a simple [vector algebra system](https://bewegung.readthedocs.io/en/latest/vectors.html) and a ["camera" for 3D to 2D projections](https://bewegung.readthedocs.io/en/latest/camera.html). `bewegung` is developed with ease of use, compute time and memory efficiency in mind.
 
 ## Installation
 
+`bewegung` can be installed both via ``conda`` and via ``pip``.
+
+### Via `pip`
+
 A bare minimum of `bewegung` can be installed with Python's package manager `pip`:
 
 ```bash
@@ -20,6 +33,16 @@ pip install -vU bewegung[all]
 
 Certain non-Python components must installed separately and before invoking the above command. [For detailed instructions, see documentation](https://bewegung.readthedocs.io/en/latest/installation.html). Most notably, `ffmpeg` should be installed for producing actual video files instead of video frames as individual files. See [download section](https://ffmpeg.org/download.html) of the `ffmpeg` project website for further instructions.
 
+### Via `conda`
+
+An almost complete installation can be triggered by running:
+
+```bash
+conda install -c conda-forge bewegung
+```
+
+Please note that [mplcairo](https://github.com/matplotlib/mplcairo), a dependency of `bewegung` and alternative backend for `matplotlib`, is currently not available via `conda` and must be installed manually. `bewegung` [does also work without `mplcairo` present](https://bewegung.readthedocs.io/en/latest/canvas.html#acceleratingmatplotlib) and falls back to the `cairo` backend of `matplotlib`.
+
 ## Example
 
 See [`demo.py`](https://github.com/pleiszenburg/bewegung/blob/master/demo/demo.py).

docs/canvas.rst

@@ -337,6 +337,10 @@ Aside from its rich set of features, ``matplotlib`` is known for its mediocre pe
 .. _mplcairo: https://github.com/matplotlib/mplcairo
 .. _different backends for rendering: https://matplotlib.org/faq/usage_faq.html#what-is-a-backend
 
+.. warning::
+
+    If ``mplcairo`` can not be installed or is not present for whatever reason, ``bewegung`` will show a warning and fall back to ``matplotlib``'s internal ``cairo`` backend.
+
 In animation frameworks for ``matplotlib``, such as the "official" `matplotlib.animation`_ sub-package, it is common practice to re-use and update existing figure and subplot / axes objects. This speeds up the rendering process considerably. This strategy is also supported by ``bewegung``.
 
 .. warning::

docs/installation.rst

@@ -4,6 +4,17 @@ Installation
 Quick Install Guide
 -------------------
 
+`bewegung` can be installed both via ``conda`` and via ``pip``. In principle, ``bewegung`` works across all modern operating systems.
+
+.. note::
+
+    In terms of memory usage and performance, ``bewegung`` behaves best on Unix-like systems due to `Windows's lack of "fork"`_.
+
+.. _Windows's lack of "fork": https://stackoverflow.com/q/985281/1672565
+
+Via ``pip``
+~~~~~~~~~~~
+
 ``bewegung`` can be installed with Python's package manager ``pip``:
 
 .. code:: bash
@@ -24,18 +35,29 @@ All further Python dependencies are optional and allow to use certain optional c
 
     Certain **non-Python components must installed separately and before invoking the above command**. For further instructions, see :ref:`detailed installation instructions <detailedinstallation>`. Most notably, ``ffmpeg`` should be installed for producing actual video files instead of video frames as individual files.
 
-In principle, ``bewegung`` works across all modern operating systems.
+Via ``conda``
+~~~~~~~~~~~~~
+
+An almost complete installation can be triggered by running:
+
+.. code:: bash
+
+    conda install -c conda-forge bewegung
 
 .. note::
 
-    In terms of memory usage and performance, ``bewegung`` behaves best on Unix-like systems due to `Windows's lack of "fork"`_.
+    `mplcairo`_, a dependency of ``bewegung`` and alternative backend for ``matplotlib``, is currently not available via ``conda`` and must be installed manually. ``bewegung`` :ref:`does also work without mplcairo present <acceleratingmatplotlib>` and falls back to the ``cairo`` backend of ``matplotlib``.
 
-.. _Windows's lack of "fork": https://stackoverflow.com/q/985281/1672565
+.. _mplcairo: https://github.com/matplotlib/mplcairo
 
 .. _detailedinstallation:
 
-Detailed Installation Options
------------------------------
+Detailed Installation Options (``pip``)
+---------------------------------------
+
+.. note::
+
+    This section is only relevant if you install ``bewegung`` with ``pip``.
 
 Video File Encoding
 ~~~~~~~~~~~~~~~~~~~
@@ -109,10 +131,14 @@ Dependencies:
 - ``numpy``
 - ``matploblib``
 - ``pycairo``
-- ``mplcairo``
+- ``mplcairo`` (optional, but :ref:`highly recommended <acceleratingmatplotlib>`)
 
 The `cairo library`_ and its headers must be installed, see `pycairo's documentation`_.
 
+.. note::
+
+    If ``mplcairo`` can not be installed or is not present for whatever reason, ``bewegung`` will show a warning and fall back to ``matplotlib``'s internal ``cairo`` backend.
+
 Faster Camera
 ~~~~~~~~~~~~~
 

src/bewegung/__init__.py

@@ -28,7 +28,7 @@
 # EXPORT
 # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-__version__ = '0.0.1'
+__version__ = '0.0.2'
 
 from .core.camera import Camera
 from .core.backends import *

src/bewegung/core/backends/matplotlib.py

@@ -29,8 +29,9 @@
 # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 from typing import Any, Callable
+import warnings
 
-from PIL.Image import Image, fromarray
+from PIL.Image import Image, fromarray, frombuffer, merge
 
 from ._base import BackendBase
 from ..abc import ColorABC, NumberTypes, VideoABC
@@ -51,6 +52,8 @@ def __init__(self):
 
         self._plt, self._Figure = None, None
 
+        self._mplcairo_present = False
+
     def _prototype(self, video: VideoABC, **kwargs) -> Callable:
 
         if 'dpi' not in kwargs.keys():
@@ -97,9 +100,18 @@ def _isinstance(self, obj: Any) -> bool:
 
     def _load(self):
 
-        import mplcairo.base # import before matplotlib
+        try:
+            import mplcairo.base # import before matplotlib
+            self._mplcairo_present = True
+        except ModuleNotFoundError:
+            warnings.warn('`mplcairo` matplotlib backend is not installed, falling back to `cairo`')
+
         import matplotlib
-        matplotlib.use("module://mplcairo.base", force = True) # use mplcairo.base as non-GUI backend
+        matplotlib.use(
+            "module://mplcairo.base" if self._mplcairo_present else "cairo",
+            force = True,
+        ) # use mplcairo.base as non-GUI backend
+
         import matplotlib.pyplot as plt # import pyplot last
         from matplotlib.figure import Figure
 
@@ -110,12 +122,26 @@ def _load(self):
 
     def _to_pil(self, obj: Any) -> Image:
 
-        obj.canvas.draw()
+        if self._mplcairo_present:
+
+            obj.canvas.draw()
+
+            buffer = obj.canvas.renderer.buffer_rgba()
+            assert buffer.dtype.name == 'uint8' # TODO cairo & mplcairo also support RGBA128F
+
+            image = fromarray(buffer) # depends on matplotlib backend - https://stackoverflow.com/q/57316491/1672565
+
+        else:
 
-        buffer = obj.canvas.renderer.buffer_rgba()
-        assert buffer.dtype.name == 'uint8' # TODO cairo & mplcairo also support RGBA128F
+            surface = obj.canvas._get_printed_image_surface() # returns ARGB32 cairo surface
 
-        image = fromarray(buffer) # depends on matplotlib backend - https://stackoverflow.com/q/57316491/1672565
+            image = frombuffer(
+                mode = 'RGBa',
+                size = (surface.get_width(), surface.get_height()),
+                data = surface.get_data().tobytes(), # call to "tobytes" required because of RGBa mode
+                )
+            b, g, r, a = image.split()
+            image = merge('RGBa', (r, g, b, a)).convert("RGBA")
 
         if hasattr(obj, '__bewegung_managed__'): # close flagged image
             self._plt.close(obj)