Crate stac

source ·
Expand description

Rust implementation of the SpatioTemporal Asset Catalog (STAC) specification.

The SpatioTemporal Asset Catalog (STAC) specification provides a common language to describe a range of geospatial information, so it can more easily be indexed and discovered. A ‘spatiotemporal asset’ is any file that represents information about the earth captured in a certain space and time.

This is a Rust implementation of the specification. Similar projects in other languages include:

§Data structures

STAC has three core data structures:

All three are provided as serde (de)serializable structures with public attributes. Each structure provides a new method that fills most of the object’s attributes with sensible defaults:

use stac::{Item, Catalog, Collection};
let item = Item::new("id");
let catalog = Catalog::new("id", "description");
let collection = Catalog::new("id", "description");

All attributes of STAC objects are accessible as public members:

use stac::{Item, Link};
let mut item = Item::new("id");
assert_eq!(item.id, "id");
assert!(item.geometry.is_none());
assert!(item.links.is_empty());
item.links.push(Link::new("an/href", "a-rel-type"));

§Value

A Value can represent any of the three core data structures, as well as an ItemCollection, akin to serde_json::Value:

use stac::{Value, Item};

let value = Value::Item(Item::new("an-id"));

Value implements most traits that are shared between the data structures, so users of this library can do work (e.g. migration) without needing to know what type of object the value represents:

use stac::{Value, Migrate, Version};

let value: Value = stac::read("examples/simple-item.json").unwrap();
let value = value.migrate(&Version::v1_1_0).unwrap();

§Input and output

Synchronous reads from the filesystem are supported via read:

let value: stac::Item = stac::read("examples/simple-item.json").unwrap();

If the reqwest feature is enabled, synchronous reads from urls are also supported:

#[cfg(feature = "reqwest")]
{
    let url = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json";
    let item: stac::Item = stac::read(url).unwrap();
}

To write, use write():

use stac::Format;

stac::write("an-id.json", stac::Item::new("an-id")).unwrap();

Enable the object-store feature to get and put objects from e.g. AWS s3 (with the object-store-aws feature) or from other backends (see features for a complete listing):

use stac::Item;

#[cfg(feature = "object-store")]
{
    stac::io::put_opts("s3://bucket/item.json", Item::new("an-id"), [("foo", "bar")]).await.unwrap();
    let item: Item = stac::io::get_opts("s3://bucket/item.json", [("foo", "bar")]).await.unwrap();
}

For more, see the documentation in the io module.

§Features

  • gdal: read raster assets, see gdal
  • geo: add some geo-enabled methods, see geo
  • geoarrow: read and write geoarrow, see geoarrow
  • geoparquet: read and write geoparquet, see geoparquet
    • geoparquet-compression: enable parquet compression
  • object-store: get and put from object stores. Sub-features enable specific protocols:
    • object-store-aws
    • object-store-azure
    • object-store-gcp
    • object-store-http
    • object-store-all (enable them all)
  • reqwest: get from http and https urls when using read

Re-exports§

Modules§

  • datetime
    Datetime utilities.
  • extensions
    Extensions describe how STAC can use extensions that extend the functionality of the core spec or add fields for specific domains.
  • gdalgdal
    Functions that leverage GDAL.
  • geogeo
    Geometry utilities, enabled by the geo feature.
  • geoarrowgeoarrow
    Convert between ItemCollection and Table. (experimental)
  • geoparquet
    Read data from and write data to stac-geoparquet.
  • io
    Read and write STAC.
  • item
    STAC Items.
  • link
    Links.
  • mime
    Media Types are a key element that enables STAC to be a rich source of information for clients.

Structs§

  • Asset
    An Asset is an object that contains a URI to data associated with the Item that can be downloaded or streamed.
  • Band
    Bands are used to describe the available bands in a STAC entity or Asset.
  • Catalog
    A STAC Catalog object represents a logical group of other Catalog, Collection, and Item objects.
  • Collection
    The STAC Collection Specification defines a set of common fields to describe a group of Items that share properties and metadata.
  • Extent
    The object describes the spatio-temporal extents of the Collection.
  • ItemAsset
    An item asset is an object that contains details about the datafiles that will be included in member items.
  • ItemCollection
    A GeoJSON FeatureCollection of items.
  • Provider
    This object provides information about a provider.
  • SpatialExtent
    The object describes the spatial extents of the Collection.
  • Statistics
    Statistics of all pixels in the band.
  • TemporalExtent
    The object describes the temporal extents of the Collection.

Enums§

  • Bbox
    A bounding box.
  • DataType
    The data type gives information about the values in the file.
  • Error
    Error enum for crate-specific errors.
  • Format
    The format of STAC data.
  • Type
    Enum for the four “types” of STAC values.
  • Value
    An enum that can hold any STAC object type.
  • Version
    A version of the STAC specification.

Constants§

Traits§

  • Assets
    Trait implemented by anything that has assets.
  • Fields
    Trait for structures that have gettable and settable fields.
  • FromJson
    Create a STAC object from JSON.
  • FromNdjson
    Create a STAC object from newline-delimited JSON.
  • Href
    Implemented by all three STAC objects, the Href trait allows getting and setting an object’s href.
  • Migrate
    Migrates a STAC object from one version to another.
  • ToJson
    Write a STAC object to JSON.
  • ToNdjson
    Write a STAC object to newline-delimited JSON.

Functions§

Type Aliases§