Skip to main content

Crate utz_build

Crate utz_build 

Source
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 setzonesland- zonesmerge
now6463zones identical from today onward merged
1970304301zones identical since 1970 merged
all444419every 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.

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§

pub use error::Error;
pub use error::Result;
pub use config::Config;

Modules§

config
The consumer-facing builder API for the custom tier, where the typed config IS the build config (rustdoc’d, IDE-completable, with no file discovery). It is meant for a consumer build.rs with utz_build as a build-dependency (the prost-build pattern):
density
Population density for density-weighted simplification (GHS-POP R2023A).
download
The conditional-GET download cache stores ETag / Last-Modified next to each cached file and revalidates with If-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 from derive_more, foreign errors enter via derive_more::From, and domain variants are #[from(skip)]. Library paths use typed variants; the measurement tools in utz_dev_cli may use Error::Msg for 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), or all (444 zones).
presets
The canonical preset recipe table. Every preset asset the workspace ships is described here exactly once, as a Recipe constant; the builder presets (utz_build::Config), the gen-preset command, and the data crates’ recipe guards all consume this table instead of restating the numbers.

Macros§

ensure
An anyhow-style guard that returns a typed Error.

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: 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.
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.

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_encode itself stays density-agnostic (see the encode::encode() docs).
load
Loads a dataset via the download+GeoJSON pipeline (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 the cache_dir() chain.