Release Notes

---

ARD release notes

January 20, 2022

• Removed eval field from accounts

• Removed sqkm limit from accounts and users; removed available sqkms from usage

December 1, 2022

See the December 2022 Release Announcement for details.

Feature	More info	Resources
Tasking API	Users can submit an AOI and additional matching criteria in a tasking request. Collected images are automatically ordered and delivered to you.	Tasking User Guide
Monitoring Improvements	General improvements to the Monitoring API.	Monitoring User Guide
30 CM HD	30 CM HD is now available to order.	Ordering HD
User Interface Updates	Timeline visualization of an imagery selection; generate an S3 bucket policy from the Ordering interface.	Maxar ARD Dashboard

Developer Tool Updates

Updated Postman Collection

July 20, 2022

The deprecated components from this announcement have been retired.

July 13, 2022

We've added an asynchronous usage API endpoint. This endpoint lets you make a usage request and get the results asynchronously. You'll also receive a csv file with usage data in email. This is especially useful if you have a high volume of usage data that may cause a synchronous request to time out.

Asynchronous Usage API Reference

May 12, 2022

Maxar ARD Dashboard user interface

• Access the Maxar ARD Dashboard

• Sign in using your ARD credentials (email and password).

Feature	More info	Resources
Explore Cell Metadata	Explore cell coverage and metadata for your Area of Interest.	Explore Help Topic
Select Imagery	Select imagery to order from our Area of Interest. Includes a "cart" view where you can see the selected imagery and remove images before placing your order.	Select Help Topic
Order	Order the imagery you selected or order imagery by a list of acquisition IDs with an optional AOI.	Order Help Topic

New Features and Improvements

Update	More info	Resources
Temporal/Seasonal Queries	New query fields to allow querying by month, day of month, or day. Ranges can be used to create seasonal queries.	Temporal Queries documentation
WorldView-1 imagery	WorldView-1 imagery is now orderable as analysis-ready data.	WorldView-1 Imagery Guide
Masks are now optional	Choose which masks to have delivered with your order.	Order Settings Guide
Thumbnail image support	Use the Browse API to view an image tile thumbnail.	Preview Tile Thumbnail Guide
New metadata field for order requests	The metadata field can be used on orders to track projects or to include any information you want to track with the order.	Metadata field for Orders documentation
Change to Select API response	The response to a POST /select request is now asynchronous for faster processing.	Select Results Documentation
Changes to Select STAC item file	The Select STAC item file has been updated for better STAC compliance and readability.	Change Summary
Changes to Order STAC item file	The Order STAC item metadata file has been updated for better STAC compliance.	Order STAC item changes

60-day deprecation notices

RETIRED July 20, 2022

The following changes will be made on Tuesday July 12, 2022. We will support the legacy and new fields related to these changes until that date. See the Deprecation Announcement.

Update	More info	Resources
Move bundle_adjust field to new order settings section	The bundle_adjust field, which is used to run Bundle Block Adjustment (BBA) on an order has been added to the new "settings" section on orders. It will be removed from the top-level order request body on July 12th. Both locations will be supported till then.	Bundle Adjust Change Announcement
Remove eo:bands from masks	The order STAC item metadata file will no longer include eo:bands fields for raster mask items.	STAC update announcement

Developer Tool Updates

Download the latest Postman collection

SDK users: Upgrade to Version 1.5.0

March 18, 2022

Tile metadata requests can now accept a list of acquisition IDs. See Tile Metadata Guide.

An example request that uses acquisition IDs has been added to the Postman Collection.

March 15, 2022

ARD orders now have more detailed status messages. See Get the Status of an order.

March 3, 2022

Update	More info	Resources
Healthy Vegetation Mask	Raster and vector masks to identify healthy, green vegetation are now part of an ARD order delivery.	Healthy Vegetation Mask Documentation
Panchromatic Flare Mask	Raster and vector masks to identify flared pixels from a panchromatic image are now part of an ARD order delivery.	Pan Flare Mask Documentation
Monitoring API	Watch for new imagery acquisitions based on an Area of Interest (AOI) and optional matching criteria. When the Monitor finds a newly acquired matching image, it sends a notification.	Monitoring Guide
Cell Metadata API	Explore areas of the world covered by Maxar ARD to discover ARD tiles you may want to order.	Cell Metadata Guide

SDK users: Upgrade to Version 1.4.0.

