#[repr(u8)]pub enum GeomEncoding {
VarintArcs = 0,
FixedWidthArcs = 1,
FullRings = 2,
Coarse = 3,
}Expand description
The geometry encoding, which decides how an asset stores its polygons and how lookups read them.
The three polygon encodings answer bit-identically; they trade storage
for lookup speed. Coarse alone trades precision instead: it drops the
polygons and answers at grid-cell precision.
The measured cost/speed ladder lives here. Every other doc site links
back to this table rather than restating numbers. Size columns are
whole assets relative to the VarintArcs build of the same preset;
lookup speed is the flash-XIP (execute-in-place, zero RAM) leg of the
embedded bench, against the same baseline.
| encoding | geometry section | raw | best-compressed | XIP lookup |
|---|---|---|---|---|
VarintArcs | shared arcs, delta + zigzag-varint coords | 1× | 1× | 1× |
FixedWidthArcs | shared arcs, absolute quant-width coords | 1.4–1.7× | 1.15–1.3× (xz) | 1.3–1.5× |
FullRings | whole rings, absolute quant-width coords | 2.1–3.2× | 1.4–2.1× (xz) | 2.0–3.3× |
Coarse | none (grid only) | 0.05–0.33× | 0.01–0.14× | grid probe only |
Narrow-quant FullRings XIP even outran the RAM preload cache on the
embedded bench. On fixed-width payloads the codec ranking flips: xz
overtakes brotli at every preset. Coarse shrinks with preset fineness
twice over: the grid is all it keeps, and grids compress extremely well.
The size columns come from utz_dev_cli whittle --extended (2026-07,
TZBB 2026c), measuring full assets per preset recipe against the
VarintArcs build. The XIP
lookup column is from the 2026-07 bench-firmware runs against earlier
payload revisions; read it as a relative ladder.
Variants§
VarintArcs = 0
This encoding stores shared arcs as delta + zigzag-varint streams; it is the default, for minimal storage size.
FixedWidthArcs = 1
This encoding stores shared arcs as absolute fixed-width
(quant-width) coordinates, so streaming lookups no longer decode a
varint per vertex, the dominant lookup cost on embedded targets. It
reaches near-eager speed with no RAM cache and suits uncompressed
-static assets read in place from memory-mapped flash, at a
storage cost (table above).
FullRings = 2
This encoding stores each ring in full: coordinates are flattened
per ring as quant-width pairs plus ring/poly index tables, 4-byte
aligned; it is the preload cache serialized. Slice kernels read it
in place: from memory-mapped flash via from_static()
(eager-lookup speed with no RAM cache and no preload pass at boot)
or from the decompressed buffer via from_slice(). There is no arc
store, so borders shared between zones are duplicated per ring,
making this the largest encoding (table above). It works on
little-endian hosts only.
Coarse = 3
A grid-only asset carrying the header, tzid pool, parent table,
and grid, with no geometry at all. lookup() answers at cell
precision, the same answer lookup_coarse() gives; precision is a
property of the asset, like epsilon_m. It is by far the smallest
storage (table above) and works on any endianness, and a reader
built only for coarse assets compiles no point-in-polygon code.
Implementations§
Source§impl GeomEncoding
impl GeomEncoding
Sourcepub const fn name(self) -> &'static str
pub const fn name(self) -> &'static str
The canonical CLI name (varint-arcs, fixed-width-arcs,
full-rings, or coarse), a spelling
from_name() accepts.
Sourcepub fn from_name(name: &str) -> Option<GeomEncoding>
pub fn from_name(name: &str) -> Option<GeomEncoding>
The encoding a name selects, the inverse of
name().
Sourcepub const fn from_byte(byte: u8) -> Option<GeomEncoding>
pub const fn from_byte(byte: u8) -> Option<GeomEncoding>
The encoding a header byte names, if any.
Trait Implementations§
Source§impl Clone for GeomEncoding
impl Clone for GeomEncoding
Source§fn clone(&self) -> GeomEncoding
fn clone(&self) -> GeomEncoding
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more