Overview | API | Data Structures | Parameters | Example Map
Version 2.0 of the TerraService is now available! Version 2.0 supports the Urban Area data theme. Click on Version 2.0 changes to learn the specific changes required in your application to use Version 2.0.
TerraService Appliction Programming Interface methods are grouped into the following categories:
The following table lists all the TerraService methods by functional category. Click on a method name to see a full description:
The following methods are used to obtain meta-data or image-data about one or more tiles in the TerraServer database. All methods except the GetTile() method return meta-data. GetTile() is the only method that returns compressed image data.
The TerraServer database is a repository of high resolution imagery captured by satellite, aerial photography, or scanned from large paper products. Normally these data-sets are stored as large graphics data files ranging from 15 MB to 5 GB. Often, imagery in one graphics file may overlap with data in two or more other data files. These data files are very hard to work with standard "shrinked wrap" software such as Microsoft PhotoDraw, Adobe Photoshop, PaintShop Pro, etc. Usually, sophisticated GIS and image editing software, e.g. ERDAS' Imagine, are required to manipulate and view the files. The files are impossible to work with over the internet.
The storage scheme within the TerraServer system is to create small, 200 pixel by 200 pixel, compressed image "tiles". The tiles are aligned to specific, predictable coordinates on the globe. An image pyramid is pre-computed at predictable image resolutions and also stored as 200 pixel by 200 pixel, compressed image tiles. The TerraServer data-loading system "does the right thing" and merges pixels from overlapping source data files into individual tiles. Depending on the data theme being processed, up to four source files might contribute pixels to a single tile. Conceptually, the load system lays the input imagery "on the floor" and aligns each input image to the correct ground coordinate. Then the loading program "cookie cutters" 200 pixel by 200 pixel tiles aligned on grid. The standard TerraServer web application displays two, six, or twelve tiles adjacent tiles. HTML tags are used to re-position the HTML web page with a different center TerraServer tile, or zoom in or out to a different layer in the image pyramid.
The benefit of this design is that users can quickly navigate and browse a huge database, 3.0 Terabytes of compressed image tiles created from 12 Terabytes of uncompressed image data files, over slow speed lines with a standard web browser. No special software or high-speed connection is required to view this vast amount of imagery.
The down-side of this design is that users must always view imagery as some number of adjacent tiles. It is not easy to create a single image from a set of TerraServer image tiles and crop the image to the specification provided by an end user. The TerraServer web application built a java applet to "stitch together" a set of TerraServer image tiles into a single JPEG file. But cropping the image was more that we felt a generic java applet could handle on the vast majority of browsers. As it is, our java applet only runs on Windows and Unix machines, and does not work on Mac computers.
The TerraService Tile functions are designed to help application developers replicate the existing functionality available within the TerraServer web application - locate TerraServer tiles of interest by place name, locate tiles by longitude & latitude, navigate to adjacent tiles, and navigate to tiles in other image resolutions. The Tile methods also help application developers stitch together, crop, and draw on top of images on either the client computer or within server applications.
public AreaBoundingBox GetAreaFromPt(LonLatPt center, int theme, Scale scale, int displayPixWidth, int displayPixHeight)
The GetAreaFromPt method returns the tile meta-data for a Geographic rectangle. Use this call to identify the tiles required to construct an image of a specific size and resolution with a known center point. The GetAreaFromPt is typically called in applications that want to control the size of the display area. Using GetAreaFromPt, the caller controls the specific Longitude and Latitude point to be displayed in the center. The LonLatPt point parameter identifies the Geographic center of the rectangle of interest. The theme and Scale input parameters identify the type imagery and resolution of interest. The displayPixWidth and displayPixHeight parameters identify the size of image the caller intends to create. The GetAreaFromPt method computes the TerraServer tiles that overlap the corners of your image area in the resolution specified in the Scale parameter.
Sample Call:
TerraService ts = new TerraService();
LonLatPt center;
center.Lon = -122.5;
center.Lat = 37.5;
int theme = 1; // Fetch an aerial photo, previously Theme.Photo in version 1.0
try {
AreaBoundingBox abb = ts.GetAreaFromPt(center, theme, Scale.Scale16m, 600, 400);
}
catch { // Catch exceptions thrown by GetAreaFromPt, e.g. bad theme, bad scale, etc.
}
public AreaBoundingBox GetAreaFromRect(LonLatPt upperLeft, LonLatPt lowerRight, int theme, Scale scale) {
The GetAreaFromRect method returns the tile meta-data for a Geographic rectangle. The LonLatPt upperLeft and LonLatPt lowerRight parameter identify the corners of the rectangle of interest in Geographic coordinates. The theme and Scale input parameters identify the type imagery and resolution of interest. The LonLatPt upperLeft and LonLatPt lowerRight parameters define the geographic rectangle. The GetAreaFromRect method computes the image tile address of the tile that overlaps the upperLeft point in the image Theme and Scale requested. The data is fetched and the NorthWest AreaCoordinate structure of the AreaBoundingBox structure is filled in. The method repeats the computation using the lowerRight parameter and fills in the SouthEast AreaCoordinate structure of the AreaBoundingBox structure. The upperLeft Latitude and lowerRight Longitude values are used to compute the tile address and fill in the NorthEast AreaCoordinate structure of the AreaBoundingBox structure. The lowerLeft Longitude and lowerRight Latitude value are used to compute the tile address and fill in the SouthWest AreaCoordinate structure of the AreaBoundingBox structure.
Sample Call:
TerraService ts = new TerraService();
LonLatPt upperLeft= new LonLatPt(), lowerRight= new LonLatPt();
upperLeft.Lon = -122.4276;
upperLeft.Lat = 37.7875671;
lowerRight.Lon = -122.1532;
lowerRight.Lat = 37.654394;
int theme = 2; // theme=2 requests a topographic map, Theme.Topo in Version 1.0
try{
AreaBoundingBox abb = ts.GetAreaFromRect(upperLeft, lowerRight, theme, Scale.Scale16m);
}
catch { }
public AreaBoundingBox GetAreaFromTileId(TileId id, int displayPixWidth, int displayPixHeight)
The GetAreaFromTileId method is similar to the GetAreaFromPt method except that input parameter is a TileId structure. The method returns an AreaBoundingBox structure using the TileMeta Center point of the specified in the TileId parameter. The GetAreaFromTileId method is typically used when panning from a given longitude and latitude point. Applications may find it more convenient to use GetAreaFromTileId than using GetAreaFromPt during panning operations.
Sample Call:
TerraService ts = new TerraService();
TileId id = new TileId();
id.Theme = 2; // Fetch a topographic map, previously Theme.Topo in version 1.0
id.Scale = Scale.Scale16m;
id.Scene = 10;
id.X = 172;
id.Y = 1306;
try{
AreaBoundingBox abb = ts.GetAreaFromTileId(id, 600, 400);
}
catch { }
public TileMeta GetTileMetaFromLonLatPt(LonLatPt point, int theme, Scale scale)
The GetTileMetaFromLonLatPt method returns a TileMeta structure containing the meta-data for a single TerraServer image tile. The meta-data contains the geographic corner points of the image, the capture date (date photographed or printed), etc. The LonLatPt parameter identifies the geographic point of interest. The theme and Scale parameters are required.
Sample Call:
TerraService ts = new TerraService();
LonLatPt p = new LonLatPt();
p.Lon = -122.4276;
p.Lat = 37.7875671;
int theme = 2; // Fetch a topographic map, previously Theme.Topo in version 1.0
DumpObject("GetTileMetaFromLonLatPt", ts.GetTileMetaFromLonLatPt(p, theme, Scale.Scale16m));
public TileMeta GetTileMetaFromTileId(TileId id)
The GetTileMetaFromTileId is similar to the GetTileMetaFromLonLatPt method call. GetTileMetaFromTileId returns a TileMeta structure containing the meta-data for a single TerraServer image tile. The TileId parameter identifies the geographic point of interest. The Theme and Scale parameters are required.
Sample Call:
TerraService ts = new TerraService(); TileId id = new TileId(); id.Theme = 2; // fetch a topographic map, previously Theme.Topo in version 1.0 id.Scale = Scale.Scale16m; id.Scene = 10; id.X = 172; id.Y = 1306; TileMeta tm = ts.GetTileMetaFromTileId(id);
public Byte[] GetTile(TileId id)
The GetTile method returns a Byte array containing the compressed image data for the requested tile. The TileId input parameter identifies the specific data row in the TerraServer database to be returned. WebForm applications typically call this method within HTTP handlers that will use GDI functions to de-compress, manipulate, and re-compress the image data. Most image tiles in TerraServer are JPEG format. There are three tile resolutions in the USGS Topographic Map theme that return GIF image tiles - 2 meter resolution (Scale.Scale2m), 8 meter (Scale.Scale8m), and 32 meter (Scale.Scale32m).
Sample Call:
TerraService ts = new TerraService(); TileId id = new TileId(); id.Theme = 2; // fetch a topographic map tile, previously Theme.Topo in version 1.0 id.Scale = Scale.Scale16m; id.Scene = 10; id.X = 172; id.Y = 1306; Byte[] image = ts.GetTile(id);
The TerraService offers a number of methods for locating imagery within the TerraServer database by something other than longitude and latitude. The Tile Information Methods search the database by TileId or LonLatPt. Most end users have no clue what their longitude or latitude is except for those armed with a GPS unit. Most users know locations by a familiar name like Seattle Washington, Statue of Liberty, or Washington, D.C. Thus, the TerraServer database maintains a "place name gazetteer" that translates popular place names to a longitude and latitude value.
The TerraService methods in this section provide a programmatic interface to the TerraServer place name data. The place name data is referred to as the "Gazetteer" throughout this document and the TerraServer application.
public PlaceFacts GetPlaceFacts(Place place)
The GetPlaceFacts method returns a PlaceFacts structure for a specific Place (City, State, and Country). Unfortunately, there maybe several rows in the TerraServer Gazetteer that match the same City, State, and Country. TerraServer returns the first match, which may not be what you want. We recommend the GetPlaceList or GetPlaceListInRect methods.
Sample Call:
TerraService ts = new TerraService();
Place place = new Place();
place.City = args[0];
place.State = args[1];
place.Country = args[2];
DumpObject("PlaceFacts", ts.GetPlaceFacts(place));
public PlaceFacts[] GetPlaceList(string placeName, int MaxItems, Boolean imagePresence)
The GetPlaceList method calls the TerraServer methods and returns an array of PlaceFacts data for all names that match the placeName parameter. The placeName parameter is expected to be a single string containing the city or well known place name, state name, and country name separated by comma characters, e.g. "San Franicisco, CA, USA". Any of the three values may be missing. Thus the following are all valid placeName parameter values:
The MaxItems parameter limits the number of elements returned in the PlaceFacts array. It is recommended that MaxItems not exceed 100.
The imagePresence flag tells the method how to factor in imagery into the search. Typically, applications call GetPlaceFacts method to locate imagery for the named places. Thus passing true as the imagePresence parameter will return array elements only when the named locations have imagery associated with them. Passing false will return array elements whether are associated with imagery or not.
Sample Call:
TerraService ts = new TerraService();
PlaceFacts[] pfs = ts.GetPlaceList((args.Length == 0) ? "San Francisco" : args[0], 100, false);
if (pfs == null) Console.WriteLine("NULL");
foreach (PlaceFacts pf in pfs) {
if (pf == null) break;
DumpObject("GetPlaceList", pf);
Console.WriteLine();
}
public PlaceFacts[] GetPlaceListInRect(LonLatPt upperleft, LonLatPt lowerright, PlaceType ptype, int MaxItems)
The GetPlaceListInRect method retrieves TerraServer Gazetteer data for specific geographic rectangle. This method is typcially used to locate all the place names that overlap an geographic rectangle passed to the GetAreaFromPt, GetAreaFromRect, or GetAreaFromTileId. The PlaceType parameter can be used to limit the PlaceFacts array to places of a specific type, e.g. towns, rivers, points of interest, etc. The MaxItems parameter limits the number of PlaceFacts array elements to a specific number.
Sample Call:
TerraService ts = new TerraService();
LonLatPt upperLeft = new LonLatPt();
LonLatPt lowerRight = new LonLatPt();
upperLeft.Lon = -122.4276;
upperLeft.Lat = 37.7875671;
lowerRight.Lon = -122.1532;
lowerRight.Lat = 37.654394;
PlaceFacts[] pfs = ts.GetPlaceListInRect(upperLeft, lowerRight, PlaceType.UnknownPlaceType, 10);
// PlaceType: UnknownPlaceType, AirRailStation, BayGulf, CapePeninsula, CityTown, HillMountain,
// Island, Lake, OtherLandFeature, OtherWaterFeature, ParkBeach, PointOfInterest, River
if (pfs == null) Console.WriteLine("NULL");
else {
foreach (PlaceFacts pf in pfs) {
if (pf == null) break;
DumpObject("GetPlaceListInRect", pf);
Console.WriteLine();
}
}
public int CountPlacesInRect(LonLatPt upperleft, LonLatPt lowerright, PlaceType ptype)
The CountPlacesInRect method is similar to the GetPlaceListInRect method except that it returns the count of matching places rather than the list of matching places. This method is useful for applications that don't want to guess at the number of MaxItems to pass to the GetPlaceListInRect method. The CountPlacesInRect method can be used to compute the exact number.
Sample Call:
TerraService ts = new TerraService(); LonLatPt upperLeft = new LonLatPt(); LonLatPt lowerRight = new LonLatPt(); upperLeft.Lon = -122.4276; upperLeft.Lat = 37.7875671; lowerRight.Lon = -122.1532; lowerRight.Lat = 37.654394; Int32 CountOfPlaces = ts.CountPlacesInRect(upperLeft, lowerRight, PlaceType.CityTown);
You are dealing with "Projection Systems" anytime you are dealing with a map or a globe. For our purposes within the TerraService, the earth is a sphere. Points on it are referenced by Longitude and Latitude "lines". They are not lines really, but complex curves. Maps are flat drawing of earth. Satellite or aerial imagery, in its raw state, is more-flat-than-its round. It is mathematically impossible to present a sphere on a flat surface without distorting something. Cartographers have dealt with this issue for centuries by developing different methods, known as map projections, for representing portions of earth with minimal, or at least predictable, distortions.
The USGS Cartographers selected the Universal Transverse Mercator (UTM) projection system for many of their high resolution map products, for example the USGS Topographic Map theme. The USGS chose to project the USGS Digital Orthoquadrangle aerial imagery into the UTM. There are several variants of the UTM projection system, the USGS aerial imagery and USGS topographic map data within TerraServer are in the UTM NAD 83 projection. (NAD 83 stands for North American Datum of 1983).
The TerraService provides a set of methods to convert between "Geographic" projection and UTM. That is, convert between longitude and latitude points and UTM NAD 83 points and vice-versa. TerraServer image tiles carry meta-data fields of the longitude and latitude of the corner points and center point of the tile. The TileId mate-data fields can be used to compute the UTM coordinates of any point in a tile. The Scale, Scene, X, and Y fields can be used to compute the UTM NAD 83 coordinates for the lower left hand pixel in the TerraServer tile (XOffset=0 and YOffset=200). The following formulas are required to compute the UTM NAD 83 for the lower left hand pixel:
Int32 UtmZone = Scene; Int32 metersPerPixel = (1 << ((Int32) Scale - 10)); Int32 UtmEasting = X * 200 * metersPerPixel; Int32 UtmNorthing = Y * 200 * metersPerPixel;
Returns a String describing the Place name and direction to the closest place to the LonLatPt passed to the method. In the TerraServer-USA web site, the closest place name string is displayed over the image to give users a textual reference point for the image.
public String ConvertLonLatPtToNearestPlace(LonLatPt point) {
public UtmPt ConvertLonLatPtToUtmPt(LonLatPt point)
Converts a Geographic, LonLatPt point to a UtmPt point.
Sample Call:
TerraService ts = new TerraService();
LonLatPt l = new LonLatPt();
l.Lon = -122.4276;
l.Lat = 37.7875671;
DumpObject("ConvertLonLatPtToUtmPt", ts.ConvertLonLatPtToUtmPt(l));
public LonLatPt ConvertUtmPtToLonLatPt(UtmPt utm)
Converts a UtmPt point to a Geographic, LonLatPt point.
Sample Call:
TerraService ts = new TerraService();
UtmPt utmpt = new UtmPt();
utmpt.Zone = 10;
utmpt.X = 500000;
utmpt.Y = 4323434;
DumpObject("ConvertUtmPtToLonLatPt", ts.ConvertUtmPtToLonLatPt(utmpt));
public LonLatPt ConvertPlaceToLonLatPt(Place place)
Obtains the Geographic LonLatPt for a specific Place (City, State, and Country).
Sample Call:
TerraService ts = new TerraService(); Place place = new Place(); place.City = "San Francisco"; place.State = "CA"; place.Country = "USA"; LonLatPt point = ts.ConvertPlaceToLonLatPt(place);
public ThemeBoundingBox[] GetLatLonMetrics(LonLatPt point)
The GetLatLonMetrics method describes the extent of available imagery for the LonLatPt passed to the function. In the TerraServer system, there is a concept of a navigable "Scene". The expance of a Scene is dependent on the source of the imagery and the imagery's projection system. For data in the Geographic projection system, the expanse is the entire globe. Effectively there is one Scene.
For UTM data, there are sixty Scenes, each covering approximately six longitude degrees. The GetLatLonMetrics method describes this fact in a ThemeBoundingBox structure.
Sample Call:
TerraService ts = new TerraService();
LonLatPt point = new LonLatPt();
point.Lon = -122.4276;
point.Lat = 37.7875671;
DumpObject("GetLatLonMetrics", ts.GetLatLonMetrics(point));
public ThemeInfo GetTheme(int theme)
The GetTheme method returns attributes that apply to all tiles belonging to a specific theme. The theme parameter identifies the theme to return the ThemeInfo attributes for. The GetTheme method should be called by applications as part of the initialization process. The ThemeInfo identifies the projection system of the theme and the copyright notice that should be displayed when presenting the theme's imagery.
Sample Call:
TerraService ts = new TerraService();
DumpObject("Photo ThemeInfo", ts.GetTheme(1));
DumpObject("Topo ThemeInfo", ts.GetTheme(2));
DumpObject("Relief ThemeInfo", ts.GetTheme(3));
