s2json/lib.rs
1#![no_std]
2#![forbid(unsafe_code)]
3#![deny(missing_docs)]
4#![cfg_attr(docsrs, feature(doc_cfg))]
5
6//! # S2 JSON 🌎 🗺️
7//!
8//! ```text
9//! ________
10//! / ___/__ \
11//! \__ \__/ /
12//! ___/ / __/
13//! /____/____/
14//!
15//! _______ ____ _ __
16//! / / ___// __ \/ | / /
17//! __ / /\__ \/ / / / |/ /
18//! / /_/ /___/ / /_/ / /| /
19//! \____//____/\____/_/ |_/
20//! ```
21//!
22//! ## Install
23//!
24//! ```bash
25//! cargo add s2json
26//! ```
27//!
28//! ## About
29//!
30//! A collection of geospatial base types primarily designed for WGS84, Web Mercator, and S2.
31//!
32//! This library is designed to be **lightweight** with minimal dependencies. All code is `no_std`
33//! complient, denies unsafe code, and can be used in any environment.
34//!
35//! ## Usage
36//!
37//! The Documentation is very thorough in this library. Therefore the best thing to do is follow
38//! the links provided as needed.
39//!
40//! This library wraps both a GeoJSON spec and the newer S2 JSON spec. For tooling that builds ontop
41//! of this library, see gis-tools.
42//!
43//! ### Core
44//!
45//! #### Top Level Topology
46//!
47//! - [`crate::FeatureCollection`]: WG FeatureCollection following the GeoJSON spec
48//! - [`crate::S2FeatureCollection`]: S2 FeatureCollection following the S2JSON spec
49//! - [`crate::Feature`]: WG Feature following the GeoJSON spec
50//! - [`crate::VectorFeature`]: S2 Feature following both the S2JSON spec
51//! - [`crate::Attributions`]: A list of attributions. Used by [`crate::FeatureCollection`] and [`crate::S2FeatureCollection`]
52//! - [`crate::FeatureCollections`]: An enum of either [`crate::FeatureCollection`] or [`crate::S2FeatureCollection`]
53//! - [`crate::Features`]: An enum of either [`crate::Feature`] or [`crate::VectorFeature`]
54//! - [`crate::JSONCollection`]: A JSON FeatureCollection can be any of [`crate::FeatureCollection`], [`crate::S2FeatureCollection`], [`crate::Feature`], or [`crate::VectorFeature`]
55//!
56//! #### Bounding Boxes
57//!
58//! - [`crate::BBox`]: A BBOX is defined in lon-lat space and helps with zooming motion to see the entire line or polygon The order is (left, bottom, right, top) If WM, then the projection is lon-lat If S2, then the projection is s-t
59//! - [`crate::BBox3D`]: A BBOX is defined in lon-lat space and helps with zooming motion to see the entire 3D line or polygon
60//! - [`crate::BBOX`]: BBox or BBox3D enum
61//!
62//! #### Primitive Types
63//!
64//! Note that [`crate::MValue`] is the key type used by the rest of the library, gis-tools, s2tiles, s2maps, etc.
65//! Allows a lot of cool encoding/decoding mechanics along with better rendering tools.
66//!
67//! - [`crate::Axis`]: The axis to apply an operation to
68//! - [`crate::Projection`]: Enum for the WG or S2 Projections
69//! - [`crate::Face`]: Cube-face on the S2 sphere. Optionss are [0, 5] inclusive.
70//! - [`crate::PrimitiveValue`]:
71//! - [`crate::ValuePrimitiveType`]:
72//! - [`crate::ValueType`]:
73//! - [`crate::ValuePrimitive`] / [`crate::MapboxProperties`]:
74//! - [`crate::Value`] / [`crate::Properties`] / [`crate::MValue`]:
75//! - [`crate::MValues`]:
76//! - [`crate::JSONValue`]:
77//! - [`crate::JSONProperties`]:
78//!
79//! #### Geoemtry
80//!
81//! - [`crate::STPoint`]: An Point in S2 Space with a Face
82//!
83//! **Primitives**
84//!
85//! - [`crate::Point`]: A very basic cheap X-Y point
86//! - [`crate::MultiPoint`]: An array of [`crate::Point`]
87//! - [`crate::LineString`]: An array of [`crate::Point`]
88//! - [`crate::MultiLineString`]: An array of [`crate::LineString`]
89//! - [`crate::Polygon`]: An array of [`crate::LineString`]
90//! - [`crate::MultiPolygon`]: An array of [`crate::Polygon`]
91//! - [`crate::Point3D`]: A very basic 3D X-Y-Z point
92//! - [`crate::MultiPoint3D`]: An array of [`crate::Point3D`]
93//! - [`crate::LineString3D`]: An array of [`crate::Point3D`]
94//! - [`crate::MultiLineString3D`]: An array of [`crate::LineString3D`]
95//! - [`crate::Polygon3D`]: An array of [`crate::LineString3D`]
96//! - [`crate::MultiPolygon3D`]: An array of [`crate::Polygon3D`]
97//! - [`crate::PointOrPoint3D`]: Either a [`crate::Point`] or [`crate::Point3D`]
98//! - [`crate::GeometryType`]: The type of geometry
99//! - [`crate::Geometry`]: The geometry. An enum of all primtive geometry types
100//!
101//! **Vector Primitives**
102//!
103//! - [`crate::VectorPoint`]: A Vector Point uses a structure for both 2D or 3D points. Useful for geometry that also has m-values
104//! - [`crate::VectorMultiPoint`]: An array of [`crate::VectorPoint`]
105//! - [`crate::VectorLineString`]: An array of [`crate::VectorPoint`]
106//! - [`crate::VectorMultiLineString`]: An array of [`crate::VectorLineString`]
107//! - [`crate::VectorPolygon`]: An array of [`crate::VectorLineString`]
108//! - [`crate::VectorMultiPolygon`]: An array of [`crate::VectorPolygon`]
109//! - [`crate::VectorGeometryType`]: The type of vector geometry
110//! - [`crate::VectorGeometry`]: The vector geometry. An enum of all vector geometry types
111//! - [`crate::VectorOffsets`]: The offsets for a vector geometry (rarely used)
112//!
113//! ### Traits
114//!
115//! These traits are the fundamental building box for all geometry tooling. If you need your own
116//! custom data structure you can implement these traits and use all the tools built not only in
117//! this library but gis-tools as well.
118//!
119//! **Getters**
120//!
121//! - [`crate::GetXY`]: Get the X and Y coordinates of a point
122//! - [`crate::GetZ`]: Get the Z coordinate of a point
123//! - [`crate::GetXYZ`]: Get the X, Y, and Z coordinates of a point
124//! - [`crate::GetM`]: Get the M coordinate of a point
125//! - [`crate::GetXYZM`]: Get the X, Y, Z, and M coordinates of a point
126//!
127//! **Setters**
128//!
129//! - [`crate::SetXY`]: Set the X and Y coordinates of a point
130//! - [`crate::SetZ`]: Set the Z coordinate of a point
131//! - [`crate::SetXYZ`]: Set the X, Y, and Z coordinates of a point
132//! - [`crate::SetM`]: Set the M coordinate of a point
133//! - [`crate::SetXYZM`]: Set the X, Y, Z, and M coordinates of a point
134//!
135//! **New**
136//!
137//! - [`crate::NewXY`]: Get and Set the X and Y coordinates of a point
138//! - [`crate::NewXYM`]: Get and Set the X, Y, and M coordinates of a point
139//! - [`crate::NewXYZ`]: Get and Set the X, Y, and Z coordinates of a point
140//! - [`crate::NewXYZM`]: Get and Set the X, Y, Z, and M coordinates of a point
141//!
142//! **Full Get, New, and Set**
143//!
144//! - [`crate::FullXY`]: Get, New, and Set the X and Y coordinates of a point
145//! - [`crate::FullXYM`]: Get, New, and Set the X, Y, and M coordinates of a point
146//! - [`crate::FullXYZ`]: Get, New, and Set the X, Y, and Z coordinates of a point
147//! - [`crate::FullXYZM`]: Get, New, and Set the X, Y, Z, and M coordinates of a point
148//!
149//! **Utilities**
150//!
151//! You probably won't have to implement these. Created for convenience.
152//!
153//! - [`crate::MValueCompatible`]: Descriptor of all the traits that make using M-Value tools simple
154//! - [`crate::Bounded`]: Used by [`BBox`] and [`BBox3D`]. Defines a min and max value.
155//! - [`crate::Interpolate`]: Easy access to interpolation tooling for All S2JSON Core Types
156//!
157//! ### Derives
158//!
159//! - [`crate::MValueCompatible`]: Ensure M implements All MValue Traits used by VectorPoints
160//! - [`crate::JSONPropertiesCompatible`]: Ensure M implements All MValue Traits used by complex GeoJSON properties. Not used by gis-tools.
161//! - [`crate::Properties`]: Ensure M implements All MValue Traits used by VectorPoints
162//! - [`crate::MValue`]: Ensure M implements All MValue Traits used by VectorPoints
163//! - [`crate::ValuePrimitive`]: Sub type used by [`crate::MValue`]
164//! - [`crate::JSONProperties`]: JSON Properties specification to-from mechanics
165
166extern crate s2json_core;
167#[cfg(feature = "derive")]
168extern crate s2json_derive;
169
170pub use s2json_core::*;
171#[cfg(feature = "derive")]
172pub use s2json_derive::*;