Expand description
The self-describing container serializer.
The layout is as follows (all little-endian):
prologue: magic "uTZ1" | version u8 | 3 reserved bytes — format identity,
the only layout frozen across versions
header: one fixed [`PayloadHeader`] record (utz_common), PLAINTEXT —
codec, decompressed size, every section offset and count; the
encoder Pwrites it, the reader Preads it (before decompressing
anything), so the field list IS the wire layout
sections (compressed per the header's codec):
zone table: str_offsets u16[n_features+1] | tzid pool bytes (zone i = feature i)
arc store: arc_offsets u32[n_arcs+1] (relative to arc data)
| per arc: varint vcount | first vertex i{16,24,32}×2
| zigzag-varint deltas
ring index: parent u16[n_polys] + poly_offsets u32[n_polys+1]
(relative to ring data) — grid candidates are polys
| per feature: npolys u16; per poly: bbox i{16,24,32}×4
| nrings u16; per ring: varint nrefs | varint signed arc refs
(id<<1|rev)
grid: primary u16[ncols*nrows]
| list_offsets u16[uniq+1] | list_ids u16[Σ]
release: the TZBB release string bytes (the payload tail)The header records every knob, so the runtime decoder stays generic. The grid and bboxes are derived from the QUANTIZED geometry, so what the runtime PIPs is exactly what the grid indexed.
Structs§
- Params
- The parameters of one encode run: they carry the recipe knobs plus the provenance recorded in the asset’s header.
- Payload
Stats - The byte size of each payload section plus post-simplification geometry counts: these are the viewer’s “delta+varint” stage stats.
Enums§
- 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§
- 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. - PAYLOAD_
HEADER_ LEN PayloadHeader’s serialized size. The section blob starts atPROLOGUE_LEN + PAYLOAD_HEADER_LEN.- 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§
- build_
payload - Builds everything but the outer header and compression, so size sweeps can compress one payload with several codecs.
- compress
- Compress
rawwithcodec(body only, no outer header). - encode
- Runs the full uniform-ε pipeline: topology → RDP → quantize → grid →
serialize → compress. Spatially varying tolerance (population weighting)
is a simplification concern, not a serialization one: build the topology
yourself (
topo::build_topology_weighted()) and usepayload_from_topology()andfinish()(seeutz_build’s wrapper). - finish
- Prepend the outer header, compressing the payload with
codec. - payload_
from_ topology - Serializes an already-simplified topology: quantize → grid → sections.
arc_coordsmay differ fromtopology.arc_coords(the wasm viewer simplifies per-arc itself);featssupplies only per-feature metadata (tzid, offset). Geometry comes from the arcs.params.epsilon_mis recorded in the header, not applied. - push_
fixed - Appends one fixed-width coordinate at the quant width: the value’s low 2, 3, or 4 little-endian bytes for i16, i24, and i32 quantization. Public so the runtime crate’s coordinate-unpacking tests can round-trip against the encoder’s real byte layout instead of a mirror copy.
- to_
simplify - Builds the ε-driven
Simplifyfor the topology builder: ε is a max deviation in degrees for RDP and Imai–Iri, and Visvalingam’s area threshold is derived as ε². The viewer uses the same convention, so parameters found in the viewer plug straight into build scripts.