Skip to content

Maxar ARD Python SDK - ARD Collections

ARDCollections connect you to a storage location (cloud or local) and provides high-level abstractions of ARD tiles. The ARDCollection object scans ARD tiles in a location and can filter them down to more specific groups based on spatial or temporal filters. It also provides logical groupings of tiles by source (an Acquisition) or by location (a Stack of tiles in a grid cell). ARD Tiles also have their own high-level object to make data access simple and convenient.

This example uses Maxar sample data stored in the public S3 bucket maxar-ard-samples in the prefix v4/sample-001. If you've read the Selecting ARD tutorial already, you'll see that ARDCollections work similarly to SelectResult objects.

Passing public=True tells the SDK to skip authentication since this is a public bucket. See the end of this document for more information about authenticating with the different cloud providers.

from max_ard import ARDCollection

collection = ARDCollection('s3://maxar-ard-samples/v4/sample-001/', public=True)

An ARDCollection can tell you which IDs it has:

collection.acquisitions

[<Acquisition of 104001002124FA00 [<ARDTile at Z10-120020223023>]>,
 <Acquisition of 1040010022712A00 [<ARDTile at Z10-120020223023>, <ARDTile at Z10-120020223032>]>,
 <Acquisition of 103001005C2E5E00 [<ARDTile at Z10-120020223023>, <ARDTile at Z10-120020223032>]>,
 <Acquisition of 103001005D31F500 [<ARDTile at Z10-120020223032>]>]

An ARDCollection can also tell you which ARD grid cells it covers. A Stack is a container of all the tiles that cover a grid cell.

collection.stacks

[<Stack at Z10-120020223023 [<ARDTile of 104001002124FA00>, <ARDTile of 1040010022712A00>, <ARDTile of 103001005C2E5E00>]>,
 <Stack at Z10-120020223032 [<ARDTile of 1040010022712A00>, <ARDTile of 103001005C2E5E00>, <ARDTile of 103001005D31F500>]>]

Date properties

print(collection.dates)
print(collection.start_date)
print(collection.end_date)

['2016-09-22', '2016-09-23', '2016-09-30', '2016-10-08']
2016-09-22
2016-10-08

Zone properties

print(collection.zones)

[10]
- You can modify an ARDCollection's attributes that match the keywords in the call signature
  • This resets the collection but keeps the backing file cache
  • The resulting properties are read-only
start = '2016-01-01'
middle = '2019-10-01'
end = '2021-02-01'

c = ARDCollection('s3://maxar-analytics-data/ard_orders', earliest_date=start, latest_date=middle)
for tile in c.tiles:
    # do something with the tile


### Change the dates on the collection
### this resets the collection automatically
c.earliest_date = middle
c.latest_date = end

# c.end_date = end # this is a read-only property! It will return the end date of the actual data

for tile in c.tiles:
    # do something with the tile

If you need to reset the file cache:

c.clear_filesystem_cache()

ARD Tiles

Collections expose ARDTile objects representing the tiles. A tile is considering to be all of the data products from one acquisition within a specific grid tile.

collection.tiles

[<ARDTile of 104001002124FA00 at z10-120020223023>,
 <ARDTile of 1040010022712A00 at z10-120020223023>,
 <ARDTile of 103001005C2E5E00 at z10-120020223023>,
 <ARDTile of 1040010022712A00 at z10-120020223032>,
 <ARDTile of 103001005C2E5E00 at z10-120020223032>,
 <ARDTile of 103001005D31F500 at z10-120020223032>]

Let's look at a tile:

tile = collection.get_tile('1040010022712A00', 'z10-120020223032')
print('Tile:', tile)
print('Cell:', tile.cell)
print('Properties:')
for k,v in tile.properties.items():
    print(f'  {k}: {v}')

Tile: <ARDTile of 1040010022712A00 at z10-120020223032>
Cell: <Cell Z10-120020223032>
Properties:
  datetime: 2016-09-23 19:36:58Z
  platform: WV03
  gsd: 0.38
  ard_metadata_version: 0.0.1
  catalog_id: 1040010022712A00
  utm_zone: 10
  quadkey: 120020223032
  view:off_nadir: 28.0
  view:azimuth: 290.3
  view:incidence_angle: 59.0
  view:sun_azimuth: 170.0
  view:sun_elevation: 51.5
  proj:epsg: 32610
  proj:geometry: {'type': 'Polygon', 'coordinates': [[[549843.75, 4185156.25], [549843.75, 4179843.75], [555156.25, 4179843.75], [555156.25, 4185156.25], [549843.75, 4185156.25]]]}
  proj:bbox: [549843.75, 4179843.75, 555156.25, 4185156.25]
  tile:data_area: 28.2
  tile:clouds_area: 0.0
  tile:clouds_percent: 0

Tiles have Shapely geometry properties. For the full tile, use the geometry of a tile's cell:

from shapely.geometry import shape
shape(tile.cell)

A tile's data_mask is the geometry outlining filled pixels.

tile.data_mask

ARD V4 deliverables also includes the following vector mask assets:

  • Cloud mask
  • Cloud shadow mask
  • Terrain shadow mask
  • Water mask
  • Healthy vegetation mask
  • Saturated multispectral pixel mask
  • Pan band flare pixel mask

These assets are available through "magic" accessors which return Shapely geometries:

  • .cloud_mask
  • .cloud_shadow_mask
  • .terrain_shadow_mask
  • .water_mask
  • .healthy_vegetation_mask
  • .ms_saturation_mask
  • .pan_flare_mask
tile.water_mask