Expand description
This crate holds the types and utilities shared across the workspace: the asset codec identifiers, the payload header record that both the encoder and the reader serialize through, and the deterministic LCG behind every reproducible test/bench sampler.
Modules§
- presets
- The canonical preset recipe table. Every preset asset the workspace
ships is described here exactly once, as a
Recipeconstant; the builder presets (utz_build::Config), thegen-presetcommand, and the data crates’ recipe guards all consume this table instead of restating the numbers.
Structs§
- Lcg
- A minimal MMIX LCG for reproducible test/bench data (not for cryptography). Callers keep their own seeds so historical sequences stay bit-identical.
- Payload
Header - The container’s one fixed header record, which carries everything the
reader needs to locate every section. It sits in PLAINTEXT right after
the outer header (only the section blob after it is compressed), so
any container is inspectable and validated before decompression. The
encoder
Pwrites it, the readerPreads it (both little-endian); field order is the wire order; all offsets are relative to the section blob that follows.
Enums§
- CellTag
- One decoded primary-grid cell. The wire form is the u16 the constants above describe; this decoder is shared by the runtime lookup, the format validator, and the encoder’s measurement tools, so the tag layout is interpreted in exactly one place.
- Codec
- The compression applied to an asset’s payload. The encoder picks one codec; loading the asset needs the matching decoder compiled in.
- Dataset
- The dataset an asset was built from, naming a
timezone-boundary-builder release as a zone set × ocean coverage
pair. The zone set trades zone count for historical fidelity:
nowand1970merge zones whose rules are identical since that date, andallkeeps every distinct tzid. Ocean coverage decides whether maritime timezones tile the rest of the planet or queries at sea returnNone. (The discriminants keep the wire bitfield: the zone set lives in bits 0–1, and a set bit 2 means land-only.) - Geom
Encoding - The geometry encoding, which decides how an asset stores its polygons and how lookups read them.
- Quant
Bits - The coordinate quantization width, which is how many bits each stored coordinate occupies (the wire value IS the bit count).
- Simplify
Algorithm - The simplification algorithm records which simplifier the encoder ran
when the asset was generated. Each variant sketches its algorithm;
guarantees, citations, and the density-weighted variants are
documented in the
utz_simplifycrate.
Constants§
- BORDER_
FLAG - A primary-grid cell’s border flag: the u16’s high bit set means the low 15 bits index a candidate list instead of naming a zone.
- CELL_
ID_ MASK - The mask selecting a primary-grid cell’s 15-bit value, a zone id or
(under
BORDER_FLAG) a candidate-list index. Zone ids and list indices stay strictly belowNO_ZONE, the all-bits-set sentinel. - KM_
PER_ DEG - Kilometers per degree,
METERS_PER_DEGscaled; area math usesKM_PER_DEG²(with a latitude cosine) for km² per square degree. - MAGIC
- The magic bytes every
.utzasset starts with. The bytes are ASCII on purpose (“μ” is 2 bytes in UTF-8 and byte literals reject non-ASCII): the project brands itself as μTZ, and the container as uTZ1. - METERS_
PER_ DEG - Meters per degree of latitude (and of longitude at the equator):
the workspace’s one flat conversion between tolerances in meters
(
epsilon_m) and coordinate degrees. - MMIX_
ADD - Knuth’s MMIX LCG increment.
- MMIX_
MUL - Knuth’s MMIX LCG multiplier (TAOCP vol. 2, 3rd ed., §3.3.4 table 1).
- NO_ZONE
- The primary grid table’s “no zone covers this cell” marker (all 15 id bits set). Zone/feature ids stay strictly below it; the u16’s high bit flags a border cell carrying a candidate-list index instead.
- PAYLOAD_
HEADER_ LEN PayloadHeader’s serialized size. The section blob starts atPROLOGUE_LEN + PAYLOAD_HEADER_LEN.- PAYLOAD_
SEED - The workspace-wide seed for pseudo-random payload bytes in codec
roundtrip tests (ASCII
uztrip). - POINT_
SEED - The workspace-wide seed for
gen_pts()point sampling. Every bench and measurement command draws the same point sequence from it, so lookup numbers stay comparable across tools. - PROLOGUE_
LEN - The byte length of the container prologue, which is
MAGIC(4),VERSION(1), and 3 reserved bytes. The prologue is the only part of the format whose layout is frozen across versions; everything after it isVERSION-specific. - VERSION
- The container-format version this workspace reads and writes; a reader refuses any other value.
Functions§
- dq_lat
- Dequantizes a latitude from a grid with half-range
qmax, the inverse ofq_lat(). - dq_lon
- Dequantizes a longitude from a grid with half-range
qmax, the inverse ofq_lon(). The input isf64so fractional grid positions (e.g. ring intersection points) dequantize too; stored coordinates pass throughf64::from. - gen_pts
alloc - Generates
countuniform world points(lon, lat)fromseed. This is the shared sampler behind the measurement commands and benches: the same seed gives the same points, so numbers stay comparable across tools. - grid_
cell - The primary-grid cell containing a lon/lat position, as
(row, col): truncate toward zero, then clamp into the grid. The encoder’s rasterizer, the runtime reader, and the measurement tools all share this one formula, so what a lookup probes is exactly what the grid indexed. - q_lat
- Quantizes a latitude onto a grid with half-range
qmax. - q_lon
- Quantizes a longitude onto a grid with half-range
qmax(seeqmax_for()). - qmax_
for - The half-range of an
i{bits}quantization grid (2^(bits-1) - 1).