OpenAstexViewer Scripting Language

Table of Contents

Loading and Deleting Molecules

OpenAstexViewer can read molecules from a variety of common file formats. These include PDB files, MDL mol files and to a limited extent Sybyl mol2 files. If the file name ends with .gz then it will be assumed to have been compressed with gzip. If OpenAstexViewer is running as an applet it will attempt to locate files in any of the places that are allowed. This includes on the server, or in the Jar file that OpenAstexViewer was downloaded in. It will also check to see if it can find a gzip'ed version of the file in any of these locations. It should be noted that applets cannot usually read or write files from the local disk of the machine that is running the applet. It is possible to change this behaviour in Internet Explorer running on Windows, without resorting to the use of signed applets. This is described in detail in a later section.

molecule load name file_or_url
This is the basic command to load a molecule into OpenAstexViewer. The name will be used to refer to this molecule in future operations. The name may be optionally quoted in either single or double quotes (valid names are discussed in detail later on). The final parameter is a string that refers to a filename or a URL. Note there are many limitations on what files/URL's can be read by a standard applet (this is discussed in detail later on). Errors are not handled gracefully, and will usually result in error messages written to the console or the Java console if running as an applet.
molecule lazy name file_or_url
This variant on the molecule load command will only load the molecule if one by this name doesn't already exist. This is usually used as a convenience when a web application doesn't know if a target molecule has already been loaded.
molecule remove pattern
This command removes the molecules whose names match the specified pattern. The pattern can consist of simple wildcard characters and ranges (see later for a full description of the allowed patterns), but does not support full regular expressions.
molecule display pattern {on/off/toggle}
Change the way a molecule is displayed. Accepted values of action are on, off and toggle. The toggle option will turn a molecule on if it is off and off if it is on. Molecules that are off do not contribute to the graphics display at all (note that graphical objects that are derived from a molecule are not affected by this setting, but lines, spheres, cylinders, distances, labels etc. are affected).
write -molecule name [options]
This new style command provides capabilities for writing molecules. Molecules can be written to files and to url's. The supported options are
-type {pdb/mol}
Write the molecule out in this format. If no type is specified the molecule is written out in the format it was read from. In the PDB format CONECT records are used to keep track of bond orders, by specifying the bond multiple times (similar to the way RasMol does this). Element types are recorded on the end of the ATOM records as described in the PDB format description.

MDL mol files will support the basic element, bond orders and charges. Behaviour is undefined when writing more than 999 atoms or bonds to a mol file.

-file string
Specify the file name to write the file to. You are responsible for supplying the correct file extension and the path information in the right format for your operating system.
-url string
Write the specified molecule to a url. This is done by packing the molecule into a string, encoding it to protect special characters and POST'ing it to the specified url. By default the molecule is sent as the parameter pdb=.... Additional name/value pairs specified in the url are identified and posted along with the molecule. This provides a very powerful way for communicating changes back to a database, using only basic Internet standard protocols. [Note, if running as an Applet you are usually only able to write to url's on the same server that you were downloaded from].
-parameter name
Change the parameter that is used for sending a molecule to a url. The new parameter must be a valid name for a URL. The default parameter name for url writes is pdb.

Loading and Deleting Maps and Grids

map load name file_or_url
This is the basic command to load a map into OpenAstexViewer. The name will be used to refer to this map in future operations. The name may be optionally quoted in either single or double quotes (valid names are discussed in detail later on). The final parameter is a string that refers to a filename or a URL. Note there are many limitations on what files/URL's can be read by a standard applet (this is discussed in detail later on). Errors are not handled gracefully, and will usually result in error messages written to the console or the Java console if running as an applet.
map remove pattern
This command removes the maps whose names match the specified pattern. The pattern can consist of simple wildcard characters and ranges (see later for a full description of the allowed patterns), but does not support full regular expressions.
map name contour {0/1/2} {on/off/toggle}
When a map or grid is loaded it is created with three contour levels. Exactly which contour levels are turned on or off and displayed at which levels depends on the type of map. This command allows you to change which contour levels are displayed.
map name contour {0/1/2} number
This command allows you to specify the contour value for particular contour levels.
map name contour {0/1/2} color
This command allows you to specify the color for particular contour levels.
map name contour {0/1/2} {wire/solid}
This command allows you to specify how a particular contour level is displayed. The value wire will show the contour level in the traditional electron density style, while solid will produce a shaded, triangulated version of the contour level.
map name contour {0/1/2} linewidth number
Specify the linewidth for a particular map contour. The values -1, -2 and -3 draw the contour in increasingly wide lines. Positive values will draw the lines as cylinders. A value of around 0.01 is about as thick as the thinnest line.
map name contour {0/1/2} transparency {0-255}
Specify the transparency level for a triangulated map contour. Level 0 is completely transparent and 255 is completely opaque.
When a map is loaded it creates three graphical objects which it uses to display the various contour levels. The objects are called name_0, name_1 and name_2. Extreme caution should be taken not to make changes to these objects (especially deleting them), as the map will overwrite the changes you make to them.

Display Styles for Atoms and Bonds

