#projection #map #geography #mapper

mappers

Pure Rust geographical projections library

10 releases (5 breaking)

0.6.1 Jan 24, 2024
0.5.2 Jan 24, 2024
0.5.1 Apr 14, 2023
0.3.2 Jan 16, 2023
0.0.3 Jun 24, 2022

#157 in Math

43 downloads per month

Apache-2.0

44KB
502 lines

mappers

License Crates.io dependency status docs.rs

GitHub Workflow Status GitHub Workflow Status GitHub Workflow Status

Pure Rust geographical projections library. Similar to Proj in basic functionality but allows for a use in concurrent contexts.

Projections' implementations closely follow algorithms and instructions provided in: Map projections: A working manual (John P. Snyder, 1987)

This crate in very early stages of development. If you are interested in contributing do not hesitate to contact me on Github.

Why this crate exists?

There is already a well-established, production-ready and battle-tested library for geographical projections and transformations - Proj, which has great high-level bindings in Rust. And you should probably use it in most cases instead of implementing your own functions or using this crate. Proj is even used to test mappers accuracy.

However, because Proj is not written in Rust its usage is not straightforward in concurrent context. Proj also supports mostly Linux and its installation can be a real hassle on different targets (and Proj bindings do not support other targets anyway).

mappers addresses those two issues by implementing the most commonly used geographical projections in pure Rust. But it is not (yet) thoroughly tested for precision and edge-cases. mappers possibly also has a slightly better performance than Proj because it is so much less complex. But it mainly allows for use with multiple threads (processes, tasks...) and on at least Tier 1 targets (only building Ubuntu, Windows and MacOS is tested).

So mappers should be used only when comprehensiveness (and probably correctness) of Proj is less important than a need to calculate geographical projections on non-linux targets or in concurrent contexts.

Usage example

We can project the geographical coordinates to cartographic coordinates on a map with specified projection as follows:

// First, we define the projection

// We use LCC with reference longitude centered on France
// parallels set for Europe and WGS84 ellipsoid
let lcc = LambertConformalConic::new(2.0, 0.0, 30.0, 60.0, Ellipsoid::WGS84)?;

// Second, we define the coordinates of Mount Blanc
let (lon, lat) = (6.8651, 45.8326);

// Project the coordinates
let (x, y) = lcc.project(lon, lat)?;

// And print the result
println!("x: {}, y: {}", x, y); // x: 364836.4407792019, y: 5421073.726335758

We can also inversely project the cartographic coordinates to geographical coordinates:

// We again start with defining the projection
let lcc = LambertConformalConic::new(2.0, 0.0, 30.0, 60.0, Ellipsoid::WGS84)?;

// We take the previously projected coordinates
let (x, y) = (364836.4407792019, 5421073.726335758);

// Inversely project the coordinates
let (lon, lat) = lcc.inverse_project(x, y)?;

// And print the result
println!("lon: {}, lat: {}", lon, lat); // lon: 6.8651, lat: 45.83260000001716

Some projections are mathematically exactly invertible, and technically geographical coordinates projected and inverse projected should be identical. However, in practice limitations of floating-point arithmetics will introduce some errors along the way, as shown in the example above.

Multithreading

For projecting multiple coordinates at once, the crate provides _parallel functions that are available in a (default) multithreading feature. These functions use rayon crate to parallelize the projection process. They are provided mainly for convenience, as they are not much different than calling .par_iter() on a slice of coordinates and mapping the projection function over it.

let lcc = LambertConformalConic::new(2.0, 0.0, 30.0, 60.0, Ellipsoid::WGS84)?;

// Parallel functions use slices of tuples as input and output
let geographic_coordinates = vec![(6.8651, 45.8326); 10];

let map_coordinates = lcc.project_parallel(&geographic_coordinates)?;
let inversed_coordinates = lcc.inverse_project_parallel(&map_coordinates)?;

Dependencies

~1.1–1.9MB
~41K SLoC