-----------------
Elliptic Billiard
-----------------

.. figure:: elliptic_billiard_example_1.webp
    :width: 100%
    :align: center

    An illustrative animation of an elliptic billiard.

.. figure:: elliptic_billiard_example_2.webp
    :width: 100%
    :align: center

This example illustrates the elliptic billiard. Given an ellipse, we trace the trajectory of a particle moving with constant velocity
in its interior and reflecting in its boundary. The reflections are specular: the angle of reflection equals the angle of incidence.

Using our library, we will write an interactive script to visualize the trajectories starting from any point on an ellipse. You can find the full script here :download:`elliptic-billiards.py <../../../../../examples/blender/geometry/elliptic-billiards.py>`.

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

Setup
=====

To set up our scene, we create an ellipse and use its parameterization function to define an arbitrary chord. This is equivalent to choosing a point on the ellipse and a direction to begin the trajectory.

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [setup]
   :end-before: [setup]


Billiard map
============

We define our main billiard map. It takes the chord joining a start and an end point along the trajectory and reflects it in the line, tangent to the ellipse at the end point.

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [billiard-map]
   :end-before: [billiard-map]


Visualization
=============

At this stage, we can visualize the static objects, namely the ellipse and its focal points. We also define materials, and add a top light and a camera.

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [visualize-static-blender-objects]
   :end-before: [visualize-static-blender-objects]


Add interactive property
========================

Here we set the maximum number of reflections

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [set-number-of-steps]
   :end-before: [set-number-of-steps]

and assign the current number of reflections as a custom property to our scene

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [define-callback]
   :end-before: [define-callback]

We define the callback function `run_step`

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [run-step]
   :end-before: [run-step]


Animation and Rendering
=======================

To create an animation, one can set keyframes as shown:

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [keyframes]
   :end-before: [keyframes]

To render it, we can use the function :py:func:`ddg.visualization.blender.render.render_animation` after setting the render settings

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [render-settings]
   :end-before: [render-settings]

It's also possible to add a render stamp beforehand, as shown:

.. literalinclude:: ../../../../../examples/blender/geometry/elliptic-billiards.py
   :language: python
   :start-after: [render-stamp]
   :end-before: [render-stamp]