Struct MercatorDem 

pub struct MercatorDem { /* private fields */ }

A contiguous rectangular block of decoded web-mercator (XYZ) DEM tiles, stitched into a single elevation grid and sampleable by longitude / latitude.

The stitched grid is row-major north → south, tiles_x * tile_size columns by tiles_y * tile_size rows. Sampling outside the block clamps to the nearest edge sample, so a halo that slightly overshoots the fetched coverage degrades gracefully rather than panicking — but for correct results the block should cover the target bounds (plus any halo).

Implementations

impl MercatorDem

pub fn new( zoom: u8, x0: u32, y0: u32, tiles_x: u32, tiles_y: u32, tile_size: u32, elev: Vec<f32>, ) -> Self

Wrap an already-stitched elevation block.

elev must be row-major north → south with (tiles_x*tile_size) * (tiles_y*tile_size) entries.

Panics

Panics on a length mismatch, or if any tile dimension is zero.

pub fn from_tiles<F>( zoom: u8, x0: u32, y0: u32, tiles_x: u32, tiles_y: u32, tile_size: u32, get_tile: F, ) -> Self

where F: FnMut(u8, u32, u32) -> Vec<f32>,

Build a block by pulling each XYZ tile through get_tile, which returns that tile’s decoded elevations (tile_size², row-major north → south). The closure is where you do your fetch + heightmap decode; for async callers, pre-fetch into a map and look it up here.

Tiles are requested in row-major order (x0, y0) … (x0+tiles_x-1, y0+tiles_y-1).

Panics

Panics if any returned tile does not have exactly tile_size² samples.

Examples found in repository

examples/reproject_terrain.rs (lines 57-64)

fn main() {
    let mut a = env::args().skip(1);
    let tz: u8 = a.next().expect("tms_z").parse().unwrap();
    let tx: u32 = a.next().expect("tms_x").parse().unwrap();
    let ty: u32 = a.next().expect("tms_y").parse().unwrap();
    let src_zoom: u8 = a.next().expect("src_zoom").parse().unwrap();
    let tile_size: u32 = a.next().expect("tile_size").parse().unwrap();
    let png_dir = PathBuf::from(a.next().expect("png_dir"));
    let real = a.next();

    // Target geodetic TMS tile.
    let (w, s, e, n) = geodetic_tms::tile_to_bounds(tz, tx, ty);
    let bounds = TileBounds::new(w, s, e, n);
    let grid_size = tile_size + 1; // 2^n + 1
    println!("target geodetic TMS z{tz}/{tx}/{ty}  bounds = [{w:.5}, {s:.5}, {e:.5}, {n:.5}]");

    // Widen by ~one geodetic cell so the halo (buffer=1) stays in coverage.
    let cell_lon = (e - w) / (grid_size - 1) as f64;
    let cell_lat = (n - s) / (grid_size - 1) as f64;
    let (x0, y0, ntx, nty) = MercatorDem::tiles_covering(
        src_zoom,
        w - cell_lon,
        s - cell_lat,
        e + cell_lon,
        n + cell_lat,
    );
    println!(
        "covering web-mercator z{src_zoom} tiles: x {x0}..{}  y {y0}..{}  ({} tiles, {tile_size}px)",
        x0 + ntx - 1,
        y0 + nty - 1,
        ntx * nty
    );

    // Build the mercator DEM by reading each covering tile from disk.
    let dem = MercatorDem::from_tiles(src_zoom, x0, y0, ntx, nty, tile_size, |z, x, y| {
        let path = png_dir.join(format!("{z}_{x}_{y}.png"));
        let bytes = std::fs::read(&path).unwrap_or_else(|_| panic!("missing tile {path:?}"));
        let img = decode_image(&bytes).expect("decode png");
        assert_eq!(img.width, tile_size);
        assert_eq!(img.height, tile_size);
        terrarium::decode(&img.rgb, img.width, img.height)
    });

    // Reproject onto the geodetic grid + a halo grid for seamless normals.
    let grid = dem.geodetic_grid(&bounds, grid_size);
    let buffered = dem.buffered_geodetic(&bounds, grid_size, 1);

    let (gmin, gmax) = min_max(&grid);
    println!("reprojected geodetic grid {grid_size}×{grid_size}: {gmin:.1} .. {gmax:.1} m");

    let bytes = encode_terrain(
        &grid,
        grid_size,
        &bounds,
        &TerrainOptions {
            max_error: 4.0,
            compression_level: 6,
            normals: NormalMode::BufferedGradient(buffered),
            ..Default::default()
        },
    );
    let mesh = DecodedMesh::decode(&bytes).expect("decode our output");
    println!(
        "ours: {} bytes (gzip), {} verts, {} tris, height {:.1}..{:.1} m, normals={}",
        bytes.len(),
        mesh.vertices.len(),
        mesh.indices.len() / 3,
        mesh.header.min_height,
        mesh.header.max_height,
        mesh.extensions.normals.is_some(),
    );

    if let Some(path) = real {
        let raw = std::fs::read(&path).expect("read real .terrain");
        let rm = DecodedMesh::decode(&raw).expect("decode real");
        println!(
            "real: {} bytes, {} verts, {} tris, height {:.1}..{:.1} m, normals={}  ({})",
            raw.len(),
            rm.vertices.len(),
            rm.indices.len() / 3,
            rm.header.min_height,
            rm.header.max_height,
            rm.extensions.normals.is_some(),
            path,
        );
        println!(
            "note: height offset vs real is expected — real is EGM2008 geoid-blended, ours is raw Terrarium (ellipsoidal)."
        );
    }

    println!("\nOK ✅  web-mercator → geodetic-TMS reprojection produced valid .terrain");
}

