Home

NASA Earthdata Wiki

GIBS Supported Clients

From NASA Earthdata Wiki
Jump to: navigation, search

Contents

Introduction

There are several supported clients and methods available to take advantage of NASA's Global Imagery Browse Services (GIBS) via OGC Web Map Tile Service (WMTS) and Tiled Web Map Service (TWMS) protocols. Listed below is a set of clients, code snippets, working examples, and screen captures designed to help in building your own user interface to explore NASA's Earth imagery. Alternatively, these guidelines can also help to integrate that imagery into your existing client or to build scripts to retrieve imagery from GIBS.

Web-based Clients

OpenLayers

OpenLayers is an open source, web browser-based mapping library written in JavaScript. OpenLayers maps can also be viewed on mobile devices since no plugins are required to use it.

Usage

First create a map object with a geographic (i.e., lat-lon) projection and nine zoom levels: 

map = new OpenLayers.Map({
    div: "map",
    projection: "EPSG:4326",
    numZoomLevels: 9,
    zoom: 2
});


Next, define product-specific constants related to their map projection and resolution: 

var TILEMATRIXSET_GEO_250m = "EPSG4326_250m";
var TILEMATRIXSET_GEO_500m = "EPSG4326_500m";
var TILEMATRIXSET_GEO_1km = "EPSG4326_1km";
var TILEMATRIXSET_GEO_2km = "EPSG4326_2km";


Define service-specific constants (see here for more info): 

var GIBS_WMTS_GEO_ENDPOINT = "http://map1.vis.earthdata.nasa.gov/wmts-geo/wmts.cgi";


Now create base layers and overlays (more info on available products can be found here): 

// Create base layers
var layerModisTerraTrueColor = new OpenLayers.Layer.WMTS({
	name: "Terra / MODIS Corrected Reflectance (True Color), 2012-06-08",
	url: GIBS_WMTS_GEO_ENDPOINT,
	layer: "MODIS_Terra_CorrectedReflectance_TrueColor",
	matrixSet: TILEMATRIXSET_GEO_250m,
	format: "image/jpeg",
	style: "",
	transitionEffect: "resize",
	projection: "EPSG:4326",
	numZoomLevels: 9,
	maxResolution: 0.5625,
	'tileSize': new OpenLayers.Size(512, 512),
	isBaseLayer: true
});

// Create overlays
var layerModisAerosolOpticalDepth = new OpenLayers.Layer.WMTS({
	name: "Terra / MODIS Aerosol Optical Depth, 2012-06-08",
	url: GIBS_WMTS_GEO_ENDPOINT,
	layer: "MODIS_Terra_Aerosol",
	matrixSet: TILEMATRIXSET_GEO_2km,
	format: "image/png",
	style: "",
	transitionEffect: "resize",
	projection: "EPSG:4326",
	numZoomLevels: 9,
	maxResolution: 0.5625,
	'tileSize': new OpenLayers.Size(512, 512),
	isBaseLayer: false,
	visibility: false
});

// The "time" parameter isn't being included in tile requests to the server
// in the current version of OpenLayers (2.12);  need to use this hack
// to force the inclusion of the time parameter.
//
// If the time parameter is omitted, the current (UTC) day is retrieved
// from the server
layerModisTerraTrueColor.mergeNewParams({time:"2012-06-08"});
layerModisTerra721.mergeNewParams({time:"2012-06-08"});
layerModisAerosolOpticalDepth.mergeNewParams({time:"2012-06-08"});
layerAirsDustScore.mergeNewParams({time:"2012-06-08"});


Finally, add the layers to the map, add a layer switcher, and set the view extent: 

// Add layers to the map
map.addLayers([layerModisTerraTrueColor, layerModisTerra721,
	layerModisAerosolOpticalDepth, layerAirsDustScore]);
	
// Add layer switcher control
map.addControl(new OpenLayers.Control.LayerSwitcher());

