# The TopoVista Viewer

TopoVista displays an interactive 3-D perspective view of a digital elevation model. It reads data from elevation grids prepared by `tvconvert`; see Preparing Data for details. The synthesized views are pseudo-colored by elevation or by optionally supplied PPM images.

TopoVista uses an RTIN (Right Triangular Irregular Network) hierarchy to approximate the original surface. The approximation is sensitive to the current eye position, so that portions of the terrain near the eye are more closely approximated than those farther away. This improves interactive response by reducing the number of triangles rendered for each frame.

Imagine a flat triangular sheet whose three corners are nailed to the surface of the earth. Because the earth is bumpy, while the sheet is flat, the earth's surface may, in some places, be above or below the sheet. The error of the triangle is the maximum vertical distance from the sheet to the earth's surface. When the error is too big, TopoVista bisects the triangle to use two smaller triangles that better approximate the bumpy surface of the earth.

## Running TopoVista

TopoVista is run by specifying a tile (an elevation grid) and optionally some additional files. The command synopsis is as follows:

>     topo [options] tile [coloring...] [track...] [flightpath...]

>       -c tsvc   configuration file for token service interaction
>       -d nn.nn  distance threshold
>       -e nn.nn  error threshold
>       -t        time the hierarchy and surface creation
>       -v nn.nn  vertical scaling factor

The starting tile must have a name of the form xxxUyyyc`.tvg` and can be any of:

- a simple file name
- `file:`///path/xxxUyyyc`.tvg`
- `http:`//host/path/xxxUyyyc`.tvg`
- `tvtp:`//host/comment/xxxUyyyc`.tvg`
- `trvp:`//host/comment/xxxUyyyc`.tvg`

Arguments following the tile specify files for coloring, tracks, or flight paths, in any order. File type is determined by inspection.

TopoVista comes with some sample data files. From the top-level TopoVista directory, with the `bin` directory in your search path, try any of these commands:

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

## TopoVista Windows

TopoVista opens three windows. The control window displays lines of text giving current parameter settings. The square overhead window shows a two-dimensional view of the initial tile. The rectangular perspective window displays a three-dimensional view.

The V shape in the overhead window indicates the field of view displayed in the perspective window. The black dot (initially centered in the overhead window) shows the focus of attention. The overhead and perspective windows can be resized.

The viewing position is changed by clicking or dragging the left mouse button in the overhead window. The right button sets the focus. Clicking or dragging in the margins scrolls the overhead window and may load additional data if available.

Clicking the center button of the mouse writes the latitude, longitude, and elevation of the selected point to standard output. If land use information is available from a PPM file, that is also included:

> `42.938491 –122.145240 elev 2101.9m Evergreen Forest Land`

The view can also be changed by keystroke commands, which can be entered in any of the three windows:

> `Space` | moves the viewer forward
> `Backspace` | moves the viewer backward
> `Left Arrow` | swings the view leftward
> `Right Arrow` | swings the view rightward

If the shift key is held down, these commands have a greater effect.

## Viewing Parameters

Most of the values in the control window affect the display. The are altered either by clicking with the left or right mouse button, or by keying into any window the character indicated in brackets.

