Making movies using SPDBV, miniproc, povinterp.mpc, and mpeg_encode

Table of contents

Introduction
Compiling miniproc
Step by step instructions
Adding additional objects
Hints and Gotchas
SAF specific Hints and Gotchas
Example povinterp instructions file
Example GridEngine/povray/miniproc/povinterp.mpc/mpeg_encode shell script
Author and date information

Introduction

This distribution contains tools and instructions for making movies of molecules. You should already have these files:

  example.pdb       PDB file for example movie
  example.pov       POVray .pov file for example movie
  example.inc       POVray .pov file for example movie
  example.txt       povinterp instructions for example movie
  instructions.html This file
  miniproc.c        Source code for miniproc program
  miniproc_doc.html Documentation for miniproc
  povinterp.mpc     Script for generating frame specific .pov/.inc files
  timrom_specs.mpc  text/font attribute information, called by povinterp.mpc
  testfile.mpc      Test script for miniproc

In addition to these files, you will need

  miniproc          miniproc program.  Download or compile from source code provided
  SPDBV 3.7         Swiss PDB viewer ONLY versions 3.7 and 3.6B3 will work!
  mpeg_encode       MPEG1 encoder from Berkeley
  

Movies of molecular objects are produced by first using SPDBV 3.7 to define a set of objects and views. The final movie will show different sets of these objects as it moves smoothly between the views. Additionally, captions (fixed text) and labels (which are attached to objects) will be added. The trick is to get from the SPDBV information to the final movie. To do this the miniproc script povinterp.mpc is used. Under the direction of a file which describes the movie it processes the files output by SPDBV to generate rendering instructions for each frame. These are then run through the POVray ray tracer to produce images of each frame. The frames are then fed through MPEG_ENCODE to produce the final movie.

Next the miniproc script povinterp.mpc processes all of these files according to instructions you supply to it in a command file (see example.txt). This generates the desired number of ".pov" files, each containing instructions for the rendering of a single frame of the movie, plus several ".inc" files which hold the objects which the .pov files display, and a ".act" script, which contains instructions for rendering the .pov files. This script smoothly interpolates between views (which are read from the example.pdb file) to achieve this result. Specifically, it uses a constant set of object coordinates and rotates the camera and lights around these objects. While doing so, and independently of the view, it can turn on or off objects (layers) and apply labels and captions to the image.

After the ".act" script has been executed - which may take a very long time - a large set of frame images will have been produced. These are then converted into an MPEG-1 movie with the mpeg_encode program.

Compiling Miniproc

There may already be a copy of miniproc on your system, in which case you need only run the test described below to verify that it will be able to run the povinterp.mpc script. Otherwise, you will need to build an executable version of this program. Miniproc should build on any system that has an ANSI C compiler and a command line. The following list shows build commands for several platforms:

• Solaris (Forte): %cc -Xc -O -I /usr/include -I /usr/include/sys -o miniproc miniproc.c -lm
• Most unixes and Windows via Cygwin (gcc):
  %gcc -ansi -pedantic -DS_IFDIR=0040000 -Wall -I /usr/include -I /usr/include/sys -o miniproc miniproc.c -lm
• Linux/Alpha (Compaq C): %ccc -std1 -arch host -o miniproc miniproc -lm
• Tru64 (Compaq C): %cc -std1 -o miniproc miniproc -lm
• IRIX 6.x: cc -ansi -o miniproc -I /usr/include -I /usr/include/sys miniproc.c -lm
• VMS/Alpha:
  $ cc/standard=ansi89/prefix=all/warn=(enable=all,disable=(TRUNCINTASN,DOLLARID,UNUSEDINCL))/error=100 miniproc.c
  $ link miniproc.obj
• Macintosh: it's likely that Miniproc will build under OS X but I do not have access to such a system to try it.

  % miniproc testfile.mpc FAILONLY=1

and then view the results, for instance on Unix with

  % cat test.txt
  
or on VMS or Windows (DOS shell) with

  % type test.txt

Ideally the result will be a very large number of successful tests and zero failed tests.

Step by step instructions

Here are the steps which were used to create the example files. If you recreate these steps be careful not to write over the example files provided in the distribution! The choice of objects to display was essentially arbitrary.

