.. _animations:

Animating ddg Objects
=======================

This guide explains how to animate ddg objects (and their visualizations in Blender)
by introducing parameters that can be accessed and changed via Blender's GUI.
Animations can easily be created by :ref:`adding keyframes <keyframes>` to the parameters.


.. contents:: Table of contents
   :local:
   :backlinks: none



Adding Parameters with a Callback Function
------------------------------------------

The most central tool for creating animations is the function
:py:func:`~ddg.blender.props.add_props_with_callback`.
You pass the labels and initial values of the parameters as well as a
**callback function** in the function call.
The callback function will be executed each time one of the parameters changes its value.
The parameters, called *Blender properties*, can now be accessed via Blender's GUI.

Here is a basic example:

.. literalinclude:: ../../../../../examples/blender/docs/props_basic.py
   :language: python

.. note::

    The **labels** "a", "b", "c" and "s" of the parameters can be chosen freely.
    The callback function will be called with the parameters as arguments in given order.

    The type of the **initial parameters** determines the type
    of the parameters, e.g. "0" will result in `int`, "0.0" in `float`.


The example creates the properties `a`, `b`, `c` and `s`.
In Blender's 3D Viewport you can click on the little arrow to the right side
of the coordinate system to open the sidebar. Alternatively you can also press 'n'.
In addition to the  `Item`, `Tool` and `View` tabs, you now also find a `DDG` tab that
stores the Blender properties.

.. image:: animations01.png


If we adjust any of them,
the callback function `print_props` will be executed, and
will print the properties values to the console.

.. image:: animations02.png

.. note::

    The properties need to reside on some object inside of Blender.
    We store them on the **scene**, which can be obtained with
    ``bpy.context.scene``. This is important to know if you want to
    access these properties via the API (e.g.
    ``bpy.context.scene.a``)  for example when animating them.

.. warning::

    If there is no activity, even when changing the parameters, check the console you have started
    Blender with. Error messages will appear there without being shown in Blender.

.. warning::

    Since closing Blender loses all Python state, the callback will no longer exist after saving and reloading a .blend file.

Parameter dependent ddg Objects
-------------------------------

For more interesting examples involving geometric objects,
we can replace `print_props` by a function that creates Blender objects.

For example,

.. literalinclude:: ../../../../../examples/blender/docs/props_clear.py
   :language: python

The above callback is simple and robust.
However, the callback function might be expensive to compute.
If we wish to access previously computed results, :py:func:`~ddg.blender.props.hide_previous` may be useful.
This might be the case if we want to replay an animation as described in :ref:`animated_props`.

.. literalinclude:: ../../../../../examples/blender/docs/props_hide.py
   :language: python

The downside is that memory usage grows with the number of calls to the callback function.
Blender also doesn't handle many objects well and may crash.


.. _advanced props:

Finer Control over Properties
-----------------------------

If you want to set the description, minimum or maximum value of a property and more,
you'll have to define the properties yourself:

.. literalinclude:: ../../../../../examples/blender/docs/props_custom_props.py
   :language: python

Consult the `Blender documentation <https://docs.blender.org/api/current/bpy.props.html>`_ for all the options.


.. _animated_props:

Creating an Animation
---------------------

Like any Blender properties, DDG properties can be keyframed and interpolated.
In particular, the library's tools for keyframes can be applied,
with the slight catch that we store the interactive properties on Blender's **scene**, as mentioned above.

To animate the parameter ``x`` we already added in the example above, we could do:

.. literalinclude:: ../../../../../examples/blender/docs/props_keyframes.py
   :language: python

For a more detailed guide on setting and editing keyframes, see :ref:`keyframes`.

Replaying animations is the primary use-case for :py:func:`~ddg.blender.props.hide_previous`, because it caches the results.

To find out more about rendering animations check out our :ref:`blender_rendering` guide.