stt_core/lib.rs
1//! Core library for the **SpatioTemporal Tiles (STT)** format.
2//!
3//! The canonical container is the **packed format** ([`pack`]): a per-dataset
4//! `manifest.json` plus many content-addressed, immutable pack objects
5//! (`packs/<blake3>.sttp`) and one directory object (`index/<blake3>.sttd`).
6//! Splitting a dataset into small, immutable objects is what makes it
7//! edge-cacheable on a plain CDN — see `docs/spec/stt-packed-format.md`.
8//!
9//! Building blocks:
10//! - [`pack`] — the packed format: [`PackWriter`], [`PackedReader`], [`Manifest`],
11//! [`transcode_archive_to_packs`], [`verify_packed_objects`].
12//! - [`arrow_tile`] — Arrow-IPC tile payloads with GeoArrow geometry.
13//! - [`directory`] — the run-length tile directory (v5 = packed; v4 = legacy single-file).
14//! - [`curve`] — spatial (Hilbert) + temporal blob ordering.
15//! - [`metadata`] — dataset metadata (folded verbatim into the manifest).
16//! - [`compression`] — per-blob zstd / gzip.
17//!
18//! The single-file [`archive`] container ([`ArchiveWriter`] / [`ArchiveReader`])
19//! predates the packed format and is **no longer a deployment target**. It
20//! survives only as (a) the bounded-RAM streaming *intermediate* that
21//! `stt-build --streaming-arrow` transcodes into packs, and (b) the read side
22//! that [`transcode_archive_to_packs`] consumes when migrating old archives.
23
24pub mod archive;
25pub mod arrow_tile;
26pub mod budget;
27pub mod compression;
28pub mod curve;
29pub mod directory;
30pub mod directory_page;
31pub mod error;
32pub mod geometry;
33pub mod metadata;
34pub mod pack;
35pub mod projection;
36pub mod tile;
37pub mod timestamp;
38pub mod types;
39
40// Re-export commonly used types.
41// Packed format — the canonical container.
42pub use pack::{
43 repack_directory, transcode_archive_to_packs, transcode_archive_to_packs_paged,
44 transcode_archive_to_packs_paged_level, transcode_packs_to_packs_paged_level,
45 verify_packed_objects, Manifest, PackWriter, PackedReader,
46};
47pub use directory_page::{
48 decode_paged_directory, encode_paged_directory, verify_paged_structure, PageDescriptor,
49 PagedRoot, DEFAULT_PAGE_ENTRIES,
50};
51// Single-file archive — legacy/intermediate surface (see the module doc above).
52pub use archive::{Archive, ArchiveReader, ArchiveWriter};
53pub use curve::BlobOrdering;
54pub use error::{Error, Result};
55pub use tile::TileId;
56pub use timestamp::{
57 normalize_timestamp_to_ms, reject_negative_timestamp, scale_timestamp_to_ms, TimestampUnit,
58};
59pub use types::{BoundingBox, TimeRange};
60
61#[cfg(test)]
62mod tests {
63 use super::*;
64
65 #[test]
66 fn test_tile_id_ordering() {
67 let t1 = TileId::new(10, 512, 384, 1609459200000);
68 let t2 = TileId::new(10, 512, 384, 1609545600000);
69 assert!(t1 < t2);
70 }
71}