ChemRote README File

The following is a brief introduction to java, hopefully enough to enable you to use the ChemRote applet. The text on java is an excerpt from a short Java faq I wrote, the rest is the specifics for installing and using ChemRote.
Table of Contents:


1.0 Java Applet Introduction

Java, unlike HTML, is a programming language. This means to create something in Java, you should have a basic knowledge of Java. Java can be used to write stand alone programs, called applications, or for programs that run within a web page, called applets.

1.1 Using a Java applet on a web Page

To run Java on a web page, the applet must be embeded within an HTLM document. This is done with the applet tag. This tag can be used to specify a Java applet, its size, as well as any parameters that are specific to that applet.

The starting <applet> tag has several components. These include the applet name (Java program to be executed), as well as the width and height of the applet, within the HTML page. An optional codebase (directory the applet resides in) can also be included. For an applet named Test.class, in the java directory, with a width of 20 and height of 10, would look like this:

    <applet codebase="/java" code="Test.class" width=20 height=10>
    </applet>
Notice the tag closer, </applet>. All parameter files go between the <applet> tag and the </applet> tag. If you wanted to include an HTML tag that would be seen on a browser that could not see your applet (a non Java-enabled browser), then that code would also be between the <applet> and >/applet> tags. Note that this extra code is ignored by browsers that are Java enabled.

1.2 Using Applet Parameters

A parameter tag for an applet has two fields in it, the name, and the value. Lets say our previous example had a parameter called color, and we wanted to set it to red. Lets also assume that we want to load an image called NoJava.gif if they can't see the applet. The code would then look like this:

    <applet codebase="/java" code="Test.class" width=20 height=10>
    <param name="color" value="red">
    <img src="NoJava.gif">
    </applet>

2.0 The ChemRote applet

This is a very simple applet, that will display a molecule as set of vectors in a web page. It will allow a user to directly interact with the molecule through rotating and resizing directly on the page.

2.1 Unpacking and Installing

The ChemRote applet comes in two distributions, at tarred, gziped archive for Uniz platforms, and a zipped file for Windows platforms. If you require a compressed file of another type, contact John N. Huffman at jnhuffma@indiana.edu, and arrangements will be made.

2.1a Using the ChemRote.tar.gz File

To unpack the tarred gzipped file (ChemRote.tar.gz), go to the directory you wish to install the files into. This must be within the directory tree of your HTML files being served by your web server. Then use the command:

	gzip -cd ChemRote.tar.gz | tar xvf -
This will extract the files into a directory called ChemRote. If you just wish to see the contents of the archive file, use:

	gzip -cd ChemRote.tar.gz | tar tvf -

2.1b Using the ChemRote.zip File

To unpack the zipped archive file (ChemRote.zip), go to the directory you wish to install the files into. This must be within the directory tree of your HTML files being served by your web server. Then use the command:

	pkunzip -d ChemRote.zip
This will extract the files into a directory called ChemRote. If you just want to see the contents of the archive file, use:

	pkunzip -v ChemRote.zip

2.2 Including ChemRote in an HTML File

To include this applet in an HTML page, use the following tag if you unpacked the ChemRote archive in the root directory of your web server files:

	<applet codebase="/ChemRote" code="ChemRote.class" width=20 height=10>
	<PARAM NAME="model" value="bucky.crt">
	</applet>
Note that the tags for the applet are not case sensitive, but the valuse are, so if the crt file were BUCKY.CRT, type it in the same case in the value field:
	<PARAM NAME="model" value="BUCKY.CRT">
For more Information on including a Java applet, see section 1.1, Using a Java applet on a web Page.

2.3 ChemRote Parameter Tags

There are several parameters that can be used to modify the way this applet looks. Depending on which parameter you use, different parts of the program are loaded on the clients machine when the applet is started. Below is a list of the parameters the applet will accept, as well as any additional information that may be needed.

Parameter Name: Parameter Value:
model*crt file name
backgroundbackground color
border**include a border
image**include a tiled background image

*This is a required parameter.
**This causes the web browser to load an extra file when the applet is loaded, but generally won't take much longer than if it were not use.

2.3a Model Parameter

The model parameter gives the name of the crt file to be used for the applet. This is the only parameter that is required. It has the following form:

	<PARAM NAME="model" VALUE="bucky.crt">
This applet came with a test file called bucky.crt. The above tag works if the file bucky.crt is in the same directory as the ChemRote applet. If it is in another location, specify the path relative to the web files on your server. For example, if all your web files are in /usr/local/www, and your data files (crt files) are in /usr/local/www/data, then the parameter name would look like:

	<PARAM NAME="model" VALUE="/data/bucky.crt">

