DIGSTATS Java 3D Slicer Instructions

DIGSTATS Java 3D Slicer Overview

DIGSTATS Java 3D Slicer is a Java program designed to run over the internet with a web browser. It aids in visualization of three dimensional datasets by displaying a slice, or cross-section, of the dataset. The position and angle of the slice is modifiable by various controls within the program. The applet has been tested with Netscape Communicator 4.05 and Microsoft Internet Explorer 3.0, though it runs much faster under Netscape because of certain optimizations in the Netscape Java Virtual Machine.

Opening a dataset

The program starts with an empty data set. Choose a file from the drop down box in the upper-left hand corner of the window (some files are larger than others and will take more time to load). Once the file is loaded, the first data set is automatically displayed. Files with multiple data sets will list them in the drop-box in the upper-right hand corner. It may take a moment to convert the data to a format usable by your machine and to map the data to colors for display, but this is only done once, each time the data set is loaded.

The applet is capable of viewing any HDF file on the server, not just those in the drop-box. If you wish to view a file not in the list, simply select "Open URL..." and enter the address of the file you wish to view. The file is added to the list and then loaded. Note that because of security restrictions imposed upon the Applet by Java, you cannot enter the URL of a file on your own local hard-drive, or a server other than that where the applet was started from. To do this, you will need to download the applet and run it outside of your web-browser.

Screen layout

Across the top lie drop-boxes for selecting a file to load, and for selecting a particular data set to view if the file has more than one. A box to the left of the window, the viewport, displays the actual slice. Underneath it is displayed the X, Y and Z coordinates of a particular piece of data in the data set. You can view the numerical values of different points by moving the mouse over the slice being displayed. In the center lies a color legend, showing what the colors displayed in the viewport represent, and a wire-frame box with a polygon inside representing position of the current slice being displayed. On the right are controls for adjusting the position of the current slice.

Standard controls

The standard controls are selected by default. With these controls, the orientation of the slice can be changed by choosing one of the three buttons, "Adjust X," "Adjust Y," and "Adjust Z." The "Adjust X" button will produce a slice that is parallel to the Y-Z plane. Moving the "Position" slider or entering a value in the text field will move the plane in the X direction. You can move the slider either by clicking and dragging on the handle, or by clicking once anywhere along the length of the slider. The slice displayed is scaled to fit the viewport.

Advanced controls

Select the advanced controls by clicking on the "Advanced" button under "Control complexity." There are now three variables used to control the slice position: the horizontal angle, the vertical angle, and the radius. The horizontal angle specifies how much the slice is rotated around the Z-axis, which may be adjusted from 0 to 360 degrees. The vertical angle specifies how much the slice is rotated down from the Z-axis, which may be adjusted from 0 (perpendicular to the Z-axis) through 90 (parallel to the Z-axis) to 180 degrees (perpendicular to the Z-axis again). The radius indicates how far from the center of the data set the slice is offset, in a direction perpendicular to the plane. All three variables may be adjusted with the sliders, or by entering a value in the text-fields for more precision. The viewport for slices does not scale or stretch slices to the maximum size, it instead scales the slices smaller so that wide slices, such as those that stretch diagonally across the 3D space, will still have room to display.

Numerical Info

When moving the mouse over the slice currently being displayed, four fields at the bottom of the window will tell you the X, Y and Z coordinates of the point the mouse is over, plus the value of the data at that point. If the data set defines a range for each variable different from the number of data entries along that axis, these coordinates will be in that range. The slice position, however, is still adjusted by the number of data entries present along each axis.

Downloading the Applet

If you wish to view HDF files that are not on a web-server, but instead are on your own local hard-drive, you will need to run the viewer outside of a web-browser in order to avoid the security restrictions placed on applets. You will need several things in order to do this.

Required Items

A Java Virtual Machine
Because it is written in Java, you will need an interpreter for your computer in order to run this program. The applet should run under any version of Sun's Java Developement Kit that is backward compatible to the 1.02 specification (which is currently all of them). Unless you are writing your own Java programs, you will probably only need to download Java Runtime Environment, which contains the bare minimum required to run Java programs. For those using a Mac, Apple's Mac OS Runtime for Java will be required. If you already have one of these components installed, you can skip this part.
- Sun's Java Runtime Environment
- Apple's Mac OS Runtime for Java
- Java Developement Kit
3D Slicer Class Files
These are the files for the actual program. Because there are so many of them, they are all contained in a single zip file. Because they are stored in compressed format, to speed their transfer over the internet, you cannot use them directly with the Java Virtual Machine, which requires uncompressed zip files, but must first unpack them.
- 3D Slicer Class Files (approx. 109 K)

Once you have downloaded and installed the Java Virtual Machine (following the instructions from the web-site you obtained it from), simply create a directory for the program, and extract the files from Slicer.zip, making sure you preserve the directory structure stored in the file (you should now have two subdirectories: Slice3D and hdf). Now you just need to start the Java interpreter with the Slicer class file.

Under Sun's JRE:
At the command-line, type
```
     jre Slicer
    
```
Under Apple's MRJ
Please refer to Apple's documentation for the MRJ. At some point in the future this may be automated for you using JBindery.
Under Sun's JDK:
At the command-line, type
```
    java Slicer
    
```

Using Sun's JRE or JDK, it may be possible to launch the applet while it is still compressed in the .ZIP file, with one of the following commands:

jre -cp Slicer.zip Slicer

Or,

java -cp Slicer.zip Slicer

The index.slice file

The initial list of files present when you start the viewer is located in a file called index.slice. This file is simply a list of data set name/URL pairs, one line each, such as:

    My Data
    mydata.hdf
    My Other Data
    http://www.myserver.com/somedir/myotherdata.hdf

An optional end may appear by itself on the last line. This file should be placed in the same directory where the viewer is started, and all URL's are resolved relative to this position. Note that Applet security restrictions prevent the Applet from loading a file from any server other than the one it was started on. These restrictions do not apply when the viewer is run on its own Java Virtual Machine outside of a web-browser.