1. Prepare a story board. This will help you set your views and define objects/layers that you want to show. It is easiest to sketch this out on a piece of paper, and it should look something like this:

   
   Frame   View   Objects/labels displayed                  Caption(s)
   1       view1  layer5/"sheet1",layer6/"sheet2","His32"   "Two sheets to the wind"
   2       |      ditto                                     ditto
   3       |      ditto                                     ditto
   4       view2  ditto                                     ditto
   5       |      layer1/"A chain","Tyr87"                  "Active site"
   6       |      ditto                                     ditto
   7       |      layer1/"A chain"                          "Active site without key residue"
   5       view3
   

   Each layer (see below) will be a separate object. Labels are applied to coordinates in PDB space, so to place 'HIS32 NE2' find that atom in the example.pdb and note its coordinates. It is generally a good idea to have the first and last frames in the story be at of the same view. That way the movie may be looped continuously without having a discontinuity in view at that point. Similarly, the speed of transition from one view to another is determined by the number of intervening frames. If there are less than 10 frames between two views that are widely spaced the movie will jerk as it moves between them. Note that the view, object, label, and caption may all be set independently on a frame.
   
   
2. Open SPDBV 3.7 (or, in a pinch, SPDBV 3.6B3). No other versions will work correctly, really! In particular, 3.5 versions lack the SPDBVV records in the PDB file which are needed to extract the different views, and 3.7B2 has a glitch which prevents it from correctly storing POVray files.
   
   
3. Load the PDB file 1TNRA 6 times sequentially. This will create 6 layers, each named 1tnra.
   
   
4. Use Edit->Rename current layer... to rename these layers layer1 through layer6, in the order they were loaded. In the control panel pull down menu the first layer loaded will be at the top, the last at the bottom.
   
   
5. At this point the molecule has not been rotated, translated, or zoomed. Define the first viewby Display->Views->save and type in view1.
   
   
6. In SPDBV 3.6B3 be sure that the save in original coordinates option on the Files menu is set. SPDBV 3.7 only operates in this mode.
   
   
7. Edit the contents of each layer using the select and build menu options until it looks like this:
   
   layer1: any one residue, make it invisible
   layer2: 29-36, show backbone and sidechain of 28-43, color it green
   layer3: 71-83, show backbone and sidechain of 68-88, color it red
   layer4: all EXCEPT 29-37, 71-83, show backbone and sidechain, color it CPK
   layer5: 28-43 (sheet region), show ribbon, color it green
   layer6: 68-88 (sheet region), show ribbon, color it red
   


8. In the control panel set the layer to layer1. Without changing that setting define the other views using Display->Views->save. It is critical that all views be defined for layer1 only!
   
   view2 center on His32
   view3 zoom in
   view4 rotate roughly 90 degrees around X (hold down F5 and rotate)
   view5 rotate roughly 90 degrees around Y (hold down F6 and rotate)
   view6 rotate roughly 90 degrees around Z (hold down F7 and rotate) and Zoom out
   
   
   The difference between one view and the next can be almost completely arbitrary, including translation, zoom, and rotation. However, two views that appear sequentially in a movie should never differ by a simple 180 degree rotation around an axis because the interpolated path between them in that case is undefined. Interpolation is by a type of "shortest path" method, and the 180 degree case asks for the shortest path between the North and South poles of a sphere along its surface, and there is no unique answer to that question.
   
   
