added decorator for dynamic plots

Author: tomvanmele

docs/_images/tutorial/plotters_dynamic.gif

@@ -290,8 +290,66 @@ Vectors
 Dynamic Plots
 =============
 
+Dynamic plots, or animations, can be made with the "on" decorator :meth:`compas_plotters.Plotter.on`.
+Simply add the decorator to a callback functions that updates the geometry in the plot at a specified interval.
+
+.. code-block:: python
+
+    @plotter.on(interval=0.1, frames=50)
+    def move(frame):
+        for a, b in pairwise(pointcloud):
+            vector = b - a
+            a.transform(Translation.from_vector(vector * 0.1))
+
+For example, the following will update the locations of the points of a pointcloud
+for 50 frames and with an interval of 0.1 seconds between the frames.
+
+.. code-block:: python
+
+    from compas.geometry import Pointcloud, Translation
+    from compas.utilities import i_to_red, pairwise
+
+    from compas_plotters import Plotter
+
+    plotter = Plotter(figsize=(8, 5))
+
+    pointcloud = Pointcloud.from_bounds(8, 5, 0, 10)
+
+    for index, (a, b) in enumerate(pairwise(pointcloud)):
+        artist = plotter.add(a, edgecolor=i_to_red(max(index / 10, 0.1), normalize=True))
+
+    plotter.add(b, size=10, edgecolor=(1, 0, 0))
+    plotter.zoom_extents()
+    plotter.pause(1.0)
+
+    @plotter.on(interval=0.1, frames=50)
+    def move(frame):
+        for a, b in pairwise(pointcloud):
+            vector = b - a
+            a.transform(Translation.from_vector(vector * 0.1))
+
+If you want to keep the plot alive at the end of the animation, add a call to ``show``.
+
+.. code-block:: python
+
+    plotter.show()
+
+To save the animation to an animated gif, set the ``record`` flag to ``True``, and add a ``recording`` path.
+
+.. code-block:: python
+
+    @plotter.on(interval=0.1, frames=50, record=True, recording='docs/_images/tutorial/plotters_dynamic.gif')
+    def move(frame):
+        for a, b in pairwise(pointcloud):
+            vector = b - a
+            a.transform(Translation.from_vector(vector * 0.1))
+
+.. figure:: /_images/tutorial/plotters_dynamic.gif
+    :figclass: figure
+    :class: figure-img img-fluid
+
+
 Interactive Plots
 =================
 
-Exports
-=======
+*Coming soon*.

docs/tutorial/plotters.rst

@@ -0,0 +1,26 @@
+from compas.geometry import Pointcloud, Translation
+from compas.utilities import i_to_red, pairwise
+
+from compas_plotters import Plotter
+
+plotter = Plotter(figsize=(8, 5))
+
+pointcloud = Pointcloud.from_bounds(8, 5, 0, 10)
+
+for index, (a, b) in enumerate(pairwise(pointcloud)):
+    artist = plotter.add(a, edgecolor=i_to_red(max(index / 10, 0.1), normalize=True))
+
+plotter.add(b, size=10, edgecolor=(1, 0, 0))
+plotter.zoom_extents()
+plotter.pause(1.0)
+
+
+@plotter.on(interval=0.1, frames=50, record=True, recording='docs/_images/tutorial/plotters_dynamic.gif', dpi=150)
+def move(frame):
+    print(frame)
+    for a, b in pairwise(pointcloud):
+        vector = b - a
+        a.transform(Translation.from_vector(vector * 0.1))
+
+
+plotter.show()

docs/tutorial/plotters_dynamic.py

@@ -5,19 +5,17 @@
 
 from compas_plotters import Plotter
 
-pointcloud = Pointcloud.from_bounds(8, 5, 0, 10)
-
-
 plotter = Plotter(figsize=(8, 5))
 
+pointcloud = Pointcloud.from_bounds(8, 5, 0, 10)
+
 for a, b in grouper(pointcloud, 2):
-    if a and b:
-        line = Line(a, b)
-        plotter.add(line,
-                    linewidth=2.0,
-                    linestyle=random.choice(['dotted', 'dashed', 'solid']),
-                    color=i_to_rgb(random.random(), normalize=True),
-                    draw_points=True)
+    line = Line(a, b)
+    plotter.add(line,
+                linewidth=2.0,
+                linestyle=random.choice(['dotted', 'dashed', 'solid']),
+                color=i_to_rgb(random.random(), normalize=True),
+                draw_points=True)
 
 plotter.zoom_extents()
 plotter.save('docs/_images/tutorial/plotters_line-options.png', dpi=300)

docs/tutorial/plotters_line-options.py

@@ -1,6 +1,9 @@
+import os
 from typing import Callable, Optional, Tuple, List, Union
 import matplotlib
 import matplotlib.pyplot as plt
+import tempfile
+from PIL import Image
 
 import compas
 from compas_plotters import Artist
@@ -202,8 +205,9 @@ def pause(self, pause: float) -> None:
         if pause:
             plt.pause(pause)
 
-    def zoom_extents(self) -> None:
+    def zoom_extents(self, padding: Optional[int] = None) -> None:
         """Zoom the view to the bounding box of all objects."""
+        padding = padding or 0
         width, height = self.figsize
         fig_aspect = width / height
         data = []
@@ -214,8 +218,8 @@ def zoom_extents(self) -> None:
         xmax = max(x)
         ymin = min(y)
         ymax = max(y)
-        xspan = xmax - xmin
-        yspan = ymax - ymin
+        xspan = xmax - xmin + padding
+        yspan = ymax - ymin + padding
         data_aspect = xspan / yspan
         if data_aspect < fig_aspect:
             scale = fig_aspect / data_aspect
@@ -359,3 +363,36 @@ def save(self, filepath: str, **kwargs) -> None:
 
         """
         plt.savefig(filepath, **kwargs)
+
+    def on(self,
+           interval: int = None,
+           frames: int = None,
+           record: bool = False,
+           recording: str = None,
+           dpi: int = 150) -> Callable:
+        """Method for decorating callback functions in dynamic plots."""
+        if record:
+            if not recording:
+                raise Exception('Please provide a path for the recording.')
+
+        def outer(func: Callable):
+            if record:
+                with tempfile.TemporaryDirectory() as dirpath:
+                    paths = []
+                    for f in range(frames):
+                        func(f)
+                        self.redraw(pause=interval)
+                        if record:
+                            filepath = os.path.join(dirpath, f'frame-{f}.png')
+                            paths.append(filepath)
+                            self.save(filepath, dpi=dpi)
+                    images = []
+                    for path in paths:
+                        images.append(Image.open(path))
+                    images[0].save(recording, save_all=True, append_images=images[1:], optimize=False, duration=interval * 1000, loop=0)
+            else:
+                for f in range(frames):
+                    func(f)
+                    self.redraw(pause=interval)
+
+        return outer