Fetch STAC-hosted rasters via gdalcubes — dft_stac

Query a STAC catalog, build a gdalcubes image collection, and extract per-year rasters cropped and masked to the AOI. Works with any STAC collection hosting single-band classified rasters (IO LULC, ESA WorldCover, custom COGs).

Usage

dft_stac_fetch(
  aoi,
  source = "io-lulc",
  years = NULL,
  stac_url = NULL,
  collection = NULL,
  asset = NULL,
  res = 10,
  crs = NULL,
  dt = "P1Y",
  aggregation = "first",
  resampling = "near",
  tile_size = NULL,
  cache_dir = NULL,
  force = FALSE,
  sign_fn = rstac::sign_planetary_computer()
)

Arguments

aoi: An sf polygon defining the area of interest.
source: Character. A known source name passed to dft_stac_config(). Ignored when stac_url, collection, and asset are all provided.
years: Integer vector of years to fetch. When NULL, uses available_years from dft_stac_config().
stac_url: Character. STAC API endpoint URL. Overrides source.
collection: Character. STAC collection ID. Overrides source.
asset: Character. Asset name within each STAC item. Overrides source.
res: Numeric. Output pixel size in CRS units (default 10).
crs: Character. Target CRS as an EPSG string (e.g. "EPSG:32609"). When NULL, auto-detected from the AOI centroid's UTM zone.
dt: Character. ISO 8601 duration for the temporal aggregation window (default "P1Y").
aggregation: Character. Temporal aggregation method (default "first"). Use "median" for multi-scene composites.
resampling: Character. Spatial resampling method (default "near" for categorical data).
tile_size: Numeric or NULL (default). Edge length, in CRS units (metres for the default UTM CRS), of the download-tiling grid. When NULL, one cube is streamed over the whole AOI bounding box (the download scales with the bbox, not the AOI). When set, the bbox is split into a grid of tile_size-square tiles and only tiles that intersect the AOI polygon are streamed, then mosaicked — so a thin, diagonal AOI (e.g. a floodplain corridor) fetches close to its footprint instead of its full bounding box. Snapped to a multiple of res. Smaller tiles waste less bbox but cost more per-tile round trips; there is no auto-tuning. Tiled fetches cache a terra GeoTIFF (.tif) rather than a gdalcubes NetCDF (.nc).
cache_dir: Character. Cache directory path. When NULL, uses dft_cache_path().
force: Logical. Re-fetch even if cached, replacing the cached file (default FALSE). The replacement is atomic, so a raster returned by an earlier call keeps reading the entry it was opened against rather than picking up half-rewritten contents, and an interrupted forced re-fetch leaves the previous entry intact.
sign_fn: A signing function for STAC assets. Default is rstac::sign_planetary_computer().

Value

A named list of terra::SpatRaster objects, one per year. The STAC items are attached as attr(, "stac_items") for use with dft_stac_classes() — paged to exhaustion, with the (stale) next link stripped so a caller re-running rstac::items_fetch() on them cannot silently duplicate features. The cache key is attached as attr(, "cache_key") so a caller can record which cache entry served the fetch; it is per call, not per year — cached files are named <year>_<cache_key>, so one key covers every year the call returned. Its format changed in 0.12.0 (#48): 16 lowercase hex characters, from digest::digest(algo = "xxhash64") over a canonical string, where it was previously 12 from rlang::hash().

Details

Fetched rasters are cached under dft_cache_path() as v2/<source>/<year>_<key>.nc (or .tif when tile_size is set — see below), where key is a hash of the AOI geometry and every fetch parameter that affects the output (res, crs, dt, aggregation, resampling, stac_url, collection, asset, and tile_size). Repeat calls with the same AOI and parameters reuse the cache; changing any of them re-fetches.

Entries are published atomically — written to a temp file in the same directory and renamed into place only after a complete, validated write — so an interrupted fetch cannot leave a partial file under the canonical name for a later run to trust. A cached entry is also validated before it is served: it must open as a raster, be sanely georeferenced, and return its pixels without a read error. An entry that fails is re-fetched with a warning rather than served or left for the user to delete by hand.

The read check samples rather than proves — it reads one row, so interior damage that leaves the file structurally walkable can pass it. The guarantee against partial entries is the atomic write, not the check.

The key is a function of content alone (#48), so the same AOI and parameters produce the same filename on any machine, R version, rlang version and architecture — a cache can be copied between machines and stay valid. The leading v2 is the cache-scheme generation: a deliberate key change moves it, leaving older entries findable rather than silently orphaned. See dft_cache_info() and dft_cache_clear() for reporting and reclaiming them.

Note sf::st_as_binary() honours sf::st_precision(), so setting a precision on the AOI changes its WKB and therefore the key. That has always been true.