// Set global view
var extent = "-146.0, -94.0, 146.0, 94.0";
var OLExtent = new OpenLayers.Bounds.fromString(extent, false).transform(
		new OpenLayers.Projection("EPSG:4326"),
		map.getProjectionObject());
map.zoomToExtent(OLExtent, true);


Requirements
  • The OpenLayers (http://openlayers.org/) mapping library included in your HTML file
  • The map itself and all other layers must be in the lat-lon ("geographic" EPSG:4326) projection since multiple projections are not supported in a concurrent fashion by OpenLayers. This means OpenStreetMap, Bing, and other tiles currently cannot be mashed with GIBS imagery.
  • A reasonably modern web browser with JavaScript enabled.
Sample Clients

Google Earth Plugin

Google Earth (Plugin) is a virtual globe that can be embedded on a webpage and manipulated through Javascript. It utilizes the KML interface of TWMS to retrieve data.

Usage

The Javascript uses a callback function to load data from a URL. The list of available products can be found here. 

var url = "http://map1.vis.earthdata.nasa.gov/twms-geo/kmlgen.cgi?layers=MODIS_Terra_CorrectedReflectance_TrueColor&time=2012-07-12";
google.earth.fetchKml(ge, url, function(object){
	if (!object) {
		// wrap alerts in API callbacks and event handlers
		// in a setTimeout to prevent deadlock in some browsers
		setTimeout(function() {
			displayDialog('Bad or null KML.');
		}, 0);
		return;
	}

	ge.getFeatures().appendChild(object);
	object.setVisibility(true);
	//object.setOpacity(alpha); // use to change transparency of layer
});
}

Limitations: Google Earth does not have a convenient method of layering maps on top of each other. One can achieve the effect by changing the elevation that the map layers are displayed at, although that sometimes can introduct unwanted artifacts on the display.

Requirements
Screenshots
Additional Documentation


Adobe Flash/Flex Client Library

The Flash/Flex client library is a native Flash client written in ActionScript. It can be embedded into Flash applications on web pages as well as an embedded application that utilizes the Adobe Air framework. It is built upon ArcGIS's Flex API libraries to load tiles and present images with a custom TWMS data loader.

The library comes with a sample HTML page that presents a simple Flash client which can load layers from arbitrary TWMS servers and allow users to select time-values.

Usage

To use the library, include the pre-compiled Flash library and use the following code snippet in the .mxml file. 

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
			   xmlns:s="library://ns.adobe.com/flex/spark"
			   xmlns:mx="library://ns.adobe.com/flex/mx"
			   xmlns:esri="http://www.esri.com/2008/ags"
			   xmlns:layers="gov.nasa.jpl.common.gui.map.layers.*"
	<esri:Map id="map" logoVisible="false" scaleBarVisible="false">
	<layers:TiledWMSLayer url="http://map1.vis.earthdata.nasa.gov/twms-geo/twms.cgi" visibleLayer="MODIS TERRA tileset"/>
</esri:Map>
</s:Application>
Requirements
Screenshots

  • Maps Display

  • Selecting Dates for Maps

Additional Documentation

The Flex API for ArcGIS can be obtained here: http://help.arcgis.com/en/webapi/flex/

Code Snippets

