Merge pull request #140 from martinRenou/animations_docs

Add documentation for animations

Author: martinRenou

docs/source/animations.rst

@@ -0,0 +1,109 @@
+Animations
+==========
+
+Animation loop
+--------------
+
+The "slow" approach
++++++++++++++++++++
+
+You can make an animation loop using a simple ``for-loop`` in Python and using the ``sleep`` function from the standard ``time`` module.
+It is essential that you use the ``hold_canvas`` context manager in order to improve the performances of your animation.
+
+A simple animation loop will look like the following:
+
+.. code:: Python
+
+    from time import sleep
+
+    from ipycanvas import Canvas, hold_canvas
+
+    canvas = Canvas()
+    display(canvas)
+
+    # Number of steps in your animation
+    steps_number = 200
+
+    for i in range(steps_number):
+        with hold_canvas(canvas):
+            # Clear the old animation step
+            canvas.clear()
+
+            # Perfom all your drawings here
+            # ...
+            # ...
+
+        # Animation frequency ~50Hz = 1./50. seconds
+        sleep(0.02)
+
+
+You can also make an infinite animation using a ``while`` loop:
+
+.. code:: Python
+
+    from time import sleep
+
+    from ipycanvas import Canvas, hold_canvas
+
+    canvas = Canvas()
+    display(canvas)
+
+    while(True):
+        with hold_canvas(canvas):
+            # Clear the old animation step
+            canvas.clear()
+
+            # Perfom all your drawings here
+            # ...
+            # ...
+
+        # Animation frequency ~50Hz = 1./50. seconds
+        sleep(0.02)
+
+
+Making an animation with ``from time import sleep`` should be fast enough in most cases.
+If you draw lots of shapes in your animation loop, you can decrease the animation frequency by sleeping a bit longer: *e.g.* ``sleep(0.033)`` for a ~30Hz animation.
+You should also make use of the vectorized versions of the methods ``fill_rect``, ``fill_circle`` etc if you use them a lot, see :ref:`drawing_shapes`.
+
+This approach might be slow if there is latency between the server and the Jupyter client, and if the server and the client are not the same machine (on MyBinder for example).
+In that case, the next approach is preferable.
+
+
+The "fast" approach
++++++++++++++++++++
+
+Because it's more complicated, this approach is only recommended if the "slow" approach is not fast enough in your case, or if the server is not on the same machine as the client.
+
+Unlike the slow approach, we will use the ``sleep`` method of your canvas instead of using the ``time`` module.
+The ``sleep`` method will ask your canvas to sleep for a certain amount of time, unlike the ``time`` module, the canvas's ``sleep`` method takes a duration in millisecond.
+
+Using this approach, it is recommended to wrap the entire animation in the ``hold_canvas`` context. This way, you will send the entire animation as a single message
+to the Jupyter client, and the animation will run entirely without any communication with the server.
+
+.. code:: Python
+
+    from time import sleep
+
+    from ipycanvas import Canvas, hold_canvas
+
+    canvas = Canvas()
+    display(canvas)
+
+    # Number of steps in your animation
+    steps_number = 200
+
+    # Note how `hold_canvas` now wraps the entire for-loop
+    with hold_canvas(canvas):
+        for i in range(steps_number):
+            # Clear the old animation step
+            canvas.clear()
+
+            # Perfom all your drawings here
+            # ...
+            # ...
+
+            # Animation frequency ~50Hz = 1000./50. milliseconds
+            canvas.sleep(20)
+
+
+You cannot make an infinite animation using this approach.

docs/source/drawing_shapes.rst

@@ -1,3 +1,5 @@
+.. _drawing_shapes:
+
 Drawing simple shapes
 =====================
 
@@ -125,3 +127,45 @@ There is one command for drawing a straight line from one point to another:
     canvas
 
 .. image:: images/lines.png
+
+
+Vectorized methods
+------------------
+
+Some methods like ``fill_rect`` and ``fill_circle`` have a vectorized counterpart: ``fill_rects`` and ``fill_cicles``. It is essential
+to use those methods when you want to draw the same shape multiple times with the same style.
+
+For example, it is way faster to run:
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(width=300, height=300)
+
+    canvas.global_alpha = 0.01
+
+    size = [i for i in range(300)]
+    position = [300 - i for i in range(300)]
+
+    canvas.fill_rects(position, position, size)
+
+    canvas
+
+instead of running:
+
+.. code:: Python
+
+    from ipycanvas import Canvas
+
+    canvas = Canvas(width=300, height=300)
+
+    canvas.global_alpha = 0.01
+
+    for i in range(300):
+        size = i
+        position = 300 - i
+
+        canvas.fill_rect(position, position, size)
+
+    canvas

docs/source/usage.rst

@@ -13,6 +13,7 @@ Usage
     drawing_text
     drawing_images
     retrieve_images
+    animations
     canvas_state
     transformations
     events