pub fn tiles_covering( zoom: u8, west: f64, south: f64, east: f64, north: f64, ) -> (u32, u32, u32, u32)

Range of XYZ tiles at zoom covering a longitude/latitude box, returning (x0, y0, tiles_x, tiles_y).

Widen the box by your halo before calling if you intend to sample a buffer beyond the tile (e.g. for buffered_geodetic).

Examples found in repository

examples/reproject_terrain.rs (lines 42-48)

fn main() {
    let mut a = env::args().skip(1);
    let tz: u8 = a.next().expect("tms_z").parse().unwrap();
    let tx: u32 = a.next().expect("tms_x").parse().unwrap();
    let ty: u32 = a.next().expect("tms_y").parse().unwrap();
    let src_zoom: u8 = a.next().expect("src_zoom").parse().unwrap();
    let tile_size: u32 = a.next().expect("tile_size").parse().unwrap();
    let png_dir = PathBuf::from(a.next().expect("png_dir"));
    let real = a.next();

    // Target geodetic TMS tile.
    let (w, s, e, n) = geodetic_tms::tile_to_bounds(tz, tx, ty);
    let bounds = TileBounds::new(w, s, e, n);
    let grid_size = tile_size + 1; // 2^n + 1
    println!("target geodetic TMS z{tz}/{tx}/{ty}  bounds = [{w:.5}, {s:.5}, {e:.5}, {n:.5}]");

    // Widen by ~one geodetic cell so the halo (buffer=1) stays in coverage.
    let cell_lon = (e - w) / (grid_size - 1) as f64;
    let cell_lat = (n - s) / (grid_size - 1) as f64;
    let (x0, y0, ntx, nty) = MercatorDem::tiles_covering(
        src_zoom,
        w - cell_lon,
        s - cell_lat,
        e + cell_lon,
        n + cell_lat,
    );
    println!(
        "covering web-mercator z{src_zoom} tiles: x {x0}..{}  y {y0}..{}  ({} tiles, {tile_size}px)",
        x0 + ntx - 1,
        y0 + nty - 1,
        ntx * nty
    );

    // Build the mercator DEM by reading each covering tile from disk.
    let dem = MercatorDem::from_tiles(src_zoom, x0, y0, ntx, nty, tile_size, |z, x, y| {
        let path = png_dir.join(format!("{z}_{x}_{y}.png"));
        let bytes = std::fs::read(&path).unwrap_or_else(|_| panic!("missing tile {path:?}"));
        let img = decode_image(&bytes).expect("decode png");
        assert_eq!(img.width, tile_size);
        assert_eq!(img.height, tile_size);
        terrarium::decode(&img.rgb, img.width, img.height)
    });

    // Reproject onto the geodetic grid + a halo grid for seamless normals.
    let grid = dem.geodetic_grid(&bounds, grid_size);
    let buffered = dem.buffered_geodetic(&bounds, grid_size, 1);

    let (gmin, gmax) = min_max(&grid);
    println!("reprojected geodetic grid {grid_size}×{grid_size}: {gmin:.1} .. {gmax:.1} m");

    let bytes = encode_terrain(
        &grid,
        grid_size,
        &bounds,
        &TerrainOptions {
            max_error: 4.0,
            compression_level: 6,
            normals: NormalMode::BufferedGradient(buffered),
            ..Default::default()
        },
    );
    let mesh = DecodedMesh::decode(&bytes).expect("decode our output");
    println!(
        "ours: {} bytes (gzip), {} verts, {} tris, height {:.1}..{:.1} m, normals={}",
        bytes.len(),
        mesh.vertices.len(),
        mesh.indices.len() / 3,
        mesh.header.min_height,
        mesh.header.max_height,
        mesh.extensions.normals.is_some(),
    );

    if let Some(path) = real {
        let raw = std::fs::read(&path).expect("read real .terrain");
        let rm = DecodedMesh::decode(&raw).expect("decode real");
        println!(
            "real: {} bytes, {} verts, {} tris, height {:.1}..{:.1} m, normals={}  ({})",
            raw.len(),
            rm.vertices.len(),
            rm.indices.len() / 3,
            rm.header.min_height,
            rm.header.max_height,
            rm.extensions.normals.is_some(),
            path,
        );
        println!(
            "note: height offset vs real is expected — real is EGM2008 geoid-blended, ours is raw Terrarium (ellipsoidal)."
        );
    }

    println!("\nOK ✅  web-mercator → geodetic-TMS reprojection produced valid .terrain");
}

