Digital Earth: tsmApi: Tspec File Format


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

Digital Earth > tsmApi > File Formats > Tspec Files

Tspec Files:

TerraVision uses a single file to store the metadata associated with an imagery (OI) or elevation (DEM) pyramid. This file is referred to as a tspec file (pro. tee-spec), and has the filename tiles.tspec. It is stored in the top-level directory of a Pyramid.

The following is an example tspec file (for an ortho-image Pyramid) as used by TerraVision. Note that comments (lines beginning with a hash symbol, #) are included to separate the fields into a number of semantic groupings.

  # ---- tile-set.tspec ----
  inverse-resolution-scale-factor 2
  min-valid-level-and-resolution 0 0.0166667
  max-valid-level-and-resolution 8 4.26667
  tile-set-description "USGS 1km AVHRR imagery"
  # ---- identity.tspec ----
  name "gtopo30.oi"
  geo-name "Earth (Gtopo30)"
  planet earth
  checksum-lrbt -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
  checksum-jpeg -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
  type ortho-image
  subtype none
  source-type "unknown"
  sources ""
  operations gauss-reduce
  operation-date "11/1/2000"
  operation-done-by "the tsmApi library"
  # ---- tile.tspec ----
  num-pixels-per-tile-ix 128
  num-pixels-per-tile-iy 128
  num-pixels-overlap-per-tile-ix 0
  num-pixels-overlap-per-tile-iy 0
  num-components-per-pixel 3
  num-bytes-per-component 1
  component-number-type unsigned-byte
  # ---- pixel.tspec ----
  component-names red green blue
  min-pixel-value 0
  max-pixel-value 255
  pixel-scaling-type linear
  scale 1
  offset 0
  # ---- projection.tspec ----
  projection-type latlong-projection
  wrap-lat "yes"
  wrap-long "yes"
  # ---- 3d-coordinate-system.tspec ----
  3d-coordinate-system-type spheroid
  spheroid-name wgs-84
  equatorial-radius 6378137
  polar-radius 6356752.314
  geocentric-to-lcs-matrix 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1
  lcs-to-geocentric-matrix 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1
  lcs-type none
  origin-lat -90
  origin-long -180
  component-units degrees
  # ---- image-transformation.tspec ----
  uv-to-ixiy-matrix 60.0 0 10800.0 0 60.0 5400.0 0 0 1
  ixiy-to-uv-matrix 0.016666 0 -180 0 0.016666 -90 0 0 1
  # ---- tile-set.tspec (all levels) ----
  min-tile-tx 0 0 0 0 0 0 0 0 0
  min-tile-ty 0 0 0 0 0 0 0 0 0
  max-tile-tx 168 84 42 21 10 5 2 1 0
  max-tile-ty 84 42 21 10 5 2 1 0 0
  num-pixels-ix 21632 10880 5504 2816 1408 768 384 256 128
  num-pixels-iy 10880 5504 2816 1408 768 384 256 128 128
  min-valid-pixel-ix 0 0 0 0 0 0 0 0 0
  min-valid-pixel-iy 0 0 0 0 0 0 0 0 0
  max-valid-pixel-ix 21599 10799 5399 2699 1349 674 337 168 84
  max-valid-pixel-iy 10799 5399 2699 1349 674 337 168 84 42

Although a little out of date now, many of the fields in the above tspec example are description in the following technical report (in PostScript format):

Y. G. Leclerc, "Tile set definitions", Technical Note 541, SRI International, Menlo Park, CA, Mar. 1994.

Coordinate Systems:

A DEM and its corresponding ortho-image is like a map in two important ways: First, every DEM has an (x,y) coordinate system such that every point in the DEM can be mapped to a well-defined point on the earth (as defined by, say, the latitude and longitude of the point on the earth). Second, the elevation of a point in the DEM represents the elevation above some well-defined reference surface. For regular maps, this reference surface is the "geoid", which repesents "mean sea level" everywhere, even on land!.

Three coordinate systems are currently supported:

Universal Transverse Mercator (UTM)

Here, the x and y coordinates in the DEM represent UTM eastings and northings, respectively. The reference surface is a "geoid" that approximates mean sea level. The elevation at a point (x,y) is the perpendicular distance from this reference surface to the earth's surface (i.e., it represents the "height above sea level").

The advantage of this representation is that it is a very common map projection, so it it straightforward to compare ortho-images rectified using the UTM coordinate to standard maps. The disadvantage is that a complex computation must be performed to translate a point's easting, northing, and elevation coordinates to a Euclidean coordinate system for rendering and ortho-rectification.

Geodetic or Latitude/Longitude (GDC)

In a geodetic system, the x and y coordinates in the DEM or OI represent longitude and latitude in units of degrees. The reference surface is a geoid that approximates mean sea level. The elevation at a point (x,y) is the height above the geoid, measured in units of meters.

The advantage of this representation is that it can be used to represent datasets that cover a very large area, such as the entire planet. However, it drastically oversamples regions towards the poles, where all lines of longitude converge.

Local Vertical Coordinate System (LVCS)

Here, the reference surface is a flat plane. The x-y plane of the LVCS is defined as the reference plane. At the origin of this coordinate system the plane is tangent to the earth's surface. Consequently, the z-axis is vertical (i.e., it represents gravitational "up") at the origin. Furthermore, the LVCS is oriented so that the x axis points east, and the y axis points north at the origin. The elevation at a point (x,y) represents the perpendicular distance from the plane to the earth's surface.

The advantages of this coordinate system are that coordinates can be directly used for visualization, and the z-axis is approximately vertical (at least within a few hundred kilometers of the origin). The disadvantage is that the products rectified using this coordinate system are in a non-standard format.