2.3b Background Parameter

The background parameter specifies a background color for the applet, and if it is not specified, defaults to grey. The value uses the same form as any other color in an HTML tag, RRGGBB, where each set of letters represents the hexadecimal values of a red, a green, and a blue value between 0 (00) and 255 (FF). The only difference between this and a regular color tag is that the # must be omited. The tag for using the color red would look like this:

	<PARAM NAME="background" VALUE="FF0000">
Note: The wireframe molecule uses a shading technique that makes it look like it is fading into the background. This is known as depth queing. To accomplish this, the model fades from black, to the background color specified. If you want to use a background image instead, use a background color also, that is similar in color to the background image. That way, the molecule will apear to fade into the background image.

2.3c Border Parameter

This parameter will add a border around the outside of the applet. It is a raised border, and is used to highlight the boundaries of the applet. To use this parameter, include the tag:

	<PARAM NAME="border" VALUE="true">
Note that any value in the value field will produce a border. If you don't want a border, just leave out this tag.

2.3d Image Parameter

This parameter will cause the applet to use the gif or jpeg image specified to be tiled in the background behind the molecule. This can be used to blend into a page with a background image, or just for putting an image behind the molecule. Transparent gif images work within the applet, so if the background parameter is used with a color, that color will show up through the transparent gif. Note that if this parameter is used, the image is tiled in the applet on top of the color, so if both the background parameter and the image parameter are used, then the background color may not be seen. To use this parameter, use the tag:

	<PARAM NAME="image" VALUE="background.gif">
The above tag works if the file background.gif is in the same directory as the ChemRote applet. If it is in another place, use the files path relative to the web files on your server. That means if all your web files are in /usr/local/www, and your image files are in /usr/local/www/images, then the parameter name would look like:

	<PARAM NAME="image" VALUE="/images/background.gif">

3.0 The crt file format

This applet uses the crt file format, a format in use at the Indiana University Molecular Structure Center (IUMSC) to describe crystallographic data for molecules in Cartesian coordinates. The file consists of the xyz coordinates of each atom followed by bond pairs. An example crt file is provided, bucky.crt. There are three main parts to the crt file, the header, the atom coordinates, and the bond pairs.

3.1 crt Header

The header is composed of four elements: the Keyword CARTESIAN, the number of atoms, the number of bonds, then a short, non-whitespace identification string. The identification string is ignored in this program, but is necessary in other programs provided by the IUMSC. An example header, for a file with 24 atoms and 25 bonds would look lie this:

CARTESIAN	24	25	MSC96491

3.2 crt Atom Table

Each entry in the atom table has four elements: The atom identification string, the x, y, and z coordinates, and the atomic number. The Identification string is Composed of One or more letters (the atomic symbol) followed by an alpha-numeric string in parenthesis. There should not be more or less lines than specified in the crt header line. The key word ENDATOMS is used to signify the end of the atom data. This table would look something like this:
C(1)         0.00000   0.00000   0.00000   6
C(2)         0.22746  -1.36771  -0.19379   6
S(1)         0.79195   2.50881   0.96553  16
S(2)        -0.97161   3.06715   0.12215  16
 .		.	  .	    .	   .
 .		.	  .         .      .
 .		.	  .         .      .
H(9)         1.46573   2.66531  -4.03502   1
H(10)        1.17476   2.30247  -1.75361   1
ENDATOMS

3.3 crt Bond Table

Immediately following the ENDATOMS key word, the bond table begins. This is a list of pairs of indexes into the above atom table. Each line has two integer numbers, representing a bond to the corresponding atoms. At the end of the list is the key word ENDBONDS. An example bond table would look like this:
   1   2
   1   6
   2   3
   .   .
   .   .
   .   .
  12  22
  13  23
  14  24
ENDBONDS

4.0 ChemRote commands

Using ChemRote is very simple. To rotate the molecule, click the left mouse button in the applet, then move the mouse. The molecule should rotate in the direction the mouse is dragged. Clicking the right mouse button (<alt>+click for a one button mouse) within the applet and moving the mouse will resize the image. To reset the molecule size and rotation, press r. Pressing shift and any mouse button within the applet will take you to more information about the applet.

CommandAction
left mouse click + moveRotate molecule
Right click + move
(<alt>+mouse button)
Resize molecule
<shift> + clickTake you to information on applet
r keyresets molecules size and position