Module heightmap 

Heightmap codecs for elevation tile formats.

Two flavours of heightmap encoding are supported:

• RGB tiles (this module, top level): terrarium, mapbox, gsi. Elevations packed into 3-byte (R, G, B) pixels, usually served wrapped in a PNG or WebP container.
• Cesium heightmap-1.0 (cesium): 16-bit little-endian heights plus child-tile mask. Cesium’s legacy terrain format.

The container submodule (behind the png / webp / avif cargo features) wraps the encoded RGB bytes in PNG, WebP, or AVIF for serving as image tiles.

API shape: allocation-free by default

Every codec ships in three flavours so callers can pick the right allocation profile:

Function	Output	Allocation
encode_pixel	[u8; 3]	none
encode_into	caller-owned &mut [u8]	none
encode_to<W>	impl Write	none (4 KiB stack buffer)
encode	Vec<u8>	one Vec

Decoding mirrors this: decode_pixel, decode_into, HeightmapView (zero-copy borrowed iterator), and decode (Vec<f32>).

Unified runtime-dispatch API

When the format is only known at runtime, use the HeightmapFormat enum and the top-level encode_pixel, decode_pixel, encode_into, decode_into, encode_to, encode, decode functions:

use terrain_codec::heightmap::{HeightmapFormat, encode_pixel};
let fmt: HeightmapFormat = "terrarium".parse().unwrap();
let rgb = encode_pixel(fmt, 123.45);

Modules

cesium

Cesium heightmap-1.0 terrain tile format.

container

PNG / WebP / AVIF container helpers for heightmap RGB bytes.

gsi

Geospatial Information Authority of Japan (GSI / 国土地理院) DEM tile encoding.

mapbox

Mapbox “Terrain-RGB” elevation tile encoding.

terrarium

Mapzen / Tilezen / Stadia “Terrarium” elevation tile encoding.

Structs

HeightmapView

Zero-copy borrowed view over an encoded RGB heightmap.

ParseHeightmapFormatError

Error returned by HeightmapFormat::from_str for an unrecognised name.

Enums

HeightmapFormat

Identifies one of the supported RGB heightmap encodings, for runtime-dispatched encode/decode via the top-level functions.

Functions

decode

Decode a flat width × height × 3 RGB buffer back to elevations.

decode_into

Decode RGB bytes into a caller-owned f32 buffer.

decode_pixel

Decode a single (R, G, B) pixel into elevation (metres) using the chosen format.

encode

Encode elevations into a freshly allocated RGB Vec.

encode_into

Encode elevations into a caller-owned RGB buffer.

encode_pixel

Encode a single elevation sample (metres) into (R, G, B) using the chosen format.

encode_to

Encode elevations into RGB bytes streamed to a writer.