Crate stac

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:

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.
Geometry: Geometry Objects
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 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

Functions§

user_agent: Returns a string suitable for use as a HTTP user agent.
version: Return this crate’s version.

Type Aliases§

Result: Custom Result type for this crate.

Crate stacCopy item path