You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/map-library-usage.md
+105-6Lines changed: 105 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,15 @@ Please see our ["GIBS Web Examples" GitHub area](https://github.com/nasa-gibs/gi
19
19
20
20
## GDAL
21
21
22
-
The Geospatial Data Abstraction Library ([GDAL](https://gdal.org/){:target="_blank"}) can be used as a basis to generate imagery from custom scripts. Its WMS driver supports several internal 'minidrivers' that allow access to different web mapping services. Each of these services may support a different set of options in the Service block. Documentation for these minidrivers can be found in the [GDAL WMS documentation area](https://gdal.org/drivers/raster/wms.html){:target="_blank"}. Two of these minidrivers in particular can be used by users to download GIBS imagery programmatically. They are the Tile Map Specification (TMS) and the OnEarth Tiled WMS (TiledWMS) minidrivers. Examples for both of these minidrivers are included below.
22
+
The Geospatial Data Abstraction Library ([GDAL](https://gdal.org/){:target="_blank"}) can be used as a basis to generate imagery from custom scripts. GDAL is a well known geospatial data access library which is part of most GIS applications. GDAL can read (and sometimes write) geospatial raster and vector data in many formats, the format specific operations being handled by a GDAL driver.
23
+
24
+
The GDAL WMS driver can access many of the known tiled and non-tiled protocols. GDAL WMS has a common part that handles interfacing with GDAL, making the requests and receiving the responses, decoding the received data as needed and a few other things. Since using tiles and multiple resolutions (known as a pyramid) is well supported in GDAL and widespread in the GIS domain, the core of the WMS driver is based on this model, and tile requests are made even when accessing a dynamic service that could provide its own subsetting and resampling.
25
+
26
+
The WMS driver supports several internal "minidrivers" that allow access to different web mapping services. Each of these services may support a different set of options in the Service block. Documentation for these minidrivers can be found in the [GDAL WMS documentation area](https://gdal.org/drivers/raster/wms.html){:target="_blank"}. Two of these minidrivers in particular can be used by users to download GIBS imagery programmatically. They are the Tile Map Specification (TMS) and the OnEarth Tiled WMS (TiledWMS) minidrivers. Examples for both of these minidrivers are included below.
27
+
28
+
The WMS driver is also used by many other GDAL drivers, for example it is used by the [GDAL WMTS driver](https://gdal.org/drivers/raster/wmts.html){:target="_blank"}. Accessing GIBS imagery the WMTS driver is detailed further below.
29
+
30
+
23
31
24
32
### Requirements
25
33
@@ -45,7 +53,24 @@ This section provides basic examples of both the TiledWMS and WMS GDAL drivers.
45
53
```
46
54
47
55
#### TiledWMS Driver
48
-
The TiledWMS GDAL minidriver relies on a simple XML configuration block (see example below) from the user, pulling all other information from the GIBS Tiled Web Map Service ([TWMS](../access-basics/#tiled-web-map-service-twms)) "Tile Service" document at runtime.
56
+
TiledWMS adds a GetTileService call to the OGC WMS, the XML document returned is what contains all the information needed to configure and connect to any dataset. The GetTileService request for datasets in EPSG:4326 projection is https://gibs.earthdata.nasa.gov/twms/epsg4326/best/twms.cgi?request=GetTileService
57
+
This URL can be used by gdalinfo to get a list of available datasets with their `TiledGroupName`:
To see information about a single dataset, the `gdalinfo` command may be invoked with the associated `SUBDATASET` ID of the `TiledGroupName` for the dataset by using the `-sd` flag. For example:
The TiledWMS GDAL minidriver supports a simple XML configuration block (see example below) from the user, pulling all other information from the GIBS Tiled Web Map Service ([TWMS](../access-basics/#tiled-web-map-service-twms)) "Tile Service" document at runtime.
49
74
50
75
```xml
51
76
<GDAL_WMS>
@@ -61,13 +86,15 @@ In the above XML block, the following values may be changed to meet your needs:
61
86
62
87
***Server Url** - Set the *ServerUrl* to a value of `{Endpoint Root}/twms.cgi?`, where the endpoint root is defined in [this](../access-basics/#service-endpoints_2) table.
63
88
* e.g. `https://gibs.earthdata.nasa.gov/twms/epsg4326/best/twms.cgi?`
64
-
***Tiled Group Name** - When accessing visualizations through TWMS, the *TiledGroupName* value is utilized instead of the layers identifier. The *TiledGroupName* can be generated by replacing all underscores in a visualization's *Identifier* with spaces and appending " tileset". For example:
89
+
***Tiled Group Name** - When accessing visualizations through TWMS, the *TiledGroupName* value is utilized instead of the layers identifier. The *TiledGroupName* can also be generated by replacing all underscores in a visualization's *Identifier* from GetCapabilities with spaces and appending " tileset". For example:
***Tiled Group Name** - MODIS Aqua CorrectedReflectance TrueColor tileset
67
-
***Time** - Insert the date (e.g. 2013-08-21) or datetime (e.g. 2013-08-21T00:00:00Z) you are requesting.
92
+
***Time** - Insert the date (e.g. 2013-08-21) or datetime (e.g. 2013-08-21T00:00:00Z) you are requesting. If no time is provided, you can add an option to your GDAL command to specify the value, e.g., `-oo Change=time:2020-02-05`
68
93
69
-
The following examples demonstrate how to invoke the GDAL TiledWMS driver.
70
-
##### #1 - Configuration File Input
94
+
95
+
96
+
The following examples demonstrate how to invoke the GDAL TiledWMS driver for imagery requests.
In this example, the following XML file is created and saved to your local file system. Then the `gdal_translate` command shown below is run with your desired area of interest and output dimensions.
72
99
73
100
```xml
@@ -79,17 +106,44 @@ In this example, the following XML file is created and saved to your local file
79
106
</Service>
80
107
</GDAL_WMS>
81
108
```
109
+
Let's save the XML as a file named `GIBS_Aqua_MODIS_true.xml`
The XML file can be opened in any GDAL based GIS software. However, in ArcGIS Pro, TileWMS is not recognized without some extra configuration steps, but it can be dragged and dropped into a map and it will work. Alternatively, we can change the extension into something supported, like .tif for example.
115
+
116
+
This file shows one of the main advantages of the TiledWMS over other GDAL WMS minidriver protocols. Only the minimum amount of information is stored in the handle file. No fiddling with bounding boxes, tile sizes, number of levels is required. Getting the detail correct becomes the responsibility of the source server. All that is needed is the server URL, the name of the tiled group and optionally a set of parameter changes supported by the tiled group.
86
117
87
118
##### #2 - "TiledWMS" Driver Command Line Input
88
119
This example invokes gdal_translate with the content of the TileWMS local service description XML file embedded as a command line argument. This approach is useful for automated scripting to download various layers, dates, etc. To generate the same image as the previous example, run the following:
##### #4 - Generate "TiledWMS" Configuration Files for Specified Datasets
139
+
gdal_translate has a `-sds` option where each subdataset of the input is copied, in sequence. This can be used to generate multiple handle files in a single command. We can use the open options to restrict which gets generated. For example, this generates all the handle files for patterns that contain the word "infrared":
**Note the drawback of using WMTS is that the `time` parameter is not supported. This means users are limited to only the default `time` for any given layer.**
256
+
257
+
##### #1 - Configuration File Input
258
+
Create a local service description XML file and invoke gdal_translate. In this example, GIBS_Terra_MODIS_true.xml is used to generate a true color JPEG image from Terra MODIS of the entire world for the current day. The contents of GIBS_Terra_MODIS_true.xml would be:
Note that the WMTS driver defaults to 4 bands, which may result in discoloration if the incorrect number of bands is specified. There is currently not a way to specify the number of bands from the command line with the WMTS driver, which may result in discoloration with this example.
0 commit comments