# Building TopoVista

## Prerequisites

Building and using TopoVista requires certain software that may not be currently installed on your system. This software is described below.

TopoVista has been built and tested on Linux, Irix, and Macintosh systems. Other systems will probably work, provided that the necessary software is available, but minor configuration changes may be needed.

On an Apple Macintosh, building and running TopoVista is done in Unix fashion, by typing commands in a terminal window. All the necessary software is provided by the “Xcode CD” (formerly the “Developer CD”); this CD accompanies a Mac OS X package but must be separately installed.

## OpenGL and GLUT

TopoVista uses OpenGL and GLUT. This software is included in a full installation of Red Hat Linux. In other environments, you may need to add it.

OpenGL is a software library for rendering graphics. Originally from Silicon Graphics, OpenGL is available from several workstation vendors including SGI, Sun, IBM, and HP. It is also part of many standard Linux distributions. For information on OpenGL, see the OpenGL website.

Mesa, a free clone, can be used as a substitute for OpenGL. Mesa runs on several platforms including Linux. For information on Mesa, see the Mesa website.

The GLUT library, designed for use with OpenGL, provides event and window handling and a framework for using OpenGL. For information on GLUT, see the GLUT page.

## Java

Many parts of the TopoVista package are written in Java. TopoVista needs Java 2 version 1.4. On Linux, we use the Java Development Kit distributed for Linux by Sun Microsystems. For SGI and other commercial systems, get Java from the manufacturer.

## Other Prerequisites

TopoVista uses the Zlib compression library to read input files in gzip format. If this library is not part of your system, you can find it at the Gzip website.

The `tvshow` script uses an image viewer specified by the environment variable TVVIEWER. The default viewer is the ImageMagick `display` viewer, which is distributed with Red Hat Linux. `xv` and `xloadimage` have also been tested. Set TVVIEWER to select an alternate viewer.

Two auxiliary scripts (`tvfly` and `tvlose`) use the Icon programming language. Icon is not required unless you wish to use these scripts, which are not central to the functioning of TopoVista.

## Configuration

Configuration options are set by editing the `Makedefs` file.

It may be possible to build TopoVista without making any changes. This is the case for Red Hat Linux 9 and SGI Irix 6.5.

For Mac OS X 10.2 or 10.3, change the `GLIB` definition as indicated in the comments.

Other possibilities are given in the comments.

## Building

After verifying prerequisites and making any necessary changes to the `Makedefs` file, enter

> `make`

to build the TopoVista system.

A successful build leaves all the useful end products in the `bin` directory. Add this directory to your search path.

## Testing

To run automated tests of TopoVista components, enter

> `make test`

A successful run concludes with the message “ALL TESTS PASSED”.

A small set of sample data is provided in the `data` directory. Enter one of the following commands to start TopoVista:

> `bin/topo data/crater/504J309i.tvg data/crater/crater.ppm.gz
> bin/topo data/supai/252L6279f.tvg data/supai/trail.fp
> bin/topo data/lemmon/503L465h.tvg data/lemmon/lemmon.fp`

The first example includes land use coloring. The other two examples include prepared flight paths; press the `P` key in any of the three TopoVista windows to start the animation.

## Running TopoVista

See The TopoVista Viewer for full documentation on running the viewer. See Preparing Data for instructions on obtaining your own data sets.

INDEX