wxy_domain/lib.rs
1//! # wxy-domain
2//!
3//! One data model for gridded, mesh and feature data, with no I/O and no
4//! CRS dependency. This is stage S1 of the wxylib roadmap; the design is in
5//! [wxylib/design](https://github.com/wxylib/design), documents 02 and 03.
6//!
7//! The model separates three things that gridded-data software usually
8//! blurs (after *Regular in what?*, hypertidy/regular-in-what):
9//!
10//! - **index mapping**: how a position follows from an index
11//! ([`Positions`], one variant per rung of the [`Rung`] ladder);
12//! - **frame**: what the positions mean ([`Frame`], opaque to this crate);
13//! - **storage**: what a producer wrote down. Readers record the stored
14//! form as given, and [`normalise`] turns it into a cheaper, equivalent
15//! mapping when the evidence allows, with a [`normalise::Report`].
16//!
17//! A [`Domain`] is index space ([`Dim`]s) plus any number of [`Mapping`]s,
18//! each covering some of the dims and naming its frame. A [`Field`] is
19//! values on a domain. A [`Collection`] groups fields and domains, and
20//! covers a classic raster dataset, a multidimensional group, a mesh with
21//! its datasets, or a feature layer.
22//!
23//! ## Index space convention
24//!
25//! Continuous index coordinates follow GDAL's pixel convention: `0.0` is
26//! the outer edge of the first element along a dim and `i + 0.5` is the
27//! centre of element `i`. Every mapping evaluates in this space, whatever
28//! its [`CellConvention`] says about where stored coordinates sit.
29//!
30//! ## What is implemented in S1
31//!
32//! Rungs R0 to R3 (index only, regular, rectilinear, curvilinear) are
33//! implemented and evaluate positions. R3' (fitted models), R4 (implicit
34//! meshes such as DGGS) and R5/R6 (explicit meshes, features) are present
35//! as trait-object variants so the types will not change when they arrive.
36
37pub mod affine;
38pub mod collection;
39pub mod dim;
40pub mod domain;
41pub mod field;
42pub mod frame;
43pub mod mapping;
44pub mod normalise;
45pub mod positions;
46
47pub use affine::Affine;
48pub use collection::{Collection, Relation, RelationKind};
49pub use dim::Dim;
50pub use domain::Domain;
51pub use field::{DataType, Field, Location, ValueSemantics};
52pub use frame::Frame;
53pub use mapping::{CellConvention, Mapping};
54pub use positions::{CoordArray, Positions, Rung};