0.0.6 release

.gitignore

@@ -15,3 +15,7 @@ test/
 *pleiszenburg*
 _build/
 MATERIAL/
+.hypothesis/
+.coverage
+.pytest_cache/
+htmlcov/

CHANGES.md

@@ -1,5 +1,32 @@
 # Changes
 
+## 0.0.6 (2021-11-07)
+
+Highlights: Major overhaul of linear algebra functionality, better package structure and a test suite.
+
+- FEATURE: All vector and vector array classes expose `ndim`, number of dimensions.
+- FEATURE: Common base class, `Vector`, for all vector classes.
+- FEATURE: Common base class, `VectorArray`, for all vector array classes.
+- FEATURE: Vector arrays are iterators.
+- FEATURE: Added missing right-hand-side operators to `Vector` and `VectorArray` classes.
+- FEATURE: Tuple export of `VectorArray` types can optionally provide direct access to underlying ``ndarray``s, i.e. new ``copy`` parameter can be set to ``False``.
+- FEATURE: 3D vectors and vector arrays can export geographic coordinates.
+- FEATURE: The `Color` class, using RGBA internally, can now import HSV values.
+- FEATURE: Added equality check, "is close" check, tuple export and copy to `Matrix`.
+- FEATURE: Added new `MatrixArray` class.
+- FEATURE: New dedicated sub-module for core animation engine named `bewegung.animation`.
+- FEATURE: New dedicated sub-module for `DrawingBoard` named `bewegung.drawingboard`, now allowing direct import.
+- FEATURE: New dedicated sub-module for linear algebra named `bewegung.lingalg`.
+- FEATURE: All linear algebra classes have consistent dtype and error handling.
+- FEATURE: Cleanup of internal type hierarchy.
+- FEATURE: Added test suite with some initial tests, based on `pytest`, `hypothesis` and `coverage`.
+- API CHANGE: Vector array method `update_from_vector` renamed to `update_from_vectorarray`.
+- API CHANGE: `Vector2Ddist` and `VectorArray2Ddist` removed in favor of meta data dictionaries within all vector, vector array, matrix and matrix array classes.
+- FIX: Development dependency switched from unmaintained `python-language-server` to maintained fork `python-lsp-server`.
+- FIX: Imports in `contrib` were broken.
+- FIX: `test` target in `makefile` was broken.
+- FIX: `typeguard` was not really an optional dependency.
+
 ## 0.0.5 (2021-07-30)
 
 - FEATURE: Python 3.9 support.

README.md

@@ -21,6 +21,16 @@
 
 `bewegung` can be installed both via ``conda`` and via ``pip``.
 
+### 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`.
+
 ### Via `pip`
 
 A bare **minimum** of `bewegung` can be installed with Python's package manager `pip`:
@@ -37,16 +47,6 @@ pip install -vU bewegung[all]
 
 Certain non-Python **prerequisites** 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).
@@ -65,6 +65,6 @@ This resulting `video.mp4` file should look like this:
 
 See [documentation](https://bewegung.readthedocs.io).
 
-`bewegung`'s development status is "well-tested alpha". Its API should not be considered stable until the project is labeled "beta" or better, although significant changes are very unlikely.
+`bewegung`'s development status is "well-tested alpha". Its API should not be considered stable until the project is labeled "beta" or better.
 
 `bewegung` can be drastically accelerated by deactivating debugging features. See [relevant section in the documentation](https://bewegung.readthedocs.io/en/latest/performance.html#typecheckingperformance).

demo/demo.py

@@ -42,10 +42,9 @@
     Camera, Color, Video,
     Vector2D, Vector3D, VectorArray3D,
     FadeInEffect, FadeOutEffect,
-    backends,
     )
 
-DrawingBoard = backends['drawingboard'].type
+from bewegung.drawingboard import DrawingBoard
 
 # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # CONST
@@ -145,9 +144,9 @@ def project(self):
                 for line2d in self._lines2d
                 for a, b in zip(line2d[:-1], line2d[1:])
             ]
-            self._lines2d.sort(key = lambda item: item[0].dist, reverse = True)
-            minimum = self._lines2d[0][0].dist
-            maximum = self._lines2d[-1][0].dist
+            self._lines2d.sort(key = lambda item: item[0].meta['dist'], reverse = True)
+            minimum = self._lines2d[0][0].meta['dist']
+            maximum = self._lines2d[-1][0].meta['dist']
             self._factor = lambda x: (x - minimum) / (maximum - minimum)
 
         @FadeInEffect(v.time_from_seconds(4.0))
