# TopoVista Programs and Scripts

This document provides a brief synopsis of the options accepted by the programs and scripts in the TopoVista `bin` directory.

## ctg2ppm — prepare CTG file for use with TopoVista

    usage:  ctg2ppm [CTGfile [PPMfile]]

    ctg2ppm converts a USGS Composite Theme Grid (CTG) file to a PPM file with
    special comments specifying geographic coordinates for use with TopoVista.

    For CTG data files, go to edc.usgs.gov/geodata and select "LULC".
    The 100K data files are smaller but 250K coverage is more complete.
    Find your area, download the "grid_cell" file, and unzip it before
    running ctg2ppm.

    Example:  gunzip <grid_cell.gz | ctg2ppm | gzip >landuse.ppm.gz

## gpxflat — convert GPX data to flat ASCII format

    usage:  gpxflat [file...]

    gpxflat translates one or more GPX files to the format read by TopoVista.
    GPX is an XML data format for GPS tracks, routes, and waypoints.
    For more information about GPX, see www.topografix.com/gpx.asp.

## sdts2dem — convert SDTS DEM files to native mode

    usage:  sdts2dem [-n] [DDFbase [DEMbase [cell_id]]]

                -n:  add nonstandard newline after each 1024-char block
           DDFbase:  first 4 chars (ABCD) of DDF file name (ABCDxxxx.DDF)
           DEMbase:  file name for output, without .DEM extension
           cell_id:  last two characters of CELL file name, if not L0

    sdts2dem reads the set of *.DDF files that form an SDTS DEM dataset
    and writes a native mode DEM file with the same data.

    sdts2dem asks for DDFbase and DEMbase if they are not supplied as
    command-line arguments.  It can usually infer cell_id to be L0.