9. Set the view back to view1.
   
   
10. Display->Views->view1 to set the default orientation of the molecule to one with no rotation, translation, or zoom. Then do File->Save->Project and enter example, which creates the file: example.pdb
    
    
11. File->Save->Pov3...and enter example, which creates the files: example.pov and example.inc. Before doing this it is essental that all objects which will appear in the movie are visible in the display or they will not be written to the POVray file.
    
    
12. Minor changes to make if you used SPDBV 3.6B3. This version has a problem is with ribbon objects. First, it writes them in such a way that POVray won't render them. Second, it does not declare them as objects. If you created any ribbon objects the example.inc file will contain one or more sections like this:

        
    //---- Ribbon ----
    smooth_triangle {<14.291,11.967,-11.578><-0.631,-0.679,0.374>,<14.482,11.811,-11.538><-0.631,-0.679,0.374>,<14.400,11.560,-12.132><-0.631,-0.679,0.374>texture{pigment{ colour red 0.80 green 0.80 blue 0.80} finish{ RIBBON_FINISH }}}
    smooth_triangle {<14.291,11.967,-11.578><-0.631,-0.679,0.374>,<14.400,11.560,-12.132><-0.631,-0.679,0.374>,<14.356,11.425,-12.452><-0.631,-0.679,0.374>texture{pigment{ colour red 0.80 green 0.80 blue 0.80} finish{ RIBBON_FINISH }}}
    etc.
    
    You need to edit these sections to look like one of these forms, the second one is marginally
    faster, but requires much more editing.  
    
    Slower, more memory intensive form - but easier to edit:
    //---- Ribbon ----
    
    #declare R1_shape=union{
    smooth_triangle {<14.291,11.967,-11.578><-0.631,-0.679,0.374>,<14.482,11.811,-11.538><-0.631,-0.679,0.374>,<14.400,11.560,-12.132><-0.631,-0.679,0.374>texture{pigment{ colour red 0.80 green 0.80 blue 0.80} finish{ RIBBON_FINISH }}}
    smooth_triangle {<14.291,11.967,-11.578><-0.631,-0.679,0.374>,<14.400,11.560,-12.132><-0.631,-0.679,0.374>,<14.356,11.425,-12.452><-0.631,-0.679,0.374>texture{pigment{ colour red 0.80 green 0.80 blue 0.80} finish{ RIBBON_FINISH }}}
    etc.
    }
    
    Marginally faster, less memory intensive form - more complex to edit:
    
    //---- Ribbon ----
    #declare TXTR1=texture{pigment{ colour red 0.80 green 0.80 blue 0.80} finish{ RIBBON_FINISH }}
    #declare TXTR2=texture{pigment{ colour red 0.00 green 1.00 blue 0.00} finish{ RIBBON_FINISH }}
    #declare TXTR3=texture{pigment{ colour red 1.00 green 0.00 blue 0.00} finish{ RIBBON_FINISH }}
    
    #declare R1_shape=mesh{
    smooth_triangle {<14.291,11.967,-11.578><-0.631,-0.679,0.374>,<14.482,11.811,-11.538><-0.631,-0.679,0.374>,<14.400,11.560,-12.132><-0.631,-0.679,0.374>texture{ TXTR1 }}
    smooth_triangle {<14.291,11.967,-11.578><-0.631,-0.679,0.374>,<14.400,11.560,-12.132><-0.631,-0.679,0.374>,<14.356,11.425,-12.452><-0.631,-0.679,0.374>texture{ TXTR1 }}
    etc.
    }
    

    For the faster form, specifically what is done is to:
    1. Name each texture with a #declare statement, and then use that name in the smooth_triangle statements. If the number of colors used is small this can be easily done with any good text editor using search and replace operations. NEDIT works well, for example.
    2. Originally no objects were defined. The #declare R1_shape=mesh{} construct groups all the triangles into an object and names it R1_shape. If you have multiple ribbons they might be named R2_shape, R3_shape, and so forth.
       
       
    FInally, the ribbon objects must be placed into layers. Edit the file example.pov from

    
    // ----- layer5 -----
    
    // ----- layer6 -----
    
    
    to 
    
     
    // ----- layer5 -----
    
    object{ R1_shape }   // Ribbon 1
    
    // ----- layer6 -----
    
    object{ R2_shape }   // Ribbon 2
    

    
    
    
13. Minor changes to make if you used either version of SPDBV. Change this line in example.pov

    #version 3 // this scene uses POV-Ray 3.x syntax
    
    to 
    
    #version 3.1 // this scene uses POV-Ray 3.x syntax
    
    

    If you are using Povray 3.5 (or above, most likely), expect a lot of warnings about #declare statements lacking semicolons as well as some warnings about text statements. These can be ignored.
14. Prepare the file example.txt. This file contains the instructions for povinterp that tell it which objects to use in which frames, and which views to use. It implements the story board. Look at the example.txt file for more directions.
    
    
15. Run the script. On a Unix system the command would be:

    
      % miniproc povinterp.mpc 'root=&example' 'outroot=&new'
      
    

    and on a windows system the command would be:

    
      % miniproc povinterp.mpc "root=&example" "outroot=&new"
      
    

    Watch out for warnings about frames with no objects. While you might actually intend to make some completely dark frames in your movie it is more typically a result of having put the wrong commands into example.txt. When it runs these files will be created ("new" is not mandatory, you may use another string there, like "my_movie" or "second_try". No spaces or other punctuation should be included in the file name though!) :

      new_common.pov    most of the definitions from example.inc
      new_layer1.inc    this layer, in its own file
      new_layer2.inc
      etc.
      new_layerK.inc    where K is the largest layer number you used
      new_frame_1.pov   instuctions for rendering this frame
      etc.
      new_frame_M.pov   M is the highest frame number
      new.act           A script to render the images
    

    The distribution example.txt will generate a new.act file which is just the render instructions for POVray on a Unix system. By modifying example.txt a different new.act may be generated which is more appropriate for your site.
    
    