Adding a map layer (Provided by ArcGIS's API) 

var tiledWMSLayer:TiledWMSLayer = new TiledWMSLayer();
tiledWMSLayer.url = <url>;
tiledWMSLayer.visibleLayer = String(<map name>);
tiledWMSLayer.dateString = <date>;
map.addLayer(tiledWMSLayer);
Sample Clients

Standalone Clients

NASA World Wind

World Wind is a multi-platform virtual globe developed by NASA that runs Java. It can load GIBS data through either the KML interface or the TWMS interface.

Usage (KML)

To run the World Wind client with GIBS KML capabilities, load the "KML Viewer" demo application from either the standalone client or the online demo. To load a specific layer, select File | Open URL... and enter a URL for the layer in this format: http://<url to kmlgen.cgi>?layers=<layername>&time=<time> for example, http://map1.vis.earthdata.nasa.gov/twms-geo/kmlgen.cgi?layers=MODIS_Terra_CorrectedReflectance_TrueColor&time=2012-06-21

To enable time adjustment on a particular layer, use the following URL parameter: time=R10/<date>/P1D for example, http://map1.vis.earthdata.nasa.gov/twms-geo/kmlgen.cgi?layers=MODIS_Terra_CorrectedReflectance_TrueColor&time=R10/2012-05-26/P1D

Additional documentation is available here.

Limitations: The name of the layer has to be known prior to entering the URL. The list of available layers can be found here.

Usage (TWMS)

To run the World Wind client with TWMS capabilities, load the WMS Layer Manager demo application from either the standalone client or the online demo. In the layers menu, add the TWMS endpoint http://map1.vis.earthdata.nasa.gov/twms-geo/twms.cgi. This will load the list of layers available from TWMS and selecting a layer will allow it to be shown on the globe.

Limitations: World Wind will continue to zoom and try to load images even if they're beyond the depth of the highest resolution tile. When this happens, the images will go blank. In addition, this interface does not allow the selection of variables such as time.


Requirements
Screenshots

  • WorldWind with GIBS WMS Interface

  • WorldWind with GIBS KML Interface


Google Earth

GIBS can generate KML files to be used with Google Earth. Those KMLs include pointers to GIBS imagery via the NetworkLink keyword. Users have two options on loading KML files into Google Earth as described below.

Usage (Generate/Download KML file)

Using the information on generating KMLs, you can load that downloaded file from within Google Earth (File | Open) or usually by simply double-clicking on the KML file itself. The layer will show up in the "Temporary Places" within the "Places" window.

Usage (Load from within Google Earth)

After launching Google Earth, choose the "Network Link" item from the "Add" menu. Choose whatever Name you wish and in the "Link" field, insert the appropriate link (e.g., http://map1.vis.earthdata.nasa.gov/twms-geo/kmlgen.cgi?layers=MODIS_Terra_CorrectedReflectance_TrueColor&time=2012-06-21). The list of available layers can be found here. For more details on how to compose a proper KML generation request from the GIBS server, see here.


Limitations (both methods):

  • Due to the way NetworkLink is handled in Google Earth for global datasets, you may need to zoom out to a more "global" view before imagery begins loading.
  • When using a KML that contains multiple time steps, the time slider by default usually attempts to display the entire time range simultaneously; this can cause a Z-fighting problem where all time steps are fighting to be shown. To correct the problem, narrow the range of currently-shown time to a single day using the time widget.
Requirements


Perceptive Pixel Client

Perceptive Pixel, a company that makes high-end touch displays such as CNN's Magic Wall, includes a built in WMS client that can be configured to use TWMS. The FeltBoard application allows for a natural user interface to interact with maps and allows arbitrary map layer sizing, rotations, intersections, as well as annotations.

Usage

The FeltBoard application requires the server2.xml file to be updated with the WMS endpoint for each layer. The list of available layers can be found here. The <base_deg> is the size of the most coarse tile in degrees and must be a divisor of 180. The <depth> tag is set to the number of levels in the tile pyramid. This value may not be the entire tile pyramid, rather, the number of levels starting with the tile level that <base_deg> defines. The <wms_options> can be used to define a specific date. 

<MapTileServer server_code="MODIS_Aqua_CorrectedReflectance_TrueColor" server_type="WMSMapServer">
	<server_code>MODIS_Aqua_CorrectedReflectance_TrueColor</server_code>
	<server_name>MODIS AQUA</server_name>
	<db_url>http://map1.vis.earthdata.nasa.gov/twms-geo/twms.cgi</db_url>
	<base_deg>36</base_deg>
	<depth>6</depth>
	<im_format>Image::IMG_JPG</im_format>
	<boundary>((-180,0),(180,180))</boundary>
	<basis>Projection::B_SPHERICAL</basis>
	<projection>Projection::P_MERCATOR</projection>
	<wms_layers>MODIS_Aqua_CorrectedReflectance_TrueColor</wms_layers>
	<wms_styles></wms_styles>
	<wms_options>&time=2012-06-18</wms_options>
</MapTileServer>
Requirements
  • Perceptive Pixel Display + FeltBoard Application
Screenshots
  • View video

ESRI ArcMap 10.1

While ESRI ArcMap 10.1 can connect to OGC WMTS servers, the GIBS WMTS server currently only supports Key-Value Pair (KVP) style requests, while ArcMap makes requests in a REpresentational State Transfer (REST) style; both are valid types of WMTS requests, though GIBS does not yet support REST.

SCISS Uniview

Use NASA imagery in your planetarium! The SCISS Uniview software supports access to GIBS imagery through the Tiled WMS service endpoint using the geographic projection (EPSG:4326). The list of available products can be found here.

Mobile Clients

iOS Client Library

The iOS client library is a native library written in Objective-C and can be incorporated into any iOS app for the iPod Touch, iPhone, and iPad. It is built upon ArcGIS's iOS client libraries, which provides a MapView and asynchronous tile loading, coupled with a custom TWMS data loader.

The library comes with a sample client to display TWMS maps and includes basic manipulations such as presenting data from arbitrary TWMS server, selecting a time-value, and map layer reordering.

Usage

To use the library, create an AGSMapView object, either programmatically or linked from Interface Builder, and use the following code snippet as an example. 

TWMSTiledWebMapService *earthTwms = [[TWMSTiledWebMapService alloc] initWithUrl:[NSURL URLWithString:@"http://map1a.vis.earthdata.nasa.gov/twms-geo/twms.cgi?request=GetTileService"]];
TWMSTiledMap *aquaMap = [[earthTwms tiledMaps] valueForKey:@"MODIS AQUA tileset"];
TWMSTiledMapLayer *aquaMapLayer = [[TWMSTiledMapLayer alloc] initWithTiledMap:aquaMap];
[agsMapView addMapLayer:aquaMapLayer withName:[aquaMap name]];
Requirements
Screenshots

  • Showing maps

  • Reordering layers

  • Showing available layers

  • Customizing sources

  • Multiple TWMS servers

Additional Documentation

The ArcGIS iOS documentation can be obtained from: http://resources.arcgis.com/en/help/runtime-ios-sdk/apiref/index.htm

The standard iOS documentation can be viewed here: http://developer.apple.com/library/ios/navigation/

The iOS library defines 3 classes that are used to load TWMS data:

TWMSTiledWebMapService: Instantiated for each TWMS endpoint.

TWMSTiledMap: Represents an individual map layer in the TWMS.

TWMSTiledMapLayer: A subclass of ArcGIS's map layer to show TWMS data.

TWMSTiledWebMapService

Properties

name: The name of the TWMS as defined in the GetTiledService request.

title: The title of the TWMS as defined in the GetTiledService request.

abstract: The abstract of the TWMS as defined in the GetTiledService request.

tiledMaps: A dictionary where the keys are the name of each map layer and values are the TWMSTiledMap instances.

Methods

(id)initWithUrl:(NSURL*)url: Loads the TWMS data given by the url to instantiate this class.

(NSArray*)listAllTiledMapsByName: Returns a sorted list of map layer names.

(void)setTiledMapKeyValue:(NSString*)value forTiledMapKey:(NSString*)key: Assigns variable keys for all TiledMaps in the TWMS server.

(NSDictionary*)tiledMapKeyValues: Returns a dictionary of all the keys used in all TiledMaps and the value its currently set to.

TWMSTiledMap Properties

name: The name of the layer as defined in the GetTiledService request.

title: The title of the layer as defined in the GetTiledService request.

uuid: A randomly generated unique ID for the layer.

Code Snippets

Create a new TWMSTiledWebMapService using a URL 

TWMSTiledWebMapService *earthTwms = [[TWMSTiledWebMapService alloc] initWithUrl:[NSURL URLWithString:@"http://map1a.vis.earthdata.nasa.gov/twms-geo/twms.cgi?request=GetTileService"]];

List all map layers in a TWMS server 

NSArray *tiledMapNames = [earthTwms listAllTiledMapsByName];
for(NSString *tiledMapName in tiledMapNames) {
	NSLog(@"%@", tiledMapName);
}

Update variables for all TWMS endpoints 

[earthTwms setTiledMapKeyValue:@"2012-07-12" forTiledMapKey:@"${time}"];

Add, reorder, and remove map layers (Provided by ArcGIS's MapView class) 

AGSMapView *mapView = <the map view>;
TWMSTiledMap *tiledMap = <obtained from TWMSTiledWebMapService>;
TWMSTiledMapLayer *tiledMapLayer = [[TWMSTiledMapLayer alloc] initWithTiledMap:tiledMap];

[mapView addLayer:tiledMapLayer withName:[tiledMap uuid]];
[mapView insertMapLayer:tiledMapLayer withName:[tiledMap uuid] atIndex:<index>];
[mapView removeLayerWithName:[tiledMap uuid]];

Set map layer transparency (Provided by iOS UIView's transparency settings) 

UIView *view = [[[mapView mapLayerViews] objectForKey:[tiledMap uuid]];
[view setAlpha:<transparency value>];


OpenLayers for Mobile

Mobile support in OpenLayers is enabled by default.

See the prior section on using it as a web-based client for info on connecting to GIBS.

Additional Documentation

Script-level access to imagery

Users can write scripts to download GIBS imagery programmatically via the Tiled WMS driver for the Geospatial Data Abstraction Library (GDAL).

Usage
  • Option 1) Create a local service description XML file, for example, TERRA.xml and invoke gdal_translate. The contents of TERRA.xml would be:

<GDAL_WMS>

<Service name="TiledWMS">
<ServerUrl>http://map1.vis.earthdata.nasa.gov/twms-geo/twms.cgi?</ServerUrl>
<TiledGroupName>MODIS TERRA tileset</TiledGroupName>
<Change key="${time}">2012-06-27</Change>
</Service>

</GDAL_WMS>

gdal_translate -of GTiff -outsize 2800 2200 -projwin -84.0740 44.9165 -77.9216 40.0825 TERRA.xml GreatLakes1.tif
gdal_translate -of JPEG GreatLakes1.tif GreatLakes1.jpg


  • Option 2) Invoke gdal_translate with the content of a description XML file embedded into command:


gdal_translate -of GTiff -outsize 2800 2200 -projwin -84.0740 44.9165 -77.9216 40.0825 '<GDAL_WMS><Service name="TiledWMS"><ServerUrl>http://map1.vis.earthdata.nasa.gov/twms-geo/twms.cgi?</ServerUrl><TiledGroupName>MODIS TERRA tileset</TiledGroupName><Change key="${time}">2012-06-27</Change></Service></GDAL_WMS>' GreatLakes2.tif
gdal_translate -of JPEG GreatLakes2.tif GreatLakes2.jpg

In very limited testing, our experience has been that better image quality is obtained by using the GeoTIFF output format from the TiledWMS, then converting this to other formats, if desired, using a second gdal_translate, or other programs such as ImageMagick convert.

The list of TiledGroupName can be obtained from:
http://map1.vis.earthdata.nasa.gov/twms-geo/twms.cgi?request=GetTileService

The “layers=” name within the TilePattern element gives a little more descriptive name for the layer. Note that only one layer, i.e. TiledGroupName, can be retrieved per gdal_translate call.

More information on GDAL_WMS can be found here (note the "Tiled WMS" section):
http://www.gdal.org/frmt_wms.html

Requirements
  • GDAL version 1.9.1 or greater with cURL support enabled
Retrieved from "http://earthdata.nasa.gov/wiki/main/index.php?title=GIBS_Supported_Clients&oldid=6276"
Personal tools
Namespaces
Variants
Actions