ARD Order Deliveries¶
Last updated: December 1, 2022
Overview¶
Maxar's Analysis-Ready Data (ARD) is ordered by making a request to the Ordering API. The order request specifies the cloud storage location where the data should be delivered. We refer to the output of an order as an "ARD order delivery".
Contents of an order delivery¶
The output of a delivery is a time-series stack of tiles and their accompanying metadata. The files are:
-
A single-band panchromatic GeoTIFF.
-
A 4 or 8-band multispectral GeoTIFF.
-
A 3-band RGB GeoTIFF. We refer to this file as a "visual" tile.
-
A set of data masks delivered individually in both raster GeoTIFF and vector GeoPackage formats. Individual masks can be excluded from the delivery as part of the order requests.
-
A set of STAC-compliant metadata files that describe the contents of the order delivery.
Delivery file directory structure¶
ARD orders are delivered in the following directory structure:
📁 {bucket or container}
└── 📁 {prefix (optional)}
└── 📁 acquisition_collections
└─╴📄 {acquisitionID}_collection.json
└── 📁 order_collections
└─╴📄 {orderID}_root_collection.json
└── 📁 {UTM-zone}
└── 📁 {quadkey}
└── 📁 {acquisition-date}
└─╴📄 (files)
└── 📄 {orderID}-request.json
-
If a prefix is not submitted with the order request, the files will be delivered directly to the bucket location.
-
There can be multiple prefixes in the path.
-
The UTM zone and quadkey indicate where the tile is located on the grid.
-
The acquisition date is the month, day, and year the image was acquired by the satellite. In a list view, the acquisition-date folders are arranged from oldest to most recent. The image files and accompanying data are stored in the acquisition date folder.
See About the Directory Structure for details.
Non-intersecting tiles report¶
Most orders will not include a non-intersecting tiles report file.
The imagery selection and order validation steps use an estimated image footprint, based on metadata. The estimated footprint and the actual footprint can be slightly different. Most of the time, the difference doesn't impact the ordering process.
Occasionally, when only the edge of the estimated footprint intersects with the AOI, the shift is enough that the actual footprint does not intersect. In this scenario, the imagery would pass select and order validation, but the non-intersecting tile or tiles cannot be ordered. When this occurs, the intersecting image tiles in the order are delivered, and a report is generated that lists the non-intersecting tiles that could not be delivered.
The report is named {orderID}_non_intersecting_tiles_report.json
.
It is located in the order_collections
subdirectory.
📁 {bucket or container}
└── 📁 {prefix}
└── 📁 acquisition_collections
└─╴📄 {acquisition ID}_collection.json
└─╴ 📁 order_collections
└─╴📄 {orderID}_root_collection.json
└─╴📄 {orderID}_non_intersecting_tiles_report.json
Image files¶
There are three raster image files for each tile in a delivery. These are cloud-optimized GeoTiffs, or "COGs". Click the image file link for more details about each image type.
Image file | Description | Filename |
---|---|---|
multispectral image | A 4 or 8-band multispectral image in GeoTiff format. | {acquisitionID}-ms.tif |
panchromatic image | A single-band panchromatic image in GeoTiff format. | {acquisitionID}-pan.tif |
visual (RGB) image | A 3-band RGB image in GeoTiff format. | {acquisitionID}-visual.tif |
See About ARD for more information about ARD image tiles and additional pre-processing steps.
Data Masks¶
ARD order deliveries include a set of data masks for each tile. A raster GeoTiff (.tif) and a vector GeoPackage (.gpkg) file are delivered for most masks. There are two exceptions:
-
Clouds and cloud shadows are both captured in a single raster mask called the "cloud/cloud shadow coverage raster". Cloud and cloud shadows have individual vector files, named "cloud polygons" and "cloud shadow polygons".
-
The "data mask" is derived from the raster image and is delivered only as a vectorized GeoPackage.
The mask names in the table can be clicked for additional documentation and imagery examples. There is no additional documentation for the "data mask" which simply identifies pixels with data.
Mask | Description | File type | Filename |
---|---|---|---|
Cloud/Cloud Shadow Coverage Raster | Identifies clouds and cloud shadow pixels. | raster | {acquisitionID}-clouds.tif |
Cloud Polygons | Traces the boundaries of identified cloud polygons. | vector | {acquisitionID}-cloud-mask.gpkg |
Cloud Shadow Polygons | Traces the boundaries of identified cloud shadows. | vector | {acquisitionID}-cloud-shadow-mask.gpkg |
Data Mask | Identifies all pixels classified as "data" in the raster image and vectorizes those pixels as a GeoPackage. Pixels are either classified as "data" or "no data". | vector | {acquisitionID}-data-mask.gpkg |
Healthy Vegetation Mask | Binary raster indicating green, healthy vegetation pixels. | raster | {acquisitionID}-healthy-vegetation.tif |
Healthy Vegetation Polygons | Polygons that indicate the detected boundaries of green, healthy vegetation. | vector | {acquisitionID}-healthy-vegetation-mask.gpkg |
MS Pixel Saturation Mask | Identifies saturated pixels in a 4 or 8-band multispectral image. | raster | {acquisitionID}-ms-saturation.tif |
MS Pixel Saturation Polygons | Traces the boundaries of identified saturated pixels in a multispectral image. | vector | {acquisitionID}-ms-saturation-mask.gpkg |
Pan Flare Mask | Detected flared pixels from a panchromatic image. | raster | {acquisitionID}-pan-flare.tif |
Pan Flare Polygons | Traces the boundaries of detected flare pixels from a panchromatic image. | vector | {acquisitionID}-pan-flare-mask.gpkg |
Terrain shadows mask | Identifies terrain shadow pixels. | raster | {acquisitionID}-terrain-shadows.tif |
Terrain Shadows Polygon | Traces the boundaries of detected terrain shadows. | vector | {acquisitionID}-terrain-shadow-mask.gpkg |
Water Mask | Detects pixels for bodies of water and swimming pools. | raster | {acquisitionID}-water.tif |
Water Polygons | Traces the boundaries of bodies of water and swimming pools. | vector | {acquisitionID}-water-mask.gpkg |
Metadata files¶
An ARD order delivery includes additional files with information about the order and its contents. The metadata files adhere to the Spatio-temporal Asset Catalog (STAC) specifications.
Click a filename to learn more about the contents of a specific file.
File | Description | File type | Filename |
---|---|---|---|
STAC item metadata file | Describes the ordered tile and its assets. | JSON | {acquisitionID}.json |
Order STAC collection file | Describes the contents of the order delivery. | JSON | /order_collections/{orderID}_root_collection.json |
Acquisition STAC collection file | Describes the acquisitions in the order delivery. | JSON | /acquisition_collections/{acquisitionID}_collection.json |
Order request file | Shows the JSON body of the order request. | JSON | /{orderID}-request.json |