DigitalGlobe GBDX Raster Data Access API (RDA) GDAL Quick Start Guide
The GBDX Raster Data Access API (RDA) provides easy yet powerful access to raster data from DigitalGlobe's archive as well as other third-party raster data archives. This quick start guide provides an introduction to RDA for GDAL users.
Getting a GBDX Account
Before you begin, you will need a GBDX account. If you do not already have an account, visit https://gbdx.geobigdata.io to sign up. You'll need your GBDX username and password to use the tools provided in this docker image.
Supplying GBDX Credentials to the Docker Container
Once you have GBDX credentials, you'll need to supply them to the docker container. The easiest way to do that is to supply them as environment variables using the '--env-file' option on the 'docker run' command as follows:
docker run -i -t --env-file env_file.txt ...
In this example, the contents of 'env_file.txt' would be:
You may use any other means supported by docker to pass GBDX_USERNAME and GBDX_PASSWORD into the docker container as environment variables.
Alternatively, instead of supplying credentials as environment variables, you can edit the .gbdx-config file that's included in the docker to add a 'user_name' and 'user_password' line. For additional information on the .gbdx-config file structure, please refer to the gbdxtools docs (here and here).
Alright already... lets access some data...
This docker image contains two command-line applications that provide a simple interface for accessing raster metadata and materializing raster data locally as tif files. They are in the home directory of the docker container. The applications are thin python wrappers around two common gdal commands, 'gdalinfo' and 'gdal_translate'. The two applications are described below.
info.py wraps the familiar 'gdalinfo' command with a simple CLI. It prints the 'gdalinfo' command that is executed and returns the response of the command just as 'gdalinfo' would.
To see usage of the CLI:
> docker run -i -t tdgp/rda-getting-started python info.py -h
Note that you didn't need to provide GBDX credentials to the previous command. That's because we didn't actually access RDA, we just listed the contents of a file inside the docker image. All subsequent commands in this tutorial will require GBDX credentials to be provided. You'll see that we add a '--env-file ~/rda-docker-env-file.txt'. You should replace '~/rda-docker-env-file.txt' with the location of your environment file if that's how you want to supply GBDX credentials using an env. file.
To get information about an image:
> docker run -i -t --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python info.py -c 1030010079016D00 -b PAN -ct Acomp -p UTM
The previous command returns information about the atmospherically corrected panchromatic band from 1030010079016D00 projected to UTM coordinates at native resolution.
Here's a query of the multispectral bands from that image with the same options applied. Note that the number of bands reported by gdal are different since this WV02 image has 8 multispectral bands and only one pan band. Note, also that the height and width are 4x larger for the pan image since the satellite collects pan data at 4x higher resolution.
> docker run -i -t --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python info.py -c 1030010079016D00 -b MS -ct Acomp -p UTM
A common way to combine the resolution of the pan data with the multispectral information is called pan-sharpening. To get info about the pan-sharpened version of this image run the following command:
> docker run -i -t --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python info.py -c 1030010079016D00 -b Pansharp -ct Acomp -p UTM
translate.py wraps the 'gdal_translate' command with a simple CLI in a similar manner to info.py. The 'gdal_translate' command is printed and then it's executed. It's use is very similar to info.py with one notable difference. The command produces image files, so you should mount a local directory on your docker container so that you can access the image files after the docker container exits and write output image into that location.
To see usage information about translate.py:
> docker run -i -t tdgp/rda-getting-started python translate.py -h
To access a panchromatic, UTM chip with atmospheric correction applied:
> docker run -i -t -v/tmp:/data --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python translate.py -c 1030010079016D00 -b PAN -ct Acomp -p UTM -bbox 333560.0 166000.0 334560.0 165000.0 -of /data/pan.tif
Note the use of the -v docker option to mount the local /tmp directory inside the docker container as /data and that the output file is written to /data. Following this pattern the image file, 'pan.tif', is available to access in /tmp after the docker command exits.
The following command gets the multispectral chip for the same bounding box (in UTM coordinates):
> docker run -i -t -v/tmp:/data --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python translate.py -c 1030010079016D00 -b MS -ct Acomp -p UTM -bbox 333560.0 166000.0 334560.0 165000.0 -of /data/ms.tif
The combination of bandSelection and draType parameters provide a 3 band, 8-bit image. bandSelection options are "RGB", "All", or a comma separated list of band indices. An available draType is "HistogramDRA" which rescales the output image to an 8-bit image. The following command is the same MS image as an RGB, 8-bit chip:
> docker run -i -t -v/tmp:/data --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python translate.py -c 1030010079016D00 -b MS -p UTM -bbox 333560.0 166000.0 334560.0 165000.0 -s RGB -dt HistogramDRA -of /data/ms_rgb.tif
Or as a false color, 3 band image, which highlights vegetation:
> docker run -i -t -v/tmp:/data --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python translate.py -c 1030010079016D00 -b Pansharp -p UTM -bbox 333560.0 166000.0 334560.0 165000.0 -s 6,4,2 -dt HistogramDRA -of /data/ms_falsecolor.tif
As a final example, we will access a chip from the same image that's projected in WGS84 Latitude/Longitude (EPSG:4326). Note that no -p option is necessary because EPSG:4326 is the default projection system. Note also, that the bbox parameter is in degrees of longitude and latitude (to correspond to the projection).
> docker run -i -t -v/tmp:/data --env-file ~/rda-docker-env-file.txt tdgp/rda-getting-started python translate.py -c 1030010079016D00 -bbox 103.52 1.25 103.53 1.24 -of /data/ships.tif
We'll continue to add additional examples to this docker-based tutorial. The current examples use the RDA GDAL driver. We'll include more examples that use gbdxtools (the python client library for the GBDX platform) in the future.