<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="usage.animation" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Animation system</title>

  <para>
    As described in the <link linkend="usage.rendering">preceding sections</link> of this manual, OVITO can be used to visualize simulation sequences, 
    play them back within the program, or produce simulation movies. On top of this basic functionality, the program provides powerful animation capabilities, which 
    let you animate the virtual camera or other parameters. The following sections explain the 
    underlying animation system of OVITO in more detail.
    <figure>
    	<title>The animation panel of the <link linkend="scene_objects.file_source">External File Source</link>.</title>
        <screenshot><mediaobject><imageobject>
        <imagedata fileref="images/usage/animation/file_source_animation_panel.png" format="PNG"/>
        </imageobject></mediaobject></screenshot>
    </figure>
  </para>
  
  <simplesect>
    <title>Animation frames vs. simulation frames</title>
    <para>
       After loading a simulation sequence into OVITO, the timeline below the viewport windows indicates
       the length of the current animation interval. Animation frame numbers start at zero in OVITO. Thus, an animation 
       starting at frame 0 and ending at frame 100, for example, consists of 101 video frames. 
    </para>
    <para>
       It is important to point out that there is a semantic difference between <emphasis>simulation frames</emphasis>
       (i.e. the simulation snapshots imported into OVITO) and <emphasis>animation frames</emphasis>, which are 
       the time units used by OVITO's internal timeline.
       By default there is a one to one mapping between the two, i.e., the number of animation frames in OVITO's timeline is automatically adjusted to match the number of loaded simulation snapshots.
       This default behavior is controlled by the <guilabel>Adjust animation length to time series</guilabel>
       option in the <guilabel>Animation panel</guilabel> of the selected <link linkend="scene_objects.file_source">external file source</link>, which is highlighted in the
       screenshot.
    </para>
    <para>
       It is possible to decouple the animation length from the length of the loaded simulation sequence by turning
       off this option. Then you will be in control of the animation length, since OVITO no longer
       adjusts the internal animation length to accommodate all frames of the loaded simulation. 
       You can manually change the length of the current animation in the 
       <link linkend="animation.animation_settings_dialog">Animation settings dialog</link>. 
       If you make the animation interval longer than the
       number of imported simulation frames, you will get additional still images at the end of the animation.
    </para>
    <para>
       The <guilabel>Animation panel</guilabel> provides two additional options,
       which control how the imported simulation frames are mapped to animation frames. The <guilabel>Playback rate</guilabel>
       setting allows you to specify a mapping that is not one to one. For example, a playback rate of
       1:2 would stretch the simulation sequence to extend over twice as many animation frames. Each snapshot
       of the simulation would then be visible for two consecutive video frames. A playback rate of
       2:1, in contrast, would compress the playback of the simulation sequence to half of the animation frames.
       Then, every other simulation snapshot is skipped in the rendered animation.
       The <guilabel>Start at animation frame</guilabel> setting controls when the playback of the simulation sequence
       begins on OVITO's animation timeline. By default it starts immediately at animation frame 0, but you can
       change this number, e.g. to insert still frames at the beginning of a movie.
    </para>
    <para>
       Note that OVITO provides the possibility to load multiple simulation datasets simultaneously into one scene to display them
       next to or on top of each other. Attention must be paid if not all imported simulation sequences
       contain the same numbers of snapshots. To avoid possible conflicts, OVITO activates the <guilabel>Adjust animation length to time series</guilabel>
       option only for the first simulation sequence that you import, and not for those subsequently added to the same scene. 
       Of course you can modify these settings later on, or disable the
       automatic adjustment for all external file sources in the scene and then specify an animation length
       by hand in the <link linkend="animation.animation_settings_dialog">Animation settings dialog</link>.
       <informalfigure><screenshot><mediaobject><imageobject>
         <imagedata fileref="images/animation_settings_dialog/animation_settings_dialog.png" format="PNG" scale="60" />
       </imageobject></mediaobject></screenshot></informalfigure>
    </para>
  </simplesect>
  
  <simplesect>
    <title>Playback speed</title>
    <para>
      In addition to the animation length, the <link linkend="animation.animation_settings_dialog">Animation settings dialog</link> 
      also lets you change the playback speed (frames per second) of the current animation. This number determines the frame rate of 
      video files produced by OVITO (e.g. AVI or MPEG). It also affects the playback within OVITO, which, however, typically 
      happens at a lower effective rate because loading the next simulation snapshot from disk takes too long to reach the 
      realtime frame rate.
    </para>
  </simplesect>
  
  <simplesect>
    <title>Animation via time-dependent functions</title>
    <para>
       Simple animation effects can readily be achieved using the <link linkend="particles.modifiers.expression_select">Expression select</link> 
       and <link linkend="particles.modifiers.compute_property">Compute property</link> modifiers. These modifiers
       allow you to enter arbitrary mathematical formulas and Boolean expressions to select subsets of
       particles or to manipulate certain particle properties (e.g. position, color, transparency, etc.).
    </para>
    <para>
       Within such a math expression, you can incorporate the special variable <literal>Frame</literal>, which evaluates
       to the current animation frame number. Thus, if you reference this variable in an expression, the formula becomes
       time-dependent and OVITO will recompute the results on every animation frame.
    </para>
  </simplesect>
  
  <simplesect xml:id="usage.animation.keyframes">
    <title>Animation via key frames</title>
    <para>
       <informalfigure><screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/slice_modifier_animatable_parameter.png" format="PNG" />
       </imageobject></mediaobject></screenshot></informalfigure>
       OVITO also provides a key-based animation framework. It lets you specify the value of an animatable parameter 
       at certain animation times (for example at the beginning and at the end of the animation). In between these
       key frames, the value of the parameter is then determined using smooth interpolation (typically linear).
    </para>
    <para>
       <informalfigure><screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/keyframe_dialog.png" format="PNG" scale="45" />
       </imageobject></mediaobject></screenshot></informalfigure>
       The screenshot on the right shows the parameter panel of the <link linkend="particles.modifiers.slice">Slice</link>
       modifier as an example. Animatable parameters are indicated by an <guibutton>A</guibutton> button next to the input field.
       This button opens the animation key dialog for that parameter, which allows you to define 
       new animation keys. Animation keys are time-value pairs. 
    </para>
    <para>
       In the next screenshot on the right, two animation keys have been defined for the <emphasis>Distance</emphasis> parameter of the slicing plane, 
       one at frame 0 and the other at frame 50. Thus, the parameter will have a value of 20.0 
       at the beginning of the animation and reach 80.0 at the second animation key frame. 
    </para>
    <para>
       Note that an animatable parameter always has at least one animation key.
       As long as there is only that single key, it defines the constant value of the parameter. 
       Once you add another key OVITO will interpolate between the key values and the
       parameter actually becomes animated.
    </para>
  </simplesect>
  
  <simplesect>
    <title>Auto-key mode</title>
    <para>
       The animation toolbar at the bottom of the main window contains a button with a key icon, which activates 
       the so-called <emphasis>Auto-key mode</emphasis>:
       <screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/key_mode_button.png" format="PNG" scale="25" />
       </imageobject></mediaobject></screenshot>
       While this mode is active, the time slider background is highlighted red and any change made to an animatable
       parameter in the program will automatically generate a new animation key at the current animation time.
       For example, after activating <emphasis>Auto-key mode</emphasis>, you can jump to animation frame 0
       using the time slider and set the <emphasis>Distance</emphasis> parameter of the Slice modifier to a value 20.
       You then go to the last frame of the animation and change the parameter value to 80.
       Each of the two parameter changes results in the creation of a new animation key at the corresponding animation time.
    </para>
    <para>
       Don't forget to deactivate <emphasis>Auto-key mode</emphasis> after you are done creating the desired 
       animation keys. Otherwise you might inadvertently define more keys for other parameters which you don't
       want to animate. The <emphasis>Auto-key mode</emphasis> provides a convenient alternative for creating 
       new animation keys, which can be faster than using the animation key dialog introduced in the previous section.
    </para>
  </simplesect>
  
  <simplesect>
    <title>Editing keys using the animation track bar</title>
    <para>
       The <emphasis>track bar</emphasis> is located right below the time slider and displays the created animation keys
       for the currently selected scene object and its parameters:
       <screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/track_bar.png" format="PNG" />
       </imageobject></mediaobject></screenshot>
       Each key is represented by a small marker at the corresponding position of the timeline. Positioning the
       mouse cursor over a marker will show the key's information in a small tool tip window.
       You can use the mouse to drag animation keys to a different position on the timeline.
       Right-clicking on a key opens a context menu which allows you delete the key.
    </para>
    <para>
       Note that the track bar will only display the animation keys of parameters that are actually animated,
       i.e., which have at least two keys defined. Thus, as soon as only one key is left, it
       will automatically disappear from the track bar.
    </para>
  </simplesect>
  
  <simplesect xml:id="usage.animation.camera">
    <title>Animating the camera</title>
    <para>
       <informalfigure><screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/create_camera_function.png" format="PNG" scale="50" />
       </imageobject></mediaobject></screenshot></informalfigure>
       To animate the camera, you first have to create a <emphasis>camera object</emphasis>. This is done
       from a viewport's <link linkend="usage.viewports.menu">context menu</link> as shown in screenshot on the right. The new camera object will be
       placed in the three-dimensional scene at the current viewpoint.
       Furthermore, the active viewport will be linked to the new camera object so that when the camera is moved,
       the viewport will be updated to show the scene as seen through the new camera position. Conversely, if you use
       the zoom, pan, or orbit functions to adjust the viewport's view, the camera object in the scene will
       be moved accordingly.
    </para>
    <para>
       <informalfigure><screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/viewports_with_camera.png" format="PNG" scale="70" />
       </imageobject></mediaobject></screenshot></informalfigure>
       The newly created camera object is visible in the other three viewports. You might have to zoom out to see it.
       Click on the camera object in the viewports to select it
       and show its parameters in the command panel. Alternatively, you can select the camera object using the
       object selector box located in the top right corner of the main window, which lists all objects in the
       current scene:
       <screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/object_selection_box.png" format="PNG" scale="50" />
       </imageobject></mediaobject></screenshot>
    </para>
    <para>
       The camera object can be moved around in space using the <guilabel>Move</guilabel> tool and
       the <guilabel>Rotate</guilabel> tool in the main toolbar:
       <screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/move_and_rotate_tool.png" format="PNG" />
       </imageobject></mediaobject></screenshot>
       While one of these modes is active, you can drag the camera object with the mouse; or use
       the numeric input fields that appear in the status bar area, which let you enter the position coordinates and 
       Euler orientation angles of the selected object:
       <screenshot><mediaobject><imageobject>
         <imagedata fileref="images/usage/animation/numeric_move_tool.png" format="PNG" scale="60" />
       </imageobject></mediaobject></screenshot>
    </para>
    <para>
       Similar to other parameters, the position and the orientation of the camera object can be animated
       using the keyframing approach. To create animation keys for the camera position or rotation, 
       you first have to activate the <emphasis>Auto-key mode</emphasis> as described above. 
       If you now change the camera's position at different animation times, animation keys will automatically be created 
       and the camera will move on an interpolated path between the keyframe positions. The created animation keys are also shown in 
       the <emphasis>track bar</emphasis> while the camera is selected.
    </para>
    <para>
       By the way, instead of animating the camera's position, you can also animate the simulation box
       and let it rotate, for example. This is done in an analogous way by selecting the simulation box
       and using the <guilabel>Rotate</guilabel> tool while <emphasis>Auto-key</emphasis> mode
       is active.
    </para>
  </simplesect>
  
</section>
