Although PyMOL uses OpenGL for all real-time rendering, the simple ray-tracing engine inside of PyMOL is incapable of understanding arbitrary OpenGL calls. Thus, any graphics scene must be translated into a set of primitives (spheres, cylinders, and triangles) that can be provided to the ray-tracer in order to generate high quality images with "ideal" geometries, lighting, and shadows.
Compiled graphics objects are a PyMOL-specific format which enables any Python programmer to create three-dimensional geometries and animations which can be displayed at high-speed via OpenGL and also rendered into maximum-quality images via the raytracer without any additional work.
NOTE: Molscript is a commercial software (free to academics) available at http://www.avatar.se/molscript/ and must be obtained separately. It is our intention to eventually implement our own Molscript-quality ribbons directly from within PyMOL, but that day has not yet come.
PyMOL can automatically translate Raster3D format input files output by Molscript (with "-r" option) into Compiled Graphics Objects for display and rendering inside of PyMOL. PyMOL expects these files to have the file extension ".r3d". NOTE: the Raster3D-to-CGO interpreter is a bare-minimum Python implementation, and doesn't include anything beyond what is required to read what is output by Molscript.
load test/dat/pept.r3d # loads one of the example raster3d files
molauto
When using molauto to preparing input files for PyMOL, it is important to use the "-nocentre" option to prevent any transformation of the protein. That way the PDB file and the Molscript ribbons will be in the same frame of reference.
Unix> molauto -nocentre 3al1.pdb | molscript -r > test1.r3d Unix> molauto -nocentre -nice 3al1.pdb | molscript -r > test2.r3d
You can load both PDB and ribbon files directly into PyMOL as separate objects.
load 3al1.pdb # loads the coordinates load test1.r3d # loads molscript ribbon
Molscript Input Files
Unfortunately, PyMOL does not have the ability to write molscript input files which reflect the current atom colorings and visibilities. Therefore, you will need to get in the habit of manually editing Molscript input files in order color and customize ribbons appropriately. Here are some tips:
1. Remove any line starting with "transform atom" from existing Molscript input files in order to preserve the frame of reference. For example:
transform atom * by centre position atom *;
2. For performance reasons, you may want to set the segments to a small number while working with Molscript ribbons in real-time. Later on you can increase this number, recreate, and reload the ".r3d" files.
set segments 2; # good for real-time graphics set segments 8; # good for rendering
The easiest way to create new ribbons using PyMOL is to use the "save" command to write out a PDB file containing the atom selection of interest. You can then apply the "system" command to run molauto and molscript, and then load the Raster3D file back into PyMOL.
save tmp.pdb,(chain C) system molauto -nocentre tmp.pdb | molscript -r > tmp.r3d load tmp.r3d
Compiled graphics objects contain equivalents to the normal line and triangle primitives found in OpenGL but also include primitives for spheres and cylinders.
At the Python level, compiled graphics objects are constructed as a simple linear list of Python floating point numbers, which is conceptually equivalent to an OpenGL stream.
from pymol.cgo import * # get constants from pymol import cmd obj = [ BEGIN, LINES, COLOR, 1.0, 1.0, 1.0, VERTEX, 0.0, 0.0, 0.0, VERTEX, 1.0, 0.0, 0.0, VERTEX, 0.0, 0.0, 0.0, VERTEX, 0.0, 2.0, 0.0, VERTEX, 0.0, 0.0, 0.0, VERTEX, 00, 0.0, 3.0, END ] cmd.load_cgo(obj,'cgo01')
CGOs support the standard OpenGL BEGIN/END formalism as well as a few stand-alone primitives, SPHERE, CYLINDER, and TRIANGLE, which should NOT appear within a BEGIN/END block.
A CGO is simply a Python list of floating point numbers, which are compiled by PyMOL into a CGO object and associated with a given state.
Lowercase names below are should be replaced with floating-point numbers. Generally, the TRIANGLE primitive should only be used only as a last restore since it is much less effective to render than using a series of vertices with a BEGIN/END group.
BEGIN, { POINTS | LINES | LINE_LOOP | LINE_STRIP | TRIANGLES | TRIANGLE_STRIP | TRIANGLE_FAN },
VERTEX, x, y, z,
COLOR, red, green, blue,
NORMAL, normal-x, normal-y, normal-z,
END,
LINEWIDTH, line-width,
WIDTHSCALE, width-scale, # for ray-tracing
SPHERE, x, y, z, radius # uses the current color
CYLINDER, x1, y1, z1, x2, y2, z2, radius,
red1, green1, blue1, red2, green2, blue2,
TRIANGLE, x1, y1, z1,
x2, y2, z2,
x3, y3, z3,
normal-x1, normal-y1, normal-z1,
normal-x2, normal-y2, normal-z2,
normal-x3, normal-y3, normal-z3,
red1, green1, blue1,
red2, green2, blue2,
red3, green3, blue3,
CGO lists are loaded into PyMOL using the "load_cgo" function.
cmd.load_cgo(list,name,state)
Arbitrary 3D animations can be created by loading CGOs into consecutive states of a given object. The example below is a static image from the "examples/devel/cgo03.py" cgo animation demonstration program.