@@ -158,7 +157,7 @@ def project(self):
         )
         def wiremesh(self, canvas):
             for line in self._lines2d:
-                factor = self._factor(line[0].dist)
+                factor = self._factor(line[0].meta['dist'])
                 gray = round(64 + 191 * factor)
                 canvas.draw_polygon(
                     *line,

demo/demo_mpl.py

@@ -42,10 +42,9 @@
     Color, Video,
     Vector2D,
     FadeInEffect, FadeOutEffect,
-    backends,
     )
 
-DrawingBoard = backends['drawingboard'].type
+from bewegung.drawingboard import DrawingBoard
 
 # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # CONST

demo/demo_mpl_fast.py

@@ -42,10 +42,9 @@
     Color, Video,
     Vector2D,
     FadeInEffect, FadeOutEffect,
-    backends,
     )
 
-DrawingBoard = backends['drawingboard'].type
+from bewegung.drawingboard import DrawingBoard
 
 # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # CONST

docs/algebra.rst

@@ -1,7 +1,7 @@
 Linear Algebra
 ==============
 
-``bewegung`` offers a bunch of convenience classes for tasks related to linear algebra.
+``bewegung`` offers a number of *convenience* classes for tasks related to linear algebra. They are isolated into a distinct sub-module named ``bewegung.linalg``.
 
 .. note::
 
@@ -12,4 +12,5 @@ Linear Algebra
    :caption: The API in detail
 
    vectors
+   matrices
    camera

docs/camera.rst

@@ -1,7 +1,7 @@
 3D to 2D projections: A Camera
 ==============================
 
-``bewegung`` includes a `pin-hole camera`_ for simple 3D to 2D projections. In a nutshell, the a :class:`bewegung.Camera` object can convert a :class:`bewegung.Vector3D` object into a :class:`bewegung.Vector2Ddist` object given a location and direction in 3D space, i.e. the 3D vector is projected into a plane in 2D space. Because the "camera" is actually not a rendering system on its own, it simply adds meta information to the returned 2D vector: The absolute distance from the "pinhole" in 3D space to the vector in 3D space. This allows to (manually) implement various kinds of depth perception, e.g. backgrounds and foregrounds, in visualizations. The camera is a useful tool if e.g. multiple :ref:`drawing backends <drawing>` are combined within a single animation and some kind of common 3D visualization is required. A typical combination is :ref:`datashader <datashader>` for density distributions and :ref:`cairo <backendcairo>` for annotations on top, see :ref:`gallery <gallery>` for examples.
+``bewegung`` includes a `pin-hole camera`_ for simple 3D to 2D projections. In a nutshell, the a :class:`bewegung.Camera` object can convert a :class:`bewegung.Vector3D` object into a :class:`bewegung.Vector2D` object given a location and direction in 3D space, i.e. the 3D vector is projected into a plane in 2D space. Because the "camera" is actually not a rendering system on its own, it simply adds meta data (:attr:`bewegung.Vector.meta`) to the returned 2D vector: The absolute distance (``meta["dist"]``) from the "pinhole" in 3D space to the vector in 3D space. This allows to (manually) implement various kinds of depth perception, e.g. backgrounds and foregrounds, in visualizations. The camera is a useful tool if e.g. multiple :ref:`drawing backends <drawing>` are combined within a single animation and some kind of common 3D visualization is required. A typical combination is :ref:`datashader <datashader>` for density distributions and :ref:`cairo <backendcairo>` for annotations on top, see :ref:`gallery <gallery>` for examples.
 
 .. _pin-hole camera: https://en.wikipedia.org/wiki/Pinhole_camera
 

docs/drawingboard.rst

@@ -41,10 +41,10 @@ The ``DrawingBoard`` Class
 
 The ``DrawingBoard`` class makes use of :ref:`vectors <vectors>` and :ref:`colors <colors>`.
 
-.. autoclass:: bewegung.core.backends.drawingboard.core.DrawingBoard
+.. autoclass:: bewegung.drawingboard.DrawingBoard
     :members:
     :private-members:
 
 .. note::
 
-    The ``DrawingBoard`` class can, most efficiently, be accessed via ``bewegung.backends['drawingboard'].type``.
+    The ``DrawingBoard`` class can be imported from ``bewegung.drawingboard``.

docs/index.rst

@@ -39,7 +39,7 @@ bewegung - a versatile video renderer
 
 .. warning::
 
