Skip to content

Maxar ARD SDK

max_ard 1.7.4

A Python SDK and CLI for working with ARD Imagery

Introduction

max_ard consists of a Python SDK for selecting, ordering, and working with Maxar ARD imagery and a set of CLI tools for common tasks. These include:

  • Authentication and access to the ARD API
  • Running ARD Selects and working with their results
  • Searching using the lower-level Metadata API
  • Create and manage Monitors to alert when new imagery is available
  • Generate and run ARD orders
  • Explore and work with ARD products

The goal of the SDK is to provide high-level abstractions so users can get quickly get started with ARD. However, the SDK is not required to work with the ARD API or deliverables. It is possible to communicate with the HTTP API and order ARD just using the requests package, as well as read pixels from ARD tiles just using rasterio or any other Python package that can read TIFF files.

max_ard is tested on Python 3.7 - 3.9, due to the availability of Python wheels for all of the package's dependencies.

For general information about Maxar ARD, see the main documentation at https://ard.maxar.com/docs

Installation

max_ard comes in two flavors:

  • max_ard is the base version. This lets you interact with the API and explore ARD collections in S3 or copied to your local system. It lacks the requirements Fiona, and Rasterio which you would use to read the ARD raster and vector products. This makes installation of max-ard faster and easier. You can install any of the two libraries later if needed.

  • max_ard[full] includes 'Fiona' and 'Rasterio' for users who want to read data from the raster and vector ARD files.

Functionality and requirements

Feature Fiona Rasterio
Read/write images X
Read ARD vector masks X
Read spatial files for AOIs X
Output QGIS layers and shapefiles X

OS X and Linux Installation

To install the base version:

pip install max_ard

For the full version:

pip install 'max_ard[full]'

Note that Python 3.10 does not have Rasterio wheels yet so the full installation will require manual build steps.

Earlier versions of max_ard are available at packages.ard.maxar.com. Starting at version 1.5.2 this package became available through PyPI.

To read ARD data stored in Azure you will also need to install adlfs, and for ARD data in Google Cloud Storage, install gcfsf. These are not needed to order ARD tiles to these platforms.

Windows Installation

We highly recommend Windows users use a Conda-based installer to manage their environment and dependencies. We recommend Miniforge but any of the "-Conda" or "-Forge" based installers will work. max_ard requires Shapely and these installers will install it correctly. To install the base max_ard package run:

% conda create -n ard-env shapely
% conda activate ard-env
% pip install max_ard

To install the full max_ard version, you should also use Conda to install Fiona and Rasterio. Note this requires you to use Python 3.7 until Conda-Forge releases updated Rasterio packages. You do not need to specify max_ard[full] when using Conda.

% conda create -n ard-env python=3.7 gdal rasterio fiona shapely
% conda activate ard-env
(ard-env) % pip install max_ard

If you install Fiona, you will likely need to set the PROJ database location. If you see warnings about "Cannot find proj.db", run this command in your ARD env:

(ard-env) % $Env:PROJ_LIB = "$Env:CONDA_PREFIX\Library\share\proj\proj.db"

If you do not use Anaconda or Miniconda, you can try to install pre-compiled binaries for the C-based dependencies in this order:

Next install the Wheel files for GDAL, Rasterio, and Fiona. From the links below, download the correct wheel file for your system. You will need to match Python versions (-cp38- means Python 3.8 and so on) and system architecture (most likely AMD64). Once you have downloaded the file, install it with pip install path/to/package.whl.

Upgrading max_ard

Use the --upgrade parameter in pip:

pip install max_ard --upgrade

Prerequisites

If you are using the SDK or CLI to access data in a private S3 bucket, you will need to configure your AWS credentials locally. We recommend installing the AWS CLI tools and following their configuration guide.

To interact with the ARD API services, you will need to obtain and configure ARD account credentials. Currently we store the credentials locally in a file in your home directory called .ard-config. It should contain:

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

The CLI tools can be used to create this file if it does not exist:

max-ard login

Python AutoDocs

Autogenerated documentation of max_ard and companion grid library maxar_ard_grid can be found at:

Sample Data

Several sample datasets are available in the bucket s3://maxar-ard-samples/v4. No authentication is required for access. To browse the sample data structure you can use this web-based file browser.

Back to top