Expand description
The μTZ builder library generates custom .utz assets from a
build.rs.
Everything routes through the typed builder, Config. In a
build.rs (with utz_build as a build-dependency):
utz_build::Config::new()
.dataset(utz_build::Dataset::Now)
.epsilon_meters(500.0) // simplification tolerance ceiling
.quant_bits(24) // 16 / 24 / 32
.codec(utz_build::Codec::Gzip)
.generate()?; // writes $OUT_DIR/tz.utz (+ .guard.rs)The utz crate’s “Building a custom asset” section is the
full walkthrough: embedding the asset, the guard file, and matching
reader features. Every knob is a Config method; everything else
this crate exposes (source loading, density weighting) is machinery
those methods drive.
§Source data
Sources download on first use into a per-user cache directory
($XDG_CACHE_HOME/utz_build, overridable with UTZ_CACHE_DIR or
Config::cache_dir(); see
cache_dir()) and are revalidated with conditional GETs: the
timezone-boundary-builder GeoJSON (tens of MB per dataset,
ODbL), and for density-weighted recipes the GHS-POP population
raster (~460 MB once, CC BY 4.0). Set UTZ_TZBB_RELEASE to pin a
TZBB release for reproducible builds (see loader).
§Datasets
The source data is OSM timezone-boundary-builder. The dataset
picks which TZBB release an asset is generated from and is baked
in at generation time. Its two knobs are the zone set and ocean
coverage: now and 1970 merge zones whose rules are identical
since that date, all keeps every distinct tzid, and a land-
prefix selects the land-only releases (oceans are covered by
default).
| zone set | zones | land- zones | merge |
|---|---|---|---|
now | 64 | 63 | zones identical from today onward merged |
1970 | 304 | 301 | zones identical since 1970 merged |
all | 444 | 419 | every distinct tzid kept |
Dropping the oceans does not shrink an asset: the shared-arc
geometry encodings make ocean coverage nearly free, and the
land- variants actually measure slightly bigger (at the tiny
recipe’s knobs, uncompressed: land-now 89.7 KiB vs now
86.7 KiB). Their best use is coarse (grid-only) assets that will
only ever be queried for land coordinates: a coarse asset answers
at cell precision, and with oceans covered a land point near the
coast resolves to the ocean timezone whenever most of its cell is
ocean; without ocean zones the cell keeps the land answer.
§Related crates
The utz_build_cli binary (gen and gen-preset, the CLI
counterpart of a build.rs) lives in its own crate: it carries the
runtime-reader dependency, so this library stays reader-free and
build scripts are not rebuilt by reader-only changes. The generated
assets are read by utz; the repo-internal measurement
and viewer tooling lives in the unpublished utz_dev_cli and
utz_viz crates.
Re-exports§
Modules§
- config
- The consumer-facing builder API for the
customtier, where the typed config IS the build config (rustdoc’d, IDE-completable, with no file discovery). It is meant for a consumerbuild.rswithutz_buildas a build-dependency (theprost-buildpattern): - density
- Population density for density-weighted simplification (GHS-POP R2023A).
- download
- The conditional-GET download cache stores
ETag/Last-Modifiednext to each cached file and revalidates withIf-None-Match/If-Modified-Since; a 304 reuses the cache untouched. - error
- The builder error type follows the workspace error pattern (see
utz::Error): the derives come fromderive_more, foreign errors enter viaderive_more::From, and domain variants are#[from(skip)]. Library paths use typed variants; the measurement tools inutz_dev_climay useError::Msgfor one-off messages. - loader
- This module loads the source data. The source is OSM
timezone-boundary-builder; datasets pick ocean cover (with-oceans or
land-only) and the zone set:
now(64 zones, default),1970(304 zones), orall(444 zones). - 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.
Macros§
Structs§
- Feat
- One timezone feature as loaded from the source
GeoJSON: it carries the polygons plus the tzid and UTC offset metadata.
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.
- 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.
Functions§
- cache_
dir - Returns the source-data cache directory, resolved at call time as the first match in this chain:
- dataset
- Parses a dataset name (
[land-]now|1970|all):Dataset::from_name()with this crate’s error type. - encode_
weighted - Runs
encode::encode()with population-density-weighted simplification. The per-edge ε multiplier is a simplification knob, so it lives here with the density code;utz_encodeitself stays density-agnostic (see theencode::encode()docs). - load
- Loads a dataset via the download+
GeoJSONpipeline (conditional-GET cached). - load_
with_ release - Runs
load()and also returns the TZBB release tag the features came from, for stamping container headers (provenance). The tag is"dev"when the source isn’t a pinned release (the offline fallback). - load_
with_ release_ in - Runs
load_with_release()against an explicit cache directory instead of thecache_dir()chain.