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
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.
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.

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]

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]