map_engine/
lib.rs

1/*!A library to work with tiled geospatial (raster) data.
2
3This is the base library of a series of crates. It contains methods to:
4
5* Work with XYZ tiles
6* Read raster data intersecting a tile
7* Style data to generate coloured PNG files
8
9🚧 This is a work in progress so the API is unstable and likely to change as the related crates are
10developed. 🚧
11
12## Related crates
13
14* [map-engine-server](<https://crates.io/crates/map-engine-server>): An HTTP tile server
15
16## Example
17
18```
19use map_engine::{
20    errors::MapEngineError,
21    cmap::{Composite, viridis},
22    raster::{Raster, RawPixels},
23    tiles::Tile,
24};
25use std::path::PathBuf;
26
27fn main() -> Result<(), MapEngineError> {
28    let tile = Tile::new(304, 624, 10);
29    let raster = Raster::new(PathBuf::from("src/tests/data/chile_optimised.tif"))?;
30
31    // Note that these three things should support the same number of bands (in this case, 1).
32    // At the moment we don't enforce this at compile time.
33    // https://gitlab.com/spadarian/map_engine/-/issues/36
34    let comp = Composite::new_gradient(0.0, 27412.0, &viridis);
35    let bands = &[1];
36    let na_value = vec![0.0];
37    assert!(comp.n_bands() == bands.len());
38    assert!(comp.n_bands() == na_value.len());
39
40    let arr: RawPixels<f64> = raster.read_tile(&tile, Some(bands), None)?;
41    let styled = arr.style(comp, na_value)?;
42    let png = styled.into_png()?;  // PNG as a byte sequence
43
44    // The PNG can then be sent as an HTTP response, written to disk, etc.
45    // Also, we have a method to write to disk:
46    // styled.write_to_disk(std::path::Path::new("path_to_png"))?;
47
48    Ok(())
49}
50```
51
52## Intallation notes
53
54At the moment, we only support Linux but the crate might work on macOS and Windows (let us know!).
55
56We depend on [GDAL](http://gdal.org/) `>3.3` and you might need to [compile it yourself](https://gdal.org/download.html#development-source).
57
58### Ubuntu
59
60The [UbuntuGIS](https://launchpad.net/~ubuntugis/+archive/ubuntu/ppa) team has a recent version of GDAL (3.3.2) that might work for you.
61*/
62extern crate lazy_static;
63
64#[cfg(test)]
65mod tests;
66
67pub mod affine;
68pub mod cmap;
69pub mod colour;
70pub mod errors;
71pub mod gdal;
72pub mod mercator;
73pub mod png;
74pub mod raster;
75pub mod tiles;
76pub mod windows;
77
78/// Maximum zoom level supported
79pub const MAXZOOMLEVEL: u32 = 32;
80
81/// Available tile formats to request.
82///
83/// At the moment, only PNG8 tiles are supported.
84pub const SUPPORTED_FORMATS: &[&str] = &["png"];
map_engine/lib.rs

map_engine/
lib.rs