pub fn width_px(&self) -> u32

Stitched-grid width in pixels (tiles_x * tile_size).

pub fn height_px(&self) -> u32

Stitched-grid height in pixels (tiles_y * tile_size).

pub fn sample(&self, lon: f64, lat: f64) -> f32

Bilinearly sample the elevation at (lon, lat) in degrees.

Latitude is clamped to the web-mercator limit. Positions outside the fetched block clamp to the nearest edge sample. NaN samples (e.g. missing data filled by the caller) are tolerated: the interpolation falls back to any defined neighbour, returning NaN only if all four corners are NaN.

pub fn geodetic_grid(&self, bounds: &TileBounds, grid_size: u32) -> Vec<f32>

Resample onto a geodetic grid_size × grid_size grid covering bounds, row-major north → south — ready for crate::terrain::encode_terrain.

Panics

Panics if grid_size < 2.

Examples found in repository

examples/reproject_terrain.rs (line 67)

fn main() {
    let mut a = env::args().skip(1);
    let tz: u8 = a.next().expect("tms_z").parse().unwrap();
    let tx: u32 = a.next().expect("tms_x").parse().unwrap();
    let ty: u32 = a.next().expect("tms_y").parse().unwrap();
    let src_zoom: u8 = a.next().expect("src_zoom").parse().unwrap();
    let tile_size: u32 = a.next().expect("tile_size").parse().unwrap();
    let png_dir = PathBuf::from(a.next().expect("png_dir"));
    let real = a.next();

    // Target geodetic TMS tile.
    let (w, s, e, n) = geodetic_tms::tile_to_bounds(tz, tx, ty);
    let bounds = TileBounds::new(w, s, e, n);
    let grid_size = tile_size + 1; // 2^n + 1
    println!("target geodetic TMS z{tz}/{tx}/{ty}  bounds = [{w:.5}, {s:.5}, {e:.5}, {n:.5}]");

    // Widen by ~one geodetic cell so the halo (buffer=1) stays in coverage.
    let cell_lon = (e - w) / (grid_size - 1) as f64;
    let cell_lat = (n - s) / (grid_size - 1) as f64;
    let (x0, y0, ntx, nty) = MercatorDem::tiles_covering(
        src_zoom,
        w - cell_lon,
        s - cell_lat,
        e + cell_lon,
        n + cell_lat,
    );
    println!(
        "covering web-mercator z{src_zoom} tiles: x {x0}..{}  y {y0}..{}  ({} tiles, {tile_size}px)",
        x0 + ntx - 1,
        y0 + nty - 1,
        ntx * nty
    );

    // Build the mercator DEM by reading each covering tile from disk.
    let dem = MercatorDem::from_tiles(src_zoom, x0, y0, ntx, nty, tile_size, |z, x, y| {
        let path = png_dir.join(format!("{z}_{x}_{y}.png"));
        let bytes = std::fs::read(&path).unwrap_or_else(|_| panic!("missing tile {path:?}"));
        let img = decode_image(&bytes).expect("decode png");
        assert_eq!(img.width, tile_size);
        assert_eq!(img.height, tile_size);
        terrarium::decode(&img.rgb, img.width, img.height)
    });

    // Reproject onto the geodetic grid + a halo grid for seamless normals.
    let grid = dem.geodetic_grid(&bounds, grid_size);
    let buffered = dem.buffered_geodetic(&bounds, grid_size, 1);

    let (gmin, gmax) = min_max(&grid);
    println!("reprojected geodetic grid {grid_size}×{grid_size}: {gmin:.1} .. {gmax:.1} m");

    let bytes = encode_terrain(
        &grid,
        grid_size,
        &bounds,
        &TerrainOptions {
            max_error: 4.0,
            compression_level: 6,
            normals: NormalMode::BufferedGradient(buffered),
            ..Default::default()
        },
    );
    let mesh = DecodedMesh::decode(&bytes).expect("decode our output");
    println!(
        "ours: {} bytes (gzip), {} verts, {} tris, height {:.1}..{:.1} m, normals={}",
        bytes.len(),
        mesh.vertices.len(),
        mesh.indices.len() / 3,
        mesh.header.min_height,
        mesh.header.max_height,
        mesh.extensions.normals.is_some(),
    );

    if let Some(path) = real {
        let raw = std::fs::read(&path).expect("read real .terrain");
        let rm = DecodedMesh::decode(&raw).expect("decode real");
        println!(
            "real: {} bytes, {} verts, {} tris, height {:.1}..{:.1} m, normals={}  ({})",
            raw.len(),
            rm.vertices.len(),
            rm.indices.len() / 3,
            rm.header.min_height,
            rm.header.max_height,
            rm.extensions.normals.is_some(),
            path,
        );
        println!(
            "note: height offset vs real is expected — real is EGM2008 geoid-blended, ours is raw Terrarium (ellipsoidal)."
        );
    }

    println!("\nOK ✅  web-mercator → geodetic-TMS reprojection produced valid .terrain");
}

