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.


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