Skip to main content

Module encode

Module encode 

Source
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.
PayloadStats
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: now and 1970 merge zones whose rules are identical since that date, and all keeps every distinct tzid. Ocean coverage decides whether maritime timezones tile the rest of the planet or queries at sea return None. (The discriminants keep the wire bitfield: the zone set lives in bits 0–1, and a set bit 2 means land-only.)
GeomEncoding
The geometry encoding, which decides how an asset stores its polygons and how lookups read them.
QuantBits
The coordinate quantization width, which is how many bits each stored coordinate occupies (the wire value IS the bit count).
SimplifyAlgorithm
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_simplify crate.

Constants§

MAGIC
The magic bytes every .utz asset 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 at PROLOGUE_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 is VERSION-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 raw with codec (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 use payload_from_topology() and finish() (see utz_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_coords may differ from topology.arc_coords (the wasm viewer simplifies per-arc itself); feats supplies only per-feature metadata (tzid, offset). Geometry comes from the arcs. params.epsilon_m is 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 Simplify for 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.