Archive Catalog Developer Tools
Below are some open source tools commonly used to search and visualize STAC APIs that we recommend considering when looking to search the Umbra Archive Catalog.
Pystac Client
Pystac-client is a library for Python that is used to search a STAC API. To install it:
pip install pystac-client
You can then use it to connect to Archive Catalog and perform a search.
import pystac_client
stac_api_url = "https://api.canopy.umbra.space/archive"
catalog = pystac_client.Client.open(stac_api_url)
time_range = "2020-01-01/2024-12-31"
# You can create a supported geometry using https://geojson.io/
intersect_geometry = None
stac_search = catalog.search(max_items=10, collections=["umbra-sar"], intersects=intersect_geometry, datetime=time_range)
items = stac_search.item_collection()
print(items[0].to_dict())
items
You can use https://geojson.io/ to create an intersect_geometry by copying over the geometry dictionary and assigning it to intersect_geometry
.
If you are using Jupyter, thumbnails from the STAC items can be displayed in the Notebook.
from IPython.display import Image
def display_item_thumbnail(item):
return Image(url=item.assets['thumbnail'].href)
display_item_thumbnail(items[0])
Leafmap
Leafmap is a Python package for searching and visualizing geospatial data with an interactive map in Jupyter. Start by installing it:
pip install leafmap
Then use it inside a Jupyter Notebook to display an interactive map:
import leafmap
search_map = leafmap.Map(zoom=4)
search_map
You can draw a box on the map to use as bounds for a STAC API search.
After drawing the box, send a search request.
if len(m.draw_features) == 1:
intersects = m.draw_features[0]['geometry']
bbox = None
print("You have drawn a Feature on Leafmap. Using your selection to perform the search.")
else:
intersects = None
bbox = m.get_bbox()
print("You have not drawn anything on the Leafmap. Using the entire bounds to perform the search.")
stac_api_url = "https://api.canopy.umbra.space/archive"
time_range = "2020-01-01/2024-12-31"
items = leafmap.stac_search(
url=stac_api_url,
max_items=10,
collections=["umbra-sar"],
datetime=time_range,
bbox=bbox,
intersects=intersects,
get_collection=True,
)
print(f"Returned {len(items)} results")
And examine the results.
# You have drawn a Feature on Leafmap. Using your selection to perform the search.
# Returned 2 results
print(items[0].to_dict())
items[0]
You can overlay the resulting images on Leafmap.
def layer_from_item(item):
thumbnail_url = item.assets['thumbnail'].href
bbox = item.bbox
bounds = ((bbox[1], bbox[0]), (bbox[3], bbox[2]))
return leafmap.ImageOverlay(
url=thumbnail_url,
bounds=bounds
)
m = leafmap.Map()
for i, item in enumerate(items):
layer = layer_from_item(item)
layer.name = str(i)
m.add_layer(layer)
center = leafmap.get_center(items[0].geometry)
m.set_center(lon=center[0], lat=center[1], zoom=12)
m
Custom Catalog
You can add the Umbra Archive Catalog as an available API to Leafmap.
catalogs = {
"Umbra Archive Catalog": "https://api.canopy.umbra.space/archive"
}
tmap = leafmap.Map(catalog_source=catalogs)
tmap
Then in the map cell, open the Discover Catalog panel and click Collections and then Items. The map will then show clickable outlines of STAC items.
Updated about 1 year ago