Contents Previous Next



States and Frames

PyMOL has a powerful and unique molecular movie-making capability. In order to use it, you first need to understand a few key concepts:

The user can fully interact with models while movies are playing.

NOTE: State and frame indexes begin with 1, and not 0 as most C and Python programmers would expect. If you load states into an object with a state index of 0, you are indicating that you want the state to be appended after the last existing state in the object.

Important Commands To Know


The "load" command is used to populate states of an object. By default, each new file loaded will be appended onto the object's states. However, the optional third argument to the load command is the frame index into which the file should be loaded. See "help load" or consult the reference section for more information.

   load foo1.pdb,mov       # loads foo1.pdb into state 1 of "mov".
   load foo2.pdb,mov       # loads foo2.pdb into state 2 of "mov".
   load foo3.pdb,mov,3     # loads foo3.pdb into state 3 of "mov".
   load foo4.pdb,mov,4     # loads foo4.pdb into state 4 of "mov". 


The "mset" command is used to specify which states get included as frames of a movie. If the mset command is not used, PyMOL will by default play through all states in sequential order. However, if you wish to use the other movie commands (such as mdo), it is necessary to explicity use the mset command to create a movie definition inside of PyMOL.

The mset command is followed by an arbitrarily list of statements which defines the entire movie. Each statement takes on one of three forms:

  1. # A number simply indicates a state is to be played next.
  2. x# A lowercase "x" immediately followed by a number (no space) indicates that the previous state should be repeated that many times total.
  3. -# A hyphen immediately followed by a number (no space) indicates that a numeric sequence of states are to be appended onto the movie starting with the previously played state going to indicated state.

Once a movie has been defined, the red "VCR" controls in the lower-right-hand corner of the viewer can be used to step or play through the movie.


   mset 1 x30      # creates a 30 frame movie consisting of state 1 played 30 times.
   mset 1 -30      # creates a 30 frame movie: states 1, 2, ... up through 30.
   mset 1 -30 -2   # 58 frames: states 1, 2, ... , 29, 30, then 29, 28, ... , 4, 3, down to 2
   mset 1 6 5 2 3  # 5 frames: states 1, 6, 5, 2, 3 in that order.

See "help mset" or the reference section for more information.


The "mdo" command allows you to bind a particular series of PyMOL commands to a frame in the movie. For instance, you can perform a rotation about the axis at each frame of the movie in order to sweep the camera about the object. See "help mdo" or the reference section for more information.

NOTE: The "util" module includes two python commands for generating mdo commands, "util.mrock" and "util.mdo". These functions have not been documented, but the source code can be found in the file modules/pymol/ Since they are actual python functions, explicit parenthesis are required to invoke them.

util.mrock(start, finish, angle, phase, loop-flag)
util.mroll(start, finish, loop-flag)


The "mmatrix" command allows you to store and recall a particular viewing matrix to be used to set up frame 1 of the movie. This can be particularly helpful when you're trying to preserve a movie's orientation while performing other actions within PyMOL during the same session. See "help mmatrix" or the reference section for more information.

Simple Examples

Here a static structure is subject to a gentle rock. The following statements create a sixty frame movie which simply rocks the protein by 10 degrees.

   load test/dat/pept.pdb       # load a structure
   mset 1 x60                   # define the movie
   util.mrock(1,60,10,1,1)      # issues mdo commands to create +/- 10 deg. rock over 60 frames

In this next example, the protein is rotated through a full 360 sweep about the Y-axis over 120 frames

   load test/dat/pept.pdb       # load a structure
   mset 1 x120                  # define the movie
   util.mroll(1,120,1)          # issues mdo commands to create full rotation over 120 frames

Complex Examples

The following is a Python program (with a .py or .pym extension) which uses a Python loop to load a large number of numbered PDB files, and then configures PyMOL to show them both forwards and backwards.

from glob import glob
from pymol import cmd

file_list = glob("mov*.pdb"):

for file in file_list

cmd.mset("1 -%d -2"%len(file_list))

Previewing Ray-traced Movie Images

PyMOL has the ability to cache a series of images in RAM and to play them back at a much higher rate than they could be rendered originally. This is most-useful for ray-traced images, but it can also be used with OpenGL images.


The cache_frames option controls whether or not PyMOL saves frames in memory. Its usage is demonstrated in the following script. NOTE: caching images takes a tremendous amount of memory, so you should use the "viewport" command to shrink the window before utilizing this option.

   viewport 320,240
   load test/dat/pept.pdb
   show sph
   mset 1 x30
   util.mrock 1,30,3,1,1
   set ray_trace_frames=1
   set cache_frames=1


Once you have loaded a set of frames into RAM, the frames will remain there until you run the "mclear" command, even if you manipule that model. You can also press the mclear button on the external GUI window.

   mclear  # flushes the frame cache

Saving movies


You can save movie images to numbered PNG format files with a common prefix. If you want each frame to be ray-traced, you should turn on raytracing of frames, turn off caching, and clear the cache (see the Movie Menu or use the following commands).

   set ray_trace_frames=1
   set cache_frames=0

You can save the movie using the "mpng" command, or you can save it from the "File" menu. Either way, you must provide a prefix which will be used to create numbered PNG files.

   mpng mov  # will create mov0001.png, mov0002.png, etc.

If you are compressing movies using Adobe Premiere (recommended for best quality), you will probably want to convert the files using ImageMagick or a similar package into a format that Premiere is capable of reading (such as ".tga" - targa format).

NOTE: This manual is a PyMOL Incentive Product with a One-Year Evaluation Period. You, your school, or your employer must purchase a PyMOL License & Maintenance Subscription to cover usage beyond the first year. We trust you to support the PyMOL project via the "honor" system, so please do your part! See Usage Terms for more information.
Copyright © 2004 DeLano Scientific LLC. All Rights Reserved.

Contents Previous Next