Digital Earth: tsmApi: Tutorials


tsmApi^TM Library
•	About
•	Download
•	License
•	What's New
•	Tutorials
•	GeoVRML Support
•	Adding File Filters
•	API Specification
•	File Formats

Digital Earth > tsmApi > Tutorials

tsmApi Tutorials:

The following links provide some instruction on how to use the tsmApi^TM interface for performing various command operations. Incomplete source code segments are provided to demonstrate concepts were necessary.

Compiling a tsmApi Program	Describes all of the tsmApi^TM libraries, what they are for, and how you can compile a program that has been developed for use with the tsmApi^TM and DPSS libraries.
Opening a connection	Shows you how to open a connection to a terrain dataset and how to use the TsmConnectionParams structure.
Querying a connection	Once you've opened a connection to a dataset, you may often want to know something about it. For example, the size of the dataset, its name, the image format of its data, etc. Here's how you do all of that.
Reading Tiles	Now that you can open a connection to a dataset, this tutorial shows you how you can read data from that dataset.
Manual Tile Buffer Management	If you want, then you can manage all of the tile buffer allocation yourself for reading tiles. This tutorial shows you how to do this, and tells you why you might not want to do this.
Copying Data	Copying data from one place to another is a common task. So tsmApi^TM makes this easier for you with a number of useful copying functions.
Command Line Parsing	To make parsing of command line arguments easier in your shell programs, tsmApi^TM provides some useful functions to check for options, as well as supporting a number of standard tsmApi^TM command line options.
The Emulation Layer	If you used the old server-centric tsmApi^TM, then this tutorial gives you some information on the differences between this and the new connection-based API.

Example Source Code:

The following links provide access to a number of complete programs written in C using the tsmApi^TM library. These are provided both to illustrate how to use the tsmApi^TM, and also to server as useful utilities for manipulating tile and associated data. This material is released under the Apache Open Source License.

These programs are part of the tsmUtils distribution. You can download tar archives of the source code for these programs, as well as pre-compiled binaries for a number of platforms, from the tsmApi Download Page.

Makefile	A Makefile to help simplify the process of compiling up code that uses the tsmApi^TM and DPSS libraries. You can easily customise this for your particular platform and system - just follow the comments.
simple.c	simple main program to read in one tile and print it's checksum. This illustrates the basic operations for using the tsmApi^TM. Note that no error checking is included in order to reduce "clutter" for the example.
get_tile.c	Reads a single tile from a dataset and saves this out to a PBM format file in the current directory called "tile.ppm". This will also display various bits of information about the connection such as it's dimensions, tile sizes, name, etc.
get_tspec.c	Reads the tspec file from a dataset and the outputs this to stdout. You can redirect this to a file if you want to save the tspec to disk. The normal tsmApi^TM read options are available so you can select where you want to read the tspec from for DPSS and localdisk datasets.
copy_dataset.c	Copies tile and tspec data from one location to another. The source and destination can be on different media, e.g. localdisk or DPSS. Options are provided to selectively copy only the tspec or only the tile data. When copying to a DPSS you can select the server combination, image format, and tspec location(s). Manual Page
get_http_tile.c	This was designed as a CGI program which needs to be installed in the /cgi-bin directory of an http server in order to serve tiles from that http server. This is required because the TIFF format stores all tiles in one file, so this CGI script runs on the server to extract the specified tile from this file and return it to the client.
time_tiles.c	test program to time how long it takes to read in all of the tiles in an entire pyramid, or just a single pyramid level. Used to compare read speed for different dataset representations.
database.c	This program provides various facilities for maintaining a dataset database. This includes being able to list all of the server names and dataset names in the database, add a new server to the database, remove all instances of a server from the database, and update the contents of the database with the datasets on all of the servers that it knows about.
make_oi.c	creates an entire OI pyramid (UTM). This can generate the tspec file, the tiles for each level of the pyramid, and the PyramidUrls database. The dataset can be written to localdisk or directly to a DPSS, and in raw or JPEG compressed formats. Manual Page
make_dem.c	creates an entire DEM pyramid (UTM). This can generate the tspec file, the tiles for each level of the pyramid, and the PyramidUrls database. The dataset can be written to localdisk or directly to a DPSS. Manual Page
make_geovrml.c	creates an GeoVRML 1.0 compliant version of a TerraVision OI and DEM dataset. This involves creating a GeoLOD hierarchy using GeoElevationGrid nodes for the geometry of each tile. Manual Page
dem_to_pgm.c	reads a DEM pyramid level and outputs this as a grayscale image where white = high. Automatically strips out overlap pixels and resamples 32-bit values down to 8-bit intensities. This is useful for visualising DEM datasets as most image viewers can't handle 32-bit data and even then the overlap pixels can cause artifacts.
checksum.c	checksum management for a pyramid. The tspec for a pyramid can hold a checksum for the entire pyramid and a checksum for each level of the pyramid. This program lets you read the current values, calculate the values from the pyramid, write these new computed values to the pyramid's tspec, clear the pyramid's values, and do a comparison between the current and computed checksums.
calc_stats.c	Reads every tile in a pyramid and updates the min and max pixel values in the tspec file. These values are important, particularly for DEM pyramids, to find good ranges to scale values to. This utility will also fill in the checksum array for the specified image format.
utm_conv.c	coordinate conversion program that will let you convert between UTM and Lat/Long coordinate systems using the tsmApi's conversion functions.