EVOLUTION-MANAGER

Edit File: frmt_rda.html

<html>
<head>
    <title>RDA (DigitalGlobe Raster Data Access)</title>
</head>

<h1>RDA (DigitalGlobe Raster Data Access)</h1>

(GDAL/OGR &gt;= 2.3)<p>

This driver can connect to DigitalGlobe RDA REST API.
    GDAL/OGR must be built with Curl support in order for the
    RDA driver to be compiled.
<p>

The driver retrieves metadata on graphs and fetches the raster by tiles.
    Data types byte, uint16, int16, uint32, int32, float32 and float64 are
    supported.
<p>

Any valid graph or template is supported via the DigitalGlobe RDA REST API.
<p>

There is no support for overviews.
<p>

<h2>Dataset name syntax</h2>

The minimal syntax to open a datasource is :
<pre>{"graph-id":"some_value", "node-id": "another_value"}</pre>
OR
<pre>{"template-id":"some_value", "params": [{ "someparam": "someparamval"}]}</pre>
<p>

So a JSon serialized document with 2 attributes graph-id and node-id.
<p>

<p>Those values can for example be retrieved from graphs built by
    <a href="https://rda.geobigdata.io/">GraphStudio</a>.</p>

<h2>Connection String options (optional)</h2>
<ul>
    <li>
        <pre>"options": {"delete-on-close": false}</pre>
        can be added to
        the JSon document to request that cached tiles and metadata are not destroyed
        at dataset closing. The default, if not specified, is true.
    </li>

<li>
        <pre>"options": {"max-connections": 32}</pre>
        can be added to
        the JSon document to request that cached tiles be fetched using a maximum number of
        concurrent connections. The default, if not specified, is equal to 8 * number of CPUs.
    </li>

<li>
        <pre>"options": {"advise-read": false}</pre>
        can be added to
        the JSon document to request advise read not be used when reading the dataset.
        The default, if not specified, is true.
    </li>
</ul>

<h2>Authentication</h2>

<p>Access to the API requires an authentication token. For that, 2 parameters
    (username, password) must be provided to the driver.
    They can be retrieved from the below configuration options, or from the
    ~/.gbdx-config file.</p>

<p>The access token will be cached in ~/.gdal/rda_cache/authentication.json and
    reused from there until its expiration period is reached.</p>

<h2>Configuration options</h2>

The following configuration options are available :
<ul>
    <li><b>GBDX_AUTH_URL</b>=value: To specify the OAuth authentication endpoint.
        Defaults to https://geobigdata.io/auth/v1/oauth/token/. If not specified, the
        auth_url parameter from ~/.gbdx-config will be used if it exists.
    </li>
    <li><b>GBDX_RDA_API_URL</b>=value: To specify the RDA API endpoint.
        Defaults to https://rda.geobigdata.io/v1. If not specified, the
        rda_api_url parameter from ~/.gbdx-config will be used if it exists.
    </li>
    <li><b>GBDX_USERNAME</b>=value: To specify the OAuth user name needed to get
        to an authentication token. If not specified, the
        user_name parameter from ~/.gbdx-config must be set.
    </li>
    <li><b>GBDX_PASSWORD</b>=value: To specify the OAuth user name needed to get
        to an authentication token. If not specified, the
        password parameter from ~/.gbdx-config must be set.
    </li>
</ul>

<h2>~/.gbdx-config file</h2>

<p>This file may be created in the home directory of the user (value of the
    $HOME environment variable on Unix, $USERPROFILE on Windows). It can contain
    values from the above configuration options.</p>

<pre>
[gbdx]
auth_url = https://geobigdata.io/auth/v1/oauth/token/ (optional)
rda_api_url = https://rda.geobigdata.io/v1 (optional)
user_name = value (required)
user_password = value (required)
</pre>

<h2>Caching</h2>

<p>By default, the authentication token is cached in the ~/.gdal/rda_cache
    directory. This directory may be changed with the RDA_CACHE_DIR configuration
    option. By default, dataset metadata and tiles are temporarily cached in
    ~/.gdal/rda_cache/{graph-id}/{node-id}, and deleted on dataset closing,
    unless
<pre>"options": {"delete-on-close": false}</pre>
is found in the dataset name.</p>

<h2>Open Options</h2>

<p>By default, the number of concurrent downloads will be 8*number of CPUs up to a maximum of 64. The maximum number of
    concurrent connections can be configured by the <em>MAXCONNECT</em> option</p>

<h3>Examples</h3>
<ul>
    <li> Display metadata, and keep it cached:

<pre>gdalinfo '{"graph-id":"832050eb7d271d8704c8889369ee0a8a1da82acdee1b20e1700b6d053e94d1fe","node-id":"Orthorectify_hko89y", "options": {"delete-on-close": false}}'</pre>

<pre>
Driver: RDA/DigitalGlobe Raster Data Access driver
Files: none associated
Size is 9911, 7084
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 = (-84.183163638386631,33.835018117204456)
Pixel Size = (0.000020885734819,-0.000020885734819)
Metadata:
  ACQUISITION_DATE=2017-04-07T16:25:29.156Z
  CLOUD_COVER=0.0
  GSD=2.325 m
  SAT_AZIMUTH=163.7
  SAT_ELEVATION=58.3
  SENSOR_NAME=8-band (Coastal, Blue, Green, Yellow, Red, Red-edge, NIR1, NIR2) Multispectral
  SENSOR_PLATFORM_NAME=WV02
  SUN_AZIMUTH=143.5
  SUN_ELEVATION=58.6
Image Structure Metadata:
  INTERLEAVE=PIXEL
Corner Coordinates:
Upper Left  ( -84.1831636,  33.8350181)
Lower Left  ( -84.1831636,  33.6870636)
Upper Right ( -83.9761651,  33.8350181)
Lower Right ( -83.9761651,  33.6870636)
Center      ( -84.0796644,  33.7610408)
Band 1 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 2 Block=256x256 Type=UInt16, ColorInterp=Blue
Band 3 Block=256x256 Type=UInt16, ColorInterp=Green
Band 4 Block=256x256 Type=UInt16, ColorInterp=Yellow
Band 5 Block=256x256 Type=UInt16, ColorInterp=Red
Band 6 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 7 Block=256x256 Type=UInt16, ColorInterp=Undefined
Band 8 Block=256x256 Type=UInt16, ColorInterp=Undefined
</pre>
    </li>

<li> Extract a subwindow from a dataset:

<pre>gdal_translate -srcwin 1000 2000 500 500 '{"graph-id":"832050eb7d271d8704c8889369ee0a8a1da82acdee1b20e1700b6d053e94d1fe","node-id":"Orthorectify_hko89y"}' out.tif</pre>
    </li>

<li> Materialize a dataset specifying a custom number of concurrent connections:
        <pre>gdal_translate -oo MAXCONNECT=96 '{"graph-id":"832050eb7d271d8704c8889369ee0a8a1da82acdee1b20e1700b6d053e94d1fe","node-id":"Orthorectify_hko89y"}' out.tif</pre>
    </li>

<li> Materialize a dataset from a template:
        <pre>gdal_translate '{"template-id": "sample", "params": [{ "imageId": "afa56b05-35ad-47d1-bc7f-3e23d220482d"}]}' out.tif</pre>
    </li>
</ul>
</body>
</html>