pub fn buffered_geodetic( &self, bounds: &TileBounds, tile_grid_size: u32, buffer: u32, ) -> BufferedElevations

Resample onto a halo-extended geodetic grid — a BufferedElevations for crate::terrain::NormalMode::BufferedGradient.

The inner tile_grid_size × tile_grid_size block matches geodetic_grid; the surrounding buffer-cell strip is sampled from the neighbour area (so make sure this MercatorDem was built to cover bounds widened by the halo).

Panics

Panics if tile_grid_size < 2.

Examples found in repository

examples/reproject_terrain.rs (line 68)

fn main() {
    let mut a = env::args().skip(1);
    let tz: u8 = a.next().expect("tms_z").parse().unwrap();
    let tx: u32 = a.next().expect("tms_x").parse().unwrap();
    let ty: u32 = a.next().expect("tms_y").parse().unwrap();
    let src_zoom: u8 = a.next().expect("src_zoom").parse().unwrap();
    let tile_size: u32 = a.next().expect("tile_size").parse().unwrap();
    let png_dir = PathBuf::from(a.next().expect("png_dir"));
    let real = a.next();

    // Target geodetic TMS tile.
    let (w, s, e, n) = geodetic_tms::tile_to_bounds(tz, tx, ty);
    let bounds = TileBounds::new(w, s, e, n);
    let grid_size = tile_size + 1; // 2^n + 1
    println!("target geodetic TMS z{tz}/{tx}/{ty}  bounds = [{w:.5}, {s:.5}, {e:.5}, {n:.5}]");

    // Widen by ~one geodetic cell so the halo (buffer=1) stays in coverage.
    let cell_lon = (e - w) / (grid_size - 1) as f64;
    let cell_lat = (n - s) / (grid_size - 1) as f64;
    let (x0, y0, ntx, nty) = MercatorDem::tiles_covering(
        src_zoom,
        w - cell_lon,
        s - cell_lat,
        e + cell_lon,
        n + cell_lat,
    );
    println!(
        "covering web-mercator z{src_zoom} tiles: x {x0}..{}  y {y0}..{}  ({} tiles, {tile_size}px)",
        x0 + ntx - 1,
        y0 + nty - 1,
        ntx * nty
    );

    // Build the mercator DEM by reading each covering tile from disk.
    let dem = MercatorDem::from_tiles(src_zoom, x0, y0, ntx, nty, tile_size, |z, x, y| {
        let path = png_dir.join(format!("{z}_{x}_{y}.png"));
        let bytes = std::fs::read(&path).unwrap_or_else(|_| panic!("missing tile {path:?}"));
        let img = decode_image(&bytes).expect("decode png");
        assert_eq!(img.width, tile_size);
        assert_eq!(img.height, tile_size);
        terrarium::decode(&img.rgb, img.width, img.height)
    });

    // Reproject onto the geodetic grid + a halo grid for seamless normals.
    let grid = dem.geodetic_grid(&bounds, grid_size);
    let buffered = dem.buffered_geodetic(&bounds, grid_size, 1);

    let (gmin, gmax) = min_max(&grid);
    println!("reprojected geodetic grid {grid_size}×{grid_size}: {gmin:.1} .. {gmax:.1} m");

    let bytes = encode_terrain(
        &grid,
        grid_size,
        &bounds,
        &TerrainOptions {
            max_error: 4.0,
            compression_level: 6,
            normals: NormalMode::BufferedGradient(buffered),
            ..Default::default()
        },
    );
    let mesh = DecodedMesh::decode(&bytes).expect("decode our output");
    println!(
        "ours: {} bytes (gzip), {} verts, {} tris, height {:.1}..{:.1} m, normals={}",
        bytes.len(),
        mesh.vertices.len(),
        mesh.indices.len() / 3,
        mesh.header.min_height,
        mesh.header.max_height,
        mesh.extensions.normals.is_some(),
    );

    if let Some(path) = real {
        let raw = std::fs::read(&path).expect("read real .terrain");
        let rm = DecodedMesh::decode(&raw).expect("decode real");
        println!(
            "real: {} bytes, {} verts, {} tris, height {:.1}..{:.1} m, normals={}  ({})",
            raw.len(),
            rm.vertices.len(),
            rm.indices.len() / 3,
            rm.header.min_height,
            rm.header.max_height,
            rm.extensions.normals.is_some(),
            path,
        );
        println!(
            "note: height offset vs real is expected — real is EGM2008 geoid-blended, ours is raw Terrarium (ellipsoidal)."
        );
    }

    println!("\nOK ✅  web-mercator → geodetic-TMS reprojection produced valid .terrain");
}

Trait Implementations

impl Clone for MercatorDem

fn clone(&self) -> MercatorDem

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MercatorDem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.