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.
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.
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.
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.
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
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.
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.
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.
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.
Bugfixes for loading orders and pagination of objects
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.
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.
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.
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.
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.
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.
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
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 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.
The 0.0.6 release brings some new features:
No need to write a
sleep loop to poll the select API, this method will poll for you.
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.
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/
ARDTile, the cloud mask and data mask were called
extent. There was also a
nodata attribute that is the spatial difference of the tile's grid cell and
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
The previous path names of
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:
The previous attribute names of
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.
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
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.