Skip to content

CLI Quickstart

This Quickstart example will walk you through selecting and ordering ARD imagery using the ARD Python CLI.

Step 1: Install tools

The CLI tools are part of the Python SDK package. To install the SDK requires having Python installed as well as the Python package installer pip. Windows users please see the main page for details about installing some of the dependencies.

% pip install max-ard --extra-index-url https://packages.ard.maxar.com

The SDK uses the Boto3 package to access S3 resources. You will need to have correctly configured AWS credentials for the SDK to communicate with S3. We recommend installing the AWS CLI tools and following their configuration guide.

Step 2: Get Access

The ARD Python CLI manages access tokens for you. You will need to provide your username and password via a configuration file or with environment variables.

Configuration File

You can store your login information locally in a configuration file. The CLI can create this file for you by running:

max-ard login

You can also create a file in your home directory named .ard-config with the following contents:

[ard]
user_name = <your user name>
user_password = <your password>

You can check whether you can access the ARD system with the following command:

% max-ard login

Step 3: Create a Destination

To create the destination you must have correctly configured AWS credentials.

You can manually create your bucket and set access via the AWS Console or CLI tools, or with the Python SDK (described in the API and SDK quickstart sections respectively).

The ARD Python CLI also has tools to create and configure a bucket.

% max-ard storage init <new bucket name>

The same command will also add access to an existing bucket:

% max-ard storage init <existing bucket-name>

Step 4: Select ARD Tiles

If you already know the acquisition IDs you'd like to order, you can skip down to Step 5. But please come back and read this section!

The ARD Select system provides searching and selection for ARD data. In the past you would have had to search for image strips that looked promising, then write code to winnow the selection down. The ARD Select system has already precomputed tile level metadata and can apply that data to an AOI. It will then pick the best tiles to fit your requirements.

Defining a Select

To limit the scope of a Select, it needs to either be limited to a list of acquisition IDs, or restricted to a geographic area. For this example we'll look at imagery over Albuquerque, New Mexico, so we'll use a bounding box of (-106.8, 35.1, -106.4, 35.4).

We'll also restrict the images to those collected between the dates of 2020-07-01 and 2021-01-25, which we can represent as two ISO datetimes separated by a slash: 2020-07-01T00:00:00Z/2021-01-25T00:00:00Z.

In addition to the spatial and temporal restrictions, the Select system lets you filter imagery on other metadata fields such as cloud cover. For this example we'll add a filter to only return image tiles that are more than 95% cloud free. The CLI has a shortcut for this filter in the --min-cloud-free option. By passing --min-cloud-free 95 we can tell the Select system to only pick tiles that are 95% cloud free or better.

Similarly, we'd also like to receive tiles are mostly full of data. Tiles that are on an edge of a strip will contain nodata pixels, and we don't want to manage images that are mostly empty. We can set the --min-data option to control this. We'll pass --min-data 75 to require all tiles be 75% full of data.

The select system also lets you write query statements against image metadata fields. The two shortcut options described above work in lieu of setting filters on the metadata fields aoi:cloud_free_percentage and aoi:data_percentage. For an example of setting a filter, we restrict the selection to imagery captured by the Worldview 2 satellite. This filter looks like --filter platform eq worldview-02, where eq means equals (=). You can filter on any field by passing --filter <field> <operator> <value>. To see all the fields and operators supported by the system, see the API reference.

We'll also specify the stack_depth, which limits how many tiles in each cell are returned. By default, the system will return up to 5 file tiles per cell. We'll limit it to 3 tiles with the --stack-depth 3 option.

The Select system picks the tiles by scoring them and returns the best scoring tiles. The score is calculated based on the recency, with newer images favored over older ones, and how they compare to any filters that compare numerical values ( >, >=, <, <=)

For this example, when we set the cloud-free percentage to 95 (or aoi:cloud_free_percentage >= 95), the Select system will score acquisitions better the greater their cloud-free percentage is. This means that an image with a cloud-free percentage of 100 will score better on this metric than an image that is 96% cloud free. An image with 72% cloud free coverage does not satisfy the filter and is rejected.

Running a Select

Combining all these requirements into one command looks like:

% max-ard select submit \
  --bbox -106.8 35.1 -106.4 35.4 \
  --datetime '2020-07-01T00:00:00Z/2021-01-25T00:00:00Z' \
  --min-cloud-free 95 \
  --min-data 75 \
  --filter platform eq worldview-02 \
  --stack-depth 3

When run, you will likely see these results in about 10 seconds:

Select <id> has been submitted
Run `max-ard select status <id>` to check the status
When the status is "SUCCEEDED" you can:
Run `max-ard select describe <id>` to see a basic overview of the results
Run `max-ard select browse <id>` to launch a browser-based map view of the results
Run `max-ard select` to see all the `order` commands

This will return a Select ID. We can then check if the Select is complete:

% max-ard select status <id>
RUNNING

For some Select queries the system can generate an answer fast enough to give you an answer in less than 10 seconds, so you'll get a message like:

