.. _keyframes:

Blender Keyframes
=================
Animating an object in Blender comes down to setting keyframes to the properties of that object.
This can be done using Blenders GUI, see
`Blender documentation <https://docs.blender.org/manual/en/latest/animation/keyframes/editing.html>`_
This guide explains how to do this using functions of our library.
In both cases it can be helpful to use the
`Timeline in Blender's GUI  <https://docs.blender.org/manual/en/latest/editors/timeline.html>`_
to see and keep track of your keyframes.


.. contents::
   :local:
   :backlinks: none


Setting a Keyframe
------------------

The function :py:func:`~ddg.visualization.blender.animation.set_keyframe` can be used to
set a keyframe to a property of an object.
In this example the location of a tetrahedron is animated:

.. literalinclude:: ../../../../../examples/blender/docs/animation/basic_animation.py
   :language: python
   :start-after: [animate location]
   :end-before: [animate location]

.. image:: keyframe_location.gif

Additionaly, one can add animation to the rotation property of the tetrahedron in a similar way:
		   
.. literalinclude:: ../../../../../examples/blender/docs/animation/basic_animation.py
   :language: python
   :start-after: [animate rotation]
   :end-before: [animate rotation]

.. image:: keyframe_rotation.gif

Clearing the Animation Data
---------------------------

To clear the animation data that was set on the properties of an object, one can run:


.. literalinclude:: ../../../../../examples/blender/docs/animation/basic_animation.py
   :language: python
   :start-after: [clear animation data]
   :end-before: [clear animation data]

Setting Multiple Keyframes at the Same Time
-------------------------------------------
		   
When the animation becomes more complex one might want to set the values of a property in multiple frames at the same time.
Running this code block would have the same effect as the two first code blocks:
		   
.. literalinclude:: ../../../../../examples/blender/docs/animation/basic_animation.py
   :language: python
   :start-after: [one property in multiple frames]
   :end-before: [one property in multiple frames]

.. image:: keyframe_rotation.gif

For even more complex animations, one can set multiple frames to multiple properties.
This code block sets the animation for the location and the scaling at the same time:
		   
.. literalinclude:: ../../../../../examples/blender/docs/animation/basic_animation.py
   :language: python
   :start-after: [multiple properties in multiple frames]
   :end-before: [multiple properties in multiple frames]

.. image:: keyframe_scaling.gif


Making objects appear and disappear
-----------------------------------
		   
In long animation sequences involving multiple objects, one might want to make some objects only appear at a certain time.
This is possible using transparent materials together with :py:func:`~ddg.visualization.blender.animation.animate_opacity`:

.. literalinclude:: ../../../../../examples/blender/docs/animation/basic_animation.py
   :language: python
   :start-after: [animate transparency]
   :end-before: [animate transparency]

.. image:: keyframe_transparency.gif