Making Tools Scene- and Animation-aware

Chimera version 1.7 (November 5, 2012)

The Animate package implements both scene and animation functionality. Core attributes such as model names, residue types and atom positions are handled automatically by the Animate package. Tools are responsible for saving, restoring and animating objects and attributes that they introduce. Notification of scene and animation events happen through the standard Chimera trigger mechanism.

Scene Triggers

There are two triggers associated with scenes:

chimera.SCENE_TOOL_SAVE

This trigger is fired when a scene is created or updated. The core attributes have already been saved. The trigger data argument to registered handlers is the scene object.

chimera.SCENE_TOOL_RESTORE

This trigger is fired when a scene is restored (and just before an animation sequence completes, see below). The core attributes have already been restored. The trigger data argument to registered handlers is the scene object.

Each scene object has a dictionary, tool_settings, for managing tool-specific data. Tools are responsible for creating their own keys and values for storing and accessing data in the dictionary. Singleton tools such as 2DLabels can use fixed strings such as "2D Labels (gui)" as their keys; multi-instance tools will need to come up with unique keys and make sure that they are not overwriting data for some other tool. Typically, data is saved in SCENE_TOOL_SAVE and accessed in SCENE_TOOL_RESTORE handlers.

Animation Triggers

Animate updates the graphics display during transitions. There are three types of transitions:

key frame transition

When the user plays the animation, a transition occurs between each sequential pair of timeline items. If the ending item is a key frame, then a playback transition results. To transform from the starting state to the ending key frame state, data values are interpolated over the number of steps associated with the end key frame (the value is stored in the frames attribute of the key frame). There is a static "transition" for the initial frame if it has a non-zero frames value.

scene transition

When the user selects a scene (either from the Scenes list or by double-clicking on a key frame in the time line) , a transition with default parameters is used. Currently, the "transition" is a one-frame update to the selected scene.

action transition

When an animation is played and one of the timeline items is an action rather than a key frame, an action transition results. None of the triggers listed below are fired for action transitions because the target state is unknown.

There are four triggers associated with key frame and scene transitions:

chimera.ANIMATION_TRANSITION_START

This trigger is fired when a transition from one key frame to the next starts. No core attributes have been updated yet, so Chimera data represents the initial state of the transition. The trigger data argument to registered handlers is the transition object.

chimera.ANIMATION_TRANSITION_STEP

This trigger is fired for each step of the transition from one key frame to the next. The core attributes have already been updated. The trigger data argument to registered handlers is the transition object.

chimera.ANIMATION_TRANSITION_FINISH

This trigger is fired after all steps of the transition from one key frame to the next have been completed. The trigger data argument to registered handlers is the transition object.

chimera.SCENE_TOOL_RESTORE

This trigger is fired just prior to the ANIMATION_TRANSITION_FINISH. The purpose for firing this trigger is to simplify writing tools that do not need step-by-step animation yet want to restore state when a scene state is reached. These tools can just register for the SCENE_TOOL_RESTORE trigger and completely ignore the ANIMATION_TRANSITION_* triggers. Tools that wants to handle both step-by-step animation and scene restoration will need to avoid getting the SCENE_TOOL_RESTORE trigger twice by deregistering for it in ANIMATION_TRANSITION_START and reregistering for it in ANIMATION_TRANSITION_FINISH.

The transition object received by handlers has several useful attributes and methods:

frames

The total number of frames in this transition.

frameCount

The step number of the current frame in the transition. For ANIMATION_TRANSITION_START, this value should always be zero. For ANIMATION_TRANSTION_STEP, this value ranges from 1 to frames, inclusive. For ANIMATION_TRANSITION_FINISH, this value should be the same as frames.

target()

The end point for this transition, usually an instance of Animate.Keyframe.Keyframe for movie playback or Animate.Scene.Scene for scene restoration using the default transition.

scene()

The scene at the end point for this transition, or None if the target is neither a Keyframe nor a Scene.

tool_settings

A dictionary for managing tool-specific data in the same manner as scene objects. Unlike the dictionary in scene objects, the tool_settings in transition objects are transient. When a transition completes, the dictionary is automatically removed and any stored data will be lost.