max-ard
CLI¶
Select Tools¶
The ARD Select service allows you to search and filter acquisitions. It provides results in several different file formats.
max-ard select
¶
The base command for Select tools. Run this by itself to see all of the Select subcommands.
max-ard select submit
¶
Usage: max-ard select submit [OPTIONS]
Submit a select request to search for ARD imagery and estimate usage.
Options:
-
--acq-id
Limit the Select to these acquisition IDs. Can be provided multiple times. -
--datetime
Limit the Select to a given date or date range. -
--intersects
Search for tiles that intersect this geometry. Can be WKT, GeoJSON or a path to a file, see below. -
--bbox
likeintersects
, but limits search to a WGS84 bounding box in format--bbox XMIN YMIN XMAX YMAX
-
--stack-depth
Limits the number of tiles returned. When searching the tiles are ranked and the best scoring tiles will be used to return this number of tiles. Default is 5 tiles. -
--filter
Add a filter statement in the form of--filter <property> <operator> <value>
. See the Select API documentation for a list of properties and operators. -
--image-age
Limit imagery to an image age category ('fresh', 'standard', or 'training'). Can be used more than once if age ranges are contiguous. -
--min-cloud-free
Shortcut to filter the minimum percentage of cloud-free cover. Equivalent to filteringaoi:cloud_free_percentage
greater than or equal to the supplied value. -
--min-data
Shortcut to filter the minimum percentage of valid data pixels. Equivalent to filtering onaoi:data_percentage
greater than or equal to the supplied value. -
--bba
Only select images that can be used with Block Bundle Adjustment. -
--verbose
,-v
Output more information about the select, such as the raw payload. Useful for troubleshooting.
At a minimum, you must supply at least one of the following:
- a spatial filter using
intersects
orbbox
- specific acquisition ID or IDs using
--acq-id
at least once
% max-ard select submit \
--bbox -104.9 39.7 -104.5 39.9 \
--filter platform eq worldview-02 \
--filter aoi:cloud_free_percentage gt 95
The Select service will try to compute results within 20 seconds. If it takes longer than 20 seconds the command will return a job ID that you can check for completion with max-ard select status SELECT_ID
.
Intersects Inputs¶
The --intersects
parameter can be a WKT or GeoJSON string, or a path to a WKT or GeoJSON file. If Fiona is installed, most common geospatial file formats can also be read.
Note: only POLYGON and MULTIPOLYGON geometry types are accepted. Geometries with a large number of vertices may exceed the maximum HTTP POST size. For complex AOIs, We recommend simplifying the geometry first or using the bounding box of the input and the --bbox
parameter instead.
Geometries must be submitted in WGS84 units.
max-ard select status
¶
Usage: max-ard select status SELECT_ID
Check status of a running selection query given a select ID.
States are:
- RUNNING
- SUCCEEDED
- FAILED
% max-ard select status 5568159187953882262
max-ard select describe
¶
Usage: max-ard select submit SELECT_ID [OPTIONS]
Returns information about the Select given the SELECT_ID.
Options:
--dest
Saves the output to a file path in the format specified by the file extension. Formats stac
, geojson
, and geojsonl
, kml
, kmz
, and shp
write files describing the tiles. Format html
is an interactive map browser of the results - to view the map without downloading it first, use maxard select browse SELECT_ID
.
--format
If --dest
is not provided, outputs to stdout in these formats : html
, geojsonl
, kml
, or stac
. Ignored if --dest is used.
--verbose
, -v
Outputs more information about the Select such as the request payload sent to the API. Useful for troubleshooting. Ignored if --format
or --dest
is supplied.
% max-ard select describe 5568184876815431013
getting Select ID 5568184876815431013
*******************
Request details:
{"datetime": "2020-07-01T09:00:00Z/2021-01-25T09:00:00Z", "stack_depth": 3, "query": {"platform": {"eq": "worldview-02"}, "aoi:cloud_free_percentage": {"gte": 95.0}, "aoi:data_percentage": {"gte": 75.0}}, "bbox": [-105.1, 39.7, -104.7, 39.9]}
*******************
97 tiles identified in the following 18 acquisitions:
10300100AE766C00 (2020-11-01) - 16 tiles
10300100B09E5F00 (2020-12-15) - 2 tiles
10300100B18AB600 (2021-01-05) - 2 tiles
10300100B4496100 (2020-12-31) - 2 tiles
10300100B3522C00 (2020-12-17) - 2 tiles
10300100AD73AD00 (2020-09-24) - 1 tiles
10300100B00C7500 (2020-12-31) - 16 tiles
10300100B104E700 (2020-12-09) - 14 tiles
10300100AD977C00 (2020-11-01) - 4 tiles
10300100B3366B00 (2021-01-19) - 12 tiles
10300100AFA65D00 (2020-11-12) - 5 tiles
10300100B1D7A700 (2020-12-20) - 2 tiles
10300100ADA54B00 (2020-10-16) - 4 tiles
10300100AD983700 (2020-08-01) - 4 tiles
10300100AEBA9700 (2020-10-11) - 4 tiles
10300100A99E1000 (2020-07-27) - 2 tiles
Saving the Select as a GeoJSON file named my_select.geojson
:
% max-ard select describe 5568159187953882262 --dest my_select.geojson
Piping a Select to PostGIS using ogr2ogr
:
% max-ard select describe 5568159187953882262 --format geojson | ogr2ogr -f "PostgreSQL" PG:"<connection info>" /vsistdin/
max-ard select url
¶
Usage: max-ard select url SELECT_ID [--FORMAT]
Gets links for the Select result files for a Select of SELECT_ID. If no FORMAT is supplied, returns the base URL of the Select. If a FORMAT is supplied, returns a pre-signed URL to download the result of type FORMAT (stac
, geojson
, geojsonl
, and html
)
% max-ard select url 5568159187953882262
https://ard.maxar.com/api/select/5568159187953882262
% max-ard select url 5568159187953882262 --format html
<long pre-signed url>
max-ard select browse
¶
Usage: max-ard select browse SELECT_ID
Downloads the HTML interactive viewer of the Select result SELECT ID to a temporary file and opens the map with the system web browser.
When exited the temporary file is deleted. Use max-ard select describe SELECT_ID --format html > my_map.html
to save a local copy.
An example of the HTML viewer can be found in the output examples here.
% max-ard select browse 5568159187953882262
Fetching map...
Press any key when finished