Postman users: Download the latest Postman collection.

October 14, 2021

Update	More info	Resources
New ARD version	Order deliveries will include four new data masks and updated tile metadata. Current users have until December 17, 2021 to upgrade.	Release Announcement
Admin Tools	A new user interface for managing users for an account, and viewing order history and usage data.	Admin Tools documentation
SDK version 1.2.0	Adds new masks to the QGIS layer export capability. New ARD metadata and masks can be read by versions 1.1.0 and later.	max-ard SDK

August 24, 2021

A new Postman collection is available. You can download it from the Developer Tools page. Right-click the "Maxar Ard Postman Collection" link, download the file, then import it into your Postman client.

July 23, 2021

Update	More info	Resources
Account administration API	Account admins can manage users, get usage data, list orders for their account, and register Azure Blob or Google Cloud Storage credentials.	Account Administration Guide
New imagery datasets	Worldview-03 VNIR and worldview-04 can now be selected and ordered. Worldview-3 SWIR is not available.	See datasets on the About ARD page.
Support for Azure or Google cloud platforms	ARD orders can now be delivered to an Azure Blob Storage or Google Cloud Storage location. Credentials for these platforms can be registered in with the ARD credentials service (admins only) or submitted with an order request.	Register credentials (admins only)
Usage API	Get usage and cost data for your account (admins) or yourself with the Usage API. New usage data is also displayed in the select and order response.	Usage Guide
AOI size requirement reduced	The minimum size requirement for an AOI was reduced from 25 sq km to 1 sq km.	AOI Guidelines
List orders for an account	Admins can now list orders for their account.	Account Administration Guide
List your orders	You can now list the orders you've placed and view data about them.	Ordering Guide

Download the new Postman Collection

Update to the latest version of the max-ard SDK

SDK Release notes and changelog

SDK News

Versions 1.7.4

Many dependencies were getting stale leaving users without some nice new functionality, for example Computed Field decorators in Pydantic. This patch release catches the dependencies up. No updates to the public API were made.

Versions 1.7.1 - 1.7.3

Bug fixes in Usage, Orders, and ARDCollections.

Version 1.7.0

This release took the Azure work further. There were two really annoying problems that you could run into trying to use ARD data in Azure.

The first was that GDAL and adlfs use slightly different names for configuration envvars, so now when you initialize and Azure ARDCollection, the SDK tries to sync up the different equivaent credentials so you don't have to assign the same value to multiple envvars.

Next was that GDAL doesn't know how to parse all the valid configurations of an Azure ConnectionString. An issue has been filed and a fix already coded up, but in the meantime the SDK will look to see if you're trying to use a connection string that GDAL doesn't recognize, and if so it intervenes and maps the contents of the connection string to new GDAL options.

Version 1.6.0

Tasking is coming to ARD - this release just adds tasking-related categories to the usage object models so they're ready for when those fields start getting returns. Tasking functionality will be added soon but is still getting some final design work.

Version 1.5.5

Tweaks related to Azure filesystems for ARD data collections. File paths with az:// now work without having to set other mysterious options, and a bug related to opening raster and vector assets stored in Azure was fixed. Thanks to Geoneon for help troubleshooting.

Version 1.5.4

Quick fix regarding Credentials reprs. If the short description was missing the repr would throw an exception. Also changed it so if there is no short description, the repr doesn't show an empty set of parentheses where a truncated short description would normally display. Not a huge change, but we like classy reprs over here.

Version 1.5.3

Some more bug fixes in this release related to opening MS and PAN assets using magic accessors, and working with credentials. A troubling namespace collision between the JWT and PyJWT packages that would occasionally wreak havoc has been eliminated by removing the dependency altogether. We have been experiencing some stability problems with Shapely 1.8.5 in our Windows CI testing so we've pinned a maximum version of 1.8.4 for Windows only for the time being.

Version 1.5.2

This version fixes a minor and unnoticed bug in the CLI, and primarily marks the transition from hosting our own packages at packages.ard.maxar.com to hosting them at PyPI. This means users can simply pip install max_ard from this point onwards.

Version 1.5.1

The QLR exporter assumed that visual tiles were RGB, but with the addition of Worldview 1 imagery a visual tile can be either RGB or greyscale. This update switches to a single band renderer for Worldview 1 layers.

Version 1.5.0

