From ce26dd65e8707c27f7aff6a93ff90f5bef46a449 Mon Sep 17 00:00:00 2001 From: Saad Rayees <112953407+saad-up42@users.noreply.github.com> Date: Tue, 31 Oct 2023 14:07:31 +0100 Subject: [PATCH] DOC-731: Convert an SDK reference page to markdown: Catalog (#479) * Add construct_search_parameters * Update function list in overview card * Add search() * Fix function list order * Update `download_quicklooks()` * Update construct_order_parameters * Update plot_coverage() * Remove dot from overview card functions * Format code snippets * Add visualization instruction to overview * Remove deprecated `sortby` argument * Adjust language * Fix terms and capitalization * Fix small errors in job-reference.md * Change None -> none in catalogbase-reference.md * Change List -> list in tasking-reference.md * Include viz install instruction job-reference.md * Update functionality overview listing * Update visualization instruction * Searches -> Scenes * Update `construct_search_parameters()` * Update `search()` * Update `download_quicklooks()` * Update `construct_order_parameters()` * Update `estimate_order()` * Update `estimate_order()` * Update image_id in catalogbase-reference.md * Update `plot_coverage()` * describe filepaths as plural * Update `map_quicklooks()` * Add viz size to job-reference.md * Update titles description * Format python examples * Update geometry description * Add search() link * pre-signed -> signed * Update docs/reference/job-reference.md Co-authored-by: Daria Lutchenko <102282963+dustgalactic@users.noreply.github.com> * remove repeated line * add comma * Remove double sentence * Add as_dataframe back * pre-signed -> signed * Update geometry calls + syntax changes * kwargs -> **kwargs * Update docs/reference/job-reference.md * Apply suggestions from Naman's code review Co-authored-by: Naman Jain --------- Co-authored-by: Daria Lutchenko <102282963+dustgalactic@users.noreply.github.com> Co-authored-by: Naman Jain --- CHANGELOG.md | 2 +- docs/catalog.md | 1 - docs/reference/asset-reference.md | 2 +- docs/reference/catalog-reference.md | 362 +++++++++++++++++++++++- docs/reference/catalogbase-reference.md | 2 +- docs/reference/job-reference.md | 24 +- docs/reference/tasking-reference.md | 16 +- docs/structure.md | 23 +- docs/theme_override_home/main.html | 2 +- examples/asset/asset-example.ipynb | 4 +- up42/asset.py | 4 +- 11 files changed, 404 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bf0812030..e4e08ffd1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,7 +36,7 @@ For more information, see [UP42 Python package description](https://pypi.org/pro A new function added to the [Asset class](https://sdk.up42.com/reference/asset-reference): -- `get_stac_asset_url` generates a pre-signed URL that allows you to download a STAC asset from storage without authentication. +- `get_stac_asset_url` generates a signed URL that allows you to download a STAC asset from storage without authentication. ## 0.32.0 diff --git a/docs/catalog.md b/docs/catalog.md index 33eaff68b..1725d94c3 100644 --- a/docs/catalog.md +++ b/docs/catalog.md @@ -64,7 +64,6 @@ search_parameters = catalog.construct_search_parameters( start_date="2022-06-01", end_date="2022-12-31", max_cloudcover=20, - sortby="cloudCoverage", limit=10, ) diff --git a/docs/reference/asset-reference.md b/docs/reference/asset-reference.md index 550963220..a5b0ea769 100644 --- a/docs/reference/asset-reference.md +++ b/docs/reference/asset-reference.md @@ -147,7 +147,7 @@ asset.download_stac_asset( ### get_stac_asset_url() -The `get_stac_asset_url()` function returns a pre-signed download URL for a STAC asset. +The `get_stac_asset_url()` function returns a signed download URL for a STAC asset. The generated URL can be used for up to 5 minutes to download the asset without authentication. ```python diff --git a/docs/reference/catalog-reference.md b/docs/reference/catalog-reference.md index 39eb3e973..e11b64fff 100644 --- a/docs/reference/catalog-reference.md +++ b/docs/reference/catalog-reference.md @@ -1,6 +1,360 @@ # Catalog -::: up42.catalog.Catalog - selection: - inherited_members: True - members: {{ funcs_catalog }} +The Catalog class enables access to the UP42 [catalog functionality](../../catalog/). + +```python +catalog = up42.initialize_catalog() +``` + +This class also inherits functions from the [CatalogBase](catalogbase-reference.md) class. + +## Scenes + +### construct_search_parameters() + +The `construct_search_parameters()` function allows you to fill out search parameters when searching for catalog imagery. + +```python +construct_search_parameters( + geometry, + collections, + start_date, + end_date, + usage_type, + limit, + max_cloud_cover, +) +``` + +The returned format is `dict`. + +
Arguments
+ +| Argument | Overview | +| ---------------- | ----------------------------------------------------------------------------------------------------------------- | +| `geometry` | **Union[FeatureCollection, Feature, dict, list, GeoDataFrame, Polygon] / required**
The geometry of interest. | +| `collections` | **list[str] / required**
The geospatial collection names. | +| `start_date` | **str**
The start date of the search period in the `YYYY-MM-DD` format. The default value is `2020-01-01`. | +| `end_date` | **str**
The end date of the search period in the `YYYY-MM-DD` format. The default value is `2020-01-30`. | +| `limit` | **int**
The number of search results to show. Use a value from 1 to 500. The default value is `10`. | +| `max_cloudcover` | **int**
The maximum cloud coverage, in percentage. | + +
Example
+ +```python +catalog.construct_search_parameters( + geometry=up42.get_example_aoi(location="Berlin"), + collections=["phr"], + start_date="2022-06-01", + end_date="2022-12-31", + limit=20, + max_cloudcover=25, +) +``` + +### search() + +The `search()` function returns the scenes matching the search parameters. + +```python +search( + search_parameters, + as_dataframe, +) +``` + +The returned format is `Union[GeoDataFrame, dict]`. + +
Arguments
+ +| Argument | Overview | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `search_parameters` | **dict / required**
The catalog search parameters. | +| `as_dataframe` | **bool**
Determines how to return search results:
The default value is `True`. | + +
Example
+ +```python +catalog.search( + search_parameters=catalog.construct_search_parameters( + geometry=up42.get_example_aoi(), + collections=["phr"], + start_date="2022-06-01", + end_date="2022-12-31", + limit=20, + max_cloudcover=25, + ), + as_dataframe=False, +) +``` + +### download_quicklooks() + +The `download_quicklooks()` function allows you to download low-resolution previews of scenes returned in search results. +Visualize quicklooks with [`map_quicklooks()`](#map_quicklooks) or [`plot_quicklooks()`](#plot_quicklooks). + +```python +download_quicklooks( + image_ids, + collection, + output_directory, +) +``` + +The returned format is `list[str]`. + +
Arguments
+ +| Argument | Overview | +| ------------------ | ----------------------------------------------------------------------------------------------------- | +| `image_ids` | **list[str] / required**
The scene IDs. | +| `collection` | **str / required**
The geospatial collection name. | +| `output_directory` | **Union[str, Path, none]**
The file output directory. The default value is the current directory. | + +
Example
+ +```python +catalog.download_quicklooks( + image_ids=["a4c9e729-1b62-43be-82e4-4e02c31963dd"], + collection="phr", + output_directory="/Users/max.mustermann/Desktop/", +) +``` + +## Orders + +### construct_order_parameters() + +The `construct_order_parameters()` function allows you to fill out an order form for a new catalog order. + +```python +construct_order_parameters( + data_product_id, + image_id, + aoi, + tags, +) +``` + +The returned format is `dict`. + +
Arguments
+ +| Argument | Overview | +| ----------------- | ------------------------------------------------------------------------------------------- | +| `data_product_id` | **str / required**
The data product ID. | +| `image_id` | **str / required**
The scene ID. | +| `aoi` | **Union[dict, Feature, FeatureCollection, list, GeoDataFrame, Polygon]**
The order AOI. | +| `tags` | **list[str]**
A list of tags that categorize the order. | + +
Example
+ +```python +catalog.construct_order_parameters( + data_product_id="647780db-5a06-4b61-b525-577a8b68bb54", + image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd", + aoi="/Users/max.mustermann/Desktop/aoi.geojson", + tags=["project-7", "optical"], +) +``` + +### estimate_order() + +The `estimate_order()` function returns the cost estimate for a catalog order. + +```python +estimate_order(order_parameters) +``` + +The returned format is `int`. + +
Arguments
+ +| Argument | Overview | +| ------------------ | ----------------------------------------------------------------------------- | +| `order_parameters` | **Union[dict, none] / required**
Parameters with which to place an order. | + +
Example
+ +```python +catalog.estimate_order( + order_parameters=catalog.construct_order_parameters( + data_product_id="4f1b2f62-98df-4c74-81f4-5dce45deee99", + image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd", + aoi="/Users/max.mustermann/Desktop/aoi.geojson", + ), +) +``` + +## Visualization + +To use the visualization functionalities, [install](../../installation/) the advanced up42-py package. + +### plot_coverage() + +The `plot_coverage()` function allows you to visualize the coverage of scenes matching the search parameters. +Use together with [`search()`](#search). + +```python +plot_coverage( + scenes, + aoi, + legend_column, + figsize, +) +``` + +
Arguments
+ +| Argument | Overview | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `scenes` | **GeoDataFrame / required**
The scenes matching the search parameters. | +| `aoi` | **GeoDataFrame**
The order AOI. | +| `legend_column` | **str**
The column name of `scenes` to arrange legend entries by ascending order. The default value is `sceneId`. | +| `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(12, 16)`. | + +
Example
+ +```python +# Construct search parameters + +search_parameters = catalog.construct_search_parameters( + geometry=up42.get_example_aoi(location="Berlin"), + collections=["phr"], + start_date="2022-06-01", + end_date="2022-12-31", + limit=5, + max_cloudcover=25, +) + +# Search and plot scene coverage + +catalog.plot_coverage( + scenes=catalog.search(search_parameters), + geometry=up42.get_example_aoi(location="Berlin"), + legend_column="cloudCoverage", + figsize=(14, 18), +) +``` + +### map_quicklooks() + +The `map_quicklooks()` function allows you to visualize downloaded quicklooks on a Folium map. +Use together with [`search()`](#search) and [`download_quicklooks()`](#download_quicklooks). + +```python +map_quicklooks( + scenes, + aoi, + show_images, + show_features, + filepaths, + name_column, + save_html, +) +``` + +The returned format is `folium.Map`. + +
Arguments
+ +| Argument | Overview | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `scenes` | **GeoDataFrame / required**
The scenes matching the search parameters. | +| `aoi` | **GeoDataFrame**
The order AOI. | +| `show_images` | **bool**
Determines whether to visualize quicklooks: The default value is `True`. | +| `show_features` | **bool**
Determines whether to visualize the geometry:
The default value is `False`. | +| `filepaths` | **list[Union[str, Path]]**
The file paths. By default, the last downloaded quicklooks will be used. | +| `name_column` | **str**
The column name of `scenes` that provides the feature name. The default value is `id`. | +| `save_html` | **Path**
Use to specify a path to save the map as an HTML file. | + +
Example
+ +```python +# Conduct search + +scenes = catalog.search( + search_parameters=catalog.construct_search_parameters( + geometry=up42.get_example_aoi(location="Berlin"), + collections=["phr"], + limit=2, + ), +) + +# Download quicklooks + +catalog.download_quicklooks( + image_ids=list(scenes.id), + collection="phr", + output_directory="/Users/max.mustermann/Desktop/", +) + +# Map quicklooks + +catalog.map_quicklooks( + scenes=scenes, + aoi="/Users/max.mustermann/Desktop/aoi.geojson", + show_images=True, + show_features=True, + filepaths=[ + "/Users/max.mustermann/Desktop/quicklook_d0a7e38a-0087-48c9-b3f7-8b422388e101.jpg", + "/Users/max.mustermann/Desktop/quicklook_b7f2c82f-641d-4119-baff-7001a5ceb4f6.jpg", + ], + name_column="cloudCoverage", + save_html="/Users/max.mustermann/Desktop/", +) +``` + +### plot_quicklooks() + +The `plot_quicklooks()` function allows you to visualize downloaded quicklooks. +Use together with [`search()`](#search) and [`download_quicklooks()`](#download_quicklooks). + +```python +plot_quicklooks( + figsize, + filepaths, + titles +) +``` + +
Arguments
+ +| Argument | Overview | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(8, 8)`. | +| `filepaths` | **Union[list[Union[str, Path]], dict, none]**
The file paths. By default, the last downloaded quicklooks will be used. | +| `titles` | **list[str]**
The titles for the subplots. | + +
Example
+ +```python +# Conduct search + +scenes = catalog.search( + search_parameters=catalog.construct_search_parameters( + geometry=up42.get_example_aoi(location="Berlin"), + collections=["phr"], + limit=2, + ), +) + +# Download quicklooks + +catalog.download_quicklooks( + image_ids=list(scenes.id), + collection="phr", + output_directory="/Users/max.mustermann/Desktop/", +) + +# Map quicklooks + +catalog.plot_quicklooks( + figsize=(10, 10), + filepaths=[ + "/Users/max.mustermann/Desktop/quicklook_d0a7e38a-0087-48c9-b3f7-8b422388e101.jpg", + "/Users/max.mustermann/Desktop/quicklook_b7f2c82f-641d-4119-baff-7001a5ceb4f6.jpg", + ], + titles=["Scene 1", "Scene 2"], +) +``` diff --git a/docs/reference/catalogbase-reference.md b/docs/reference/catalogbase-reference.md index 964bd717c..0fb4384c2 100644 --- a/docs/reference/catalogbase-reference.md +++ b/docs/reference/catalogbase-reference.md @@ -143,7 +143,7 @@ tasking.place_order( catalog_order_parameters = catalog.construct_order_parameters( data_product_id="4f1b2f62-98df-4c74-81f4-5dce45deee99", - image_id=search_results.iloc[0]["id"], # To place a catalog order, first use catalog.search() and select a scene + image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd", aoi=geometry, ) diff --git a/docs/reference/job-reference.md b/docs/reference/job-reference.md index e56902941..91cc8d24e 100644 --- a/docs/reference/job-reference.md +++ b/docs/reference/job-reference.md @@ -292,6 +292,8 @@ job.get_jobtasks_results_json() ## Visualization +To use the visualization functionalities, [install](../../installation/) the advanced up42-py package. + ### map_results() The `map_results()` function allows you to visualize job results on a Folium map. Use together with [`download_results()`](#download_results). @@ -342,24 +344,22 @@ plot_results( figsize, bands, titles, - filpaths, + filepaths, plot_file_format, - kwargs, + **kwargs, ) ``` -The returned format is `type`. -
Arguments
-| Argument | Overview | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `figsize` | **tuple[int, int]**
The size of the visualization. The first number is length, the second one is width. The default value is `(14, 8)`. | -| `bands` | **list[int]**
A list of image bands to plot and their order. | -| `titles` | **list[str]**
Titles for the subplots. | -| `filpaths` | **Union[list[Union[str, Path]], dict, none]**
The file path. By default, the downloaded results will be used. | -| `plot_file_format` | **list[str]**
Accepted file formats. The default value is `[".tif"]`. | -| `kwargs` | Any additional arguments of [rasterio.plot.show](https://rasterio.readthedocs.io/en/latest/api/rasterio.plot.html#rasterio.plot.show). | +| Argument | Overview | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(14, 8)`. | +| `bands` | **list[int]**
A list of image bands to plot and their order. | +| `titles` | **list[str]**
The titles for the subplots. | +| `filepaths` | **Union[list[Union[str, Path]], dict, none]**
The file paths. By default, the last downloaded results will be used. | +| `plot_file_format` | **list[str]**
Accepted file formats. The default value is `[".tif"]`. | +| `**kwargs` | Any additional arguments of [rasterio.plot.show](https://rasterio.readthedocs.io/en/latest/api/rasterio.plot.html#rasterio.plot.show). |
Example
diff --git a/docs/reference/tasking-reference.md b/docs/reference/tasking-reference.md index eaab6b4a9..56a3c6e05 100644 --- a/docs/reference/tasking-reference.md +++ b/docs/reference/tasking-reference.md @@ -29,14 +29,14 @@ The returned format is `dict`.
Arguments
-| Argument | Overview | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `data_product_id` | **str / required**
The data product ID. | -| `name` | **str / required**
The tasking order name. | -| `acquisition_start` | **Union[str, datetime] / required**
The start date of the acquisition period in the `YYYY-MM-DD` format. | -| `acquisition_end` | **Union[str, datetime] / required**
The end date of the acquisition period in the `YYYY-MM-DD` format. | -| `geometry` | **Union[FeatureCollection, Feature, dict, list, GeoDataFrame, Polygon, Point] / required**
The geometry of the area to be captured. It can be a POI or an AOI depending on the [collection](https://docs.up42.com/data/tasking/limitations). | -| `tags` | **List[str]**
A list of tags that categorize the order. | +| Argument | Overview | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data_product_id` | **str / required**
The data product ID. | +| `name` | **str / required**
The tasking order name. | +| `acquisition_start` | **Union[str, datetime] / required**
The start date of the acquisition period in the `YYYY-MM-DD` format. | +| `acquisition_end` | **Union[str, datetime] / required**
The end date of the acquisition period in the `YYYY-MM-DD` format. | +| `geometry` | **Union[FeatureCollection, Feature, dict, list, GeoDataFrame, Polygon, Point] / required**
The geometry of interest. It can be a POI or an AOI depending on the [collection](https://docs.up42.com/data/tasking/limitations). | +| `tags` | **list[str]**
A list of tags that categorize the order. |
Example
diff --git a/docs/structure.md b/docs/structure.md index 8441c792e..e5b3baf87 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -57,13 +57,26 @@ === "Catalog" - {{ docstring_catalog }} -
- Available functions, see also [**Catalog reference**](catalog-reference.md): - {{ format_funcs(funcs_catalog) }} -
+ The Catalog class enables access to the UP42 [catalog functionality](../catalog/). + + ```python + catalog = up42.initialize_catalog() + ``` + This class also inherits functions from the [CatalogBase](catalogbase-reference.md) class. + See available attributes and functions on the [Catalog](catalog-reference.md) reference page: + + === "CatalogBase" The CatalogBase class is inherited by the [Tasking](tasking-reference.md) and [Catalog](catalog-reference.md) classes. diff --git a/docs/theme_override_home/main.html b/docs/theme_override_home/main.html index f072be1e2..e4eb67f95 100644 --- a/docs/theme_override_home/main.html +++ b/docs/theme_override_home/main.html @@ -20,7 +20,7 @@ {% block announce %} - New in 0.33.0: Generating pre-signed download URLs for STAC assets is supported + New in 0.33.0: Generating signed download URLs for STAC assets is supported {% endblock %} diff --git a/examples/asset/asset-example.ipynb b/examples/asset/asset-example.ipynb index cfe6e5000..be50553f1 100644 --- a/examples/asset/asset-example.ipynb +++ b/examples/asset/asset-example.ipynb @@ -3144,14 +3144,14 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Step 6. Get s STAC asset download URL to share" + "## Step 6. Get a STAC asset download URL to share" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Get a pre-signed URL to download the chosen STAC asset.\n", + "Get a signed URL to download the chosen STAC asset.\n", "The generated URL can be used for up to 5 minutes to download the asset without authentication." ] }, diff --git a/up42/asset.py b/up42/asset.py index a2ca5ff55..4e58c92a0 100644 --- a/up42/asset.py +++ b/up42/asset.py @@ -124,12 +124,12 @@ def _get_download_url(self, stac_asset_id: Optional[str] = None, request_type: s def get_stac_asset_url(self, stac_asset: pystac.Asset): """ - Returns the pre-signed URL for the STAC Asset. + Returns the signed URL for the STAC Asset. Args: stac_asset: pystac Asset object. Returns: - Pre-signed URL for the STAC Asset. + Signed URL for the STAC Asset. """ stac_asset_id = stac_asset.href.split("/")[-1] # so we can utilize all functionalities of Auth class