Github Binder

Coming from Geopandas

If you’re already using geopandas.GeoDataFrame.explore to visualize STAC items, this notebook highlights some of the advantages of stacmap.explore and some tips for transitioning.

Before we start, install the dependencies needed for geopandas.GeoDataFrame.explore:

[ ]:
!pip install geopandas matplotlib mapclassify

What are the advantages of stacmap?

  • Lightweight

  • stacmap only has a few dependencies to keep installs quick and easy.

  • Native STAC support

  • stacmap.explore directly plots STAC items and collections without converting to GeoDataFrame first.

  • Convenient features

  • Plot search extents, preview thumbnails, filter STAC properties by extension, etc.

Native STAC Support

Exploring a collection of STAC items starts with loading items from a STAC, regardless of whether you use geopandas or stacmap.

[1]:
import pystac
import stacmap
import geopandas as gpd

catalog = pystac.Catalog.from_file("https://planet.com/data/stac/disasters/hurricane-harvey/hurricane-harvey-0831/catalog.json")
print(catalog.description)
Planet Scenes and Composites for Hurricane Harvey on Aug 31, 2017

With geopandas, you’ll need to manually convert that catalog into a GeoDataFrame before exploring it.

[2]:
gdf = gpd.GeoDataFrame.from_features([item.to_dict() for item in catalog.get_all_items()], crs="EPSG:4326")
gdf.explore(column="gsd", categorical=True, cmap="Dark2")
[2]:
Make this Notebook Trusted to load map: File -> Trust Notebook

stacmap offers native support for most STAC data types, so there’s no need to build a GeoDataFrame. Just pass the STAC catalog directly into explore.

[3]:
stacmap.explore(catalog, prop="gsd", cmap="Dark2", categorical=True)
[3]:
Make this Notebook Trusted to load map: File -> Trust Notebook

Convenient Features

stacmap also offers some features that you might frequently want when exploring STAC metadata.

Search Extent

When searching for images, you might want to know how much of their footprint covers your area of interest. Pass a bounding box to bbox or a GeoJSON geometry to intersects to plot the search extent as an additional layer with stacmap.

[4]:
bbox = [-96.3, 28.8, -93.5, 30.4]
stacmap.explore(catalog, prop="gsd", cmap="Dark2", categorical=True, bbox=bbox)
[4]:
Make this Notebook Trusted to load map: File -> Trust Notebook

Thumbnails

Some STAC items contain thumbnail assets. Preview the assets in their approximate location with thumbnails=True.

[7]:
stacmap.explore(catalog, thumbnails=True, style_kwds=dict(fill=False))
[7]:
Make this Notebook Trusted to load map: File -> Trust Notebook

Metadata

stacmap.explore has some features to make metadata more useful:

  • Metadata is sorted by prefix, with base properties first and extensions after.

  • The STAC ID of each item is added to the metadata table by default (this can be disabled with add_id=False).

  • Display only relevant STAC extension properties by specifying a list of extensions (e.g. extensions=["eo", "view"])

  • Only include specific properties by specifying a list of properties (e.g. props=["eo:cloud_cover"])

Parameters

geopandas.GeoDataFrame.explore and stacmap.explore both have a lot of parameters. stacmap uses similar parameters whenever possible to make transitioning from geopandas easier, but some are renamed for clarity or dropped for simplicity, and others are added for additional functionality.

The lists below show how parameters differ between the two APIs.

Changed

Shared

Geopandas only

stacmap only

column -> prop

cmap

scheme

name

m

k

bbox

tiles & attr

categories

intersects

tooltip & popup

classification_kwds

thumbnails

highlight

marker_type

fields

categorical

marker_kwds

extensions

legend

legend_kwds

shared_fields

control_scale

add_id

vmin & vmax

zoom_to

width & height

layer_control

style_kwds & highlight_kwds

bounds_kwds

tooltip_kwds & popup_kwds

map_kwds

Note

This page was auto-generated from a Jupyter notebook. For full functionality, download the notebook from Github and run it in a local Python environment.