GBDX

How to Get a Chip with GDAL and the RDA Template API

This tutorial describes how to get an RDA chip using GDAL, the RDA Template API, and the DigitalGlobeStrip template.

How to Get GDAL with the RDA Driver

To get get GDAL with the RDA driver, see How to Get the GDAL RDA Driver

The GDAL 2.3.0 release will include the RDA driver. GDAL 2.3.0 is currently a pre-release version, and is not fully supported.

For more information, see RDA GDAL Driver.

Quickstart Tutorial

This tutorial illustrates how to get an image chip with GDAL, the RDA Template API, and the DigitalGlobeStrip template.

Sample Image

For this tutorial, we'll be using image 10400E0001DB6A00. The whole strip looks like this:

Image 1: This is the original image used in the example.

Image 1: This is the original image used in the example.

Get image metadata

The command gdalinfo prints out general image information:

gdalinfo '{"template-id": "DigitalGlobeStrip", "params": [{"crs": "EPSG:4326", "bands": "MS", "catalogId": "10400E0001DB6A00", "draType": "None", "correctionType": "DN", "bandSelection": "All"}]}'

The results of the gdalinfo command:

Driver: RDA/DigitalGlobe Raster Data Access driver
Files: none associated
Size is 12622, 10605
Coordinate System is:
GEOGCS["WGS 84",
    DATUM["WGS_1984",
        SPHEROID["WGS 84",6378137,298.257223563,
            AUTHORITY["EPSG","7030"]],
        AUTHORITY["EPSG","6326"]],
    PRIMEM["Greenwich",0,
        AUTHORITY["EPSG","8901"]],
    UNIT["degree",0.0174532925199433,
        AUTHORITY["EPSG","9122"]],
    AUTHORITY["EPSG","4326"]]
Origin = (36.866078880000003,33.977969486180378)
Pixel Size = (0.000011606180381,-0.000011606180381)
Image Structure Metadata:
  INTERLEAVE=PIXEL
Corner Coordinates:
Upper Left  (  36.8660789,  33.9779695) ( 36d51'57.88"E, 33d58'40.69"N)
Lower Left  (  36.8660789,  33.8548859) ( 36d51'57.88"E, 33d51'17.59"N)
Upper Right (  37.0125721,  33.9779695) ( 37d 0'45.26"E, 33d58'40.69"N)
Lower Right (  37.0125721,  33.8548859) ( 37d 0'45.26"E, 33d51'17.59"N)
Center      (  36.9393255,  33.9164277) ( 36d56'21.57"E, 33d54'59.14"N)
Band 1 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 2 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 3 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 4 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 5 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 6 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 7 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 8 Block=256x256 Type=UInt16, ColorInterp=Undefined

Get a chip using a pixel-based window

The gdal_translate command allows you to transform the image and write out the transformed image. We will transform the image by selecting a subset of the image based on a pixel window. Our pixel window is the 2048x2048 pixel square in the upper-left corner of the image. The window is shown below in green:

Image 2: The green square indicates the subset of the image selected based on a pixel window.

Image 2: The green square indicates the subset of the image selected based on a pixel window.

The gdal_translate command to get this window (in tif format) is:

gdal_translate -srcwin 0 0 2048 2048 '{"template-id": "DigitalGlobeStrip", "params": [{"crs": "EPSG:4326", "bands": "MS", "catalogId": "10400E0001DB6A00", "draType": "None", "correctionType": "DN", "bandSelection": "All"}]}' srcwin.tif

The resulting image chip looks like this:

Image 3: This is the resulting image chip.

Image 3: This is the resulting image chip.

Get a chip using a map-projected window

The gdal_translate command also allows you to specify a window in the projection system of the image (in this case Lat/Long WGS84 or EPSG:4326). An example projected window is shown below in blue:

Image 4: The blue square shows the example projected window.

Image 4: The blue square shows the example projected window.

The gdal_translate command to get this projected window as a tif is:

gdal_translate -projwin 36.9393 33.9164 36.9433 33.9124 '{"template-id": "DigitalGlobeStrip", "params": [{"crs": "EPSG:4326", "bands": "MS", "catalogId": "10400E0001DB6A00", "draType": "None", "correctionType": "DN", "bandSelection": "All"}]}' prjwin.tif

The resulting image chip looks like:

Image 5: This is the resulting image chip from the projected window.

Image 5: This is the resulting image chip from the projected window.

Image processing options supported by DigitalGlobeStrip template

The DigitalGlobeStrip template used in this tutorial supports many of the common image processing options required to peform analytics on DigitalGlobe imagery including orthorectification to various projection systems, atomoshpheric compensation, pan-sharpening, band selection, and dynamic-range adjustment. The processing options are set by changing the values for the 'params' in the gdal connection string. Here are some example connections strings that demonstrate the different processing options:

Map projection

Specify the map projection to use during orthorectification by setting the 'crs' parameter to a valid EPSG map projection code.

Web-mercator map projection:

'{"template-id": "DigitalGlobeStrip", "params": [{"crs": "EPSG:3857", "bands": "MS", "catalogId": "10400E0001DB6A00", "draType": "None", "correctionType": "DN", "bandSelection": "All"}]}'

UTM is a special case where we will automatically find the most appropriate UTM zone if you specify 'UTM' for the 'crs' parameter:

'{"template-id": "DigitalGlobeStrip", "params": [{"crs": "UTM", "bands": "MS", "catalogId": "10400E0001DB6A00", "draType": "None", "correctionType": "DN", "bandSelection": "All"}]}'

Atmospheric correction

The atmospheric correction options include 'DN' (no correction, pixels values are raw DN values), 'TOA' (top-of-atmoshpere reflectance), and 'AComp' (surface reflectance). The previous examples demonstrate 'DN'. For Acomp use:

'{"template-id": "DigitalGlobeStrip", "params": [{"crs": "EPSG:3857", "bands": "MS", "catalogId": "10400E0001DB6A00", "draType": "None", "correctionType": "AComp", "bandSelection": "All"}]}'

Panchromatic, multispectral, swir, and pan-sharpened multispectral output

The bands combination to process is specified by setting the 'bands' parameter. Valid options are 'PAN', 'MS', 'SWIR', and 'Pansharp'. 'PAN', 'MS', and 'SWIR' select the panchromatic (one band), multispectral (4 or 8 bands depending on satellite), and short-wave infrared bands (8 band) respectively. Not all satellites support all options. For example the WorldView 1 satellite only support 'PAN' since it only has a panchromatic sensor. Only swir images shot using WorldView 3 support the 'SWIR' option.

Dynamic range adjustment

The 'draType' parameters controls weather or not DRA is applied. Current options are "None" (for no-dra) and "HistogramDRA". "HistogramDRA" will apply RDA's default DRA (linear histogram stretch with clip and gamma adjustment).

Band Selection

The 'bandSelection' parameters controls which bands are included in the image. Options are 'All' for all available bands and 'RGB' for true-color (red-green-blue) only.

Additional Resources

To learn more about RDA, see the Raster Data Access (RDA) Course.

To see a quickstart tutorial for getting an image chip using gbdxtools, see Quickstart tutorial with gbdxtools.