OpenAstexViewer supports the usual styles for renderering molecules. These are lines, ball-and-stick, cylinders and spheres. The following scripting commands are used to change how a particular set of atoms are displayed.
display style {on/off} selection
This command controls whether or not the specified atoms are displayed in the indicated style. The allowed values for style are
spheres
A single sphere displayed in the vdW radius of the atom with the current color and transparency of the atom. There are two methods for drawing spheres. The first uses a bitmap which is very fast, allowing even the biggest structures to be rendered as spheres in real time. The second uses analytical spheres which intersect better but are much slower. This is a global setting which applies to all spheres (in graphical objects as well) and is described in View Settings.
cylinders
A sphere capped cylinder (capsule) is drawn to represent all bonds between atoms that have the cylinder style. Each half of the cylinder is drawn in the color of the atom, and the current cylinder radius is used. It should be noted that cylinders cannot be transparent in the current version of OpenAstexViewer. If a bond has a marked bond order (e.g. it came from an SD file) then the bond order will be shown. If a double bond lies in a ring then a detail line is drawn inside the most appropriate ring. Exocylic double bonds have their detail drawn in the plane of one of the sp2 atoms they are connected to.
sticks
Colored spheres are drawn for each atom, and a single color stick, usually of a slightly thinner radius is drawn for each bond between atoms that have the sticks display style. No bond order indicators are drawn, and sticks cannot be made transparent.
lines
This is the default display style for all atoms. The lines are drawn in the color of the atoms they connect, and can have different line widths. Bond order indicators are drawn in the same way that they are for the cylinder display style.
vdw number selection
Change the vdW radius of the specifed atoms. Note that the number is an absolute value rather than a scale factor. This is sometimes inconvenient and will hopefully be addressed in a future version.
ball_radius number selection
Change the radius of the balls that are used when an atom is displayed in ball-and-stick style. Again this is an absolute value.
stick_radius number selection
Change the radius of the sticks that are used when an atom is displayed in ball-and-stick style. Again this is an absolute value.
cylinder_radius number selection
Change the radius of the tubes that are drawn when an atom is displayed in cylinder style. Note it is not possible to change the radius or the offset of the bond order details in this version of OpenAstexViewer.
bond_width {0/1/2} selection
Change the width of the lines that are used to show bonds in lines style. Note that it is not possible to change the positioning of the bond order details in this version of OpenAstexViewer. Width 0 is the thinnest line that can be drawn.
transparency {0-255} selection
Change the transparency setting of spheres style for the specified atoms. Note, 0 is completely transparent, 255 is completely opaque. Transparent spheres can be rather slow to draw especially if they are very big, so use them carefully.

Coloring Atoms

Atoms can be colored in a variety of ways, on the basis of selection expressions or certain builtin coloring commands. Some of the builtin coloring commands behave directly on those atoms that are selected rather than taking a specific atom selection. This inconsistency will be fixed in a future version of OpenAstexViewer.
color name selection
Change the color of the specified atoms. Appropriate values for the name are the single word color names from the X11 set (e.g. red, cyan, magenta, orange, peach etc.), or numeric values of the form '#RRGGBB' (where RR, GG and BB are hexadecimal integers) or 'R,G,B' (where R, G and B are integers in the range 0-255).
color_by_atom
Change the color of the currently selected atoms according to what element type they are. Carbons are made green, oxygens red, nitrogens blue, sulphurs yellow, phosphorus magenta, hydrogen white etc. There is no way to change this default coloring behaviour. Alternative color schemes can be created by putting sets of color selection commands together.
color_by_chain
Change the color of the currently selected atoms according to which chain they are in. The chains are assigned colors in order from the sequence green, yellow, orange, blue and red. This list is not changeable in the current version. More sophisticated schemes can be built from groups of individual color commands.
color_by_bvalue
Change the color of the currently selected atoms according to their crystallographic b-value (or b-factor). This command applies a fixed set of b-value cutoffs to map into a ramp of eight colors from blue, through white to red. The color bands are
  •   0.0 < b <= 10.0 [blue], 10.0 < b <= 15.0, 15.0 < b <= 20.0, 20.0 < b <= 25.0
  • 25.0 < b <= 30.0, 30.0 < b <= 35.0, 35.0 < b <= 40.0, 40.0 < b [red]
color_by_bvalue_range
Change the color of the currently selected atoms according to their crystallographic b-value (or b-factor). This command applies a fixed set of b-value cutoffs to map into a ramp of eight colors from blue, through white to red. The color bands are split evenly between the minimum and maximum b-value for the selected atoms.
color_by_rainbow selection
Change the color of the specified atoms into a hue selected from the standard rainbow of colors. It should be noted that the command acts on the specified selection of atoms, rather than those atoms that are selected. Specifying the selection as 'default' will cause this command to behave in the same way as the other color by commands (the 'default' selection command returns what is currently selected or everything if nothing is selected). The color ramp that is used goes backwards from blue through the colors of the rainbow to red (blue, green, yellow, orange, red). This color ramp is used as it is convenient for showing the path of a polypeptide chain (from blue at the N-terminus to red at the C-terminus). There is no way to specify an alternate color ramp.

Labels and Distances