This version adds some minor updates for ARD V5 functionality, and updates the dependency on Click to the latest version 8 release of that package. No breaking changes from Click version 7 to version 8 affected this package however. Users should update to this version of the SDK by July 12th.

Version 1.4.1

Bugfixes for loading orders and pagination of objects

Version 1.4.0

This version adds functionality for new ARD V4 features. You can create and manage monitoring alerts that watch for new imagery. There are also several new tools exposing the Metadata API for faster search functionality. This version also adds initial features to read pixels from acquisitions across tiles in the same UTM zone. The "seamless" reader also tries to color balance the source pixels since ARD tiles are image-balanced at the tile level and neighboring tiles can be visually different in some situations.

Version 1.3.2

When ordering to Google Cloud Storage using a stored credentials ID, a KeyError would be raised. This was fixed so that stored credentials IDs work correctly.

Version 1.3.1

API requests have improved handling for timeouts and retry behavior. Some endpoint requests (namely submitting Selects and dry-running Orders) can take up to 30 seconds to respond. The SDK will wait up to 35 seconds for these to complete before retrying 3 times. This should also keep the SDK from hanging on Lambda cold-start timeouts.

Geometry inputs for things like AOIs runs through a function that examines the input and converts the geometry information to a format acceptable to the API. This version fixes errors in parsing GeoJSON Feature Collections when they are passed as strings.

Version 1.3.0

Order objects now can be initialized for Google Cloud and Azure storage locations instead of requiring multiple steps to configure the storage location.

Support for the Credentials API has also been added to the SDK to make working with GCS and Azure easier.

Version 1.2.1

Vector assets got an adjustment on their return value to make more sense.

In ARD V2, an empty mask GeoPackage (GPKG) file actually stored a single feature - an empty MultiPolygon. This was confusing, so now in ARD V3 empty mask GPKG files will have no features in them.

In the SDK, V3 vector asset data will now be represented as follows: If there is a single feature, you will get a single Shapely object. If there are multiple features, you will get a GeometryCollection of the features. If there are no features, you will get an empty GeometryCollection instead of an empty MultiPolygon.

If you are accessing older polygon AOIs, an "empty" mask will return an empty MultiPolygon. Empty GeometryCollections and MultiPolygons behave the same in use, other than the former is a better representation of an empty feature.

Version 1.2.0

The release of ARD V.3 brings new data masks to the ARD deliverables. The SDK dynamically accesses assets such as masks using the STAC Item so previous versions of the SDK can access the V3 masks. However, the QGIS export functionality in the CLI in older versions doesn't know what masks to add, and how to style them, so this version primarily updates the CLI to export updated QGIS layers for the V3 masks. We also added a --bba option to running Selects in the CLI that automatically sets the filters to match BBA requirements.

Version 1.1.0

This version adds functionality with many of the additions useful for automation. Ordering in the CLI got some new options that are useful for batch scripting. The SDK also gained a function to make it easier to generate polygons AOIs that fulfil the minimum area requirement from a variety of inputs.

The development team also put extra effort into testing resources and as a result many small but yet undiscovered bugs were fixed. The CLI tools both look better with intuitive colors and work better by sending the correct outputs to stdout and stderr.

Version 1.0.1

The first major release mostly fixes minor bugs, cleans up the CLI UI, and features updates to handle new extend usage information from the API. Most changes are behind the scenes with major upgrades to the testing and deployment code.

Usage objects

Usage information is now stored in Pydantic models. Usage now includes area and dollar cost, account limits, and account balance. Area and dollar usages also include an estimate flag to distinguish whether the usage is estimated (in a Select, or an order still in process) or actual usage (a completed order).

More Select output formats

max-ard select describe now can export to Shapefile, kml, and kmz. The existing method of piping the output to a file using > has been improved to now use the --dest option to specify the output file. The export format is inferred from the file extension

Notes and Warnings

Version 1.0.1 requires maxar-canvas-grid >= 1.0.2. This version improves tile handling around UTM zone boundaries.

Older versions of max-ard can handle updated usage responses from the API in the SDK, but the CLI command max-ard select describe with no format options will error. To use this specific command you must update to the current version.

Version 0.0.6

The 0.0.6 release brings some new features:

Select.wait_for_success()

No need to write a sleep loop to poll the select API, this method will poll for you.

SelectResult objects

These were snuck in to 0.0.5, but weren't publicized. SelectResults give you more access to selection results should you want to dig deeper. SelectResults and ARDCollections work similarly.

