datasets

datasets

Body-namespaced access to remote (non-PDS) reference rasters.

First slice of the design in Plans/datasets_subpackage_design.qmd: a baked-in registry of remote data products, namespaced by body, with windowed /vsicurl/ reads of cloud-optimised GeoTIFFs by lon/lat box — no full download. Raster + vsicurl only for now; the remote-refreshed registry, download mode, and plp datasets CLI from the design doc are deferred.

from planetarypy import datasets

datasets.bodies()                       # ['mars']
datasets.mars.hrsc_level3               # a RemoteRaster
da = datasets.mars.hrsc_level3.read_window(lon=0, lat=0, size=1.0)   # DataArray
datasets.mars.hrsc_level3.read_window(0, 0, 1.0, out="patch.tif")    # + GeoTIFF

Classes

Name	Description
RemoteRaster	A remote reference raster, accessed by streaming (/vsicurl/).
StacCollection	A STAC-backed dataset: query a collection by location → COG items.
StacItem	One STAC item resolved to its COG asset — reads like a RemoteRaster.

RemoteRaster

datasets.RemoteRaster(
    key,
    short,
    name,
    body,
    provider,
    url,
    crs,
    kind='vsicurl',
    nodata=None,
    pixel_scale_m=None,
    version=None,
    homepage=None,
    citation=None,
)

[source]

A remote reference raster, accessed by streaming (/vsicurl/).

crs is informational metadata (the read uses the file’s own CRS); the other fields document provenance. See the design doc for the fuller DatasetConfig this will grow into.

Attributes

Name	Description
vsicurl	The GDAL /vsicurl/ URL for streaming reads.

Methods

Name	Description
browse	Open this raster in the interactive COG Browser. See :func:browse.
open	Open the remote COG as a rasterio dataset (streamed, not downloaded).
read_bbox	Read an explicit lon/lat box (degrees). See :func:read_bbox.
read_window	Read a size-degree lon/lat box positioned at (lon, lat).

browse

datasets.RemoteRaster.browse(open_browser=True)

Open this raster in the interactive COG Browser. See :func:browse.

[source]

open

datasets.RemoteRaster.open()

Open the remote COG as a rasterio dataset (streamed, not downloaded).

[source]

read_bbox

datasets.RemoteRaster.read_bbox(west, south, east, north, *, out=None)

Read an explicit lon/lat box (degrees). See :func:read_bbox.

[source]

read_window

datasets.RemoteRaster.read_window(
    lon,
    lat,
    size=1.0,
    *,
    anchor='center',
    out=None,
)

Read a size-degree lon/lat box positioned at (lon, lat).

anchor says where (lon, lat) sits on the box: "center" (default), or a corner — "lower-left"/"sw", "upper-left"/"nw", "lower-right"/"se", "upper-right"/"ne" (degree-square tiling conventions use the SW corner; raster/array origin is the NW corner).

Returns a georeferenced :class:xarray.DataArray (rioxarray). If out is given, the window is also written to that GeoTIFF. Reads only the byte ranges the window needs over HTTP — no full download.

[source]

StacCollection

datasets.StacCollection(
    key,
    short,
    name,
    body,
    provider,
    stac_url,
    collection,
    kind='stac',
    asset_key=None,
    homepage=None,
)

[source]

A STAC-backed dataset: query a collection by location → COG items.

Unlike :class:RemoteRaster (one fixed COG), a collection holds many COGs (per quad / per observation); :meth:search / :meth:at resolve a location to the matching :class:StacItem (s), which then read like any COG.

Methods

Name	Description
at	Items covering a lon/lat point.
browse	Open the COG covering (lon, lat) in the COG Browser. See :func:browse.
items	List this collection’s items (its contained products), no spatial filter.
read_window	Convenience: read from the first item covering (lon, lat).
search	Items overlapping a bbox (west, south, east, north) deg, or a point.

at

datasets.StacCollection.at(lon, lat, *, limit=20)

Items covering a lon/lat point.

[source]

browse

datasets.StacCollection.browse(lon, lat, *, open_browser=True)

Open the COG covering (lon, lat) in the COG Browser. See :func:browse.

[source]

items

datasets.StacCollection.items(limit=50)

List this collection’s items (its contained products), no spatial filter.

The “unpacker”: enumerate what a collection holds. See :func:stac_items.

[source]

read_window

datasets.StacCollection.read_window(
    lon,
    lat,
    size=1.0,
    *,
    anchor='center',
    out=None,
)

Convenience: read from the first item covering (lon, lat).

[source]

search

datasets.StacCollection.search(bbox=None, lon=None, lat=None, limit=20)

Items overlapping a bbox (west, south, east, north) deg, or a point.

[source]

StacItem

datasets.StacItem(
    id,
    cog_url,
    collection,
    bbox=(),
    datetime=None,
    nodata=None,
    short='stac_item',
)

[source]

One STAC item resolved to its COG asset — reads like a RemoteRaster.

Methods

Name	Description
browse	Open this STAC item’s COG in the interactive COG Browser. See :func:browse.

browse

datasets.StacItem.browse(open_browser=True)

Open this STAC item’s COG in the interactive COG Browser. See :func:browse.

[source]

Functions

