Digital Earth: tsmApi: Dataset Database


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

Digital Earth > tsmApi > File Formats > Dataset Database

The Dataset Database:

The Dataset Database is an ASCII file containing a list of keyword/value pairs (one per line) that collectively describe numerous instances of various terrain datasets. The database also holds information about maps and models that are associated with each dataset, and all of the servers that are known to hold datasets. This is used to describe a set of terrain datasets that are available for TerraVision across any number of servers.

The format is extensible in that it allows new fields to be added in the future without breaking the format. To do this, we use a number of SGML type tags to provide information about the structure of the database, e.g. all of the keyword/value pairs between a <dataset> and </dataset> tag describe one dataset.

Keywords and SGML tags are case-sensitive and may be indented, e.g. to indicate the structure of the database. Keywords may optionally be terminated with a colon symbol (:). Unknown keywords are ignored to allow forward compatibility. Multi-part values are separated by spaces and each part may be enclosed in quotes ("). Blank lines and lines beginning with a hash symbol (#) are ignored.

SGML Tags:

The following SGML tags can be used within a Dataset Database to define the structure of the database. N.B. tags of the same name should not be nested.

<dataset> ... </dataset> : this block is used to delimit records within the database. All information between these two tags describe one particular dataset. Multiple <dataset> blocks may appear in the database.
<instance> ... </instance> : this tag pair is used to introduce a description of one particular instance or representation of the current dataset, i.e. it must appear within <dataset> block. Multiple <instance> blocks may be defined for a single dataset.
<geoset> ... </geoset> : this block contains information to tie together a DEM and an ortho-image dataset for the same region, as well as any maps and models that may be available. Multiple <geoset> blocks may appear in the database.
<model> ... </model> : this block contains information about a model, such as a set of buildings, roads, or a weather simulation. Multiple <model> blocks may appear in the database.
<map> ... </map> : this block contains information about a single 2-D map image. Multiple <map> blocks may appear in the database.
<server> ... </server> : this block contains all of the information for a single server that may be contacted for information about datasets. Multiple <server> blocks may appear in the database.
: because any unknown keywords or tags are ignored, you can include SGML type comments in a Dataset Database file, as long as they are contained on a single line. Lines beginning with a hash symbol are also treated as a comment.

For example, the following figure illustrates the general format for a dataset database file:

# An optional comment

<server>
  information about one dataset server
</server>
...

<geoset>
  information to tie together a DEM and OI
</geoset>
...

<dataset>
  general information about the dataset
  <instance>
    information about one particular representation
  </instance>
  <instance>
    information about another representation
  </instance>
</dataset>

<dataset>
  ...
</dataset>
...

Database Fields:

The following fields specify the list of servers that can be contacted to find all datasets in the database file. These fields must appear inside a <server> block. Each field should occur once only. The order of fields is not significant.

<server> fields:

location : a URL for the Tile Set Manager server [Required]
last-contacted : a date string specifying when the server was last contacted and its data reflected in the contents of the database. The first field of the value should be a hexidecimal time_t value, and can optionally be followed by a textual translation of the date value. [Optional]

The following fields provide general information about a dataset and must appear inside a <dataset> keyword. Each field should occur once only. The order of fields is not significant.

<dataset> fields:

name : an identifying (unique) title for the dataset. [Required]
type : "image-pyramid", "dem-pyramid", or "vrml-pyramid". [Required]
source-type : a string describing the source of the image. This can be any string, but standard values include: "unknown", "spot", "cir-napp". [Required if image-pyramid]
description : a more meaningful name to describe the area of coverage. [Optional]
min-resolution : the resolution of the most detailed level in the pyramid. The value should be followed by a units string, currently only "m". [Required]
max-resolution : the resolution of the least detailed level in the pyramid. The value should be followed by a units string, currently only "m". [Required]
latlong-footprint : the lat/long coordinates for the four corners of the dataset. This will consist of 8 values (degrees), given in counterclockwise order: c1.lat, c1.long, c2.lat, c2.long, ... [One of *-footprint required]
utm-footprint : the UTM coordinates for the four corners of the dataset. This will consist of 12 values (meters & zone number), given in counterclockwise order: c1.e, c1.n, c1.zone, c2.e, c2.n, c2.zone, ... [One of *-footprint required]
geo-footprint : the geocentric coordinates for the four corners of the dataset. This will consist of 12 values (meters), given in counterclockwise order: c1.x, c1.y, c1.z, c2.x, c2.y, c2,z ... [One of *-footprint required]

The following fields describe one specific instance of a dataset and must appear inside an <instance> block. Each field should occur once only. The order of fields is not significant.

<instance> fields:

location : a URL (or URN) giving the location of the dataset instance. Valid URLs include file:, x-iss, and http: protocols. [Required]
servers : if the location is an x-iss: URL (i.e. on a DPSS), then this multi-part field describes the list of servers for the particular dataset instance. [Required if dataset on DPSS]
set-id : if the location is an x-iss: URL (i.e. on a DPSS), then this field specifies the set ID of the instance on that DPSS. [Required if dataset on DPSS]
formats : if the dataset type is "image-pyramid", then this multi-part field describes the image formats that this instance is available in. Valid values are: "lrbt", "jpeg". Multiple values only make sense for this field if the location is a file: URL (DPSS pyramids can only contain data in one format). [Required if dataset is image-pyramid]

The following fields provide information to tie together an elevation dataset with the imagery for that elevation mode. Each field should occur once only, except for map and model which may occur multiple times. The order of fields is not significant.

<geoset> fields:

name : the name of the geoset. [Required]
imagery : the name of the ortho-image dataset for this geoset. This name should be the same as the name field of one <dataset> entry in the database. [Required]
dem : the name of the elevation dataset for this geoset. This name should be the same as the name field of one <dataset> entry in the database. [Required]
model : the name of a VRML model file that is associated with this dataset. This name should be the same as the name field of one <model> entry in the database. You may include multiple model fields in a geoset entry in order to represent different models. [Optional: default = ""]
map : the name of a map image that is associated with this dataset. This name should be the same as the name field of one <map> entry in the database. You may include multiple map fields in a geoset entry in order to represent different maps that are available. [Optional: default = ""]
planet : the planet that the terrain occurs on. This field can take any of the following values: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, or Pluto. Case is not sensitive for these values. [Optional: default = "Earth"]

The following fields provide information about a single VRML model. It allows for the possibility of this model file being available on multiple servers. Each field should occur once only, except the location field which can occur multiple times. The order of fields is not significant.

<model> fields:

name : a unique name for this model. This should name should be the same as in the model field of the appropriate <geoset> entry. [Required]
name : a descriptive (not necessarily unique) title for this model. This string can be used to identify the model to the user, whereas the name string is used to maintain internal correspondences. If this field is not specified, then the value of the name field should be used. [Optional: default = ""]
description : an optional descriptive text that describes what the model is. [Optional: default = ""]
location : a URL describing the location of the VRML .wrl file for the model. you can include multiple location fields in order to describe different locations where the same model file is stored. [Required]

The following fields provide information about a single map image. Each field should occur once only. The order of fields is not significant.

<map> fields:

name : a unique name for this map image. This should name should be the same as in the map field of the appropriate <geoset> entry. [Required]
location : the URL of the map image file. [Required]
uv-corners : the (u,v) coordinates of the lower-left and upper-right corners of the map. It is assumed that the map is in the same coordinate system as the associated pyramid. This field will consist of 4 values, given in the order min_u, min_v, max_u, max_v [Required]

Example Database:

The following example provides a sample database file to illustrate the above format specification. This provides information about two pyramids: an ortho-image and an elevation pyramid. Note that the local disk image pyramid is available in both lrbt and jpeg formats. In the case of the DPSS instances, we illustrate two server combinations of the image pyramid dataset, as well as a JPEG version of the dataset.

<server>
  location: x-dsm://iss-1-atm.sri.magic.net
  last-contacted: 34903097 = Thu Dec 11 10:27:35 1997
</server>

<server>
  location: http://www.ai.sri.com/~magic/TileSets
</server>

<geoset>
  name: ntc-1-utm-2scene
  imagery: ntc-1-utm-2scene.128.oi
  dem: ntc-1-utm-2scene.33.dem
  map: ntc-1-utm-2scene.1.map
</geoset>

<dataset>
  name: ntc-1-utm-2scene.128.oi
  type: image-pyramid
  source-type: cir-napp
  description: "Ft Irwin, CA"
  min-resolution: 1 m
  max-resolution: 2048 m
  latlong-footprint: 0 0  1 0  1 1  0 1
  <instance>
    location: http://www.ai.sri.com/~magic/TileSets/Pyramids/ntc-1-utm-2scene.128.oi
    formats: jpeg lrbt
  </instance>
  <instance>
    location: x-iss://iss-1-atm.sri.magic.net/Pyramids/ntc-1-utm-2scene.128.oi
    servers: sri-server1
    set-id: 66
    formats: lrbt
  </instance>
  <instance>
    location: x-iss://iss-1-atm.sri.magic.net/Pyramids/ntc-1-utm-2scene.128.oi
    servers: sri-server1 lbl-server3
    set-id: 68
    formats: lrbt
  </instance>
  <instance>
    location: x-iss://iss-1-atm.sri.magic.net/Pyramids/ntc-1-utm-2scene.128.jpg.oi
    servers: sri-server1
    set-id: 81
    formats: jpeg
  </instance>
</dataset>

<dataset>
  name ntc-1-utm-2scene.33.dem
  type: dem-pyramid
  description: "Ft Irwin, CA"
  min-resolution: 32 m
  max-resolution: 2048 m
  latlong-footprint: 0 0  1 0  1 1  0 1
  <instance>
    location: http://www.ai.sri.com.com/~magic/TileSets/Pyramids/ntc-1-utm-2scene.33.dem
  </instance>
  <instance>
    location: x-iss://iss-1-atm.sri.magic.net/Pyramids/ntc-1-utm-2scene.33.dem
    servers: sri-server1
  </instance>
</dataset>

<map>
  name: ntc-1-utm-2scene.1.map
  location: http://www.ai.sri.com/~magic/TileSets/Pyramids/ntc-1-utm-2scene.map
  uv-corners: 0 0 2839 2329
</map>