Window Readers and Writers

Point an ARDCollection at some data, and you can read and write out windows of data using only input geometries. All the spatial intersections are done for you! See the data_access notebook and documentation.

Notes and Warning

Recent changes to the SDK and ARD outputs:

max_ard requires `maxar_canvas_grid >= 0.0.12

If you are upgrading max_ard, you can also upgrade maxar_canvas_grid in one step:

pip install --upgrade max_ard maxar_canvas_grid --extra-index-url https://packages.ard.maxar.com/

Asset Names

In ARDTile, the cloud mask and data mask were called clouds and extent. There was also a nodata attribute that is the spatial difference of the tile's grid cell and extent.

Starting with this version, ARD data masks and other assets should be accessed by their names in the STAC Item assets field. This means that currently the correct ARDTile.asset_paths are:

• 'item'
• 'visual'
• 'pan'
• 'ms'
• 'cloud-mask'
• 'data-mask'

The previous path names of clouds and extent will continue to work but will be deprecated in the future.

All ARD assets are now available as keywords. For assets names with a dash in them, substitute an underscore:

• ARDTile.item
• ARDTile.visual
• ARDTile.pan
• ARDTile.ms
• ARDTile.data_mask
• ARDTile.no_data_mask
• ARDTile.cloud_mask
• ARDTile.no_cloud_mask

The previous attribute names of clouds and extent will continue to work but will be deprecated in the future. The nodata attribute will also be deprecated, and is replaced with no_data_mask. A similar attribute is provided for the cloud mask: no_cloud_mask will return the geometry of areas not covered by clouds.

API Updates

Starting 4/12/2021:

STAC Updates

The ARD image pipeline now creates "self-contained" STAC files for portability. The SDK also will use more STAC data fields to define the Python objects like ARDTile

GeoPackage layer names

The data mask GeoPackage files previously used dashes which were incompatible with some GIS software. The layer names have been changed to use underscores. SDK version 0.0.5 used hard-coded layer names with dashes to generate QGIS Layer previews and will create broken layers if used with the updated files. The current version 0.0.6 looks up the layer name and is backward compatible with older data.

Changelog

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.7.4] - 2023-10-12

Changed

• Dependencies were caught up, no changes to public API.

[1.7.3] - 2023-5-30

Fixed

• "limit" parameters in listing things (mostly Orders) was getting ignored, including a supposed default of 10 items. Limits are now working but since the default of 10 was ignored the behavior will stay the same and the docs will be updated to remove mention of of the default value.

[1.7.2] - 2023-2-8

Fixed

• Fixed ARDCollections to work when tiles are ordered without cloud masks.

[1.7.1] - 2023-2-2

Fixed

• Updated usage related objects to handle a change in the administrative API that caused model validation errors.

[1.7.0] - 2022-12-9

Changed

• Order objects can take Select Results for the "acquisitions" keyword
• Made Azure permissions easier to work with

[1.6.0] - 2022-12-2

Changed

• Usage related object models updated to hold tasking categories in preparation for tasking

[1.5.5] - 2022-11-29

Fixed

• ARDCollections in Azure don't need anon=True to work
• Fixed bug causing "File not found" errors when opening raster and vector assets in Azure
• unpinned maximum version dependencies for Shapely for Windows builds to more mystery DLL errors

[1.5.4] - 2022-10-14

Fixed

• Repr for credentials would error if no short description existed

Changed

• Credentials repr doesn't show empty () for the short description if there isn't one

[1.5.3] - 2022-10-13

Fixed

• Credentials interactions using wrong API URL
• Magic accessors for the PAN and MS assets

Changed

• removed PyJWT dependency due to namespace collision
• pinned Fiona to 1.8.4 for Windows builds due to mystery DLL errors

[1.5.2] - 2022-07-29

Fixed

• max-ard token --reset now works correctly

Changed

• Package is now available in Pypi

[1.5.1] - 2022-05-13

Fixed

• Use single band renderer for WV01 layers in QLRs

[1.5.0] - 2022-05-12

Added

• More metadata search functions
• ARD API V5 support

Changed

• Updated requirements to use the current version (8) of the Click Python package.

[1.4.1] - 2022-03-17

Added

• ARD V5 support

Changed

• Click dependency updated to latest version (8)

[1.4.1] - 2022-03-17

Fixed

• Pagination of API objects
• Loading of Order objects that don't have a status message.

[1.4.0] - 2022-03-02

Added

• Functionality for managing monitors
• Metadata search tools for faster selection
• Acquisition level "seamless" readers that can read across tiles

[1.3.2] - 2021-12-15

Fixed

• Fix KeyError encountered when providing a credentials ID in a GCS Order Configuration

[1.3.1] - 2021-12-9

Fixed

• Better parsing of string geometry inputs
• Add retry/timeout handling to API requests

[1.3.0] - 2021-11-18

Added

• Support for GCS and Azure storage in Order initialization
• Support for using the Credentials API to store GCS and Azure storage credentials

[1.2.1] - 2021-10-15

Changed

• Empty vector assets return empty GeometryCollections instead of empty MultiPolygons.

[1.2.0] - 2021-10-14

Changed

• QGIS layer export now includes V3 masks. To reduce layer size, empty masks are skipped.

Added

• max-ard select submit now has a --bba option that will filter out images that do not meet BBA requirements.

Fixed

• Inverted mask accessors use data limits instead of cell

[1.1.1] - 2021-09-16

Changed

• Some internal refactoring for future work, no changes to public API

Fixed

• Random segmentation faults due to GDAL conflicts fixed by phasing out osgeo.gdal use.

[1.1.0] - 2021-09-07

Added

SDK:

• Helper function to create bounding boxes that cover input geometries and meet the minimum area requirements
• Helper function that can convert almost anything geometric or spatial into Shapely objects
• now publishing Autodocs for the SDK

CLI:

• Order and select commands can take file paths for --intersects parameters and read most geospatial formats
• Select and order commands can be chained together using pipe operator and --select-id listen argument in order command
• order commands can take a --yes option to skip confirmation dialogs
• max-ard usage command to see account or user usage
• colors and cleaner output, with many commands gaining --verbose modes so you can get detailed info if you needed
• better error handling and messages that send to stderr

Fixed

• bug preventing max_ard order submit from running
• allow orders to write to a location that is only a bucket name (no prefix)
• All CLI options use dashes now for consistency
• Gave Usage objects dict-like access to ARD V1 API field names
• A new approach to handling refresh tokens should fix "token error" errors

[1.0.2] - 2021-08-02

Fixed

• Bug in Worldview 4 ID parsing that broke WV-04 ARDTile objects
• Gave Usage objects dict-like access to ARD V1 API keys

[1.0.1] - 2021-07-21

Fixed

• change Fiona import to conditional in shapefile export

Added

• More export formats for Selects: kml, kmz, shp
• max-ard token --reset resets the auth token

Fixed

• Tokens refresh when refresh token expires

Changed

• New Usage objects with more information
• Usage objects are Pydantic models
• max-ard select describe now takes a --dest option for file destination
• no more piping to a file
• file format is deduced from file extension

[1.0.0] - PULLED

[0.0.6] - 2021-04-04

Added

• Select.wait_for_success() polls the API for you
• windowed readers and writers: ARDCollection.read_windows and .write_windows
• SelectResults have matching structure to ARDCollections
• direct 'getters' for stacks, acquisitions, and tiles

Fixed

• QLR export will look up layer names to handle data mask layer name changes in the API

Changed

• QLR exports have better organization and include tile metadata
• ARDTiles now have attributes based on STAC asset names, i.e. .clouds is now .cloud-mask
• ARDTile.stac_item now holds the full STAC data for the tile
• ARDTile.asset_paths and ARDTile.open_asset also reflect STAC asset names
• old asset "names" like .clouds are still functional but will be deprecated in the future
• requires maxar_canvas_grid>=0.0.12
• to upgrade run pip install --upgrade max_ard maxar_canvas_grid --extra-index-url https://packages.ard.maxar.com/

[0.0.5] - 2021-03-10

Added

• SelectResults objects
• AWS role option
• Image age categories

Fixed

• Password entry is hidden
• IDs to Select don't get lost
• Rogue keyword option --acq_id in max-ard select submit changed to --acq-id

[0.0.4] - 2021-02-04

Added

• QGIS layer output

[0.0.3] - 2021-01-28

Added

• usage output

Changed

• overhaul of installation
• split to base and 'full' installation options
• switch to /v1 API

[0.0.2] - 2021-01-21

Changed

• using prod hostname for API
• revamped install

[0.0.1] - 2021-01-15

Added

• First release package