Name	Description
add_basemap	Draw a surface image behind whatever is already on ax.
basemaps	Registered rasters usable as a plotting background.
bodies	Sorted list of bodies that have at least one registered raster.
browse	Open the interactive COG Browser (the docs viewer) for a raster source.
default_basemap	The curated default background for body, or None if there is none.
list_datasets	Registered rasters, optionally filtered to one body (case-insensitive).
read_bbox	Read an explicit lon/lat box (degrees) from a raster source.
read_window	Read a size-degree lon/lat box positioned at (lon, lat).
stac_collections	Discover the collections a STAC API root offers: [{id, title, description}].
stac_items	List a collection’s items (its contents) with no spatial filter — the “unpacker”.
stac_search	Query a STAC collection by location; return its COG-bearing items as StacItems.

add_basemap

datasets.add_basemap(
    ax,
    body=None,
    source=None,
    *,
    bbox='auto',
    cmap='gray',
    stretch=(2, 98),
    zorder=-10,
    **imshow_kw,
)

Draw a surface image behind whatever is already on ax.

Built for the common case: you have lon/lat measurements plotted, and you want them in front of the surface rather than on an empty grid. Draws at a low zorder and leaves the axes limits alone, so it composes with a plot you already made — and with :func:planetarypy.nomenclature.add_features.

Parameters

Name	Type	Description	Default
ax	matplotlib.axes.Axes	Axes to draw on. Existing content and limits are preserved.	required
body	str	Body name; its curated default background is used. Ignored when source is given.	None
source	optional	Any background you like — a :class:RemoteRaster, a :class:StacItem, a registry key or short name, or a bare COG URL. Overrides body.	None
bbox	'auto' or (west, south, east, north)	"auto" (default) reads the axes’ current limits.	'auto'
stretch	(lo, hi) or None	Percentile clip for display. None leaves values untouched — use it when the numbers matter, e.g. a DEM you intend to read off.	(2, 98)

Returns

Name	Type	Description
	matplotlib.image.AxesImage

Examples

>>> fig, ax = plt.subplots()
>>> ax.scatter(lons, lats)                        # your data
>>> datasets.add_basemap(ax, "mars")              # surface behind it
>>> nomenclature.add_features(ax, "mars")         # names on top

[source]

basemaps

datasets.basemaps(body=None)

Registered rasters usable as a plotting background.

Only single-file rasters qualify: a STAC collection is a set of tiles, and picking and mosaicking the right ones is a different job from streaming one window. Pass any such item to :func:add_basemap explicitly if you want it.

[source]

bodies

datasets.bodies()

Sorted list of bodies that have at least one registered raster.

[source]

browse

datasets.browse(
    source=None,
    *,
    lon=None,
    lat=None,
    base_url=VIEWER_URL,
    open_browser=True,
)

Open the interactive COG Browser (the docs viewer) for a raster source.

source may be:

• a :class:RemoteRaster, :class:StacItem, registry key, or bare COG URL — the viewer opens on that COG, with its projection resolved to proj4 by :func:_viewer_proj4 (from the IAU code, else read from the COG);
• a :class:StacCollection — pass lon/lat to pick the covering item;
• a viewer preset name ("robbins_spole", "robbins_equatorial") or None for the default preset — the viewer carries these self-contained.

Returns the viewer URL (also opened in a browser unless open_browser=False). Note the URL points at the published docs; a locally built docs site can be targeted with base_url=".../cogbrowser/index.html".

[source]

default_basemap

datasets.default_basemap(body)

The curated default background for body, or None if there is none.

[source]

list_datasets

datasets.list_datasets(body=None)

Registered rasters, optionally filtered to one body (case-insensitive).

[source]

read_bbox

datasets.read_bbox(source, west, south, east, north, *, out=None)

Read an explicit lon/lat box (degrees) from a raster source.

source is a :class:RemoteRaster, a :class:StacItem, a registry key, or a bare COG URL. The box is transformed into the file’s own CRS via pyproj (so this works for any body / projection, not just equirectangular), then read with a single rasterio window. Returns a georeferenced :class:xarray.DataArray; writes a GeoTIFF too when out is given. Reads only the byte ranges the window needs.

[source]

read_window

datasets.read_window(source, lon, lat, size=1.0, *, anchor='center', out=None)

Read a size-degree lon/lat box positioned at (lon, lat).

source is anything :func:read_bbox accepts (RemoteRaster, StacItem, registry key, or COG URL). anchor places (lon, lat) on the box: "center" (default) or a corner — "lower-left"/"sw" (degree-square tiling convention), "upper-left"/"nw" (raster origin), "lower-right"/"se", "upper-right"/"ne". Thin wrapper over :func:read_bbox.

[source]

stac_collections

datasets.stac_collections(stac_url)

Discover the collections a STAC API root offers: [{id, title, description}].

E.g. stac_collections("https://stac.astrogeology.usgs.gov/api") lists every USGS Astrogeology collection — the ids you’d register as a :class:StacCollection.

[source]

stac_items

datasets.stac_items(coll, *, limit=50)

List a collection’s items (its contents) with no spatial filter — the “unpacker”.

Hits the STAC /collections/{id}/items endpoint. limit caps how many are returned (the endpoint paginates; this fetches the first page).

[source]

stac_search

datasets.stac_search(coll, *, bbox=None, lon=None, lat=None, limit=20)

Query a STAC collection by location; return its COG-bearing items as StacItems.

bbox is (west, south, east, north) in degrees; or pass lon/lat for a point (expanded to a tiny box, since STAC rejects a zero-area bbox).

[source]