[`C`]olor by | Cycles through alternative colorings of the terrain: any colorings from PPM files elevation-based pseudo-coloring gray “melted lead” shaded relief
Error[`>0<`] | Controls how closely the surface is approximated by triangles. The value is a ratio; the initial value allows a maximum error of one meter at a distance of one kilometer. The `>` (`<`) key increases (decreases) the allowed error, so the approximation gets worse (better). The `0` key sets the error to zero; pressing it again restores the previous error value.
Distance[`+–`] | The `+` and `–` keys alter the drop-off value which supplements the error value with additional constraints. Within the drop-off distance, initially 700m, every triangle has size 1 (the finest resolution). Within twice the distance, triangles may have size 2; within thrice, size 3; and so on.
[`E`]ye[`Zz`] | Height of the perspective viewpoint in meters. The `E` toggles between an up height and a down height. Up means the perspective view is from a position far above the surface of the earth. Down means you're walking on the surface. Don't be shocked if you can't see anything when you're down on the surface. You may be looking at a cliff, or even through a cliff. The `Z` and `z` keys fine-tune the current height.
[`2`]d Mesh | The triangles used to approximate the surface can be shown in the overhead window (the 2-D window) by toggling this option. 2-D Mesh has 3 modes `Off`, `On` and `FOV Fill`. This last mode shows the triangles in the field of view along with status indicators described below under Tile Loading Status.
[`3`]d Mesh | Shows the triangles in the perspective view. There are two modes: `Off` and `On`.
[`V`]ert.Exag. | Controls the vertical exaggeration factor. `v` increases the exaggeration and `V` decreases it.
[`S`]mooth | `On` applies smooth shading to the perspective view.
[`B`]ackface Cull | `On` suppresses the drawing of triangles with a surface normal pointing away from the viewer.
[`F`]OV Cull | `On` suppresses the drawing of triangles outside the field of view.
[`^P`]rint [`^p`]s | `Ctrl+p` writes a high-resolution PostScript image of the perspective window. Be prepared for a huge file if your current view has many triangles. Thanks to Mark J. Kilgard. `Ctrl+Shift+P` outputs an STL file, a common format for 3-D printers. File names are based on the initial DEM file but with a `.ps` or `.stl` extension.
[`P`]lay flight | Pressing `p` plays a Flight Path as described below. Playback can be interrupted by pressing `Esc`.
[`R`]ecord flight | Pressing `r` begins recording interactive actions in a Flight Path for later playback. Pressing `r` again terminates the recording.
[`Q`]uit | Exits the viewer.

The following additional commands are not shown in the control window:

`Esc` | Terminates playback of a flight path.
[`L`]oop | Takes a stroll around the boundary of the overhead window, and outputs timing measurements. `Shift-L` does this without displaying anything.
[`D`]iscard | Discards all currently loaded tile data.
`Enter` | Simulates a null move, with the effect of loading any missing tiles under the overhead window.
`Home` | Resets the overhead window and the view to the original starting tile.
`End` | Repositions the overhead window and the view to the southwest corner of the bounding box of all loaded tiles.

## Coloring

The terrain can be color coded by elevation or colored using an image from a PPM file. An image created by `ctg2ppm` (see Data Preparation) is correctly aligned to the elevation model. Any other image is simply replicated over every tile.

## Tracks

Tracks such as logs from GPS receivers can be painted on the surface. A track file is a sequence of lines; if the last two items on a line are floating-point values, they are interpreted as latitude and longitude coordinates. Other values such as timestamps may precede the coordinates. A line with no data denotes a break in the track. See sample files in topo4/data/lemmon/lemmon.trk or topo4/test/convert/josephine.trk.

## Flight Paths

A flight path directs TopoVista to present a sequence of pre-programmed views. Flight paths can be created manually, using the `R` command, or programmatically, using the tvfly utility.

A flight path file is a sequence of lines, each containing six numeric values: delay and eye height, integer; eye latitude and longitude, floating; and focus latitude and longitude, also floating. See a sample file in topo4/data/lemmon/lemmon.fp.

## Tile Loading Status

The FOV Fill display appears in the overhead window when toggled by the `2` key. This display also shows details of tile loading when using the TVRP protocol.

A circular target appears for each tile. The target is made of smaller segments that correspond to the individual records within a tile:

- The center circle corresponds to the tile header.
- Segments of the inner ring correspond to the data records.
- Segments of the outer ring correspond to the error records.

Segment colors indicate the status of data acquisition. Colors ranging from blue to green to yellow to white indicate records that are needed, with brightest colors having highest priority. Hot pink indicates data that has been received but not yet processed. Light gray indicates data that has been processed and is available for display. Dark gray indicates unavailable data; black indicates unneeded error data.

It is not uncommon for the outer ring (the error records) to be partly or completely dark. Because the error values can be computed from the data records, they can be omitted from a stored or transmitted tile.

INDEX