Animation Commands

This page defines the animation command syntax and expected behavior (this is related to ticket:9055, see also ticket:9404). The command syntax is implemented in these ​animation commands.

Note on Syntax Style

Greg's suggested using ​extended Backus-Naur form. It was used it to define a ​nucleotides command (see the ​source code comments too).

Proposed command syntax

Elaine's "corrected scheme" from ticket:9055.

"scene" is analogous to ​savepos + ​reset, "animate" is completely analogous to ​fly, except they all work on scenes instead of positions and frame arguments can be followed by comma and transition name (previously defined with "transition").

• ​http://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/savepos.html
• ​http://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/reset.html
• ​http://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/fly.html

(1) scene definition

scene scene-name (save | reset [frames[,trans-name]])
scene list
~scene (scene-name | all)

Notes

• "scene-name" and "trans-name" are user-specified, see (2) for the latter. The "trans-name" is optional -- omitting it uses a "default" transition.
• default scene not necessary.
• save corresponds to scadd.
• reset corresponds to scshow.
• scsave to file omitted for now, could be third option "write pathname".
• alternative: expand existing reset command to restore scenes, then only need:

  scene scene-name
  scene list
  ~scene (scene-name | all)
  

Scooter's proposal

Scooter proposed two minor modifications (according to Elaine):

1. change

   scene scene-name (save | reset [frames[,trans-name]])
   

   to only

   scene scene-name (save | reset)
   

   thus disallowing gradual transitions using the "scene" command. Instead only the "animate" command would show gradual transitions.

2. Have a special scene name that always means the current scene. Then "animate" could be used with the syntax of Elaine's proposal (see below) to go from the current scene to any other.

Darren's note: If so, that breaks the implicit convention that the first scene in an "animate" command is always a 'snap' transition with 1 frame (as it is in ​fly). Also, it means that the first scene in an animate command will always use the [master-frames[,master-trans]] arguments. It can have defaults, but not anything else, without breaking the current syntax convention and the parsing implementation for "animate". That is, we could not specify something like: "animate 20,linear 5 scene1 scene2" to get 5 linear frames to scene1 and then 20 linear frames to scene2; the extra 5 is a real headache! (How would you parse that without making master-frames,master-trans required arguments?)

(2) transition definition

transition trans-name [color color-options] [visibility vis-options] \
                      [style style-options] [global global-options]
transition list
~transition (trans-name | all)

Notes

• Keywords could be different, I just wanted to convey purpose/scope ... many many possibilities, e.g.

  color ( linear [f1,f2] | sigmoid [f1,f2] | abrupt f )
  

  where f are % fractions of the transition from the preceding scene (0%) to the next scene (100%). A percentage is easier to type than values in the 0-1 range.
• Would we want to allow different behaviour for different models?

(3) animation between scenes

This may be analogous to the existing ​fly command:

fly [master-frames] pos1 \
    [[ frames1_2] pos2] \
    [[ frames2_3] pos3] \
    ... \
    [[ framesN-1_N] posN]

see ​http://www.cgl.ucsf.edu/chimera/docs/UsersGuide/midas/fly.html

That is, we define a new command called 'animate' with similar syntax:

animate [master-frames[,master-trans]] scene1 \
    [[ frames1_2[,trans1_2]] scene2] \
    [[ frames2_3[,trans2_3]] scene3] \
    ... \
    [[ framesN-1_N[,transN-1_N]] sceneN]

Notes

• scene*, trans* previously defined with scene and transition commands, respectively.
• alternative: expand existing fly command to do all this.

Concerns:

• Does this limit transitions (other than positions, which would be splined as in "fly") to depending on only the bracketing pair of scenes? Do we need fancier transitions that also depend on further preceding and following scenes?
• How does animation integrate with recording, 2dlabels, coordset, other commands with frame arguments (move,turn,rock,roll)? Simply as interleaved commands between "movie record" and "movie stop"? Could coordset or 2dlabels changes occur at the same time as other transitions?

Tom Goddard notes

If you want to restore just some attributes of a scene with the scene restore command you might have an optional command argument to specify which properties to restore. The command syntax could use just one argument which takes a string with single characters indicating what to restore. The mcopy command that copies molecule attributes is an example of this command syntax.

​http://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/midas/mcopy.html

mcopy source target [ settings [c][s][v][l][x][p] | a ]

Characters after the settings keyword (default csv) control which attributes are
copied:

    c - colors (model-level and atom-level, see coloring hierarchy)
    s - atom/bond and ribbon display styles
    v - visibility (model-level, residue-level ribbon, and atom-level display,
        see display hierarchy)
    l - atom and residue labels
    x - atomic coordinates, untransformed
    p - placement (model transformation)
    a - all of the above

Implementation Notes

All the commands have been defined based on prior experience with savepos/reset/fly, regardless of the implementation status for all their features in the animate extension. At present (June 2011), to avoid confusion for daily-build users, the 'transition' and 'animate' commands are disabled in the ChimeraExtension.py, until the animate extension can implement everything to support these commands (work in progress).

scene command

r33799 provides the following 'scene' command:

scene <scene-name> save
scene <scene-name> reset
scene <scene-name> reset <intFrames>
scene list
~scene <scene-name>
~scene all

Notes:

• args to (scene | ~scene) are comprised of any non-whitespace characters, unless they are 'action' keywords (list | save | reset | all) or otherwise noted below. It is possible to save a scene called 'scene' using "scene scene save", or a scene called 'save' using "scene save save", but it is never possible to save a scene named 'list'.
• Unless the first arg to 'scene' is 'list', it must be a <scene-name> (there is no default) and the 'save' or 'reset' action is required (there is no default).
• For reset, it is an error to specify a <scene-name> that was not previously saved.
• The <intFrames> argument to reset is optional, the default is 1 frame; when it is given, it must be an integer (the value provided is cast using int()).
• The reset command effects a transition from the current display state to a saved <scene-name> state.
• When transition commands are defined and implemented, the scene command set might be augmented with a transition name:

  scene <scene-name> reset [<intFrames>[,<trans-name>]]
  

transition command

Implemented in r33819 - that completes the first approximation for an implementation of all the animation commands.

animate command

Implemented in r33819.

In order to provide reliability in parsing the animate command, the comma in the [frameN[,trans-name]] construct is required to specify any trans-name. Moreover, whenever a comma is present in the command arguments, it must be preceded by a frameN argument and followed by a trans-name argument, with no whitespace allowed between any of these elements. Hence, to specify a scene animation that will use the master-frames but a different trans-name, it is necessary to use a '0' in the place of the framesN argument. For example, "animate 10,snap scene1 0,linear scene2" will result in master-frames=10, master-trans=snap and scene2 will have 10 frames (not zero frames, that's impossible), with a 'linear' transition instead of a 'snap' master transition.