The perframe command specifies operations to be executed at each subsequent display frame, until a specified number of frames has elapsed, the end of a value range has been reached, or all per-frame operations have been discontinued collectively with ~perframe. Multiple per-frame operations can be active simultaneously. See the video mini-examples. See also: set maxFrameRate, movie-related commands, per-frame scripts in MD Movie
A per-frame operation consists of one or more Chimera commands, usually with embedded substitution arguments ($1, $2, etc.). If multiple commands are included, they should be combined into a single line with semicolon separators. If operation contains any spaces, it should be enclosed in double quotes. Alternatively, operation can be a previously defined single-word alias (defined using the alias command, with ^ before the name to indicate a beginning-of-line alias). During execution, substitution arguments in operation are replaced by the values of variables described in range specifications and/or a frame counter that starts at 1.
The number of frames N at which to perform operation can be indicated directly with the frames option or indirectly with range, where the substituted value will proceed from start to end in increments of step. If step is omitted, it will be calculated from the number of frames N (if supplied), otherwise assumed to be +1 if start < end, or –1 if start > end. The number of frames specified directly will win if it conflicts with the number of frames calculated from range information. If the end of the range is reached before the frames are complete, the substituted value will stay the same (equal to end) for the remaining frames. A range can be given for each substitution argument in operation, and multiple ranges will be used in order. If no range is given, the frame count will be substituted for $1.
The interval option allows executing operation at every Kth frame instead of every frame. Execution will start at the first frame and occur N times regardless of the interval K (where N is specified directly or indirectly, as explained above), but the total number of frames to elapse will vary: K(N – 1) + 1. The frame count for substitution purposes will only include frames at which operation is executed, from 1 to N.
The zeroPadWidth option allows padding the substituted value with leading zeroes up to width digits; this is typically used to generate output filenames from frame counts.
The showCommands option (default false) can be used to echo each expanded command to the Reply Log for debugging purposes.
Option keywords for perframe can be truncated to unique strings and their case does not matter.
Examples:
The following saves X3D files named 001.x3d, 002.x3d, ... 180.x3d as a structure is rotated in 2° increments about the Y axis:
alias ^getx3d export $1.x3dThe following saves PDB files named 001.pdb, 002.pdb, ... 360.pdb as a structure is rotated in 1° increments about the Y axis:
perframe getx3d zeropad 3; roll y 2 180; wait; ~perf
perframe "turn y 1; write #0 ~/Desktop/$1.pdb" frames 360 zero 3The following gradually changes a map contour level:
perframe "volume #0 level $1" range 2.5,0.5 frames 50The following displays individual sidechains (hiding all others) along a protein ribbon, going to the next sidechain every 10th frame:
ribbonThe following was used to “walk” a DNA-binding motor protein along a DNA molecule by superimposing the backbone of template DNA in the protein structure onto successive segments of the longer DNA:
perframe "~disp protein; disp :$1" range 17,355 interval 10
perframe "match #0:1-5.T@P #1:$1-$2.A@P" range 3,85 range 7,89The following re-evaluates hydrogen bonding between two molecules as they are gradually changed from a previously saved position named undocked to a previously saved position named docked.
alias ^evalhb hb intramod false line 2
reset undocked
perframe evalhb; reset docked 40; wait; ~perf