A variety of label styles and distances can be shown in OpenAstexViewer. Labels can be applied to sets of atoms using a syntax similar to that found in the program molscript. Basically a format statement controls which attributes of each atom are placed in that atoms label. Labels can be displayed in a variety of font colors and sizes. Also, a 3d font style is available. The command works as follows.
label format selection
The command applies the label specified in format to the atoms contained in selection. The format parameter is a mixture of plain text, tokens controlling what attributes are substituted and formatting information about what font size/color and justification to use. The meaning of the attribute tokens is explained in the table below, all attributes start with a % character.
%aThe name of the atom.
%AThe name of the atom, with greek symbols for the second character of aminoacid atoms.
%xThe x coordinate of the atom.
%yThe y coordinate of the atom.
%zThe z coordinate of the atom.
%bThe b-factor of the atom to one decimal place.
%BThe integer b-factor of the atom.
%oThe occupancy of the atom.
%qThe partial charge of the atom.
%iThe id of the atom.
%IThe insertion code of the atom.
%rThe residue number of the residue, followed by the insertion code if it is non-blank.
%RThe name of the residue.
%fThe name of the residue with only the first letter as a capital.
%cThe chain identifier.
%mThe molecule name.
%%The % character.
All other characters are included verbatim.

Characters that are prefixed with a '\' will be drawn in the Symbol font equivalent. This makes it easy to include Greek letters in labels. The %A format statement will automatically substitute lower case Greek letters for the second character of aminoacid atom names e.g. CA becomes C\a.

Additionally, the label may contain a prefix enclosed in <, > characters. This contains instructions that will affect how the label is displayed, justified etc. An example label with a prefix would be '<xoff=-0.2,3d=true>%a'. The formatting statements that can be included in the prefix are described below.
xoff=numberX-offset after transformation.
yoff=numberY-offset after transformation.
zoff=numberZ-offset after transformation.
color=nameColor of the label.
points=integerSize in points if using bitmap fonts.
3d=booleanDisplay label in 3d font.
size=numberSize of characters for 3d font.
radius=numberRadius of lines for 3d font.
justify=string Justification style for label. Composed of the following characters (e.g. bl for bottom left).
lLeft justified rRight justified
bBottom justified tTop justified
vVertical center hHorizontal center

label clear selection
Clear the labels for the atoms specified in selection.
distance -mode {pairs/nbpairs} -from { sel1 } -to { sel2 } [options]
Generate a distance monitor from every atom in sel1 to every atom in sel2 (distance monitors are not generated for atoms in common between the two selections). Note, that the selection expressions must be enclosed in '{' and '}' when used in these distance commands. If mode is 'nbpairs' then only pairs that are not connected by 1, 2 or 3 bonds will be shown. The distance creation is controlled by two additional parameters which affect the maximum separation of atoms that will be considered.
-dmax number (default 5.0)
Atoms that are more than numberÅ apart do not get a distance monitor.
-contact number (default 0.5)
Atoms that are more than the sum of their vdW radii plus numberÅ apart do not get a distance monitor.
distance -mode centroid -from { sel1 } -to { sel2 } [options]
Generate a distance monitor from the centroid of the atoms in sel1 to the centroid of the atoms in sel2. Note, that the selection expressions must be enclosed in '{' and '}' when used in these distance commands.
distance -delete pattern
Remove distance monitors whose name matches pattern.
The appearance of the distance monitors is controlled by the additional options.
-radius number (Default -1.0)
The radius of the line that represents the monitor. Negative numbers are lines of various thickness, positive numbers indicate a cylinder.
-on number (Default 0.2)
The length of the dash in the distance monitors.
-off number (Default 0.2)
The length of the gap between dashes in the distance monitors.
-color color (Default white)
The color of the distance monitor.
-format string (Default "%.2fA")
The format string that controls the label of the distance monitor. The current distance is substituted for any floating point format specifier.
-labelcolor color (Default white)
The color of the string that is shown by the distance monitor.
-name string (Default null)
The name of the distance monitor.

The command astex.MouseTracker can be used to add labelling options that occur when the mouse is moved over atoms, or to change the behaviour of clicking on atoms.

-mouseover format
Generate a label for atoms as the mouse is moved over them.
-mouseover null
Turn off the mouseover labelling of atoms.
-onclick format
Generate a label for atoms as they are clicked.
-onclick null
Turn off the onclick labelling of atoms.

Additionally the format string can contain characters enclosed in ` characters. This is reminiscent of the unix ` syntax, which runs the command between the quotes and puts the output there. In this case the string between the quotes is treated as a url and the contents are placed in the appropriate place. The url replacement is done after the substitution of format characters so attributes of atoms can be passed to urls. This allows additional data to be looked up and placed in the label strings.

e.g. the following could be used to lookup a kinase name that corresponds to the id of the atom.

astex.MouseTracker -mouseover \
        'kinase `http://path/to/cgi/lookup_kinase.cgi?id=%i`'

Controlling the View

The view that is shown in the graphics window is controlled by several parameters. These are the rotation matrix for the current orientation, the radius of the view in world coordinates (which controls the scale, but seems more convenient this way), the position of the forward and back clipping planes and the position that we are looking at. The following combination of commands are used for manipulating the view. Note that the view matrix only controls the rotation part of the view, it does not control the scale or the view point, these are specified separately.
center number number number
Change the position that the renderer is centered on. It does not change the orientation, the radius of the view or the position of the clipping planes. The units for the three numbers are Å's.
radius number
Change the radius (width) of the view. This is in effect the equivalent of scaling the view. It doesn't change the orientation. The units are Å's.
matrix
 x00 x01 x02 x03
 x10 x11 x12 x13
 x20 x21 x22 x23
 x30 x31 x32 x33