-    ``bewegung``'s development status is "**well-tested alpha**". Its API should not be considered stable until the project is labeled "beta" or better, although significant changes are very unlikely.
+    ``bewegung``'s development status is "**well-tested alpha**". Its API should not be considered stable until the project is labeled "beta" or better.
 
 .. toctree::
    :maxdepth: 2

docs/installation.rst

@@ -17,6 +17,21 @@ Quick Install Guide
 
 `bewegung` can be installed both via ``conda`` and via ``pip``.
 
+Via ``conda``
+~~~~~~~~~~~~~
+
+An almost complete installation can be triggered by running:
+
+.. code:: bash
+
+    conda install -c conda-forge bewegung
+
+.. note::
+
+    `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``.
+
+.. _mplcairo: https://github.com/matplotlib/mplcairo
+
 Via ``pip``
 ~~~~~~~~~~~
 
@@ -59,21 +74,6 @@ The actual installation of ``bewegung`` can now be triggered as follows:
 
     pip install -vU bewegung[all] # install bewegung
 
-Via ``conda``
-~~~~~~~~~~~~~
-
-An almost complete installation can be triggered by running:
-
-.. code:: bash
-
-    conda install -c conda-forge bewegung
-
-.. note::
-
-    `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``.
-
-.. _mplcairo: https://github.com/matplotlib/mplcairo
-
 Validate Installation
 ~~~~~~~~~~~~~~~~~~~~~
 

docs/layer_tasks.rst

@@ -23,6 +23,6 @@ The ``Layer`` Class
 
     Do not work with this class directly. Use the :meth:`bewegung.Video.layer` method instead.
 
-.. autoclass:: bewegung.core.layer.Layer
+.. autoclass:: bewegung.animation.Layer
     :members:
     :private-members:

docs/matrices.rst

@@ -0,0 +1,22 @@
+.. _matrices:
+
+Matrices and Matrix Arrays
+==========================
+
+``bewegung`` offers :ref:`matrices <matrix_single>` and :ref:`matrix arrays <matrix_array>`. Both of them work for 2x2 and 3x3 shapes. They are intended for simple tasks like rotations of :ref:`vectors <vector_single>` and :ref:`vector arrays <vector_array>`.
+
+.. _matrix_single:
+
+The ``Matrix`` Class
+--------------------
+
+.. autoclass:: bewegung.Matrix
+    :members:
+
+.. _matrix_array:
+
+The ``MatrixArray`` Class
+-------------------------
+
+.. autoclass:: bewegung.MatrixArray
+    :members:

docs/sequences.rst

@@ -5,7 +5,7 @@ Sequences
 
 A *sequence* is a *time-span within a video*. A sequence can hold multiple :ref:`prepare tasks <prepare_tasks>` and :ref:`layer tasks <layer_tasks>`. Every prepare task and layer task is evaluated once per video frame, if the video frames is *within the temporal boundaries* of the sequence.
 
-From a practical point of view, sequences are special user-defined and decorated classes. A user must not instantiate a sequence class. Prepare tasks and layer tasks are special, also decorated methods within those user-defined classes. If a constructor method is present in the user-defined sequence class, it is evaluated once per video rendering run (:meth:`bewegung.Video.render`). It is also (re-) evaluated if the video object is reset (:meth:`bewegung.Video.reset`). User-defined sequence classes are eventually "mixed" with the :class:`bewegung.core.sequence.Sequence` class. All of its methods and properties are therefore available in user-defined sequence classes. From a technical point of view, new classes are generated by making :class:`bewegung.core.sequence.Sequence` inherit from user-defined sequence classes.
+From a practical point of view, sequences are special user-defined and decorated classes. A user must not instantiate a sequence class. Prepare tasks and layer tasks are special, also decorated methods within those user-defined classes. If a constructor method is present in the user-defined sequence class, it is evaluated once per video rendering run (:meth:`bewegung.Video.render`). It is also (re-) evaluated if the video object is reset (:meth:`bewegung.Video.reset`). User-defined sequence classes are eventually "mixed" with the :class:`bewegung.animation.Sequence` class. All of its methods and properties are therefore available in user-defined sequence classes. From a technical point of view, new classes are generated by making :class:`bewegung.core.sequence.Sequence` inherit from user-defined sequence classes.
 
 The ``Video.sequence`` Decorator
 --------------------------------
@@ -19,5 +19,5 @@ The ``Sequence`` Class
 
     Do not work with this class directly. Use the :meth:`bewegung.Video.sequence` method instead.
 
-.. autoclass:: bewegung.core.sequence.Sequence
+.. autoclass:: bewegung.animation.Sequence
     :members:

