utz_common/lib.rs
1//! This crate holds the types and utilities shared across the workspace:
2//! the asset codec identifiers, the payload header record that both the
3//! encoder and the reader serialize through, and the deterministic LCG
4//! behind every reproducible test/bench sampler.
5#![no_std]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7
8use scroll::{Pread, Pwrite};
9
10pub mod presets;
11
12#[cfg(feature = "alloc")]
13extern crate alloc;
14
15#[cfg(feature = "alloc")]
16use alloc::vec::Vec;
17
18/// The magic bytes every `.utz` asset starts with. The bytes are ASCII on
19/// purpose ("μ" is 2 bytes in UTF-8 and byte literals reject non-ASCII):
20/// the project brands itself as μTZ, and the container as uTZ1.
21pub const MAGIC: [u8; 4] = *b"uTZ1";
22/// The container-format version this workspace reads and writes; a reader
23/// refuses any other value.
24pub const VERSION: u8 = 11;
25
26/// The byte length of the container prologue, which is `MAGIC` (4),
27/// `VERSION` (1), and 3 reserved bytes. The prologue is the only part of
28/// the format whose layout is frozen across versions; everything after it
29/// is [`VERSION`]-specific.
30pub const PROLOGUE_LEN: usize = 8;
31
32/// [`PayloadHeader`]'s serialized size. The section blob starts at
33/// `PROLOGUE_LEN + PAYLOAD_HEADER_LEN`.
34pub const PAYLOAD_HEADER_LEN: usize = 64;
35
36/// The primary grid table's "no zone covers this cell" marker (all 15 id
37/// bits set). Zone/feature ids stay strictly below it; the u16's high bit
38/// flags a border cell carrying a candidate-list index instead.
39pub const NO_ZONE: u16 = 0x7FFF;
40
41/// A primary-grid cell's border flag: the u16's high bit set means the
42/// low 15 bits index a candidate list instead of naming a zone.
43pub const BORDER_FLAG: u16 = 0x8000;
44
45/// The mask selecting a primary-grid cell's 15-bit value, a zone id or
46/// (under [`BORDER_FLAG`]) a candidate-list index. Zone ids and list
47/// indices stay strictly below [`NO_ZONE`], the all-bits-set sentinel.
48pub const CELL_ID_MASK: u16 = 0x7FFF;
49
50/// One decoded primary-grid cell. The wire form is the u16 the
51/// constants above describe; this decoder is shared by the runtime
52/// lookup, the format validator, and the encoder's measurement tools,
53/// so the tag layout is interpreted in exactly one place.
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub enum CellTag {
56 /// No zone covers the cell.
57 Empty,
58 /// A single zone covers the cell; a lookup answers without any
59 /// point-in-polygon test.
60 Zone(u16),
61 /// A zone boundary passes through the cell; the value indexes the
62 /// cell's candidate list.
63 Border(u16),
64}
65
66impl CellTag {
67 /// Decodes a primary-table cell value.
68 #[must_use]
69 pub const fn from_cell(cell: u16) -> CellTag {
70 if cell & BORDER_FLAG != 0 {
71 CellTag::Border(cell & CELL_ID_MASK)
72 } else if cell == NO_ZONE {
73 CellTag::Empty
74 } else {
75 CellTag::Zone(cell)
76 }
77 }
78}
79
80/// Meters per degree of latitude (and of longitude at the equator):
81/// the workspace's one flat conversion between tolerances in meters
82/// (`epsilon_m`) and coordinate degrees.
83pub const METERS_PER_DEG: f64 = 111_320.0;
84
85/// Kilometers per degree, [`METERS_PER_DEG`] scaled; area math uses
86/// `KM_PER_DEG²` (with a latitude cosine) for km² per square degree.
87pub const KM_PER_DEG: f64 = METERS_PER_DEG / 1000.0;
88
89/// The half-range of an `i{bits}` quantization grid (`2^(bits-1) - 1`).
90#[must_use]
91#[expect(
92 clippy::cast_precision_loss,
93 reason = "qmax = 2^(bits-1)-1 ≤ 2^31-1, exact in f64"
94)]
95pub const fn qmax_for(bits: u32) -> f64 {
96 ((1u64 << (bits - 1)) - 1) as f64
97}
98
99/// Rounds half away from zero via the truncating cast: `core` has no
100/// `f64::round`, and the encoder shares this exact expression with the
101/// reader's lookup quantizer so the two stay bit-identical.
102#[expect(
103 clippy::cast_possible_truncation,
104 reason = "callers bound |value| below i32::MAX; float as saturates"
105)]
106fn round_q(value: f64) -> i32 {
107 (value + if value >= 0.0 { 0.5 } else { -0.5 }) as i32
108}
109
110/// Quantizes a longitude onto a grid with half-range `qmax` (see
111/// [`qmax_for()`]).
112#[must_use]
113pub fn q_lon(lon: f64, qmax: f64) -> i32 {
114 round_q(lon / 180.0 * qmax)
115}
116
117/// Quantizes a latitude onto a grid with half-range `qmax`.
118#[must_use]
119pub fn q_lat(lat: f64, qmax: f64) -> i32 {
120 round_q(lat / 90.0 * qmax)
121}
122
123/// Dequantizes a longitude from a grid with half-range `qmax`, the
124/// inverse of [`q_lon()`]. The input is `f64` so fractional grid
125/// positions (e.g. ring intersection points) dequantize too; stored
126/// coordinates pass through `f64::from`.
127#[must_use]
128pub fn dq_lon(value: f64, qmax: f64) -> f64 {
129 value / qmax * 180.0
130}
131
132/// Dequantizes a latitude from a grid with half-range `qmax`, the
133/// inverse of [`q_lat()`].
134#[must_use]
135pub fn dq_lat(value: f64, qmax: f64) -> f64 {
136 value / qmax * 90.0
137}
138
139/// The primary-grid cell containing a lon/lat position, as `(row, col)`:
140/// truncate toward zero, then clamp into the grid. The encoder's
141/// rasterizer, the runtime reader, and the measurement tools all share
142/// this one formula, so what a lookup probes is exactly what the grid
143/// indexed.
144#[must_use]
145pub fn grid_cell(lon: f64, lat: f64, deg: f64, ncols: usize, nrows: usize) -> (usize, usize) {
146 #[expect(
147 clippy::cast_possible_truncation,
148 clippy::cast_sign_loss,
149 clippy::cast_possible_wrap,
150 reason = "cast saturates, then the clamp keeps the index in grid range"
151 )]
152 let cell = (
153 (((lat + 90.0) / deg) as i64).clamp(0, nrows as i64 - 1) as usize,
154 (((lon + 180.0) / deg) as i64).clamp(0, ncols as i64 - 1) as usize,
155 );
156 cell
157}
158
159/// The container's one fixed header record, which carries everything the
160/// reader needs to locate every section. It sits in PLAINTEXT right after
161/// the outer header (only the section blob after it is compressed), so
162/// any container is inspectable and validated before decompression. The
163/// encoder `Pwrite`s it, the reader `Pread`s it (both little-endian);
164/// field order is the wire order; all offsets are relative to the section
165/// blob that follows.
166///
167/// The section blob is laid out as the zone-string offsets and pool, the
168/// geometry-dependent sections at the stored offsets, the grid tables, and
169/// the TZBB release string at `release_off`.
170#[derive(Debug, Clone, Copy, PartialEq, Pread, Pwrite)]
171pub struct PayloadHeader {
172 /// The offset of the arc store (geom 0/1) or of the `FullRings`
173 /// coordinates (geom 2, 4-aligned).
174 pub arcs_off: u32,
175 /// The offset of the poly→feature parent table (plus the ring records
176 /// for geom 0/1).
177 pub rings_off: u32,
178 /// The offset of the grid tables, which hold the primary cells
179 /// followed by the CSR list offsets and ids.
180 pub grid_off: u32,
181 /// The offset of the TZBB release string (`release_len` bytes at the
182 /// payload tail).
183 pub release_off: u32,
184 /// The eager-cache reservation counts, which give exact Vec sizes for
185 /// `preload()` (the coords count is Σ referenced-arc vertex counts and
186 /// may only over-estimate).
187 pub eager_coords: u32,
188 pub eager_rings: u32,
189 pub eager_polys: u32,
190 /// The arc count (geom 0/1), which is zero when there is no arc store.
191 pub n_arcs: u32,
192 /// The section blob's decompressed size (so readers allocate once).
193 pub raw_len: u32,
194 /// The grid cell size in degrees; fractional sizes (e.g. 0.5) are
195 /// allowed.
196 pub grid_deg: f32,
197 /// The simplification tolerance the asset was built with (provenance).
198 pub epsilon_m: f32,
199 pub n_features: u16,
200 /// The grid's column count.
201 pub ncols: u16,
202 /// The grid's row count.
203 pub nrows: u16,
204 /// The number of distinct border-cell candidate lists (CSR).
205 pub uniq: u16,
206 pub release_len: u16,
207 /// This field is reserved and must be zero (room for future format
208 /// flags).
209 pub flags: u16,
210 pub dataset: Dataset,
211 pub quant_bits: QuantBits,
212 pub simplify_algorithm: SimplifyAlgorithm,
213 pub geom: GeomEncoding,
214 /// The section blob's compression codec.
215 pub codec: Codec,
216 /// The population-density weight floor in fixed-point 1e-4, where 0
217 /// means unweighted and 10000 means 1.0. Like `epsilon_m`, it is
218 /// provenance for the density-weighted simplification knob.
219 pub density_weight_floor_e4: u16,
220 /// This byte is reserved and must be zero (it pads the header to 64
221 /// bytes).
222 pub reserved: u8,
223}
224
225impl PayloadHeader {
226 /// Parses the plaintext header out of a complete asset, checking the
227 /// prologue first (magic + [`VERSION`]). The result is `None` if the
228 /// bytes are too short, not a μTZ asset, or a different format
229 /// version. The parse reads only the first
230 /// `PROLOGUE_LEN + PAYLOAD_HEADER_LEN` bytes, which makes it cheap
231 /// provenance sniffing without decompression.
232 #[must_use]
233 pub fn from_asset(bytes: &[u8]) -> Option<PayloadHeader> {
234 if bytes.len() < PROLOGUE_LEN + PAYLOAD_HEADER_LEN
235 || bytes[..4] != MAGIC
236 || bytes[4] != VERSION
237 {
238 return None;
239 }
240 bytes.pread_with(PROLOGUE_LEN, scroll::LE).ok()
241 }
242}
243
244/// The coordinate quantization width, which is how many bits each stored
245/// coordinate occupies (the wire value IS the bit count).
246#[derive(Debug, Clone, Copy, PartialEq, Eq, Pread, Pwrite)]
247#[repr(u8)]
248pub enum QuantBits {
249 Bits16 = 16,
250 Bits24 = 24,
251 Bits32 = 32,
252}
253
254impl QuantBits {
255 /// The width in bits.
256 #[must_use]
257 pub const fn bits(self) -> u32 {
258 self as u32
259 }
260
261 /// The number of bytes per stored coordinate (2 / 3 / 4).
262 #[must_use]
263 pub const fn bytes(self) -> usize {
264 (self as usize) / 8
265 }
266
267 /// The width a header byte names, if any.
268 #[must_use]
269 pub const fn from_byte(byte: u8) -> Option<QuantBits> {
270 match byte {
271 16 => Some(QuantBits::Bits16),
272 24 => Some(QuantBits::Bits24),
273 32 => Some(QuantBits::Bits32),
274 _ => None,
275 }
276 }
277}
278
279/// The geometry encoding, which decides how an asset stores its polygons
280/// and how lookups read them.
281///
282/// The three polygon encodings answer bit-identically; they trade storage
283/// for lookup speed. `Coarse` alone trades precision instead: it drops the
284/// polygons and answers at grid-cell precision.
285///
286/// The measured cost/speed ladder lives here. Every other doc site links
287/// back to this table rather than restating numbers. Size columns are
288/// whole assets relative to the `VarintArcs` build of the same preset;
289/// lookup speed is the flash-XIP (execute-in-place, zero RAM) leg of the
290/// embedded bench, against the same baseline.
291///
292/// | encoding | geometry section | raw | best-compressed | XIP lookup |
293/// |------------------|-------------------------------------------|-----------:|----------------:|-----------------|
294/// | `VarintArcs` | shared arcs, delta + zigzag-varint coords | 1× | 1× | 1× |
295/// | `FixedWidthArcs` | shared arcs, absolute quant-width coords | 1.4–1.7× | 1.15–1.3× (xz) | 1.3–1.5× |
296/// | `FullRings` | whole rings, absolute quant-width coords | 2.1–3.2× | 1.4–2.1× (xz) | 2.0–3.3× |
297/// | `Coarse` | none (grid only) | 0.05–0.33× | 0.01–0.14× | grid probe only |
298///
299/// Narrow-quant `FullRings` XIP even outran the RAM preload cache on the
300/// embedded bench. On fixed-width payloads the codec ranking flips: xz
301/// overtakes brotli at every preset. `Coarse` shrinks with preset fineness
302/// twice over: the grid is all it keeps, and grids compress extremely well.
303///
304/// The size columns come from `utz_dev_cli whittle --extended` (2026-07,
305/// TZBB 2026c), measuring full assets per preset recipe against the
306/// `VarintArcs` build. The XIP
307/// lookup column is from the 2026-07 bench-firmware runs against earlier
308/// payload revisions; read it as a relative ladder.
309// TODO(verify): re-run the XIP lookup column on target against the
310// current payload revisions (last measured 2026-07 on earlier ones).
311#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Pread, Pwrite)]
312#[repr(u8)]
313pub enum GeomEncoding {
314 /// This encoding stores shared arcs as delta + zigzag-varint streams;
315 /// it is the default, for minimal storage size.
316 #[default]
317 VarintArcs = 0,
318 /// This encoding stores shared arcs as absolute fixed-width
319 /// (quant-width) coordinates, so streaming lookups no longer decode a
320 /// varint per vertex, the dominant lookup cost on embedded targets. It
321 /// reaches near-eager speed with no RAM cache and suits uncompressed
322 /// `-static` assets read in place from memory-mapped flash, at a
323 /// storage cost (table above).
324 FixedWidthArcs = 1,
325 /// This encoding stores each ring in full: coordinates are flattened
326 /// per ring as quant-width pairs plus ring/poly index tables, 4-byte
327 /// aligned; it is the preload cache serialized. Slice kernels read it
328 /// in place: from memory-mapped flash via `from_static()`
329 /// (eager-lookup speed with no RAM cache and no preload pass at boot)
330 /// or from the decompressed buffer via `from_slice()`. There is no arc
331 /// store, so borders shared between zones are duplicated per ring,
332 /// making this the largest encoding (table above). It works on
333 /// little-endian hosts only.
334 FullRings = 2,
335 /// A grid-only asset carrying the header, tzid pool, parent table,
336 /// and grid, with no geometry at all. `lookup()` answers at cell
337 /// precision, the same answer `lookup_coarse()` gives; precision is a
338 /// property of the asset, like `epsilon_m`. It is by far the smallest
339 /// storage (table above) and works on any endianness, and a reader
340 /// built only for coarse assets compiles no point-in-polygon code.
341 Coarse = 3,
342}
343
344impl GeomEncoding {
345 /// The canonical CLI name (`varint-arcs`, `fixed-width-arcs`,
346 /// `full-rings`, or `coarse`), a spelling
347 /// [`from_name()`](GeomEncoding::from_name) accepts.
348 #[must_use]
349 pub const fn name(self) -> &'static str {
350 match self {
351 GeomEncoding::VarintArcs => "varint-arcs",
352 GeomEncoding::FixedWidthArcs => "fixed-width-arcs",
353 GeomEncoding::FullRings => "full-rings",
354 GeomEncoding::Coarse => "coarse",
355 }
356 }
357
358 /// The encoding a name selects, the inverse of
359 /// [`name()`](GeomEncoding::name).
360 #[must_use]
361 pub fn from_name(name: &str) -> Option<GeomEncoding> {
362 match name {
363 "varint-arcs" => Some(GeomEncoding::VarintArcs),
364 "fixed-width-arcs" => Some(GeomEncoding::FixedWidthArcs),
365 "full-rings" => Some(GeomEncoding::FullRings),
366 "coarse" => Some(GeomEncoding::Coarse),
367 _ => None,
368 }
369 }
370
371 /// The encoding a header byte names, if any.
372 #[must_use]
373 pub const fn from_byte(byte: u8) -> Option<GeomEncoding> {
374 match byte {
375 0 => Some(GeomEncoding::VarintArcs),
376 1 => Some(GeomEncoding::FixedWidthArcs),
377 2 => Some(GeomEncoding::FullRings),
378 3 => Some(GeomEncoding::Coarse),
379 _ => None,
380 }
381 }
382}
383
384#[cfg_attr(
385 on_docsrs,
386 doc = "[`utz_simplify`]: https://docs.rs/utz_simplify/latest/utz_simplify/index.html"
387)]
388#[cfg_attr(on_docsrs, doc = "")]
389/// The simplification algorithm records which simplifier the encoder ran
390/// when the asset was generated. Each variant sketches its algorithm;
391/// guarantees, citations, and the density-weighted variants are
392/// documented in the [`utz_simplify`] crate.
393///
394/// RDP is the default because I had the best results with it when combined with
395/// the population density weighting. But your mileage may vary, so I kept the
396/// algorithms in for people to play with.
397///
398/// [`utz_simplify`]: ../utz_simplify/index.html
399#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Pread, Pwrite)]
400#[repr(u8)]
401pub enum SimplifyAlgorithm {
402 /// No simplification runs; the geometry is stored as sourced.
403 None = 0,
404 /// Ramer–Douglas–Peucker keeps every point within a maximum deviation
405 /// of ε. This is the default.
406 #[default]
407 Rdp = 1,
408 /// Visvalingam–Whyatt repeatedly drops the vertex spanning the
409 /// smallest triangle, trading RDP's deviation bound for a
410 /// cartographically smoother caricature; the ε-driven pipeline
411 /// derives its area threshold as ε², matching the viewer.
412 Visvalingam = 2,
413 /// Imai–Iri produces provably minimum vertices for the same ε bound
414 /// as RDP, at a slower encode. Measured against RDP on full-planet
415 /// arcs it keeps 3.8% fewer vertices at ε = 100 m, rising to 18–19%
416 /// fewer at ε = 500–2000 m; a full-pipeline check at ε = 2000 m
417 /// produced a 12.6% smaller compressed asset for about four seconds
418 /// of extra encode time.
419 ImaiIri = 3,
420}
421
422impl SimplifyAlgorithm {
423 /// The canonical CLI name (`none|rdp|vw|ii`), a spelling
424 /// [`from_name()`](SimplifyAlgorithm::from_name) accepts.
425 #[must_use]
426 pub const fn name(self) -> &'static str {
427 match self {
428 SimplifyAlgorithm::None => "none",
429 SimplifyAlgorithm::Rdp => "rdp",
430 SimplifyAlgorithm::Visvalingam => "vw",
431 SimplifyAlgorithm::ImaiIri => "ii",
432 }
433 }
434
435 /// The algorithm a name selects: the canonical names plus the long
436 /// `visvalingam` and `imai-iri` aliases.
437 #[must_use]
438 pub fn from_name(name: &str) -> Option<SimplifyAlgorithm> {
439 match name {
440 "none" => Some(SimplifyAlgorithm::None),
441 "rdp" => Some(SimplifyAlgorithm::Rdp),
442 "vw" | "visvalingam" => Some(SimplifyAlgorithm::Visvalingam),
443 "ii" | "imai-iri" => Some(SimplifyAlgorithm::ImaiIri),
444 _ => None,
445 }
446 }
447
448 /// The algorithm a header byte names, if any.
449 #[must_use]
450 pub const fn from_byte(byte: u8) -> Option<SimplifyAlgorithm> {
451 match byte {
452 0 => Some(SimplifyAlgorithm::None),
453 1 => Some(SimplifyAlgorithm::Rdp),
454 2 => Some(SimplifyAlgorithm::Visvalingam),
455 3 => Some(SimplifyAlgorithm::ImaiIri),
456 _ => None,
457 }
458 }
459}
460
461/// The dataset an asset was built from, naming a
462/// [timezone-boundary-builder] release as a zone set × ocean coverage
463/// pair. The zone set trades zone count for historical fidelity: `now`
464/// and `1970` merge zones whose rules are identical since that date,
465/// and `all` keeps every distinct tzid. Ocean coverage decides whether
466/// maritime timezones tile the rest of the planet or queries at sea
467/// return `None`. (The discriminants keep the wire bitfield: the zone
468/// set lives in bits 0–1, and a set bit 2 means land-only.)
469///
470/// [timezone-boundary-builder]: https://github.com/evansiroky/timezone-boundary-builder
471#[derive(Debug, Clone, Copy, PartialEq, Eq, Pread, Pwrite)]
472#[repr(u8)]
473pub enum Dataset {
474 /// Zones whose rules are identical from today onward are merged and
475 /// the oceans are covered. This is the smallest set, and the preset
476 /// default.
477 Now = 0,
478 /// Zones identical since 1970 are merged and the oceans are covered,
479 /// which is enough to resolve any post-1970 civil time correctly.
480 Since1970 = 1,
481 /// Every distinct tzid is kept and the oceans are covered, giving
482 /// full historical fidelity; this is the largest set.
483 All = 2,
484 /// This is `Now` without maritime zones, so queries at sea return
485 /// `None`.
486 NowLandOnly = 4,
487 /// This is `Since1970` without maritime zones.
488 Since1970LandOnly = 5,
489 /// This is `All` without maritime zones.
490 AllLandOnly = 6,
491}
492
493impl Dataset {
494 /// Returns the canonical dataset name (`now`, `1970`, or `all`, with
495 /// a `land-` prefix for the land-only variants), the spelling the
496 /// builder's dataset parser accepts.
497 #[must_use]
498 pub const fn name(self) -> &'static str {
499 match self {
500 Dataset::Now => "now",
501 Dataset::Since1970 => "1970",
502 Dataset::All => "all",
503 Dataset::NowLandOnly => "land-now",
504 Dataset::Since1970LandOnly => "land-1970",
505 Dataset::AllLandOnly => "land-all",
506 }
507 }
508
509 /// The zone-set half of the name (`"now"`, `"1970"`, or `"all"`),
510 /// which picks how aggressively zones with identical rules are
511 /// merged.
512 #[must_use]
513 pub const fn zone_set(self) -> &'static str {
514 match self {
515 Dataset::Now | Dataset::NowLandOnly => "now",
516 Dataset::Since1970 | Dataset::Since1970LandOnly => "1970",
517 Dataset::All | Dataset::AllLandOnly => "all",
518 }
519 }
520
521 /// Whether maritime timezones cover the oceans (`false` names the
522 /// `land-` releases).
523 #[must_use]
524 pub const fn oceans(self) -> bool {
525 matches!(self, Dataset::Now | Dataset::Since1970 | Dataset::All)
526 }
527
528 /// The dataset a name selects (`[land-]now|1970|all`; `full` and
529 /// `comprehensive`, TZBB's own word for the unsuffixed release, are
530 /// accepted for `all`). This is the inverse of
531 /// [`name()`](Dataset::name), kept beside it so the two spellings
532 /// cannot drift apart.
533 #[must_use]
534 pub fn from_name(name: &str) -> Option<Dataset> {
535 let (land_only, rest) = match name.strip_prefix("land-") {
536 Some(stripped) => (true, stripped),
537 None => (false, name),
538 };
539 match (rest, land_only) {
540 ("now", false) => Some(Dataset::Now),
541 ("now", true) => Some(Dataset::NowLandOnly),
542 ("1970", false) => Some(Dataset::Since1970),
543 ("1970", true) => Some(Dataset::Since1970LandOnly),
544 ("all" | "full" | "comprehensive", false) => Some(Dataset::All),
545 ("all" | "full" | "comprehensive", true) => Some(Dataset::AllLandOnly),
546 _ => None,
547 }
548 }
549
550 /// The dataset a header byte names, if any.
551 #[must_use]
552 pub const fn from_byte(byte: u8) -> Option<Dataset> {
553 match byte {
554 0 => Some(Dataset::Now),
555 1 => Some(Dataset::Since1970),
556 2 => Some(Dataset::All),
557 4 => Some(Dataset::NowLandOnly),
558 5 => Some(Dataset::Since1970LandOnly),
559 6 => Some(Dataset::AllLandOnly),
560 _ => None,
561 }
562 }
563}
564
565/// The compression applied to an asset's payload. The encoder picks one
566/// codec; loading the asset needs the matching decoder compiled in.
567#[derive(Clone, Copy, PartialEq, Eq, Debug, Pread, Pwrite)]
568#[repr(u8)]
569pub enum Codec {
570 Uncompressed = 0,
571 Gzip = 1,
572 Zstd = 2,
573 Brotli = 3,
574 Xz = 4,
575}
576
577impl Codec {
578 /// The canonical CLI name (`none|gzip|zstd|brotli|xz`), a spelling
579 /// [`from_name()`](Codec::from_name) accepts.
580 #[must_use]
581 pub const fn name(self) -> &'static str {
582 match self {
583 Codec::Uncompressed => "none",
584 Codec::Gzip => "gzip",
585 Codec::Zstd => "zstd",
586 Codec::Brotli => "brotli",
587 Codec::Xz => "xz",
588 }
589 }
590
591 /// The codec a name selects: the canonical names plus the
592 /// `uncompressed` alias.
593 #[must_use]
594 pub fn from_name(name: &str) -> Option<Codec> {
595 match name {
596 "none" | "uncompressed" => Some(Codec::Uncompressed),
597 "gzip" => Some(Codec::Gzip),
598 "zstd" => Some(Codec::Zstd),
599 "brotli" => Some(Codec::Brotli),
600 "xz" => Some(Codec::Xz),
601 _ => None,
602 }
603 }
604
605 /// The codec a header byte names, if any.
606 #[must_use]
607 pub const fn from_byte(byte: u8) -> Option<Codec> {
608 match byte {
609 0 => Some(Codec::Uncompressed),
610 1 => Some(Codec::Gzip),
611 2 => Some(Codec::Zstd),
612 3 => Some(Codec::Brotli),
613 4 => Some(Codec::Xz),
614 _ => None,
615 }
616 }
617}
618
619/// Knuth's MMIX LCG multiplier (TAOCP vol. 2, 3rd ed., §3.3.4 table 1).
620pub const MMIX_MUL: u64 = 0x5851_F42D_4C95_7F2D; // 6_364_136_223_846_793_005
621/// Knuth's MMIX LCG increment.
622pub const MMIX_ADD: u64 = 0x1405_7B7E_F767_814F; // 1_442_695_040_888_963_407
623
624/// A minimal MMIX LCG for reproducible test/bench data (not for
625/// cryptography). Callers keep their own seeds so historical sequences
626/// stay bit-identical.
627pub struct Lcg(pub u64);
628
629impl Lcg {
630 #[must_use]
631 pub fn new(seed: u64) -> Self {
632 Self(seed)
633 }
634
635 /// Advances and returns the full 64-bit state.
636 pub fn next_u64(&mut self) -> u64 {
637 self.0 = self.0.wrapping_mul(MMIX_MUL).wrapping_add(MMIX_ADD);
638 self.0
639 }
640
641 /// Returns a uniform value in [0, 1) via a 53-bit mantissa
642 /// construction.
643 #[expect(
644 clippy::cast_precision_loss,
645 reason = "53-bit mantissa construction: state>>11 < 2^53 and 2^53 are both exact"
646 )]
647 pub fn unit_f64(&mut self) -> f64 {
648 (self.next_u64() >> 11) as f64 / (1u64 << 53) as f64
649 }
650}
651
652/// The workspace-wide seed for `gen_pts()` point sampling. Every bench
653/// and measurement command draws the same point sequence from it, so
654/// lookup numbers stay comparable across tools.
655pub const POINT_SEED: u64 = 0x1234_5678;
656
657/// The workspace-wide seed for pseudo-random payload bytes in codec
658/// roundtrip tests (ASCII `uztrip`).
659pub const PAYLOAD_SEED: u64 = 0x757a_7472_6970;
660
661/// Generates `count` uniform world points `(lon, lat)` from `seed`. This
662/// is the shared sampler behind the measurement commands and benches: the
663/// same seed gives the same points, so numbers stay comparable across
664/// tools.
665#[cfg(feature = "alloc")]
666#[must_use]
667pub fn gen_pts(seed: u64, count: usize) -> Vec<(f64, f64)> {
668 let mut lcg = Lcg::new(seed);
669 (0..count)
670 .map(|_| {
671 (
672 lcg.unit_f64() * 360.0 - 180.0,
673 lcg.unit_f64() * 180.0 - 90.0,
674 )
675 })
676 .collect()
677}
678
679#[cfg(test)]
680mod tests {
681 use scroll::{LE, Pread, Pwrite};
682
683 use super::{
684 Codec, Dataset, GeomEncoding, PAYLOAD_HEADER_LEN, PayloadHeader, QuantBits,
685 SimplifyAlgorithm,
686 };
687
688 #[test]
689 fn enum_names_round_trip_through_from_name() {
690 for dataset in [
691 Dataset::Now,
692 Dataset::Since1970,
693 Dataset::All,
694 Dataset::NowLandOnly,
695 Dataset::Since1970LandOnly,
696 Dataset::AllLandOnly,
697 ] {
698 assert_eq!(Dataset::from_name(dataset.name()), Some(dataset));
699 }
700 for codec in [
701 Codec::Uncompressed,
702 Codec::Gzip,
703 Codec::Zstd,
704 Codec::Brotli,
705 Codec::Xz,
706 ] {
707 assert_eq!(Codec::from_name(codec.name()), Some(codec));
708 }
709 for algorithm in [
710 SimplifyAlgorithm::None,
711 SimplifyAlgorithm::Rdp,
712 SimplifyAlgorithm::Visvalingam,
713 SimplifyAlgorithm::ImaiIri,
714 ] {
715 assert_eq!(
716 SimplifyAlgorithm::from_name(algorithm.name()),
717 Some(algorithm)
718 );
719 }
720 for geom in [
721 GeomEncoding::VarintArcs,
722 GeomEncoding::FixedWidthArcs,
723 GeomEncoding::FullRings,
724 GeomEncoding::Coarse,
725 ] {
726 assert_eq!(GeomEncoding::from_name(geom.name()), Some(geom));
727 }
728 assert_eq!(
729 Dataset::from_name("land-1970"),
730 Some(Dataset::Since1970LandOnly)
731 );
732 assert_eq!(Dataset::from_name("nowhere"), None);
733 // pre-publish legacy spellings are gone
734 assert_eq!(Dataset::from_name("osm"), None);
735 assert_eq!(Dataset::from_name("osm1970"), None);
736 assert_eq!(GeomEncoding::from_name("eager"), None);
737 assert_eq!(GeomEncoding::from_name("varint"), None);
738 }
739
740 #[test]
741 fn payload_header_round_trips_at_declared_length() {
742 let header = PayloadHeader {
743 arcs_off: 1,
744 rings_off: 2,
745 grid_off: 3,
746 release_off: 4,
747 eager_coords: 5,
748 eager_rings: 6,
749 eager_polys: 7,
750 n_arcs: 8,
751 raw_len: 14,
752 grid_deg: 0.5,
753 epsilon_m: 50.0,
754 n_features: 9,
755 ncols: 10,
756 nrows: 11,
757 uniq: 12,
758 release_len: 13,
759 flags: 0,
760 dataset: Dataset::Now,
761 quant_bits: QuantBits::Bits24,
762 simplify_algorithm: SimplifyAlgorithm::Rdp,
763 geom: GeomEncoding::FixedWidthArcs,
764 codec: Codec::Brotli,
765 density_weight_floor_e4: 200,
766 reserved: 0,
767 };
768 let mut bytes = [0u8; PAYLOAD_HEADER_LEN];
769 let written = bytes
770 .pwrite_with(header, 0, LE)
771 .expect("buffer sized to the declared length");
772 assert_eq!(written, PAYLOAD_HEADER_LEN);
773 let read: PayloadHeader = bytes
774 .pread_with(0, LE)
775 .expect("round-trip read of a full buffer");
776 assert_eq!(read, header);
777 }
778
779 #[test]
780 fn invalid_header_byte_fails_the_read() {
781 let header = PayloadHeader {
782 arcs_off: 0,
783 rings_off: 0,
784 grid_off: 0,
785 release_off: 0,
786 eager_coords: 0,
787 eager_rings: 0,
788 eager_polys: 0,
789 n_arcs: 0,
790 raw_len: 0,
791 grid_deg: 1.0,
792 epsilon_m: 0.0,
793 n_features: 0,
794 ncols: 0,
795 nrows: 0,
796 uniq: 0,
797 release_len: 0,
798 flags: 0,
799 dataset: Dataset::Now,
800 quant_bits: QuantBits::Bits16,
801 simplify_algorithm: SimplifyAlgorithm::None,
802 geom: GeomEncoding::VarintArcs,
803 codec: Codec::Uncompressed,
804 density_weight_floor_e4: 0,
805 reserved: 0,
806 };
807 let mut bytes = [0u8; PAYLOAD_HEADER_LEN];
808 bytes
809 .pwrite_with(header, 0, LE)
810 .expect("buffer sized to the declared length");
811 bytes[57] = 17; // quant_bits: no such width
812 assert!(bytes.pread_with::<PayloadHeader>(0, LE).is_err());
813 bytes[57] = 16;
814 bytes[56] = 3; // dataset: zone-set code 3 is unassigned
815 assert!(bytes.pread_with::<PayloadHeader>(0, LE).is_err());
816 bytes[56] = 0;
817 bytes[60] = 9; // codec: no such codec
818 assert!(bytes.pread_with::<PayloadHeader>(0, LE).is_err());
819 }
820}