Primitives to Generate Static SpatioTemporal Asset Catalogs • rstatic

Build browsable, server-less static SpatioTemporal Asset Catalogs (STAC) from R.

rstatic turns a folder of geospatial assets into a valid STAC catalog you can publish anywhere static files are served — GitHub Pages, an S3 bucket, or a plain web server. No database and no running service are required.

It does this through small, composable primitives for catalogs, collections, items, assets, and links. Each one is a pure builder or an explicit write to disk, so you stay in control of what gets created and where. This makes rstatic equally useful on its own and as a foundation for higher-level tools such as STAC generators and experiment catalog builders. It implements STAC specification version 1.0.0.

Features

Build catalogs, collections, items, assets, and links with simple constructor functions.
Serialize any document to its canonical static-catalog path on disk.
Track spatial and temporal extents automatically as items are added.
Optionally extract bounding boxes from rasters, render PNG thumbnail assets, and import QGIS layer styles.

The optional helpers activate automatically when their supporting packages are installed; otherwise you can still build complete catalogs by supplying bounding boxes, geometries, and styles yourself.

Installation

You can install the development version of rstatic from GitHub with:

# install.packages("remotes")
remotes::install_github("rolfsimoes/rstatic")

Usage

The example below builds a minimal static catalog with one collection and one item, writing the JSON tree under a temporary directory.

library(rstatic)

root <- tempfile("stac-")

# 1. Build the documents in memory (pure -- nothing is written yet)
catalog <- new_catalog(
  id = "example",
  title = "Example Catalog",
  description = "A minimal static STAC catalog"
)

collection <- new_collection(
  id = "land-cover",
  title = "Land Cover",
  description = "Example land cover collection"
)

item <- new_item(
  id = "land-cover-2020",
  bbox = c(-50, -10, -49, -9),
  properties = new_properties(datetime = "2020-01-01T00:00:00Z"),
  assets = list(
    data = new_asset("land-cover-2020.tif", title = "Land Cover 2020")
  )
)

# 2. Link them with the pure add_*() builders
collection <- add_items(collection, item)
catalog <- add_collection(catalog, collection)

# 3. Persist -- stac_save() is the only writer
stac_save(catalog = catalog, collection = collection, items = item,
          root_dir = root)

The resulting directory follows the canonical static catalog layout, with the collection linking to its item:

list.files(file.path(root, "stac"), recursive = TRUE)
#> [1] "catalog.json"                                          
#> [2] "collections/land-cover/collection.json"                
#> [3] "collections/land-cover/items/land-cover-2020/item.json"

Each file is a self-contained STAC document. To extend a catalog that is already on disk, read it back with stac_read(), add to it, and save again – saving is a pure overwrite, so reading first is what preserves the existing children.

Core primitives

Function	Purpose
`new_catalog()`, `new_collection()`	Build catalogs and collections in memory
`new_item()`, `new_properties()`, `new_asset()`	Build items, properties and assets
`add_collection()` / `add_items()`	Attach a collection/items to a parent, return it
`add_link()` / `add_asset()`	Attach links and assets
`stac_read()`	Read a document from disk (load-or-create with `default`)
`stac_save()`	Write documents to their canonical paths (the only writer)
`extract_bbox()` / `as_geometry()`	Spatial metadata helpers
`stac_style()` / `qml_to_style()`	Thumbnail style objects
`new_thumbnail()`	Describe a PNG thumbnail asset (rendered on save)

new_*() constructors and add_*() builders are pure and never touch disk; stac_read() and stac_save() are the only functions that do.

Documentation

Full function reference and articles: https://rolfsimoes.github.io/rstatic/
Get started: vignette("rstatic")
Per-function help, e.g. ?stac_save

Getting help

Found a bug or have a feature request? Please open an issue at https://github.com/rolfsimoes/rstatic/issues.

rstatic focuses on writing static catalogs from primitives. If you instead need to query remote STAC APIs from R, see rstac.

License

GPL (>= 3). See LICENSE.md.

rstatic