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 stop or ~perframe. Multiple per-frame operations can be active simultaneously. See also: alias, coordset, making movies
A per-frame operation consists of one or more commands or previously defined aliases, optionally 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 quotation marks. 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. 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 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. If neither frames nor any range is given, the perframe actions will continue until halted with perframe stop or ~perframe.
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 zeros up to width digits; this is typically used to generate output filenames from frame counts. Alternatively, a printf-style format string such as %d or %.3f can be supplied with the format option. If this would generate filenames with embedded spaces, the filename part of operation must be enclosed in quotation marks (possibly nested). For example, the following requires both sets of quotation marks:
perframe "turn y 10; save '~/Desktop/$1.png'" frames 9 format %3d
The showCommands option (default false) indicates whether to echo each expanded command to the Log for debugging purposes.
Examples:The following saves PNG files named 001.png, 002.png, ... 180.png as a structure is rotated in 2° increments about the Y axis:
perframe "turn y 2; save ~/Desktop/$1.png" frames 180 zero 3The following gradually changes a map contour level:
- OR -
perframe "save ~/Desktop/$1.png" zero 3; roll y 2 180; wait 180; ~perframe
perframe "volume #2 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:
cartoonThe following plays back a trajectory, with protein secondary structure re-evaluated at every fifth trajectory frame:
perframe "hide protein; show :$1" range 17,355 interval 10
perframe dssp interval 5; coordset #1 1,200; wait 200; ~perframeThe following re-evaluates hydrogen bonding between two atomic models as they are gradually moved (over 20 frames) from a previously saved view named undocked to another named docked:
alias evalhb hb intramod false rad 0.1 color magentaAn example with a substitution argument in the alias:
perframe evalhb; view docked 20; wait 20; ~perf
alias snap save ~/Desktop/$1.png width 300
perframe "snap $1" zeropad 3; roll y 2 180; wait 180; ~perf