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, with associated utilities. Similar projects in other languages include:
- Python: PySTAC
- Go: go-stac
- .NET: DotNetStac
- PHP: resto
Data structures
STAC has three data structures:
- Item is a GeoJSON Feature augmented with foreign members
- Catalog represents a logical group of other
Catalogs,Collections, andItems - Collection shares all fields with the
Catalog(with different allowed values fortypeandstac_extensions) and adds fields to describe the whole dataset and the included set ofItems
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"));Reading
Synchronous reads from the filesystem are supported via read. Read objects are returned as a Value, which implements TryInto for all three object types:
let value = stac::read("data/simple-item.json").unwrap();
assert!(value.is_item());
let item: stac::Item = value.try_into().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 value = stac::read(url).unwrap();
}If reqwest is not enabled, reading from a url will return an error:
#[cfg(not(feature = "reqwest"))]
{
let url = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json";
let error = stac::read(url).unwrap_err();
}Hrefs
When objects are read from the filesystem or from a remote location, they store the href from which they were read. The href is accessible via the Href trait:
use stac::{Href, Item};
let value = stac::read("data/simple-item.json").unwrap();
assert!(value.href().as_deref().unwrap().ends_with("data/simple-item.json"));
let item: Item = value.clone().try_into().unwrap();
assert_eq!(value.href(), item.href());Validation
If the jsonschema feature is enabled, objects can be validated against their json-schema definitions:
#[cfg(feature = "jsonschema")]
{
use stac::{Item, Validate};
let item = Item::new("an-id");
item.validate().unwrap();
}See the validate module for more examples.
Re-exports
Modules
jsonschemaStructs
Collection Specification defines a set of common fields to describe
a group of Items that share properties and metadata.Item is a GeoJSON Feature augmented with foreign members relevant to a
STAC object.