Crate mappers 

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.

Usage example

We can project the geographical coordinates to cartographic coordinates on a map with one of implemented projections as follows:

 // First, we define the projection
 // Projections are constructed with builders

 // We use LCC with reference longitude centered on France
 // parallels set for Europe and WGS84 ellipsoid (defined by default)
 let lcc = LambertConformalConic::builder()
     .ref_lonlat(30., 30.)
     .standard_parallels(30., 60.)
     .initialize_projection()?;

 // 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 inversly project the cartographic coordinates to geographical coordinates:

 // We again start with defining the projection
 let lcc = LambertConformalConic::builder()
     .ref_lonlat(30., 30.)
     .standard_parallels(30., 60.)
     .initialize_projection()?;

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

 // Inversly 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 inversible, 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.

ConversionPipe

This crate also provides a struct ConversionPipe that allows for easy conversion between two projections. It can be constructed directly from Projection with pipe_to method or directly with ConversionPipe::new().

Before using it please read the documentation of ConversionPipe.

Example

 // We start by defining the source and target projections
 // In this case we will use LCC and LongitudeLatitude
 // to show how a normal projection can be done with ConversionPipe
 let target_proj = LambertConformalConic::builder()
     .ref_lonlat(30., 30.)
     .standard_parallels(30., 60.)
     .initialize_projection()?;

 // LongitudeLatitude projection is an empty struct
 let source_proj = LongitudeLatitude;

 let (lon, lat) = (6.8651, 45.8326);

 // Now we can convert to LCC and back to LongitudeLatitude
 let (x, y) = source_proj.pipe_to(&target_proj).convert(lon, lat)?;
 let (pipe_lon, pipe_lat) = target_proj.pipe_to(&source_proj).convert(x, y)?;

 // For simple cases the error remains small
 // but it can quickly grow with more complex conversions
 assert_approx_eq!(f64, lon, pipe_lon, epsilon = 1e-10);
 assert_approx_eq!(f64, lat, pipe_lat, epsilon = 1e-10);

Tracing

Functions that are likely to be called in a complex chain of computations, namely project()/inverse_project() (checked and unchecked) from Projection trait and convert() (checked and unchecked) from ConversionPipe, implement instrument macro from tracing macro for easier debugging.

This functionality must be enabled with tracing feature.

These functions themselves don’t emit any tracing messages so to get the information provided by the instrument macro, tracing subscriber should be configured to show span events. This can be achieved using, for example .with_span_events(FmtSpan::FULL).

Modules

projections

Geographical projections implemented by the crate.

Structs

ConversionPipe

A struct that allows for easy conversion between two projections.

Ellipsoid

Ellipsoid struct that defines all values contained by reference ellipsoids.

Enums

ProjectionError

An interface for errors used within the crate and that the user may face.

Traits

Projection

An interface for all projections included in the crate.