What's New
User Guide
Mailing List
Terrain Data
Download TerraVision Datasets
OGC Web Map Server
Browse TerraVision Datasets
tsmWeb Inspector
DPSS Library

TerraVision Server

In order to serve TerraVision datasets from your http server, you need in install a TerraVision server. This is a piece of software that responds to queries to return segments of a large terrain dataset. The most efficient way to do this is using the TerraVision Apache Server module. In order to use this module, your Apache server must have been compiled with the mod_so module (available in Apache 1.3 and later).

Below is a set of TerraVision server binaries for a number of platforms. These are dynamic library files (a .dll under Windows or a .so under Unix). You should install this file in the modules directory of your server root and use the LoadModule directive to load it.

Server Operation

The TerraVision Apache module maintains a cache of open connections to datasets on the server. In addition, the binary itself is kept in memory as part of the running http server. This helps to remove any startup/shutdown delays and provides an optimized capability to serve terrain data at high-performance rates.

The server accepts URLs of the following form. Note that the pathname part of the URL must begin "TV/" in order to be recognized as a TerraVision dataset, and the extension of the file being referenced should be either ".oi" or ".dem".


This URL is then translated into a local pathname on the specified server by replacing the section of the URL up to and include the "/TV" with the server's document root. For example, if your server's root is /usr/local/httpd/htdocs, then the above URL will be translated to the following localhost pathname.


In addition, you may specify a number of options after the URL using standard CGI-type conventions. The following options are currently supported by the TerraVision Apache module.

  • x=n  -  specifies the desired tile's x coordinate
  • y=n  -  specifies the desired tile's y coordinate
  • level=n  -  specifies the desired tile's level number
  • debug=1  -  output debug information and don't get the tile
  • check=1  -  returns a known string to test for server
For example, click here to download the raw data for tile (0,0,2) of the sfbay.oi dataset on the server avila.ai.sri.com.

Server Configuration

Taking the example of configuring for the Unix platform, you should copy the mod_terravision.so file into the libexec directory of the Apache server root. Then update the conf/httpd.conf file to have it load this module on startup. You also need to set up a <Location> directive to specify when the module should be used. Once you have updated the http configuration file, you will need to restart the server for the new settings to take effect (N.B. you will normally require root privileges in order to do this). Here is an extract from a correctly configured httpd.conf script (the .... text below is meant to represent other possible Apache commands in the script).
# Dynamic Shared Object (DSO) Support
# To be able to use the functionality of a module which
# was built as a DSO you have to place corresponding
# `LoadModule' lines at this location so the directives
# contained in it are actually available _before_ they
# are used. Please read the file README.DSO in the
# Apache 1.3 distribution for more details about the DSO
# mechanism and run `httpd -l' for the list of already
# built-in (statically linked and thus always available)
# modules in your httpd binary.
# Note: The order is which modules are loaded is important.
# Don't change the order below without expert advice.
# Example:
# LoadModule foo_module libexec/mod_foo.so

LoadModule terravision_module libexec/mod_terravision.so

# Reconstruction of the complete module list from all
# available modules (static and shared ones) to achieve
# correct module execution order.

AddModule mod_terravision.c

# Set the handler for TerraVision .oi and .dem datasets.
# Currently need to prefix actual URL with /TV because
# the Location directive only seems to work (use the
# module handler) if the directory does not exist.
# How do we get round this????

<IfModule mod_terravision.c>
  <Location ~ "/TV/.*\.(oi|dem)">
    SetHandler terravision-handler


The TerraVision Apache module will output any errors that occur during its operation to the http server's error log (if it was compiled with the DEBUG flag), as defined in your httpd.conf script. Any such error reports will be prefixed with "mod_terravision":. You can look in this log to help diagnose any problems with the TerraVision server.

The source code for the mod_terravision Apache module is provided as Open Source under the Apache license as part of the tsmApi distribution (in the tsm/tsmUtils directory). You can also download the source code directly for mod_terravision.c.



Copyright © 2002 SRI International. All rights reserved.

For more information, please contact: digital-earth@ai.sri.com.
Last updated: Wednesday, 19-Dec-2001 13:17:54 PST.