Mike Hartshorn (
Astex Technology Ltd.
250 Cambridge Science Park, Milton Road
Cambridge, CB4 0WE, UK
AstexViewer is a program for displaying molecular structures and
electron density maps. It has been developed specifically for
displaying protein/ligand complexes and is not intended for high
quality molecular graphics.
The contents of this documentation are:
Conditions of Use
Web Page Applets
Conditions of Use
AstexViewer has been provided as it may prove useful to the structural biology
community. No warranties of any kind are provided or implied.You may use the program
for any purpose subject to the conditions of supply and use in the CCP4 Software
Licence and the following additional terms and Conditions of Use:
- AstexViewer is provided as is and Astex makes no warranty as to its use,
performance or results which the user may obtain using the software.
- Astex makes no warranty, express or implied, as to the merchantability,
non-infringement of third party rights, or fitness for any particular purpose.
- In no event will Astex be liable to the user for any consequential, incidental
or special damages, including any lost profits or savings, or for any claim by any
- The user is permitted to use, copy and distribute the AstexViewer software
provided that this is performed under the terms of these Conditions of Use and the
CCP4 Software Licence. A notice to Astex Technology must appear in all copies.
If you use the AstexViewer on a publicly accessible internet site the user shall
include the Astex company logo on the site as well as an acknowledgement of the origin
of the program.
- The user is not permitted to repackage the software for inclusion in other
packages without the prior approval of Astex.
- The user is not permitted to copy, modify, sublicence, distribute or transfer
the AstexViewer software except as expressly provided under these Conditions of Use
and the CCP4 Software Licence. Any attempt otherwise will automatically terminate
any user rights to use the AstexViewer software.
- Astex is under no obligation to maintain the AstexViewer software nor to respond
to requests for information from the user.
- Any publication arising from the use of AstexViewer should be accompanied by a
reference to Astex Technology as the originator and author of the AstexViewer
- All other terms and conditions of the supply of AstexViewer by CCLRC shall apply
as specified in the CCP4 Software Licence.
AstexViewer is written in Java 1.1 and will run unchanged on a
variety of computer platforms. The program has been used on PC's
running Windows 95/98/NT, SGI workstations, Linux systems and as
an applet in Netscape and Microsoft Internet Explorer.
Under Windows the program can be launched from a desktop icon
or by typing the program name (AstexViewer) in a Dos window. The
program name may be followed by one or more molecule names. These
molecules will be read in turn and displayed by AstexViewer when
it starts up.
By default the viewer will center on the first molecule named on
the command line. If a protein and ligand are stored in separate
files it is extremely simple to center on the ligand. Just name
the ligand file first on the command line.
The same method can be used for starting the viewer on Unix
machines. The program is usually called astex_viewer on these
The program has controls that are similar to many other desktop
molecular graphics programs.
||Rotate molecule using virtual trackball
||Scale molecule by moving mouse up and down
|Left-click on an atom
||Label and select the atom
|Shift-left-click on an atom
||Center on the atom
|Left-click on background
||Clear all selected atoms
The following keys perform actions when pressed in the
||If exactly two atoms are selected, then a distance
measure is drawn between them.
||The view is reset. The view is recentered and the
orientation is set back to the identity matrix. i.e.
z out of the screen, x across and y up.
||The slab plane is moved in 0.5A.
||The slab plane is moved out 0.5A.
||All atoms are selected.
||If two atoms are selected then a distance monitor
is shown between the two atoms.
If AstexViewer is run as an application, then a menubar appears
along the top of the main window. If it is run as an Applet then
a popup menu can be accessed using the keys appropriate for
the platform. This is usually pressing and releasing the
right mouse button.
- Open Structure...
- Provides a file open box. All files are
listed in a particular directory (not just
structure files), due to a deficiency in Java.
Multiple structures can be opened. PDB files
and mol files are supported.
- Open Map...
- Provides a file open box, and allows CCP4
format maps to be opened.
- Provides a menu of loaded structures. Choosing
a structure will remove that structure from the
- Write Gif
- Pops up a file chooser. A gif file name
can be specified and the current image from the
viewer will be written to that file (This
functionality works only when AstexViewer is running
as an application, not an Applet in a web browser).
Images can be us
- When running as an application this
will close the viewer.
This menu provides some partial functionality
for selecting certain atoms in the structures that
are displayed. Selected atoms are highlighted with
a yellow dot.
The viewer was originally intended for displaying
protein/ligand complexes and so currently only has
functionality for selecting ligand groups. The ligands
are identified automatically.
- This will unselect all atoms
- This makes all selections remove the matching
atoms from the current selection.
- This will select all atoms in ligand groups. If
there are no ligands this menu item should be
- Pops up a menu of all the ligand groups that
are present in the viewer. Choosing one will
select all the atoms in that group.
This menu allows the control of whether certain
objects are displayed.
- Turns on or off all electron density maps.
- Turns on or off the display of symmetry atoms.
As the center of the scene is moved, AstexViewer
automatically calculates symmetry equivalents for
all structures that have symmetry defined. If
there is a map loaded the symmetry is taken from
that, if not it is taken from the CRYST1 records
of a pdb file.
- If bumps are turned on, any atoms that are selected
are annotated with distances to nearby atoms that
are within the sum of VDW radii.
- Controls the display of solvent atoms.
- By Atom
- Will colour all atoms according to a standard atom
based colour scheme.
- By Chain
- Colours atoms according to their chain id.
- By B-factor
- Colours atoms according to a predefined b-factor range.
Blue indicates low b-factors, white intermediate, and red
- By B-factor Range
- Colours atoms by mapping their b-factors into
a range from red to blue.
- Change to
- Will change all selected atoms to the specified colour. If
no atoms are selected all atoms are changed.
- Will change the background colour to the specified colour.
- Reset the view. The molecules are recentered and the
orientation is reset.
- Center on Selection
- The view is centered on the selected atoms. The atoms
may have been selected by choosing a select menu item
or by picking them with the mouse.
- Clip Maps to Selection
- This will clip electron density to selected atoms. This
is principally useful for making pictures.
- Wide Bonds for Selection
- Selected atoms will be drawn with wide bonds. Useful
for highlighting a particular part of a structure, such
as a ligand.
- Contour Levels...
- Pops up a set of sliders that can be used to change
the contour levels for the displayed maps. The check
buttons control whether the contour level is displayed.
The colours are hard wired to red, blue and orange at
the moment. All map contour levels can be turned off
at once by choosing the Display Maps menu item.
- Doesn't measure anything just labels atoms
- Pairs of atoms that are picked get a distance indicator between them.
- Sets of three atoms have the angle in degress indicated.
- Clear distances
- Removes all distance markers.
- Clear angles
- Removes all angle markers.
AstexViewer supports the following colors
Web Page Applets
Alternatively, AstexViewer can be embedded in a web page as
a Java Applet. The following lines of HTML should be added to
a web page to include AstexViewer as an Applet.
<param name="molecule" value="1xyz.pdb">
<param name="map" value="fofc.map">
This example will read a structure called 1xyz.pdb, and a map
called fofc.map from the directory containing the web page.
The example also assumes that AstexViewer.jar is in the same
directory (it is possible to centralise the location of the
jar file by adding a
The applet can display more than one structure and map at the
same time. Multiple structures or maps are loaded by using
molecule tags with sequential ids.
<param name="molecule1" value="mol1.pdb">
<param name="molecule2" value="mol2.pdb">
<param name="molecule3" value="mol3.pdb">
<param name="map1" value="fofc1.map">
<param name="map2" value="fofc2.map">
<param name="map3" value="fofc3.map">
The Applet also supports two other tags, which allow the
specification of which atoms to center on, and which to
draw in wide bond style. Examples are shown below.
<param name="wide" value="X:1">
<param name="center" value="X:1">
The values of both these tags are simple atom selection
expressions. The expressions are of the form
examples are given below.
|A:1||Select residue 1 in chain A.|
|A:1-10||Select residues 1 to 10 in chain A.|
|1-10||Select residues 1 to 10 in any chain.|
The following example shows a typical arrangement for displaying
a protein ligand complex. The protein is in protein.pdb and the
ligand is in ligand.pdb (in residue 1 in chain X). A difference
map is in fofc.map.
<param name="molecule1" value="protein.pdb">
<param name="molecule2" value="ligand.pdb">
<param name="map" value="fofc.map">
<param name="center" value="X:1">
<param name="wide" value="X:1">
The applet displays the protein
and ligand with the electron density map contoured at
3sigma. The wide and center tags instruct the applet to center
on the ligand and display its bonds in wide bond style.
The latest version of AstexViewer supports a script tag that
allows arbitrary sets of commands to be included at startup.
This is the preferred way of loading molecules and maps in
later versions. The scripting language is described in
detail in the next section.
When creating Applets pay particular attention to the
file locations and permissions. In particular any file
that you will download through a webserver will usually need
to be world readable. The Java Console will usually give
you some clues as to the cause of the problem.
<param name="script" value="
molecule load molecule1 protein.pdb;
molecule load molecule2 ligand.pdb;
map load map1 fofc.map;
center chain X and residue 1;
display wide chain X and residue 1;
More Complex Example
A second example shows more
sophisticated control of the AstexViewer Applet. You should see a
close up view of benzamidine bound to trypsin with an electron density map.
The right hand button generates a surface for the protein or ligand.
The electron density contour levels can be changed and turned on or off with
the map controls at the bottom of the page.
AstexViewer supports a scripting language for controlling its
embedded in a web page. The language controls the loading
of maps and molecules and allows the program to customise the
appearance of the molecules.
The following are the basic commands supported by the AstexViewer scripting language.
All commands are terminated by a ';' character but these have been omitted from
the descriptions below
molecule load name 'file_or_url'
- Load the molecule specified by the file or url and give it the specified internal name.
molecule lazy name 'file_or_url'
- Load the specified molecule if nothing of that name already exists.
molecule remove name
- Remove the specified molecule from AstexViewer.
map load name 'file_or_url'
- Load the electron density map and give it the specified internal name.
map name contour contour_number value
- Set the contour level for the contour to the specified value.
map name contour contour_number on/off/toggle
- Change the display state of the specified contour for the named map.
colour colour_name selection
- Change the colour of the atoms specified by selection.
label format selection
- Label the specified atoms using the format statement. In this
version the format statement is ignored and atoms are labelled with
their atom name, residue name and residue number e.g. CA ALA:24.
- Sets the origin of the viewer to the center of the selected
atoms. The width of the view is adjusted to that of the sphere that
encloses the selected atoms.
centre x y z
- Sets the origin of the viewer to the specified coordinate. The
width of the view is not altered.
- Sets the width of the view. This is intended to be used with the center command above.
matrix x00 x01 x02 x03 x10 x11 x12 x13 x20 x21 x22 x23 x30 x31 x32 x33
- Sets the transformation matrix to that specified. Note that the
center and scale should be set with the center and radius commands
- Select the set of atoms specified by selection.
- Select the specified atoms if they are not already selected.
- Unselect the specified atoms.
The principle feature of the scripting language is atom selection
expressions. These allow sets of atoms to be identified by means of
logical expressions in terms of their attributes. Sets of atoms can be
selected on the basis of atom id/name, residue name/number, segment
name, molecule name or proximity to other groups of atoms. These
individual selection statements can be grouped with parenthesis and
| ( Expression )
| Expression and Expression
| Expression or Expression
| not Expression
| sphere radius around Expression
| sphere radius around x y z
| byresidue Expression
The meaning of the atom selection statements is explained below.
Strings may be quoted using the single quote character " ' " and may
contain wildcard characters: * for any characters, ? for any single
character and [abc] or [a-z] for ranges of characters. The atoms
selection expressions are similar to those found in other molecular
graphics/modelling programs such as CHARMM and RasMol.
id id1 [id2 id3 ...]
- Select the atoms that have the specified ids. Atoms from pdb files have
the ids that are specified on the atom records. Atoms from .mol files take
a sequential id starting from 1 for the first atom.
- Select the atoms whose atom name matches the string.
residue id1 [id2 id3 ...]
- The atoms that are in the residues with the specified ids.
- The atoms that are in residues with the specified name.
- The atoms that are in the specified aminoacid chain.
- The atoms that are in the specified molecule.
x/y/z/b/o =/>=/<= number
- The atoms that satisfy the condition on their property.
x, y and z are the respective atomic coordinates.
b is the atomic b-factor for atoms that come
from a pdb file (0.0 for atoms from mol files) and
is the occupancy for atoms from pdb files (1.0 for atoms from molfiles).
- All atoms in all molecules.
- No atoms at all (useful for resetting selections and such like).
- Atoms that are in residues that have one of the 20 standard amino-acid
- Atoms that are in residues that have standard solvent names (HOH, WAT, TIP).
- Atoms in residues that have one of the standard DNA base names.
- Atoms that are ions (Zn, Ca, Mg, Fe etc.).
- Atoms that are currently selected. They appear with yellow dots
in the dsiplay.
- Atoms that currently have a label.
- Atoms that are currently visible.
Examples of atom selections
atom CA select all C-alpha atoms (and Calciums)
atom CA and aminoacid select all C-alpha atoms
(atom C or atom CA or atom N) and aminoacid
select backbone atoms
name GLY select atoms in all Glycine residues
molecule mol1 select atoms in mol1
molecule m* select atoms in all molecules whose name
begins with m
chain A select atoms in chain A
sphere 5 around residue 100 a 5A sphere of atoms around (and including) residue 100
Once groups of atoms have been selected, they can be operated on in
various ways. For instance, they can have their colour changed or
their display style modified. The atom selection expressions also form
the basis of the surface generation commands described in the next
AstexViewer provides three methods for controlling its behaviour as
an Applet in a web page. These methods are described below. The examples
assume there is an applet in a web page called
- Passes a string of scripting language commands to an AstexViewer
applet. The commands are interpreted (no error code is returned). This
is the main method for interacting with AstexViewer from a web page by
Internet Explorer and Netscape. The calls to an Applet are usually
made from the OnClick() (and equivalent) actions of a
execute('colour green atom C*;');
execute('molecule display mol1 off;');
- This method causes AstexViewer to open the URL specified
in the argument. All output is read from the URL and it
information about what to display and other things.
AstexViewer may only open URL's on the server that it
was downloaded from. This is a restriction imposed by
the default Applet security model, and is not a limitation
- This method returns a list of selected atoms in AstexViewer.
The method returns a string that lists all of the atoms selected
for each molecule. The ids are appropriate for passing back in
a select statement. The return format is illustrated below
The selections for each molecule are separated by '|' characters.
The molecule name is the first part of each subexpression
(mol0, mol2 and ligand 23 in the example above) and the
remaining ',' separated tokens are the atom ids for each molecule.