Skip to main content

utz_encode/
types.rs

1//! The shared geometry types and quantization helpers for the encoder and
2//! the measurement tools.
3
4// Coordinate tuples are (lon, lat) — equivalently (x, y) with x = lon —
5// everywhere in the workspace: builder f64 degrees and quantized i32 grid
6// units alike. The aliases carry the semantic split: a Ring is closed
7// (implicitly; no duplicated closing vertex), an Arc is an open polyline
8// shared between the rings that reference it.
9/// One closed ring. The closing vertex is not duplicated.
10pub type Ring<T = f64> = Vec<(T, T)>;
11/// One polygon's rings, the exterior ring first and the interior (hole)
12/// rings after.
13pub type Poly<T = f64> = Vec<Ring<T>>;
14/// One open shared-boundary polyline (see `topo`). This is NOT
15/// `std::sync::Arc`.
16pub type Arc<T = f64> = Vec<(T, T)>;
17
18/// One timezone feature as loaded from the source `GeoJSON`: it carries the
19/// polygons plus the tzid and UTC offset metadata.
20pub struct Feat {
21    /// The UTC offset in hours (fractional values allowed), which serves
22    /// ocean zones without a tzid.
23    pub offset: f64,
24    /// The IANA timezone id, or `None` for pure-offset ocean zones.
25    pub tzid: Option<String>,
26    /// The feature's polygons (exterior ring first, holes after).
27    pub polys: Vec<Poly>,
28}
29
30// i24 absolute global grid (~2.4 m lon / 1.2 m lat) — default; topo::encode_topology_q
31// takes a `qbits` for i16/i24/i32.
32//
33// There is no native i24 type: quantized coords are STORED at i24 width in
34// the container (see `push_i24`/`fixed_bytes`) but live in i32 in memory —
35// these helpers quantize at the i24 default width, hence the names. The
36// variable-width equivalents are local closures over a `qmax` (encode/topo).
37pub use utz_common::{KM_PER_DEG, METERS_PER_DEG, dq_lat, dq_lon, q_lat, q_lon, qmax_for};
38
39pub const QMAX_I24: f64 = qmax_for(24);
40
41#[must_use]
42pub fn q24_lon(lon: f64) -> i32 {
43    q_lon(lon, QMAX_I24)
44}
45#[must_use]
46pub fn q24_lat(lat: f64) -> i32 {
47    q_lat(lat, QMAX_I24)
48}
49
50/// Appends `value`'s low three little-endian bytes, the stored form of an
51/// i24-quantized coordinate.
52pub fn push_i24(out: &mut Vec<u8>, value: i32) {
53    let bytes = value.to_le_bytes();
54    out.extend_from_slice(&bytes[0..3]);
55}
56#[must_use]
57pub fn read_i24(bytes: &[u8]) -> i32 {
58    let mut value = i32::from(bytes[0]) | (i32::from(bytes[1]) << 8) | (i32::from(bytes[2]) << 16);
59    if value & 0x0080_0000 != 0 {
60        value |= !0x00FF_FFFF;
61    }
62    value
63}