Crate stac

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:

• Python: PySTAC
• Go: go-stac
• .NET: DotNetStac
• PHP: resto

Data structures

STAC has three core data structures:

• Item is a GeoJSON Feature augmented with foreign members
• Catalog represents a logical group of other Catalogs, Collections, and Items
• Collection shares all fields with the Catalog (with different allowed values for type and stac_extensions) and adds fields to describe the whole dataset and the included set of Items

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 or an ItemCollection. It’s the serde_json::Value for stac-rs:

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 cloud storage, e.g. 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

• 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

• pub use geoparquet::FromGeoparquet;
• pub use geoparquet::IntoGeoparquet;
• pub use io::read;
• pub use io::write;
• pub use item::FlatItem;
• pub use item::Item;
• pub use item::Properties;
• pub use link::Link;
• pub use link::Links;

Modules

• datetime
  Datetime utilities.
• 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.
• Node
  A node in a STAC tree.
• Provider
  This object provides information about a provider.
• Resolverobject-store
  An object that uses object store to resolve links.
• 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.
• Validatorvalidate
  A cloneable structure for validating STAC.

Enums

• Bbox
  A bounding box.
• Container
  A STAC container, i.e. a Catalog or a Collection.
• 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.
• Href
  An href.
• RealizedHref
  An href that has been realized to a path or a url.
• 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

• STAC_VERSION
  The default STAC version of this library.

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.
• Migrate
  Migrates a STAC object from one version to another.
• SelfHref
  Implemented by all three STAC objects, the SelfHref trait allows getting and setting an object’s href.
• ToJson
  Write a STAC object to JSON.
• ToNdjson
  Write a STAC object to newline-delimited JSON.
• Validatevalidate
  Validate any serializable object with json-schema
• ValidateBlockingvalidate-blocking and validate
  Validate any serializable object with json-schema

Functions

• version
  Return this crate’s version.

Type Aliases

• Result
  Custom Result type for this crate.