##########################################################################################
############# pymol_movies_README.txt -- a rough overview and explanation ################
##########################################################################################


"pymol_movies.py"
is the central script -- extensive instructions about its usage are provided in the top 
half of the plaintext .py file.

"split_pdb_models.pl"
is a Perl script that automatically splits a PDB file containing several models (e.g. NMR 
models) so the output is several files "whatever_1.pdb", "whatever_2.pdb", "whatever_3.pdb", 
..., "whatever_Z.pdb".

"sample_movie_single_pdb.pml"
is a regular PyMOL script that should be used with the file "sample.pdb" to illustrate the 
use of the "pymol_movies.py" module.

"1G5V.pdb"
is simply a PDB file containing multiple models (NMR structure of an Sm-like protein), for use 
with the "split_pdb_models.pl" script, and then in PyMOL with the "pymol_movies.py" module.

The main idea is that the "pymol_movies.py" module defines three functions:

"spin_movie()"      --  for making an animation of a single PDB file spinning about the 
			y, x, and z axes (in that order)
"frames_movie()"    --  for making an animation by stepping through multiple PDB files
"write_movie()"     --  for writing out an animation (in MPG or animated GIF formats) that's 
		        already been created in PyMOL (via the above two functions or otherwise)

These examples have been tested only on Linux using PyMOL v0.88pre4. After
making the neccessary changes (path to pymol_movies.py, image-handling software such
as ImageMagick's "convert" program, etc.), behavior should be the same on
Windows PC. On UNIX, to get a feel for how these work try this:

First download and save the above 5 files in the same directory/folder. Then:

(1) Stepping through several models:

 *   run "split_pdb_models.pl 1G5V.pdb" at the unix command line
 *   launch PyMOL
 *   at the PyMOL prompt, type "frames_movie 1G5V,1,10,short" (no quotes!)
 *   you should see the movie start. The '1' and '10' are simply the beginning and ending 
     model number, and 'short' is the time-lag between successive frames -- see the USAGE 
     section of the "pymol_movies.py" file...
 *   stop the movie manually in PyMOL (or by changing the line in "pymol_movies.py") and 
     then at the PyMOL prompt enter:  "write_movie sample,gif,10" (no quotes!)

This should output an animated gif (named "sample.gif"), as well as the individual PNG-format 
images in a new ./png/ directory (sample_1.png, sample_2.png, etc.)...

(2) Making an animation of a single model:
 *   In Linux/UNIX, type ">pymol sample_movie_single_pdb.pml" to see the animation -- you can 
     alter the sample_movie_single_pdb.pml script to enter your own PDB file, cartoon respresentations, etc....
   
Also, in example (1) above, you can easily create the movie you want in PyMOL by issuing the "frames_movie ...." 
command for your own set of PDB files. For example, if you have files named crap_1.pdb, crap_2.pdb, etc. you'd 
just enter "frames_movie richard,1,99,short" and it will create a movie object in PyMOL (named "movie"), and you 
can change the display properties of that movie (cartoon, spheres, etc.) just as if it were any single PDB object....

One important last note: if you're on a linux/unix system, change the following line in the "sample_movie_single_pdb.pml" 
script so that it points to the actual location of the python file on your system:

"run /u1/cmura/FOR_OTHERS/PYMOL/pymol_movies.py"

Alternatively (and on a Windows system), just delete this line and type "run pymol_movies.py" at the PyMOL prompt....

E-mail questions/problems to cmura@ucsd.edu.