## tgztodgz — convert SDTS DEM to native mode

    usage:  tgztodgz [-#] [file]

    	-#	(where # is 1 through 9) set gzip compression argument

    tgztodgz converts a DEM file from SDTS form to USGS "native" form.

    Input is a gzipped tar file of an SDTS dataset containing USGS
    Digital Elevation Model data.

    Output is a gzipped "native" mode DEM file, as produced by SDTS2DEM,
    representing the same data.  This binary output is sent to standard
    output; commentary is sent to standard error.

    Requires sdts2dem, gzip, and gunzip in the search path.

## tkbroker — interactive interface to the token service

    usage:  tkbroker config-file [scriptfile]

    tkbroker is a command-line program for interactive or scripted testing
    of a token server.  Commands are passed to the server and results are
    printed on standard output.  Asynchronous "revoke" messages are also
    printed on standard output.

    Commands are:

    	# comment
    	get name
    	put name datastring
    	request name [x]
    	update name [datastring]
    	release name [datastring]
    	list
    	clear
    	close

    Requires tvjava in the search path.

## tkserver — run a token server process

    usage:  tkserver [options] config-file server-index

    	-c: trace client heartbeats
    	-s: trace server heartbeats
    	-l: trace leader heartbeats
    	-m: trace all other incoming messages
    	-a: trace all incoming messages
    	-1: drop 10% of incoming messages (and so on through...)
    	-9: drop 90% of incoming messages

    tkserver initiates a token server that runs until killed.

    Requires tvjava in the search path.

## topo — the TopoVista tile viewer

    usage:  topo [options] tile [coloring...] [track...] [flightpath...]

        -c  tsvc	specify configuration file for token server interaction
        -d  nn.nn	specify distance threshold
        -e  nn.nn	specify error threshold
        -v  nn.nn	specify vertical exaggeration
        -t		print timing information

    topo is the TopoVista file viewer.  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

    A coloring file is a PPM file used to set background colors.  If the file
    was created by ctg2ppm, it is aligned by geographic coordinates.

    A track file is a list of pairs of floating-point latitude and longitude
    values such as might be collected by a GPS receiver.  An empty line
    denotes a break in the path and the start of a new path.

    Lines in a flightpath have six values: delay and eye height, integer;
    eye latitude and longitude, floating; and reference latitude and longitude,
    also floating.

    The viewer is controlled interactively by mouse and keyboard actions.

## tvconvert — convert DEM files to TopoVista tiles

    usage:  tvconvert [options] file...

    	-e	include error records  (default is to omit)

    	-f	select output tile size of 64 x 64
    	-g	select output tile size of 128 x 128
    	-h	select output tile size of 256 x 256  (default)
    	-i	select output tile size of 512 x 512
    	-j	select output tile size of 1024 x 1024

    tvconvert reads one or more DEM files and/or TopoVista tiles
    and outputs TopoVista tiles, possibly of different size.

    Input files may overlap.  Later values override earlier ones,
    except that "missing values" never replace valid data.

    Output files are written to the current directory with file names
    of the form "xxxUyyyc.tvg".  All valid input values are contained
    in an output tile, but areas without data do not produce tiles.

    The environment variable TVJMEM can be set to specify, in megabytes,
    the maximum amount of memory used.  The default value is 20.

    Requires tvjava in the search path.

## tvdump — print detailed contents of TopoVista tile files

    usage:  tvdump [-c | -s | -v] file...

    	-c	print one-line concise list of record sizes for each file
    	-s	print just the summary of each file
    	-v	print verbose list of every data value in the file
    	otherwise, prints one line per tile record, plus the summary

    tvdump prints information about the structure of a TopoVista tile file
    (in contrast with tvlist, which prints information about its content).

    Requires tvjava in the search path.

## tvfly — generate TopoVista flight path from GPS track log

    usage:  tvfly [options] [filename]

    	-d	convert coordinates from WGS84 to NAD27 datum
    	-r	reverse the direction of travel
    	-R      retrace path after traversal (round trip option)
    	-v n    [10]  orient view toward nth point ahead
    	-a n	[5]   also average n points beyond that point
    	-e n    [100] set eyepoint elevation, in meters
    	-i n    [200] set playback interval, in milliseconds

    tvfly reads a GPS track log and writes (to standard output)
    a "flight path" for use with TopoVista.  Input is a sequence
    of lines; if a line ends with two numeric values, they are
    interpreted as the latitude and longitude of a location.
    Other lines are ignored, as are the beginnings of lines,
    which may contain timestamps or other information.

    Requires the Icon programming language (www.cs.arizona.edu/icon).

## tvjava — execute Java program from topovista.jar

    usage:  tvjava subpackage.classname [args...]

    tvjava executes a Java program from the TopoVista jar file.
    It is usually called by other scripts, rather than by the user.

    The environment variable TVJMEM can be set to specify, in megabytes,
    the maximum memory limit used by the Java interpreter.  The default
    is 20, which is more than sufficient for most programs.

## tvlist — print information about DEM and/or TopoVista tile flies

    usage:  tvlist [file ...]

    tvlist prints information contained in the header of a TopoVista tile
    or a native mode DEM file.

    Requires tvjava in the search path.

## tvlose — drop data from TopoVistaGrid files

    usage:  tvlose file.tvg...

    tvlose alters a set of TopoVistaGrid files in place, removing
    selected data records to simulate network transmission loss.
    For each record, a random number of trailing data or error
    records are deleted, depending on the tile location parity.

    Requires the Icon programming language (www.cs.arizona.edu/icon).

## tvmerge — run the general-purpose topovista.grid.Merge utility

    usage:  tvmerge [-{prcbt}] [file ...]

    	-p	produce raw data in PGM format
    	-r	produce relief map in PGM format
    	-c	produce contour map in PGM format
    	-b	produce binary (gzipped TypedOutputStream) output
    	-t cnu	produce TopoVista grids of order c, pruning n error levels
    		(default n=3), unzipped if suffixed with 'u'

    tvmerge runs the topovista.grid.Merge utility that is also used by
    tvlist, tvshow, and tvconvert.  This utility reads, inspects, combines,
    and reformats elevation grid files.

    With no option character, it writes information about the input file(s).

    Output is normally to standard output.  With the -t option, one or more
    input files must be a named explicitly, and output is to multiple files
    in the current directory with names of the form "xxxUyyyc.tvg".

    Requires tvjava in the search path.

## tvname — translate latitude & longitude to TopoVista tile names

    usage:  tvname nLatitude wLongitude

    tvname prints the tile names (for five tile sizes and two different
    resolutions) that correspond to the given geographic coordinates.
    Latitude and longitude are given as real numbers, in degrees N and W
    respectively.

## tvserver — run a TopoVista tileserver

    usage:  tvserver [options]

       -d dir	serve from tree rooted at dir	(default: current directory)
       -p port	listen on this port		(default: TVRP:4747, TVTP:4742)
       -e pct	error rate (dropped packets)	(default: 0 percent)
       -s msec	sleep this long between sends	(default: 0 msec)
       -t		serve older TVTP: protocol	(default: newer TVRP protocol)

    tvserver runs a TopoVista server that communicates with clients using
    TVTP ("AGILE") or TVRP protocol.  All files with names in "xxxUyyyc.tvg"
    form found in or below the specified directory are served, but note that
    neither protocol can transmit full resolution data for tiles larger than
    256x256.  The -e and -s options simulate imperfect networks.

    Requires tvjava in the search path.

## tvshow — display overlaid DEM and/or TopoVista tile files

    usage:  tvshow [file ...]

    tvshow displays a single shaded relief image of one or more TopoVista
    and/or DEM files.  It produces a PGM file and invokes the viewer
    named by the environment variable $TVVIEWER.

    If TVVIEWER is unset, tvshow uses the "display" utility, which is
    part of the ImageMagick package and is distributed with Red Hat Linux.
    The "xloadimage" and "xv" viewers have also been tested.

    Requires tvjava and the viewer in the search path.

INDEX