Change the view matrix. Only the components x00, x01, x02, x10, x11, x12, x20, x21 and x22 are used and should correspond to a rotation matrix. Currently you must specify all 16 numbers for the syntax of the command to be correct.
clip number number
Set the position of the clipping planes. The first number controls the position of the front clipping plane and the second number controls the position of the back clipping plane. The units are Å's.
center selection
Set the center, radius and clipping planes so that the specified atoms are visible. It does not change the view matrix. This is a convenient way for centering on a particular subset of atoms all in one go.
view [options]
Control various aspects of the overall graphics view. Some settings also control the default values that are used when generating offscreen images for movies, or saving images. The options that can be set are described below.
-defaultwidth number (default 400)
The default width of image that is generated when saving an image. Can be overridden at image creation time.
-defaultheight number (default 300)
The default height of image that is generated when saving an image. Can be overridden at image creation time.
-defaultsample number (default 1)
The default supersampling for an offscreen image. This causes the image to be rendered at numberxnumber samples per pixel and so large numbers use a lot of memory. A value of 2 causes acceptable antialiasing for most images.
-defaultcompress boolean (default false)
Controls whether saved images are compressed using gzip. As only Windows bitmap files (.bmp) can be saved this is useful, as it will typically compress images by a factor of five.
-defaultimage string (default "movie/image_%04d.bmp")
Specifies the default filename for movies. The frame number is substituted into the string using the format specification. This can be changed to allow for a variety of different movie filename conventions.
-writeimage string (no default)
Writes the current view to the specified file. If the filename is 'default' then all of the defaults that are in effect are used to control the size/quality of the image. This command provides the mechanism to write out the screen image e.g.
	view -writeimage 'screen.bmp';
-width number
The width of image that is generated when saving an image. Can be overridden at image creation time.
-height number
The height of image that is generated when saving an image. Can be overridden at image creation time.
-sample number
The supersampling for an offscreen image. This causes the image to be rendered at numberxnumber samples per pixel and so large numbers use a lot of memory. A value of 2 causes acceptable antialiasing for most images.
-compress boolean
Controls whether saved images are compressed using gzip. As only Windows bitmap files (.bmp) can be saved this is useful, as it will typically compress images by a factor of five.

The following options control the quality/appearance of the onscreen image.

