terrascope module¶
leafmap.terrascope
¶
Terrascope STAC API integration for leafmap.
This module provides authentication and helper functions for accessing Terrascope data services, including: - HTTP Basic Authentication for GDAL - STAC catalog search helpers - GDAL authentication for streaming COGs
Example
import leafmap.terrascope as terrascope terrascope.login() # Uses TERRASCOPE_USERNAME/PASSWORD env vars items = terrascope.search_ndvi(bbox=[5.0, 51.2, 5.1, 51.3], start="2025-05-01", end="2025-06-01") m = leafmap.Map() m.add_raster(items[0].assets["NDVI"].href, colormap="RdYlGn")
Note
Authentication uses HTTP Basic Auth via GDAL environment variables. Credentials are set in GDAL_HTTP_USERPWD for authenticated COG streaming.
cleanup_tile_servers()
¶
Kill stale localtileserver processes.
This is useful when switching between visualizations to avoid authentication errors from old tile server processes that have cached expired tokens.
Note
This uses pkill which is Unix-specific and will terminate all localtileserver processes for the current user, not just those started by this session.
create_time_layers(items, asset_key='NDVI', colormap='RdYlGn', vmin=0, vmax=250)
¶
Create tile layers for time slider visualization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
items
|
list
|
List of pystac Item objects. |
required |
asset_key
|
str
|
Asset key to use (default "NDVI"). |
'NDVI'
|
colormap
|
str
|
Colormap name (default "RdYlGn"). |
'RdYlGn'
|
vmin
|
float
|
Minimum value for colormap. |
0
|
vmax
|
float
|
Maximum value for colormap. |
250
|
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary of {date_string: tile_layer} for use with Map.add_time_slider(). |
Example
items = terrascope.search_ndvi(bbox, start, end) layers = terrascope.create_time_layers(items) m = leafmap.Map() m.add_time_slider(layers)
get_asset_urls(items, asset_key='NDVI')
¶
Extract asset URLs from a list of STAC items.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
items
|
list
|
List of pystac Item objects. |
required |
asset_key
|
str
|
Asset key to extract (default "NDVI"). |
'NDVI'
|
Returns:
| Type | Description |
|---|---|
list[str]
|
List of asset URLs. |
get_item_dates(items)
¶
Extract dates from a list of STAC items.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
items
|
list
|
List of pystac Item objects. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
List of date strings in "YYYY-MM-DD" format. |
get_stac_client()
¶
Get a pystac_client Client for the Terrascope STAC catalog.
Returns:
| Type | Description |
|---|---|
Any
|
pystac_client.Client instance. |
list_collections()
¶
List available collections in the Terrascope STAC catalog.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of collection IDs. |
login(username=None, password=None, auto_refresh=True, quiet=False)
¶
Authenticate with Terrascope using HTTP Basic Auth.
This sets up the necessary GDAL environment variables for GDAL/rasterio to authenticate with Terrascope when streaming COGs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
username
|
str | None
|
Terrascope username. Defaults to TERRASCOPE_USERNAME env var. |
None
|
password
|
str | None
|
Terrascope password. Defaults to TERRASCOPE_PASSWORD env var. |
None
|
auto_refresh
|
bool
|
Kept for API compatibility, ignored. |
True
|
quiet
|
bool
|
Suppress status messages. |
False
|
Example
import leafmap.terrascope as terrascope terrascope.login() Authenticated as: your_username
logout()
¶
Clear GDAL authentication configuration.
Unsets GDAL environment variables and cleans up any legacy OAuth2 files.
search(collection, bbox=None, start=None, end=None, max_cloud_cover=None, limit=None, unique_dates=True, **kwargs)
¶
Search for items in a Terrascope STAC collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection
|
str
|
Collection ID (e.g., "terrascope-s2-ndvi-v2"). |
required |
bbox
|
list[float] | None
|
Bounding box [west, south, east, north] in WGS84. |
None
|
start
|
str | datetime | None
|
Start date (string "YYYY-MM-DD" or datetime). |
None
|
end
|
str | datetime | None
|
End date (string "YYYY-MM-DD" or datetime). |
None
|
max_cloud_cover
|
float | None
|
Maximum cloud cover percentage (0-100). |
None
|
limit
|
int | None
|
Maximum number of items to return. |
None
|
unique_dates
|
bool
|
If True, return only one item per unique date. |
True
|
**kwargs
|
Additional arguments passed to pystac_client search. |
{}
|
Returns:
| Type | Description |
|---|---|
list
|
List of pystac Item objects, sorted by date. |
Example
items = terrascope.search( ... collection="terrascope-s2-ndvi-v2", ... bbox=[5.0, 51.2, 5.1, 51.3], ... start="2025-05-01", ... end="2025-06-01", ... max_cloud_cover=10, ... )
search_ndvi(bbox, start, end, max_cloud_cover=10.0, **kwargs)
¶
Search for Sentinel-2 NDVI products.
Convenience wrapper around search() for the terrascope-s2-ndvi-v2 collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bbox
|
list[float]
|
Bounding box [west, south, east, north] in WGS84. |
required |
start
|
str | datetime
|
Start date (string "YYYY-MM-DD" or datetime). |
required |
end
|
str | datetime
|
End date (string "YYYY-MM-DD" or datetime). |
required |
max_cloud_cover
|
float
|
Maximum cloud cover percentage. Default 10%. |
10.0
|
**kwargs
|
Additional arguments passed to search(). |
{}
|
Returns:
| Type | Description |
|---|---|
list
|
List of pystac Item objects with NDVI assets. |
Example
items = terrascope.search_ndvi( ... bbox=[5.0, 51.2, 5.1, 51.3], ... start="2025-05-01", ... end="2025-06-01", ... ) print(f"Found {len(items)} NDVI scenes")