16. Render the frames with:

    
      % source new.act
      
    

    This may take a while! Do not be alarmed if there are some warnings. Do be alarmed if some of the output files are empty or nonexistant.
    
    
17. Create a movie. One way is with the mpeg_encoder program from Berkeley. Obtain and install that. In the example 120 frames are rendered, and the resulting movie runs too fast. By duplicating each frame 4 times a smoother movie results without quadrupling the amount of rendering. (Although that's another possible solution.) This can be easily accomplished with links (Unix only) by using links. Create a file "fake_more_frames.sh" that contains:

    #!/bin/sh
    #
    # first parameter is number of frames in
    # second is number of output frames per input frame
    # It creates links called link#.ppm -> frame#.ppm.  Then the
    # resulting links can be used to generate an mpeg that runs slower
    # than the default 30 frames per second.
    #
    framein=$1
    replicate=$2
    icount=1
    lcount=1
    while [ $icount -le $framein ]
    do
      reps=$replicate
      while [ $reps -ge 1 ]
      do
        ln -s frame$icount.ppm link$lcount.ppm
        reps=`expr $reps - 1`
        lcount=`expr $lcount + 1`
      done
      icount=`expr $icount + 1`
    done
    

    Then do:

    
    % ./fake_more_frames.sh 120 4
    
    

    Set up the MPEG render parameters (these may not be optimal!)

    % cat >make_mpeg_link_params <<EOD
    BASE_FILE_FORMAT PPM
    INPUT_DIR .
    INPUT
    link*.ppm [1-480]
    END_INPUT
    INPUT_CONVERT *
    GOP_SIZE 12
    REFERENCE_FRAME ORIGINAL
    SLICES_PER_FRAME 1
    PATTERN IBBPBBPBBPBBPB
    PIXEL FULL
    RANGE  10
    PQSCALE 2
    IQSCALE 1
    BQSCALE 2
    PSEARCH_ALG LOGARITHMIC
    BSEARCH_ALG SIMPLE
    OUTPUT  movie.mpg
    EOD
    

    and finally render the movie with

    
    % mpeg_encode make_mpeg_link_params
    
    

18. There are alternative programs for creating movies from a series of frames which run on Macs or PCs. Animated GIFs may also be produced from such a series of frames but these tend to be much, much larger than MPEG or other true movie formats. Adobe Photoshop comes with a utility which will write movies. The example.txt instructions cause (eventually) POVray to produce .ppm images. These are not appropriate for most other platforms and you will probably want to change the output type. This is controlled by the -F flag whose values are:

    
      Fx      = write output file in format x
                FC  - Compressed Targa with 24 or 32 bpp
                FNn - PNG (n bits/color, n = 5 to 16, default is 8)
                FP  - PPM
                FS  - System specific
                FT  - Uncompressed Targa with 24 or 32 bpp
    
    

Adding additional objects

If POVray objects are added as layers to the initial example.pov file before processing they may be treated by the povinterp.mpc script just like any other object. For visible in every single frame generated. This limits your control over the moview, so it is usually best to not have anything visible in layer1.

Hints and Gotchas

1. Any object that will be turned on in some scenes, and off in others, must exist in a separate layer.
2. Any visible object present in the lowest layer (layer1) will be visible in every single frame generated. This limits your control over the moview, so it is usually best to not have anything visible in layer1.
3. In order to apply special effects to a POV object conditionally that object must be present (replicated) in different layers. Example: a helix is drawn as a twisted arrow in layer2 and layer3. Edit the object in example.inc and change the object so that it is different in layer2 and layer3. For instance, it might be 50% transparent in layer2 and have a "steel" texture in layer3. Then where you want it to be transparent you would cause layer2 to be displayed, and where it should be "steel" layer3 would be displayed. You would not ever display both at the same time though, as they would exist at the same position in space and the results would not be good.
4. povinterp.mpc provides a method for defining global POVray symbols which vary as any function of the frame number. To utilize these variables modify the objects in the original example.pov file so that their positions or rendering properties vary as a function of these symbols. This could be used, for instance, to show the two halves of an interacting protein pair separate from each other over time, and spin while doing so. Or it could be used to change the transparency of an object. In order to use these types of special effects you must be familiar with the POVray scripting environment - povinterp.mpc only provides a variable to use - it does not in any way tell POVray what to do with it.
5. povinterp.mpc and timrom_specs.mpc must reside in the working directory and in some instances this must be the home directory. The latter file contains font information which is needed to center text captions and labels.
6. SPDBV 3.6B3 has another glitch which will bite you if you try to work over more than one session. When the whole molecule is loaded in the examples above sheet and helix are automatically called by the program. However, when small pieces are reloaded (as in example.pdb) the smaller chains are not processed in this manner. This converts a sheet arrow or helix helix to the round cable like coil object in the resulting .pov file. If for some reason you need to reload a PDB file that has these solid features shown you will have to use the Edit menu and select methods to reset the state of these regions to s or c.
7. In order for captions to have the expected geometries when drawn by POVray they must be placed very "far" from the camera. The object is usually much closer to the camera. The result is that the object may pass in front of the caption. Although a little disconcerting at first, it is really only a problem if the caption is covered much of the time. must reside in the current directory. The latter file contains font information which is needed to center text captions and labels.
8. To achieve a smooth rotation around the Y axis the input command file must contain something like this:

     showview 'view10' 'view11'   1  10
     showview 'view11' 'view12'  10  20
     showview 'view12' 'view13'  20  30
     showview 'view13' 'view10'  30  40
   

   where view10 -> view13 are 90 degree rotations around that axis. To generate these views do:
   
   
   1. Display -> View -> view10 to set the first view to the starting/ending position.
   2. Display -> View From -> Left View
   3. Display -> View -> New and name it view11
   4. Display -> View -> view11 which will set the View From display back to Front View.
   5. Repeat the previous 3 steps 2 more times and employ the names view12 and view13. It is very important that you not manipulate the view in any other way while doing this, for instance, by centering, zooming, and so forth.
   
   To rotate around other axes or in the opposite direction select one of the other Display -> View From options.
9. Labels are more visible if they are given a color which does not exist elsewhere in any of the objects. Otherwise they may disappear within a same colored background as the objects rotate. One exception to this is if multiple chains will be oriented vertically and spun around the Y axis, and if the labels can be placed distal to the last visible residues. In that special case the labels can be colored to match their corresponding chains. When zooming be careful not to reduce the size of a label to far or it will become illegible.

SAF specific Hints and Gotchas

1. miniproc has already been installed on all of the PC workstations in the computer room. You will need to place povinterp.mpc and timrom_specs.mpc in your home directory. Run the povinterp.mpc from a DOS shell like:
   > set path=%path%;C:\Program files\miniproc
   > miniproc povinterp.mpc 'root=&example' 'outroot=&new'
   
2. miniproc has already been installed on all of the Unix workstations in the computer room and is present on your Path. Run the povinterp.mpc from a shell window like:
   % miniproc povinterp.mpc 'root=&example' 'outroot=&new'
   
3. Povray is installed on all of the PCs in the computer room, and on the Beowulf DS10 systems, but is not installed on Irix or Solaris systems.
4. SPDBV 3.7 is present on all of the PC workstations in the computer room. However it is not the default version so you when you use it it must be started explicitly from Windows NT Explorer. Its path is: C:\Program Files\SPDBV_3_6_B3\spdbv.exe
5. The beowulf system may be used to produce your movies rapidly and with little intervention. Times will vary with image complexity, but a somewhat typical MPEG, consisting of 120 frames of size 800 x 600, each frame replicated 4 times (to slow down playback) took about 7 minutes to render. To use this method do:
   
   
   1. Prerun povinterp and render on your PC at low resolution at least a few frames to catch any errors in your povinterp instructions and to verify that the movie will contain the images you expected. Your command file must use:

        width    = 800        ! of output image                   !
        height   = 600        ! of output image                   !
      

   2. Make an ssh connection to the solaris server to gain access to the command line.
   3. Verify that you have at east 30 Mb free disk quota to hold the final movie and no file named movie.mpg in your home directory. The command quota -v will show your disk usage.
   4. Place all of the needed files, as described above, in your home directory.
   5. Issue the command:
      qsub -l povray -S /bin/sh /usr/common/bin/make_movie.sh root repeat
      where root is defined as above to specify a set of files and repeat is the number of times each frame in the movie should be repeated (to slow it down) 4 is usually a good value.
   6. A large number of files will appear in your directory - two for each frame rendered. You should review some or all of these for errors. The rendered frames and movies are constructed in /usr/common/tmp/username, where username is the name you use to login. You may safely list the contents of this directory but do not touch any of these files while the movie is being generated or it may cause the procedure to fail.
   7. When the movie is completed a file MOVIE_DONE will appear in your directory. At that point the file movie.mpg will contain a valid movie. Play it with the Apple Quicktime player on a Macintosh or Windows machine or MPEG_PLAY on a Unix system. The Windows Media Player will not work with this movie.

Example povinterp instructions file

#__alt_prefix=""
!
  frames   = 120        ! total number of frames to render  !
  layers   = 6          ! total number of layers, in movie  !
  width    = 800        ! of output image                   !
  height   = 600        ! of output image                   !
!  width    = 640        ! of output image                   !
!  height   = 480        ! of output image                   !
!  numwidth = "%4.4d"    ! large enough for most things, if not, change it !
  captions = 10         ! >= number of showcaptions below   !
  labels   = 10         ! >= number of showlabels   below   !
  globals  = 10         ! >= number of addglobal statements !

  makedata              ! creates arrays for processing based on the above    !

!
!  examples showing how to define a couple of macros which make global
!  variables for use within POVRAY.  The variables so defined may be
!  used within the POVRAY sections of the input file.  Modify the one
!  input POVRAY file as desired BEFORE running povinterp.mpc and all frames
!  will be able to vary based on these values.
!

  macro    linear(0)
     macro_prototype _CREATE_INT_:frameindex _CREATE_INT_:ofil
     macro_body
     [ -
       '#declare my_linearvar = '   -
       :frameindex 1 .-. -
       frames      1 .-. -
       ./.                        ! ratio, runs 0.0 -> 1.0 !-
       '%5.4f' .d->s.             ! now as a string        !-
       '  ;'                      ! declare must end with ;!-
       '' .append_. -
     ]
     f$write RESULT :ofil
  endmacro linear

  addglobal @linear

  macro    two_cycle_sine_wave(0)
     macro_prototype _CREATE_INT_:frameindex _CREATE_INT_:ofil
     macro_body
     [ '#declare my_cyclevar  = ' -
       :frameindex 1 .-. -
       frames      1 .-. -
       ./.                             ! ratio, runs 0.0 -> 1.0 !-
       3.14159 2 .*.                   ! scale for two cycles   !-
       .*. .sin.                       ! sin(2pi*x),x=0->1.0    !-
       '%5.4f' .d->s.                  ! now as a string        !-
       '  ;'                           ! declare must end with ;!-
       '' .append_. ]
     f$write RESULT :ofil
  endmacro two_cycle_sine_wave

  addglobal @two_cycle_sine_wave
!
!
!  POVINTERP makes an output command file if there is a macro defined 
!  called emitcommand.  If it doesn't exist, no command file is created.
!  In this example a set of commands are made for running each povray
!  job sequentially.
!
  macro    emit_command(0)
     macro_prototype _CREATE_INT_:frameindex _CREATE_INT_:ofil
     macro_body

     [ -
       'povray'                      -
       ' "+I'                        -
       outroot                       -
       '_frame_'      -
       :frameindex numwidth .i->s.     -
       '.pov"'                         -
       ' "+L/usr/common/povray31/include"' -
       ' "+W'                          -
       width '%d' .i->s.               -
       '"'                             -
       ' "+H'                          -
       height '%d' .i->s.              -
       '"'                             -
       ' "+FP"'                        -
       '  "+Oframe'                    -
       :frameindex numwidth .i->s.     -
       '.ppm"'                         -
       '' .append_. ]
     f$write RESULT :ofil
  endmacro emit_command

!
! The next line is MANDATORY if any addglobal statements are used
! or an emit_command has been defined.
!
! Miniproc variables are automatically deleted when they go out
! of scope, which the macros above will when this file exits.
! In order to preserve them for future use they must be moved up
! into the scope of the main POVINTERP.MPC script, which is what
! the next command does.  
!
  [ -
      @emit_command -
      @linear -
      @two_cycle_sine_wave -
      'MINIPROC' .changescope_. -
  ]

!
!  define colors that labels and captions can use
!
  _CREATE_STRING_mywhite = 'colour red 1.00 green 1.00 blue 1.00'
  _CREATE_STRING_myred   = 'colour red 1.00 green 0.00 blue 0.00'
  _CREATE_STRING_mygreen = 'colour red 0.00 green 1.00 blue 0.00'
  _CREATE_STRING_myblue  = 'colour red 0.00 green 0.00 blue 1.00'

!
! as many of these as are appropriate, these set the values in the arrays
! for processing
!
! showlayer arguments
!   arg  what        units
!   1    layer       the layer to show
!   2    start       frame number
!   3    end         frame number 

  showlayer 2 1   20	   ! make layer 2 visible in frames  indicated !
  showlayer 2 90 120	   ! make layer 2 visible in frames  indicated !
  showlayer 3 1   20	   ! make layer 3 visible in frames  indicated !
  showlayer 4 20  90	   ! make layer 4 visible in frames  indicated !
  showlayer 5 30  90	   ! make layer 4 visible in frames  indicated !
  showlayer 6 30 120	   ! make layer 4 visible in frames  indicated !
!
!
! as many of these as are appropriate, at the end frames the view
! is exactly the one derived from SPDBV.  In between the camera travels
! on a straight line in even increments.  In the first frame of a range
! the initial view is shown with no interpolation, in the final frame of
! a range the final view is shown with no interpolation.  Therefore it is
! possible, and usually desirable, to overlap the showview commands on the
! ends so that there is no discontinuous "bump" in the film.  This overlap
! must only be ONE FRAME.  Having the same view throughout a range is allowed
! but no motion will occur within this frame.  However, captions and labels may be
! turned on and off within subranges.
!
! showview arguments
!   arg  what        units
!   1    view        the initial view to show in this range of frames
!   2    view        the final   view to show in this range of frames
!   3    start       frame number
!   4    end         frame number
!
  showview 'view1' 'view2'   1  20
  showview 'view2' 'view3'  20  40
  showview 'view3' 'view4'  40  80
  showview 'view4' 'view5'  80  100
  showview 'view5' 'view6' 100  frames
!
! frame captions:
!   arg  what        units
!   1    start       frame number
!   2    end         frame number 
!   3    upangle     degrees
!   4    rightangle  degrees
!   5    charsize    pixels
!   6    caption     'text string'
!   7    color       string var holding color descriptor
!
!   For upangle, rightangle use:
!       8.0 0.0 10.  for a top caption
!      -8.0 0.0 10.  for a bottom caption
!
!   Normally showcaption ranges will not overlap.  It's possible to have multiple
!   captions on screen at once if they are on different parts of the screen.
!
  showcaption  1   20      7.  0. 10. 'center on His32'       MYWHITE
  showcaption  21  40      7.  0. 10. 'Zoom In'               MYWHITE
  showcaption  41  80      7.  0. 10. 'Rotate around X'       MYWHITE
  showcaption  81  100     7.  0. 10. 'Rotate around Y'       MYWHITE
  showcaption 101  frames  7.  0. 10. 'Rotate around Z and Zoom Out'    MYWHITE
!
! atomic position labels
!   arg  what        units
!   1    start       frame number
!   2    end         frame number 
!   3    x           PDB coords in Angstroms
!   4    y           PDB coords in Angstroms
!   5    z           PDB coords in Angstroms
!   6    offset      Angstroms, towards viewer (always put label in FRONT of atoms!)
!   7    charsize    pixels
!   8    caption     'text string'
!   9    color       string var holding color descriptor
!
  showlabel   1  frames 29.201  10.679  38.636 2.0 7.6 'TYR86 OH'  MYWHITE
  showlabel   1  30     44.822  33.475  50.350 2.0 5.4 'HIS32 NE2' MYGREEN
  showlabel  91  frames 44.822  33.475  50.350 2.0 5.4 'HIS32 NE2' MYGREEN
  showlabel   1  40     44.185  37.799  50.117 2.0 5.4 'TYR76 OH'  MYBLUE
  showlabel  61  90     22.511  36.174  42.308 2.0 5.4 'TYR96 OH'  MYRED
  showlabel  31  90     47.536  46.273  59.008 2.0 5.4 'Sheet 1'   MYGREEN
  showlabel  31  frames 39.952  53.185  58.166 2.0 5.4 'Sheet 2'   MYRED


!******************************************************************
f$exit 1

Example GridEngine/povray/miniproc/povinterp.mpc/mpeg_encode shell script

#!/bin/bash
# make_movies.bash
#
#
# this routine automates the creation of a movie using GridEngine, miniproc, povinterp.mpc
# povray, mpeg_encoder, a beowulf cluster and a tremendous amount of pixie dust.
#
# Submit it this way: 
# qsub -l povray -S /bin/sh /usr/common/bin/make_movie.sh root frames
#
# where
#
# 1.  "root" is the prefix for the input files test.pov,test.inc,test.pdb, use
#     "test".  Do not include any path info.  These files must reside
#     in the user's home directory.
# 2.  the number of iterations of each frame to use in the movie.  The
#     default is 4.  This slows down the movie to about the right speed.
#
# Note the file formatting %4.4d below - that is the default but may
# have been overwritten by a numwidth value when povinterp was run.
# See also the width and height for the rendered frames.
#
# Besides the root.* files, povinterp.mpc and timrom_specs.mpc must
# also be in the home directory.
#
#
THEMINI=/usr/common/bin/miniproc
THEPOV=/usr/common/bin/povray
THEMPEG=/usr/common/bin/mpeg_encode
MSCRIPT=makemovie.sh
if [ $1 ]
then
  THEROOT=$1
else
  echo "Fatal syntax error for make_movie.sh"
  echo "==========================================="
  head -19 $0 | tail -18
  echo "==========================================="
  exit
fi
if [ $2   ]
then
  PADX=$2
else
  PADX=4
fi
echo "theroot is $THEROOT and padx is $PADX"
#
# create the working directory, if it doesn't already exist.
#
MYDIR=/usr/common/tmp/$USER
if [ ! -e $MYDIR ]
then
mkdir $MYDIR
fi
#
# use miniproc and povinterp.mpc to generate the .pov and .inc files
# for all the frames.  These remain in the user's home directory.
#
$THEMINI povinterp.mpc "root=&$THEROOT" "outroot=&tempf"
if [ ! $? ]
then
  echo "Miniproc logged a fatal error, processing aborted"
fi
#
# count the output frames produced
#
set `ls -1 tempf_frame_*.pov | wc `
FRAMES=$1
#
# Create a shell script to do all the render jobs:
#
cat >renderone.sh <<EOD
#!/bin/sh
JOBNO=\$SGE_TASK_ID
NUMVALUE=`printf "%4.4d" $JOBNO`
$THEPOV\
  "+Itempf_frame_\$NUMVALUE.pov" \
  "+L/usr/common/povray31/include" \
  "+W800" \
  "+H600" \
  "+FP"  \
  "+O$MYDIR/frame\$NUMVALUE.ppm"
exit
EOD
#
# create a shell script to produce the movie from the rendered frames -
# this will depend upon the link numbers
#
cat >$MSCRIPT <<EOD
#!/bin/sh
cd $MYDIR
#
EOD
if [ $PADX -ge 2 ]
then
replicate=$PADX
frameout=`expr $FRAMES \* $replicate`
cat >>$MSCRIPT <<EOD
icount=1
lcount=1
while [ \$icount -le $FRAMES ]
do
  reps=$replicate
  while [ \$reps -ge 1 ]
  do
    ln -s frame\$icount.ppm link\$lcount.ppm
    reps=\`expr \$reps - 1\`
    lcount=\`expr \$lcount + 1\`
  done
  icount=\`expr \$icount + 1\`
done
EOD
fi
#
# create an mpeg_encode parameter file
#
cat >$MYDIR/mpeg_params <<EOD
BASE_FILE_FORMAT PPM
INPUT_DIR .
INPUT
link*.ppm [1-$frameout]
END_INPUT
INPUT_CONVERT *
GOP_SIZE 12
REFERENCE_FRAME ORIGINAL
SLICES_PER_FRAME 1
PATTERN IBBPBBPBBPBBPB
PIXEL FULL
RANGE  10
PQSCALE 2
IQSCALE 1
BQSCALE 2
PSEARCH_ALG LOGARITHMIC
BSEARCH_ALG SIMPLE
OUTPUT  movie.mpg
EOD
#
# finish up the rendering script
#
cat >>$MSCRIPT <<EOD
$THEMPEG mpeg_params
#
# clean up
#
rm -f frame*.ppm
rm -f link*.ppm
rm -f mpeg_params
mv -f movie.mpg $HOME
cd
rm -f tempf*
#
echo "movie completed, look in your directory for movie.mpg"
touch $HOME/MOVIE.DONE
exit
EOD
#
# send off all the render jobs and the final cleanup (movie) job.
# This horrible syntax is required
# because qsub does not return the job number as the status value.
# run the final mpeg_encode job on barrel because that is the
# NFS file server for all other nodes and it's needlessly slow to move all this
# data out and back in over the net.  Another user's render job could be
# running on the other nodes in the meantime.
#
#
qsub -hold_jid \
      `qsub -l povray -t 1-$FRAMES -S /bin/sh renderone.sh |\
       awk -F '[ \.]' '{print $3}'` \
 -l povray -q barrel.q -S /bin/sh $MSCRIPT
#
echo "render and movie jobs have been queued."
echo "Watch for a MOVIE.DONE file in your directory"

Author and date information

Updated: 28-NOV-2001

miniproc, povinterp.mpc, and these instructions were written by David Mathog, Biology division, Caltech, mathog@caltech.edu