docs/vectors.rst

@@ -3,29 +3,29 @@
 Vectors and Vector Arrays
 =========================
 
-``bewegung`` offers :ref:`vectors <vector_single>` and :ref:`vector arrays <vector_array>`. Both of them are available in 2D and 3D variants. In 2D space, there are additional variants exposing a "distance property". The distance can be used to describe a (relative) distance to a camera or observer, which is useful for various types of renderings. Finally, there is also a :ref:`matrix <matrix>` for simple tasks like rotations both in 2D and 3D space.
+``bewegung`` offers :ref:`vectors <vector_single>` and :ref:`vector arrays <vector_array>`. Both of them are available in 2D and 3D variants. Both vectors and vector arrays can interact with each other as well as with :ref:`matrices <matrices>`.
 
 .. note::
 
-    Besides simple vector algebra, a lot of ``bewegung``'s functions and methods expect geometric input using vector classes.
+    Besides simple vector algebra, a lot of ``bewegung``'s functions and methods expect geometric input using vector objects.
 
 .. _vector_single:
 
 Vector Classes
 --------------
 
-The vector classes describe individual vectors in 2D and 3D space. Vectors are "statically typed", use Python number types and can either have ``int`` or ``float`` components. The data type of a vector is exposed through its ``dtype`` property.
+The vector classes describe individual vectors in 2D and 3D space. Vectors are "statically typed", i.e. all components are of one single type, and use Python number types (sub-classes of ``numbers.Number``). The data type of a vector is exposed through its ``dtype`` property.
 
-The ``Vector2D`` class
-~~~~~~~~~~~~~~~~~~~~~~
+The ``Vector`` base class
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: bewegung.Vector2D
+.. autoclass:: bewegung.Vector
     :members:
 
-The ``Vector2Ddist`` class
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``Vector2D`` class
+~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: bewegung.Vector2Ddist
+.. autoclass:: bewegung.Vector2D
     :members:
 
 The ``Vector3D`` class
@@ -41,28 +41,20 @@ Vector Array Classes
 
 The vector array classes describe arrays of individual vectors in 2D and 3D space. Vector arrays are "statically typed" and use ``numpy`` arrays for storing data. Just like ``numpy.ndarray`` objects, they expose a ``dtype`` property.
 
-The ``VectorArray2D`` class
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``VectorArray`` base class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: bewegung.VectorArray2D
+.. autoclass:: bewegung.VectorArray
     :members:
 
-The ``VectorArray2Ddist`` class
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``VectorArray2D`` class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: bewegung.VectorArray2Ddist
+.. autoclass:: bewegung.VectorArray2D
     :members:
 
 The ``VectorArray3D`` class
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: bewegung.VectorArray3D
     :members:
-
-.. _matrix:
-
-The ``Matrix`` Class
---------------------
-
-.. autoclass:: bewegung.Matrix
-    :members:

makefile

@@ -5,17 +5,20 @@ black:
 clean:
 	-rm -r build/*
 	-(cd docs/; make clean)
-	find src/ docs/ -name '*.pyc' -exec rm -f {} +
-	find src/ docs/ -name '*.pyo' -exec rm -f {} +
-	find src/ docs/ -name '*~' -exec rm -f {} +
-	find src/ docs/ -name '__pycache__' -exec rm -fr {} +
+	find src/ docs/ tests/ -name '*.pyc' -exec rm -f {} +
+	find src/ docs/ tests/ -name '*.pyo' -exec rm -f {} +
+	find src/ docs/ tests/ -name '*~' -exec rm -f {} +
+	find src/ docs/ tests/ -name '__pycache__' -exec rm -fr {} +
 	find src/ -name '*.htm' -exec rm -f {} +
 	find src/ -name '*.html' -exec rm -f {} +
 	find src/ -name '*.so' -exec rm -f {} +
 	find src/ -name 'octave-workspace' -exec rm -f {} +
 	-rm -r dist/*
 	-rm -r src/*.egg-info
 
+demo:
+	python demo/demo.py
+
 docs:
 	@(cd docs; make clean; make html)
 
@@ -36,8 +39,12 @@ upload:
 	done
 
 test:
-	-rm -r frames/
-	mkdir frames
-	python demo.py
+	make docs
+	make test_quick
+
+test_quick:
+	make clean
+	HYPOTHESIS_PROFILE=dev pytest --cov=bewegung --cov-config=setup.cfg --hypothesis-show-statistics # --capture=no
+	coverage html
 
-.PHONY: clean docs release test
+.PHONY: clean demo docs release test