Select <id> has completed
Run `max-ard select describe <id>` to see a basic overview of the results
Run `max-ard select browse <id>` to launch a browser-based map view of the results
Run `max-ard select` to see all the `select` commands

We can look at the results of the finished Select:

% max-ard select describe <id>
This generates an output like:

Getting Select ID 5742048259984049082...

*******************
Request details:
{   'bbox': [-106.8, 35.1, -106.4, 35.4],
    'datetime': '2020-07-01T00:00:00Z/2021-01-25T00:00:00Z',
    'query': {   'aoi:cloud_free_percentage': {'gte': 95.0},
                 'aoi:data_percentage': {'gte': 75.0},
                 'instruments': {'not-contains': 'SWIR'},
                 'platform': {'eq': 'worldview-02'},
                 'view:sun_elevation': {'gte': 5}},
    'stack_depth': 3}
*******************

53 tiles identified in the following 5 acquisitions:
10300100B3841C00 (2021-01-16) - 6 tiles
10300100B2B49700 (2021-01-16) - 14 tiles
10300100AB101A00 (2020-07-24) - 17 tiles
10300100B39ACD00 (2021-01-16) - 10 tiles
10300100A67D3100 (2020-07-10) - 6 tiles

Ordering this selection will use:
- 0.0 sqkm of fresh imagery
- 1313.0 sqkm of standard imagery
- 0.0 sqkm of training imagery

To export the Select as geojson you can use the --dest <filename>.geojson option

% max-ard select describe <id> --dest my_select.geojson

An example file my_select.geojson is included in the examples section of the docs.

To see the results in map browser:

% max-ard select browse <id>

An example map browser file called select-browse.html is also included in the examples section of the docs.

Step 5: Ordering

If you know the acquisition IDs you would like to order, for example if you searched for images on discover.maxar.com, you can order them directly. Provide a the bucket you configured above as the destination. You can add "directory" prefixes as needed to organize your deliveries. We'll pass the Albuquerque bounding box to limit the data delivered. If you do not provide some kind of Area of Interest you will receive all of the tiles covering the image strips.

% max-ard order submit \
  --destination 's3://my_bucket/prefix' \
  --bbox -106.8 35.1 -106.4 35.4
  --acquisition_id <acquisition ID 1> \
  --acquisition_id <acquisition ID 2> \
  --acquisition_id <acquisition ID 3> \
  --dry-run

However, if you ran a Select and would like to order the tiles it has picked out, you can create an order with the Select ID and a destination.

% max-ard order submit \
  --destination 's3://my_bucket/prefix' \
  --select_id <id> \
  --dry-run

Both of these command examples use the --dry-run option, which will run a basic set of order pre-checks to make sure the order can complete. In addition to the dry run succeeding, you can verify the Order system was able to access your output location by looking for a file named <id>-request.json in your output location.

% max-ard order submit \
  --destination 's3://my_bucket/prefix' \
  --select_id <id> \
  --dry-run

Request payload:
{'select_id': '<id.', 'dry_run': True, 'output_config': {'bucket': 'my_bucket', 'prefix': 'prefix'}, 'bundle_adjust': False}
Checking order in dry-run mode...
Dry run successful

To place an actual order, remove the --dry-run option. To receive an email when the order is complete, add a notification to the order:

  --add-email 'me@email.com'

When you run this command, it will return an order ID.

% max-ard order submit \
  --destination 's3://my_bucket/prefix' \
  --select_id <id> \
  --add-email 'me@email.com'

Request payload:
{'select_id': '<id.', 'output_config': {'bucket': 'my_bucket', 'prefix': 'prefix'}, 'bundle_adjust': False, 'notifications': [{'type': 'email', 'address': 'me@email.com'}]}
Order <id> has been submitted
Run `max-ard order status <id>` to check the status
When the status is "SUCCEEDED" you can:
Run `max-ard order describe <id>` to see a basic overview of the results
Run `max-ard order` to see all the `order` commands

It can take anywhere from 2 to 24 hours to deliver your order. You can check the order status from the order ID:

% max-ard order status <id>`

Step 6: Examining Data

When the tile has been delivered, you can get some information about what tiles are in your destination:

% max-ard storage describe <s3://my_bucket/prefix>

If you have the AWS CLI tools installed, you can also try to list the location's contents (note that a trailing slash is essential for this command to return contents):

aws s3 ls <s3://my_bucket/prefix/>

Using sample ARD data at maxar-ard-samples/sample-001/:

% max-ard storage describe s3://maxar-ard-samples/sample-001/
Examining ARD data in maxar-ard-samples/sample-001/...
4 acquisitions
8 tiles
Earliest date: 2016-02-21
Latest date: 2020-10-22
UTM zone: 10

% aws s3 ls s3://maxar-ard-samples/sample-001/
                           PRE 10/
                           PRE acquisition_collections/
                           PRE order_collections/
2021-01-29 15:50:27        628 5580431239134362341-request.json
Back to top