-background color
Change the color of the background. Only solid colors are supported. Most objects automatically fog to the background color. Positioning the rear clipping plane will adjust the degree of fog.
-gradient boolean
Make the background blend from one color at the top to another at the bottom. The colors are specified by -gradienttop and -gradientbottom (see below).
-gradienttop color
Change the gradient color for the top of the background. Objects will still be fogged by the current background color (so make this a blend between the current top and bottom gradient color [maybe this should be done automatically].
-gradientbottom color
Change the gradient color for the bottom of the background. Objects will still be fogged by the current background color (so make this a blend between the current top and bottom gradient color [maybe this should be done automatically].
-antialias boolean
Should the onscreen image be antialiased. This uses a 2x2 pixel sampling antialiasing procedure.
-wuantialias boolean
Draw antialiased lines using the Wu algorithm. This makes nice looking lines but doesn't interact perfectly with other object types in the scene. In particular there will artifacts where lines cross shaded objects. Also the lines only really work with a dark background as they blend colors in the background to achieve the smooth effect. This means that the lines will disappear on light backgrounds.
-realspheres boolean
If set to true, analytical spheres are used rather than bitmaps. The analytical spheres are slower but give better images and allow for transparency.
-shadows boolean
If set to true, shadows are cast on objects. Only the first light source casts a shadow. Shadow casting slows down rendering quite a bit, but simple scenes (e.g. made entirely of spheres) will still render almost interactively (the 1323 aminoacid atoms of PDB code 621p, will do about 1 frame/second on a 1GHz PIII 640x480). There are some situations that don't render quite properly. All objects cast shadows as if they were opaque, which means that lines inside a surface all look like they are in the dark. Cylinders inside transparent spheres don't always render correctly.
-solidfonts boolean
If set to true, text is rendered using the solid fonts (constructed using the Hershey font set). They will always face towards the viewer and will cast shadows when necessary.
-lightingmodel {normal/cartoon}
If set to 'cartoon' the lighting model is adapted to produce pictures similar to David S. Goodsell's Molecule of the Month pictures at the RCSB website. These can be manipulated in real time and will cast shadows in a similar fashion.
-ambient {0-255}
This provides the ambient contribution to the lighting model. The value is used for the red, green and blue contributions. This should arguably be part of the light commands which are described next.
light {0-7} [options]
Specify information about the position of one of the lights. Eight lights are supported. The lighting model only really supports white lights all of which must be point lights at infinity. The supported options are.
-x number
-y number
-z number
The direction of the light. The components are normalised, and all three should be specified in the same light command.
-on boolean
Set whether the light is on or off. Only light 0 casts shadows, so if this light is off there will be no shadows.
-specularint number
Set the specular highlight intensity for this light.
-diffuseint number
Set the diffuse intensity for this light.
-phongpower integer
Set the Phong exponent power for this light. Values from 0 to 100 are useful.

Creating Graphical Objects

In addition to the atom based display styles, OpenAstexViewer allows the creation of a number of different represenations in graphical objects. These objects exist independently of all the atoms and molecules. This is sometimes a useful aid and other times it can be a little inconvenient that a particular object does not disappear when the group of atoms it represents is turned off.

Protein Schematics (Cartoons)

schematic -name object [options] selection
This command uses the new style OpenAstexViewer command syntax which makes it much simpler to implement new commands. Argument names are prefixed by a '-' and followed by the appropriate values.

The command makes a graphical object which contains a schematic cartoon of the selection. The schematic is called object and this name can be used to modify the object later on. The schematics that are generated look a little like those that are produced by the program MolScript. Helices are shown as a wound ribbon, strands are shown as arrows and coil is shown as a narrow tube. The schematic takes its color from the atoms when they are created. The secondary structure that is currently assigned is used to generate the schematic. This can be assigned by the command secstruc. [Currently it is not possible to read the secondary structure definitions from a PDB file, hopefully this will be changed in the future].

Currently it is only possible to generate cartoons for aminoacid residues, and these residues must define the main backbone atoms. A future version will implement a different scheme that allows cartoons to be constructed from Cα coordinates alone, or that can create cartoons for DNA structures.

The appearance of the schematic can be controlled by a large number of options which are outlined below. The options are grouped together according to which part of the schematic structure they affect:

-name object
As described above this supplies the name of the generated graphical object.
-quality {1/2/3/4/5} (default 1)
This controls the overall quality of the schematic. The number of interpolation points and the number of points on the perimeter of the objects are multiplied by this number. Quality 1 has less triangles and will render fastest, quality 5 is the best.
-colorbyss boolean (default false)
Control how the schematic is colored. If colorbyss is true then each type of secondary structure is colored differently (typcially red for ribbon, yellow for arrow and white for tube). If it is false then the secondary structure colors are taken from the residues that are used in its construction.
-alltube boolean (default false)
If this option is set a curved tube is created for the entire polypeptide chain. This passes through the Cα atoms.
-ribbontangent number (default 5.0)
Controls the length of the tangent vectors for the hermite spline that smooths the helical ribbons.
-ribbonpoints number (default 8*quality)
Controls the number of points that are interpolated for a particular residue in a helix ribbon.
-ribbonwidth number (default 2.2)
The width across the peptide plane of the helical ribbon.
-ribbonminwidth number (default 0.4)
The width across the peptide plane of the helical ribbon at each end. The ribbon tapers to/from this value for the last/first residue of each helical ribbon.
-ribbonthickness number (default 0.15)
The thickness of the helical ribbon perpendicular to the plane of the helix.
-ribboncylinders boolean (default true)
If the ribbon is being drawn in a square cross section this option controls whether or not cylinders are drawn along the edge of ribbon. It should be noted that this will prevent the schematic object being truly transparent, as the cylinders cannot be made transparent. If you want a transparent schematic it is best to not use the ribbon cylinders.
-ribbonellipse boolean (default false)
Controls whether the helical ribbons are drawn with an elliptical or rectangular cross section. The elliptical ones shade nicely but use more triangles. If elliptical cross section ribbons are generated then ribbon cylinders are not produced.
-ribbonellipsepoints number (default 12*quality)
Controls the number of points that approximate the elliptical cross section of the helix if elliptical ribbons are generated.
-ribboncolor color (default red)
The color of ribbon sections if -colorbyss is set to true.
-tubesmoothing number (default 1)
The number of smoothing iterations that are applied to guide points in coil regions. If the option -alltube is specified to generate a cylindrical tube for the atoms, then no tubesmoothing is performed independent of the value of this parameter.
-tubepoints number (default 4*quality)
The number of points that are interpolated for each residue in a coil tube.
-tubeperimeter number (default 8*quality)
The number of points that are used to make the circular cross section of a coil tube.
-tubetangent number (default 2.0)
The length of the tangent vector used for the hermite spline interpolation in coil tubes.
-tuberadius number (default 0.2)
The radius of the coil tubes.
-tubetaperradius number (default 0.1)
The radius of the coil tubes at each end. The tube radius is tapered smoothly between the main radius and this value.
-tubetaper boolean (default false)
Should the tube be tapered at each end.
-tubecolor color (default white)
The color of tube sections if -colorbyss is set to true.
-arrowsmoothing number (default 3)
The number of guide point smoothing iterations that are applied to the internal residues of arrows.
-arrowpoints number (default 4*quality)
The number of spline points that are interpolated for each residue in a strand arrow.
-arrowheadwidth number (default 3.6)
The width of the widest part of the arrow head in a strand arrow.
-arrowwidth number (default 2.2)
The width of the body of the arrow in a strand arrow.
-arrowtangent number (default 2.0)
The length of the tangent used for the hermite spline interpolation for strand arrows.
-arrowthickness number (default 0.5)
The thickness of the arrow used in strand arrows.
-arrowcolor color (default yellow)
The color of arrow sections if -colorbyss is set to true.
While there are many options for the schematic command the defaults will produce a reasonable schematic for most protein structures. Before generating a protein schematic it is usually necessary to have secondary structure definitions for the residues. These can be generated using the secstruc command which is outlined below. This allows the completely automated assignment of approximate secondary structure, or assignment of specific categories to groups of atoms.
secstruc [-type {helix/strand/coil}] selection
Assign secondary structure to the specified atoms. If no type is specified the assignment is generated automatically following the algorithm of Kabsch and Sander. This should only be used as a guide to the true secondary structure, but is good enough for illustrative figures. The residues of a particular group of atoms could be assigned a particular type (helix, strand or coil) by specifying the -type option. This can be used for building up a particular secondary structure assignment or for correcting specific features generated by the automatic assignment.

Molecular Surfaces

OpenAstexViewer can create molecular surfaces for sets of atoms. These are invaluable for studying the shape of binding sites and the interactions between different groups of atoms.

There are two different styles for generating molecular surfaces. The first is the original numerical grid based method from AstexViewer 1.0, with the surface displayed as a wireframe mesh. These have the advantage that it is easy to see underlying details through the surface. The second method uses the same grid based approach but generates a shaded triangulated surface, similar to those produced by the program GRASP.

The triangulated molecular surfaces can be operated on to change their transparency, coloring, the parts that are visible and to map atom properties and colors onto them.

The methods for generating the different kinds of molecular surface are outlined below. Some of them use a mixture of selection statements and groups of atoms that are already selected.

surface [options] name color selection
Generate a grid based surface. The surface will be generated in the object called name, with the indicated base color. The surface is generated to cover the atoms that are specified in selection. However, if some of those atoms are actually selected the surface will be clipped to cover just those atoms. This procedure allows the generation of partial surfaces that correctly blend into the other atoms around the surface. The following options apply to the grid based surface generation.
-probe number (default 1.5)
The probe radius that is used for the surface generation. This is usually set to approximate the radius of an ideal water molecule. Some molecular surface programs use 1.4 as the radius.
-solid boolean (default false)
This controls whether a shaded surface is generated. The default is false to produce the old style wire mesh surface of OpenAstexViewer 1.0.

Manipulating Graphical Objects

Once graphical objects have been created they can be changed in a number of ways. This section describes the commands that operate on graphical objects and the kind of effects that can be achieved using them [Note: the ordering of the options to the object commands is somewhat inconsistent. Make sure you get them in the right order!].
object remove pattern
Remove the graphical objects whose name matches pattern.
object load name file_or_url
Load a graphical object from an OpenAstexViewer tmesh file. This is a very simple file format that can only describe triangulated meshes. The details of the file are described in another section. They are occasionally useful for importing objects from other programs.
object pattern display {on/off/toggle}
Control whether a particular graphical object is displayed. If an object is not displayed it is completely skipped in the rendering process.
object pattern colour color
Change the base color of objects whose name matches pattern to the specified color. This will remove texture attributes and other color styles. Single color graphical objects render significantly faster than other those that have other color schemes applied.
object pattern linewidth number
Change the linewidth of the objects whose name matches pattern. The values -1, -2, -3 will draw increasingly wide lines. Positive values will draw the lines of the graphical object as cylinders. The cylinder radius is in Ås so suitable values for a cylinder about as thick as a line are 0.01-0.02.
object pattern backface {on/off/toggle}
Turn backfacing triangles on or off for the objects whose name matches pattern ('on' means display the backfacing triangles). Skipping triangles that face away from the viewer can improve rendering speeds as typically only half the number of triangles are drawn. However, sometimes this is not appropriate, for instance when you have some kind of partial surface displayed. This makes the surfaces appear more correctly in those cases.
object pattern transparency {0-255}
Set the transparency level for this object. Currently the transparency level applies to the whole object. A future version may use texture values to draw variably transparent objects. It should be noted that 0 is completely transparent and 255 is completely opaque. An object with transparency of 128 should draw faster than ones with other transparency values. Additionally, only triangles will render correctly when draw transparent. [In order for the transparency process to work correctly the triangles have to be sorted from front to back from the viewers position. At the moment OpenAstexViewer draws the triangles from front to back, which removes distracting internal features. It is possible that this will be made an option in future versions so that some objects could be drawn from back to front].
object pattern -map { selection } -defaultcolor default -dmax number
Map the atom colors in the specified selection to the graphical object. In this fashion an object can be given an arbitrary coloring based on some atom based color scheme of your choosing. The color is actually a weighted average of nearby atoms. Points that are further than dmax (default 1.5) from any atoms become default color.

Property Calculations and Texture Mapping

OpenAstexViewer suppports the calculation of various properties on graphical objects. These properties are stored in two additional parameters for each vertex of the object, called u and v. The properties can be displayed on triangulated objects using a technique known as texture mapping.

Basically, the u and v values are used as an index into a texture (essentially just an image). The u parameter is used as the x coordinate of the image and the v parameter is mapped as the y coordinate of the image. The texture is scaled so that both the x and y axes are of unit length. The color of each pixel is determined by looking up the appropriate value from the image. With this technique arbitrary values can be mapped onto a triangulated object. The texture mapping expects u and v texture coordinates to be between 0 and 1 if the pixel is to be drawn. A restricted subset of the texture functions available in graphics systems such as OpenGL is provided in OpenAstexViewer.

  1. The u texture coordinate is clamped to the range 0 to 1 i.e. if u < 0, it is set equal to 0, or if u > 1 it is set equal to 1.
  2. The v texture coordinate is clipped to the range 0 to 1. i.e. if v lies outside the range 0 to 1 then the pixel is not drawn.
As most properties will not lie in the range 0 to 1, graphical objects can apply scale factors to the values to bring them into this range. This functionality provides many useful features, such as displaying a color ramp that shows properties mapped onto a surface, allows the clipping of objects subject to other properties. The following methods are available for mapping properties onto graphical objects.
object pattern texture distance {u/v} selection
This function calculates the distance to the nearest atom specified in selection and stores the value for each vertex in the specified texture coordinate (u or v) of the object. The distance texture function is usually stored in v, so that parts of an object can be clipped away based on their distance from a group of atoms.
object pattern texture electrostatic {u/v} number selection
This function calculates the coulomb potential of the atoms specified in selection and stores the value for each vertex in the specified texture coordinate (u or v) of the object. The potential uses the charge attribute of each of the atoms and uses a distance squared dielectric constant term for atoms within numberÅ. Charges will typically need to be specified for the atoms first.
object pattern texture lipophilicity {u/v} number selection
This function calculates the lipophilic potential of the atoms specified in selection and stores the value for each vertex in the specified texture coordinate (u or v) of the object. The potential uses the charge attribute of each of the atoms and uses an exponential decay term within number Å due to Fauchere. Lipophilic terms will typically need to be stored in the charge attribute of the atoms first.
object pattern texture {urange/vrange} min max
Set the texture coordinate range for u or v. The texture coordinates are scaled such that min will be transformed to 0 and max will be transformed to 1. Any texture values that lie outside the range min to max will be clamped or clipped according to the rules described above.
object pattern texture name
Set the texture map for this object. The texture object is specified by name, and the creation of these objects is covered in the next section.
object pattern clip {u/v}
Clip the triangles of objects whose name matches pattern such that only the region whose transformed texture coordinates lie within 0 to 1 is retained. Note, this permanently discards the clipped triangles and vertices.
Texture mapping requires texture coordinates (which have been covered in the previous section) and a texture map. The loading or creation of texture maps is covered here.

The main source for textures in OpenAstexViewer are external image files. These can be read from jpegs or gifs in the current version. The images are resampled to 256x256 pixels, so it is best to use images that are of this dimension initially to avoid the introduction of any artifacts. If jpeg images are to be used for texture maps it is best to turn off all compression, otherwise the images will become noticeably grainy when applied to an object.

texture load name file_or_url
Load the texture from the specified image file. It is internally resampled to 256x256 pixels for performance reasons.
texture remove name
Remove the specified texture from OpenAstexViewer.
texture -name name [options]
This is a new syntax command for generating texture maps. Currently, the only options are to specify the colors of a texture ramp either across u or v.
-coord {u/v}
Specify whether the texture ramp runs along u or v.
-values string
A string specifying the comma separated list of colors that will be evenly spaced along u or v.

Atom Selections

OpenAstexViewer provides a powerful scripting interface for selecting sets of atoms in the structures that are loaded. This is similar to the features that are available in many other programs, such as RasMol, CHARMM and other programs. It should be noted that the selection language is different to all of these programs. This section starts with commands that can be used to build up which atoms are selected in the graphical display (i.e. marked with a yellow dot). The section concludes with the components of the selection language and the way they can be grouped together with logical expressions to achieve complex effects.
select selection
This replaces the currently selected set of atoms with those specified in selection.
append selection
This appends the specified atoms to the set of atoms that are currently selected.
exclude selection
This removes the specified selection of atoms from those that are currently selected.
invert selection
This changes the selection status of those atoms that are specified in selection. Those atoms that were selected are made unselected and vice versa.
define groupname selection
This defines a name for a set of atoms that can be reused in selection expressions using the 'group groupname' feature. Note the atoms in the group are evaluated when the definition is seen. This can be useful for defining complex expressions once and then using the results in many scripting commands.

Combining Selection Expressions

Selection expressions can be combined using various logical operators and other concepts to produce composite atom selections. These are described in this section.
selection1 and selection2
Returns those atoms that are in both selection1 and selection2.
selection1 or selection2
Returns those atoms that are in either selection1 or selection2.
not selection
Returns those atoms that are not in selection.
( selection )
Groups a selection expression so that the correct logical expression can be formed.
byresidue selection
Expands selection so that it contains all atoms from any residues that had atoms selected.
sphere distance around selection
Expands selection so that it contains all atoms that lie within distance Å of any of the atoms.
sphere distance around number number number
Expands selection so that it contains all atoms that lie within distance Å of the specified coordinate.
contact distance selection
Expands selection so that it contains all atoms whose vdW surface is separated by less than distance Å. Note the inconsistent syntax compared to the sphere command.
graph selection
Expands selection so that it contains all atoms that are in the same connected molecular component.

Selection Expressions

The following selection expressions can be used to generate sets of atoms according to certain criteria. [Note: Expressions that use a list of numbers can also contain expressions of the form 'id1 to id2' to denote a range of values].
id id1 [id2 ...]
Return those atoms whose id is in the specified list. For pdb files the id is that this is specified in the file. Atoms from MDL mol files or Sybyl mol2 files are numbered sequentially from the beginning of the file, starting with 1.
atom name1 [name2 ...]
Return those atoms whose atom name is in the specified list of names. Note the names can contain wildcards in a similar fashion to those that can be used to identify graphical objects.
element z1 [z2 ...]
Return those atoms whose atomic number is in the list. Note you are sometimes at the mercy of element type identification for ligands that derive from PDB files. This is not usually a problem for atoms that originate from an MDL mol file or a Sybyl mol2 file.
{x/y/z/o/b/id} {</<=/>/>=/=} number
Return those atoms whose attribute satisfies the expression.
residue n1 [n2 ...]
Return those atoms that are in residues whose number is in the list of ids. This is the residue number given in the PDB file.
sequential n1 [n2 ...]
Return those atoms that are in residues whose sequential number is in the list of ids.
name name1 [name2 ...]
Return those atoms that are in residues whose name is in the list of names.
modulo integer
Return those atoms that are in residues whose residue number modulo integer is zero. This is useful for selecting, say, every 10th residue in a particular aminoacid chain.
insertion s
Return those atoms that are in residues whose insertion code is s. Insertion codes are sometimes used in PDB files to preserve residue numbering between related protein structures.
chain chain1 [chain2 ...]
Return those atoms that are in aminoacid chains whose chain name is in the list of names.
molecule name1 [name2 ...]
Return those atoms that are in molecules whose name is in the list. The molecule names are allowed to contain wildcards according to the standard rules.
molexact name1 [name2 ...]
Return those atoms that are in molecules whose name is in the list. The molecule names are treated literally.
group groupname
Return those atoms that are in the group that was previously 'define'd.
aminoacid
Return those atoms that are in standard aminoacid residues.
dna
Return those atoms that are in standard nucleic acid residues.
ions
Return those atoms that are in standard ion residues.
solvent
Return those atoms that are in standard solvent residues.
all
Return all atoms.
none
Return no atoms. Useful for clearing the current selection (select none;).
current
Return the atoms that are currently selected. Useful for operating on a set of atoms that have been built up on the screen.
default
Return the atoms that are currently selected, or if no atoms are selected returns all atoms. Useful for commands whose default should be to change all atoms when none are selected.
pop
Return the set of atoms that was saved to the top of the stack with a push command and remove them from the stack.
peek integer
Return the set of atoms that was saved in position integer on the stack (position 0 is the top of the stack). The set of atoms is left on the stack.

Animation Commands

OpenAstexViewer provides a simple script based interface for creating movies. This works by building up a set of different animation sequences that transform the view of the molecule. Variables that represent the fraction through the sequence can be interpolated into commands that are executed at each step in an animation sequence. The images are automatically written out in the default format specified using the view command. The animation operations are described below.
animate -state 'delete'
Remove all stages from the animation. This command should be placed at the start of the animation sequence to remove any stages that are currently in the animation sequence. Note that the word 'delete' must be placed in single quotes as it is a reserved word in the scripting language.
animate -state start -interactive boolean
Start the current animation. If interactive is true then the animation is played in the graphics window. This is useful for developing the animation. If interactive is false the movie is played with each frame being written to an image file. The image frames need to be combined together to produce a movie. See additional notes on programs and methods for accomplishing this.
The following commands actually place different animation actions in the animation sequence. There are a number of common options (such as number of steps and command to execute) that are described at the end.
animate -mode rock -angle number -steps integer -command string
Rock around the y-axis up to the specified angle. The rock goes from the start point to +number degrees, back to the start point, to -number degrees and then back to the start point once more. The rock uses a sinusoidal acceleration to give smooth start, stop and direction changes. The number of steps can be controlled and the commands to execute as the animation proceeds.
animate -mode roll -angle number -steps integer -command string
Roll around the y-axis the number of degrees specified. The number of steps can be controlled and the commands to execute as the animation proceeds.
animate -mode command -steps integer -command string
Do nothing other than execute the specified commands.
animate -mode recenter -steps integer -command string [options]
This is the most versatile animation command. It makes the view move from the current viewpoint to that defined by the options for this animation command. It will simultaneously move the view point, view width, clipping planes and interpolate the view matrices from the first view to the second. The matrix interploation is performed using quaternion spherical linear interpolation (slerp), which produces a smooth transition from one orientation to the other. The positioning of the center can be described in terms of cartesian coordinates or an atom selection. Pressing the 'm' key in the graphics window will print out an animation command that will recreate the current view settings (not the atom or graphical object display though). The options for this command are as follows.
-selection selection
-center number number number
Define the center point in terms of either a selection of atoms or an explicit coordinate. Only one of these should be used.
-radius number
The width of the final view.
-clipfront number
The final position of the front clipping plane.
-clipback number
The final position of the back clipping plane.
-matrix "x00 x01 x02 x03 x10 x11 x12 x13 x20 x21 x22 x23 x30 x31 x32 x33"
The view matrix of the final orientation. Note the difference in format from the matrix command. The elements must be enclosed in a string, but can be space or comma separated. Only the 3x3 part of the matrix is used to control the view.

Miscellaneous Scripting Commands

This section covers command that don't fit into any of the above categories.
fetch url_string
Cause OpenAstexViewer to call the specified url. Not enormously usefule as a scripting command, but this is how the Applet fetch method works. A future version may have an option to treat the output of url as a stream of OpenAstexViewer commands.
run file_or_url
Cause OpenAstexViewer to open the specified resource and execute it as a sequence of commands.
A few settings in OpenAstexViewer are controlled with 'variables'. These are listed here for completeness.
set symmetry {on/off}
Control whether on the fly symmetry generation is active. This is useful in a crystallographic environment but is often distracting when simply viewing structures. Many scripts start with this command.
set selectcount {on/off}
Control whether the number of atoms that match selection expressions is printed. These are printed in the console within '[' and ']'. They are a useful aid to see where selection expressions are going wrong (particularly when they inadvertantly match no atoms), but can be distracting if you are setting lots of atoms properties or some such.
set bumps {on/off}
Control the bump tools is active. If it is active atoms that are within their sum of vdW radii are labelled with a distance monitor. As different groups of atoms are selected the bumps update automatically.
set bump_in_same_molecule {on/off}
Controls whether bump pairs have to be between atoms in the same molecule.

AstexViewer™ Copyright (C) 1999-2007 Astex Therapeutics Ltd.
OpenAstexViewer Copyright (C) 2007-2017 Mike Hartshorn