[HOME][CONTENTS][DOWNLOAD][PREV][NEXT]

TERRABITS API

TerraBits is an enhanced Tcl interface to the TerraServer-USA Web service, a programmable interface to the world's largest online database, providing free public access to a vast data store of maps and aerial photographs of the United States.  Syntax of a TerraBits command is

terraBits.terraServiceCommand ?options?
where terraBits. is a prefix, terraServiceCommand is a standard TerraService command name, options are pairs of "-opt value" for specifying parameters and their associated values.  To retrieve options of a TerraBits command, invoke the command with a "?" as argumenmt,
terraBits.terraServiceCommand ?
To retrieve default option values of a TerraBits command, invoke the command with "default" as argument,
terraBits.terraServiceCommand default
To use TerraBits API, a user must open a TerraBits session first.  This is done by the followng command
set id [terraBits.open]
The returned id is a service identification number required by many TerraBits API commands.  The user must close a TerraBits session when the works are done in order to release the allocated resources.  To close a TerraBits session, use the following commmand,
terraBits.close $id
Standard TerraBits API. This API is a Tcl wrap of  TerraService and LandmarkService.
terraBits.ConvertLonLatPtToNearestPlace ?options?
terraBits.ConvertLonLatPtToUtmPt ?options?
terraBits.ConvertPlaceToLonLatPt ?options?
terraBits.ConvertUtmPtToLonLatPt ?options?
terraBits.CountPlacesInRect ?options?
terraBits.GetAreaFromPlace ?options?
terraBits.GetAreaFromPt ?options?
terraBits.GetAreaFromRect ?options?
terraBits.GetLatLonMetrics ?options?
terraBits.GetPlaceFacts ?options?
terraBits.GetPlaceList ?options?
terraBits.GetPlaceListInRect ?options?
terraBits.GetTheme ?options?
terraBits.GetTile ?options?
terraBits.GetTileMetaFromTileId ?options?
terraBits.GetTileMetaFromLonLatPt ?options?

terraBits.CountOfLandmarkShapesByRect ?options?
terraBits.CountOfLandmarkPointsByRect ?options?
terraBits.GetLandmarkTypes ?options?
terraBits.GetLandmarkPointsByRect ?options?
terraBits.GetLandmarkPointsFromPlace ?options?

The returned data is either a string or a tagged list.  A tagged list is a special Tcl list with its odd items as a tagged name for the following even item, which can be either a tagged list or an ordinary string.  XBit uses @ as the first character of a tagged name to distinguish a tagged list and an ordinary string.  A tagged list is used to parse an XML string returned from a service call to TerraService or LandmarkService.  For an example, the following XML string 
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<ConvertLonLatPtToUtmPtResponse xmlns="http://terraserver-usa.com/">
<ConvertLonLatPtToUtmPtResult>
<Zone>11</Zone>
<X>234798.13038006157</X>
<Y>4154570.1539562792</Y>
</ConvertLonLatPtToUtmPtResult>
</ConvertLonLatPtToUtmPtResponse>
</soap:Body>
</soap:Envelope>
is the result after invoking ConvertLonLatPtToUtmPt serivce via following TerraBits API command,
terraBits.ConvertLonLatPtToUtmPt -id $id -lat 37.5 -lon -120
The result XML string will be parsed by TerraBits and returned as a Tcl tagged list:
@Zone 11 @X 234798.13038006157 @Y 4154570.1539562792
The following scripts demonstrate how to retrieve 6 tiles covering Pentagon, DC and display them in a Tk canvas:
# create a canvas
set canv .terra
canvas $canv
pack $canv -expand 1 -fill both

# prepare parameters
set theme RGBPhoto            ;# higt-resolution RGB photo 
set scale Scale2m                 ;# scale of 2 meter pixel
set scene 18                         ;# UTM zone
set x0 321300                      ;# upleft UTM x coordinate
set y0 4304700                    ;# upleft UTM y coordinate
set X0 [expr $x0 / 400]        ;# upleft tile X
set Y0 [expr $y0 / 400]        ;# upleft tile Y

# open a terraBits session
set id [terraBits.open]

# retrieve image tiles and display them in canvas 
set canvx 0
set canvy 0
set Y $Y0
for {set i 0} {$i < 2} {incr i} {
    set X $X0
    set canvx 0
    for {set j 0} {$j < 3} {incr j} {
         set data [terraBits.GetTile -id $id -scene $scene -scale $scale -theme $theme -X $X -Y $Y]
         rimage open tile($X,$Y) base64 $data
         image create gimg imgtile($X,$Y) -file tile($X,$Y) -pal 8/8/4 -comb 1/2/3
         $canv create image $canvx $canvy -image imgtile($X,$Y) -anchor nw 
         incr canvx 200
         incr X
    }
    incr canvy 200
    incr Y -1
}

# close the terraBits session
terraBits.close $id

Advanced TerraBits API.  This API is build upon the standard TerraServer Client API with additional Tcl scripts.  All the API commands return a rimage and display it with XBit's view widget during data retrieval process.  API commands terraBits.GetTiles, terraBits.GetNearestTiles and terraBits.GetTilesFromPlace retrieve an image in units of tiles.  The width and height of an image is always in mutiple of 200, i.e., the size of a tile.  API commands terraBits.GetImageByRect, terraBits.GetImageByPlace and terraBits.GetImageByLonLatPt retrieve an image in units of pixel numbers, which are specified in options -width and -height.
terraBits.GetTiles ?options? retrieves image tiles from TerraServer using tile coordinates, mosaics them together to form a signal image and displays the image during the retrieval process.  It returns the rimage tag of the mosaiced image when it is done.

terraBits.GetNearestTiles ?options? retrieves image tiles from TerraServer using UTM coordinates, mosaics them together to form a singal image and displays the image during the retrieval process.  It returns the rimage tag of the mosaiced image when it is done. 

terraBits.GetTilesFromPlace ?options? retrieves from TerraServer image tiles centered at a specified place, mosaics them together to form a singal image and displays the image during the retrieval process.  It returns the rimage tag of the mosaiced image when it is done.

terraBits.GetImageByRect ?options? crops from TerraServer an image defined in a rectangle using UTM coordinates.  It displays the image during the crop process.  It returns the rimage tag of the cropped image when it is done.

terraBits.GetImageByPlace ?options? crops from TerraServer an image centered at a specified place, and in a rectangle defined by width and height in number of pixels.

terraBits.GetImageByLonLatPt ?options? crops from TerraServer an image centered at a specified longitude and latitude, and in a  rectangle defined by width and height in number of pixels.

To retrieve the same Pentagon image and display it in a XBit's view widget, use the follwing command,
terraBits.GetNearestTiles -theme RGBPhoto -scene 18 -scale Scale2m -x0 321300 -x1 322300 -y0 4304000 -y1 4304700

The following script retrieves an image of "White House" and displays it in a XBit's view widget:

terraBits.GetImageByPlace -theme RGBPhoto -city "White House" -state DC -scale Scale500mm

The following script retrieves a Topo map of Fremont, CA:

terraBits.GetImageByPlace -theme Topo -city Fremont -state CA -scale Scale4m -width 2000 -height 2000

[HOME][CONTENTS][DOWNLOAD]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

 
1