ChimeraX docs icon

Command: perframe

perframe  operation  [ range  start,end[,step]]M  [ frames  N ] [ interval  K ] [ zeroPadWidth  width] [ format  string] [ showCommands  true | false ]

perframe stop


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.


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 3
- OR -
perframe "save ~/Desktop/$1.png" zero 3; roll y 2 180; wait 180; ~perframe
The following gradually changes a map contour level:
perframe "volume #2 level $1" range 2.5,0.5 frames 50
The following uses multiple ranges to gradually change the color of chain A from 100,0,0,100 (opaque red) to 0,0,100,25 (75% transparent blue):
perframe "color /a $1,$2,$3,$4" range 100,0 range 0,0 range 0,100 range 100,25 frames 30
The following displays individual sidechains (hiding all others) along a protein ribbon, going to the next sidechain every 10th frame:
perframe "hide protein; show :$1" range 17,355 interval 10
The following plays back a trajectory, with protein secondary structure re-evaluated at every fifth trajectory frame:
perframe dssp interval 5; coordset #1 1,200; wait 200; ~perframe
The 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 magenta
view undocked
perframe evalhb; view docked 20; wait 20; ~perf
An example with a substitution argument in the alias:
alias snap save ~/Desktop/$1.png width 300
perframe "snap $1" zeropad 3; roll y 2 180; wait 180; ~perf

UCSF Resource for Biocomputing, Visualization, and Informatics / March 2019