Imagine a complex movie for a moment, a movie that has camera motions, objects moving independently or in concert with other objects, changing colors and representations. To handle camera motions PyMOL must know at all times where the camera is located and what it's pointed toward (as well as clipping planes). For objects to move around or be rotated without regard to the camera (the objects themselves rotate/translate, not just the camera), PyMOL has to store the coordinates and matrices for these objects, too. Changing colors and representations for each object must somehow also be stored. So, as you can see this is a multidimensional problem: at each time point in your movie, PyMOL must remember positions and representations, as well as make it easy for you to transition between them (interpolation).
Despite these complexities, PyMOL tries to enable movie making for even novice users. Let's start by defining a few PyMOL concepts—states, frames and scenes.
Basic Movie Terminology
- An object is any PyMOL-object loaded into PyMOL, like atoms, molecules, complexes, etc. When you load an PDB from disk/net it is loaded into PyMOL as an object.
- All pages regarding objects
- A selection is a specifically chosen set of atoms, molecules, complexes etc. in PyMOL. A selection is not an object, it's a subset of stuff from a (collection of) object(s). Selections can be named and when named have are distinguished from objects by having parentheses around their names. For example, foo would be an object and (foo) would be some selection. When you pick an atom (and get the default (sele) selection) or issue the ever-popular Selection command, you get a selection.
- All pages regarding selections
- A state is a particular conformation (set of coordinates) for a given object. For example an NMR ensemble could contain the same molecule, but in 20 different states. PyMOL can make movies from states. States do not store representations in PyMOL (eg. cartoons vs. sticks).
- See also All pages regarding states
- A scene as I understand stores the orientation/position of the camera, all object activity information, all atom-wise visibility, color, representations, and the global frame index.
- See Category:Scenes and Scene for more information. The Scene page has information on how to quickly add/remove and change scenes--suggested reading!
- A scene is the staged representations of objects and the orientation of the camera.
- See also All pages regarding scenes
- A frame can be thought of as a single frame in a movie reel. A frame stores state information and scene information.
- See also All pages regarding frames
- The movie panel is a frame indicator strip at the bottom of the screen. It shows a little icon for which frame you're currently on, and whether or not the camera has been set for that frame.
- See movie_panel for more information.
What is a Movie?
Now the we have the appropriate terminology to talk about movies in PyMOL, we can discuss what a movie really is. A movie in PyMOL is a series of frames stitched together in some way so as to create the desired animation. Once a movie is made in PyMOL, we have a few options for exporting it to other formats like png arrays or MPEG moves.
Movie Making Commands
This tutorial assumes you have some basic knowledge about how to use PyMOL (eg. mousing, choosing and setting your representations, etc). If you're not yet at this level, please check out the Tutorial Category of pages (most notably the beginner tutorials).
I think it's help to think of the movie as a set of frames, like in a movie reel, so let's start there. (Each command below links to the command's PyMOL wiki page, so feel free to click through for more info.)
This command tells PyMOL to set the current frame to whichever you desire. To use it, just issue the command,
where X is some integer number indicating the frame you want to go to. If you issue a frame number greater than the number of frames, PyMOL sets the frame to the highest-numbered frame you have (similarly for negative numbers or numbers smaller than the minimum numbered frame).
Let's try a quick example with frame,
# create an empty 90 frame movie mset 1 x90 # turn on the movie panel (bottom of screen) set movie_panel, on # goto frame one frame 1 # try some intermediate frames; notice the blue indicator in the movie panel frame 10 frame 50 frame 90 # try going beyond the end and see what PyMOL does frame -1 frame 100 # play through the empty movie mplay # stop the movie mstop
Again, states are particular stored conformations of objects. Here we use PyMOL to set and get the states, and see how PyMOL mapped them to our earlier movie example.
This command has a similar idea of frame, but works a little differently. Instead of typing,
# invalid command state 40
# how to set a state in PyMOL set state, stateNo, objectName # for example # set state to 40 set state, 40 # also, get state get state
States & Frames (optional reading)
As an example, look at the code from the "first movie":
fetch 1nmr mplay # issue mstop, to stop the movie
We can do a couple things now, let's try counting the number of states and frames PyMOL now knows about:
# how many frames does PyMOL know about? count_frames # what about states? count_states
and now let's see how PyMOL mapped frames to states. Using the above commands and a little Python, let's see how PyMOL mapped the frames to states:
python for x in range(1,cmd.count_frames()+1): cmd.frame(x) print "Frame => %s; and State => %s" % ( str(x), str(cmd.get('state'))) python end
which should show a 1-1 mapping of states to frames.
mset is a very powerful command. This command tells PyMOL how to assign states to frames. So, now you see why it's necessary to clearly distinguish between and use the two. Let's learn how to use mset.
The syntax for mset can be a little tricky at first. I would write the syntax as:
mset stateSpec, frameSpec
which assigns the states in stateSpec to the frames in frameSpec., where stateSpec is any mset-valid state specification. PyMOl supports to patterns for stateSpec. You can do simply supply a number eg
or you can specify a range of states—like 1 through 55 as
# setting states 1 through 55 # caution: notice the space: 1 -55, not 1-55 (this is a PyMOL parser caveat) mset 1 -55
Simple enough. Now for frameSpec you can specify a single frame number like so or you can specify how many frames PyMOL should use to map to your specified states with the xNumber command. This will make sense with an example
# Recall: mset stateSpec frameSpec # so we are setting STATE 1 across a span of 90 frames mset 1 x90 # Recall: mset stateSpec frameSpec # so we are setting states 1..120 to the next 120 frames mset 1 -120 x120
NB: Actually the syntax is a little more complicated than this as PyMOL's mset command has the ability to remember in which frame the prior specification left the movie. So, you can sort of chain the specifications. Type help mset in PyMOL for more info or see mset.
The mview command can be intimidating, but all we need to know about it at present is that it can store the (1) camera position or (2) a given object position. The idea is to essentially make 'way points' in your movie and have PyMOL interpolate the in-between positions/coordinates, etc. For example, if I wanted to make a 100-frame movie of a zoom into an object, I could store and manually set 100 camera positions, or I could do the starting position and the final position and ask PyMOL to just interpolate that over 100 frames. The latter idea is obviously much simpler. So simple in fact, let's make a super-quick movie that does exactly what I just mentioned—100 frames of a slow zoom into some object. Start with a fresh PyMOL session (reinitialize) and then copy/paste the following:
1 # let's initialize the movie to 100 frames, all of state 1 2 # it's ONLY state 1, because we're only moving the camera around, not 3 # changing structure coordinates of the leucine: 4 mset 1 x100 5 6 # show a leucine 7 frag leu 8 9 # position the residue 10 orient 11 12 # let's store the current camera position 13 mview store 14 15 # now set our way point to be frame 100 16 frame 100 17 18 # now let's zoom into some atom on the fragment 19 zoom ID 10 20 21 # now save this view at frame 100 22 mview store 23 24 # last thing is to tell PyMOL to interpolate the 100 frame zoom 25 # so we don't have to do those 100 snapshots: 26 mview reinterpolate 27 28 # voila, you have a movie. To watch it go back to frame 1 and play it 29 frame 1 30 mplay 31 32 # mstop when you're ready
'But, hold on!' you might say. Why is it so herky-jerky? We have smooth zooming but then a snap and back to frame one! Well, we never gave PyMOL any number of frames to interpolate the change from frame 100 back to frame 1 (since it wraps). If we wanted an a zoom in that was equally as fast as the zoom out we would simply replace line #16 with
# now set our way point to be frame 100 frame 100
but, if we wanted a slow, zoom in and a fast zoom out we could do
# now set our way point to be frame 100 frame 80
instead which would only give PyMOL 20 frames with which to zoom us out. Try it!
Very Basic Mview Syntax
This is a simple overview, see mview for complete details.
Using mview as you can see from above is pretty simple. The very basic syntax is:
# store the camera OR some object given by objName (if it's supplied) mview store[, object=objName] # reinterpolate (link together the positions) for the saved camera or object mview reinterpolate[, object=objName]
If you leave off the object=objName then you're storing the camera information only—and so none of your objects will be moving anywhere—just the camera. If you include an object name, then it stores that object's position information in the current frame. The mview store tells PyMOL to store the camera or objects coordinates, while the mview reinterpolate command tells PyMOL to link together the saved positions for the camera or the selected object in a smooth, cool way.