LINK="#0000FF" VLINK="#000080" ALINK="#FF0000">

AstexViewer Documentation

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
Mouse Controls
Keyboard Controls
Menu Items
Web Page Applets
Scripting Language
Applet Methods

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:

  1. 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.
  2. Astex makes no warranty, express or implied, as to the merchantability, non-infringement of third party rights, or fitness for any particular purpose.
  3. 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 third party.
  4. 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.
  5. The user is not permitted to repackage the software for inclusion in other packages without the prior approval of Astex.
  6. 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.
  7. Astex is under no obligation to maintain the AstexViewer software nor to respond to requests for information from the user.
  8. 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 software.
  9. 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 machines.

Mouse Controls

The program has controls that are similar to many other desktop molecular graphics programs.

Drag-left Rotate molecule using virtual trackball
Shift-left-drag 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

Keyboard Controls

The following keys perform actions when pressed in the viewing window.

d If exactly two atoms are selected, then a distance measure is drawn between them.
r 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.
A All atoms are selected.
d If two atoms are selected then a distance monitor is shown between the two atoms.

Menu Items

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.
  • File
    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 viewer.
    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.
  • Select

    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 greyed out.
    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.
  • Display

    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.
  • Colour
    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 high b-factors.
    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.
  • View
  • Reset
    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.
  • Measure
  • Nothing
    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.

<applet archive="AstexViewer.jar"
        width="400" height="300">
<param name="molecule" value="1xyz.pdb">
<param name="map" value="">

This example will read a structure called 1xyz.pdb, and a map called 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 codebase="wherever" tag).

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.

<applet archive="AstexViewer.jar"
        width="400" height="300">
<param name="molecule1" value="mol1.pdb">
<param name="molecule2" value="mol2.pdb">
<param name="molecule3" value="mol3.pdb">
<param name="map1" value="">
<param name="map2" value="">
<param name="map3" value="">

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 [CHAIN:]first_residue[-last_residue]. Some examples are given below.

A:1Select residue 1 in chain A.
A:1-10Select residues 1 to 10 in chain A.
1-10Select 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

<applet archive="AstexViewer.jar"
        width="400" height="300">
<param name="molecule1" value="protein.pdb">
<param name="molecule2" value="ligand.pdb">
<param name="map" value="">
<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.

<applet archive="AstexViewer.jar"
        width="400" height="300">

<param name="script" value="
molecule load molecule1 protein.pdb;
molecule load molecule2 ligand.pdb;
map load map1;
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 javascript buttons allow the different structures to be turned on or off. 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.

Scripting Language

AstexViewer supports a scripting language for controlling its behaviour either at startup or from JavaScript controls 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.
centre selection
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.
radius r
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 above.
select selection
Select the set of atoms specified by selection.
append selection
Select the specified atoms if they are not already selected.
exclude selection
Unselect the specified atoms.

Atom selections

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 Boolean operators.
Expression ::=
	| ( 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.
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.
atom string
Select the atoms whose atom name matches the string.
residue id1 [id2 id3 ...]
The atoms that are in the residues with the specified ids.
name string
The atoms that are in residues with the specified name.
chain string
The atoms that are in the specified aminoacid chain.
molecule string
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 o 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 names.
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.
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.

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 section.

Applet Methods

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 document.form.av.
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 use of JavaScript. This is supported in all recent versions of Internet Explorer and Netscape. The calls to an Applet are usually done via a JavaScript function. The actual function calls are usually made from the OnClick() (and equivalent) actions of a JavaScript control e.g.
function execute(s){

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 is returned to JavaScript as a string value. This allows JavaScript to make calls back to a server to obtain 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 of AstexViewer.
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.

Mike Hartshorn