Crate geodesy

Expand description

Geodesy

Abstract

// Find the UTM coordinates of some Scandinavian capitals
use geodesy::preamble::*;
fn main() -> anyhow::Result<()> {
    let mut prv = Minimal::new();
    let utm33 = prv.op("utm zone=33")?;

    let cph = Coord::geo(55., 12., 0., 0.); // Copenhagen
    let sth = Coord::geo(59., 18., 0., 0.); // Stockholm
    let mut data = [cph, sth];

    prv.apply(utm33, Fwd, &mut data)?;
    println!("{:?}", data);
    Ok(())
}

Rust Geodesy (RG), is a platform for experiments with geodetic software, transformations, and standards. RG vaguely resembles the PROJ transformation system, and was built in part on the basis of experiments with alternative data flow models for PROJ. The actual transformation functionality of RG is, however, minimal: At time of writing, it includes just a few low level operations, including:

The three, six, seven, and fourteen-parameter versions of the Helmert transformation
Horizontal and vertical grid shift operations
Helmert’s companion, the cartesian/geographic coordinate conversion
The full and abridged versions of the Molodensky transformation
Three widely used conformal projections: The Mercator, the Transverse Mercator, and the Lambert Conformal Conic projection
The Adapt operator, which mediates between various conventions for coordinate units and order

While this is sufficient to test the architecture, and while supporting the most important transformation primitives and three of the most used map projections, it is a far cry from PROJ’s enormous gamut of supported map projections (which, however, is partially supported through a bridge to the proj projection program). So fundamentally, RG is a geodesy, rather than cartography library. And while PROJ benefits from four decades of reality hardening, RG, being a platform for experiments, does not even consider development in the direction of operational robustness.

Hence, viewing RG as another PROJ, or PROJ RiiR, will lead to bad disappointment. At best, you may catch a weak mirage of a potential shape of jazz to come for the PROJ internal dataflow.

That said, being written in Rust, with all the memory safety guarantees Rust provides, RG by design avoids a number of pitfalls that are explicitly worked around in the PROJ code base, so the miniscule size of RG (as measured in number of code lines) compared to PROJ, is not just a matter of functional pruning, but also a matter of development using a tool wonderfully suited for the task at hand.

Also, having the advantage of learning from PROJ experience, both from a user’s and a developer’s perspective, RG is significantly more extensible than PROJ, so perhaps for a number of applications, and despite its limitations, RG may be sufficient, and perhaps even useful.

Aims

Dataflow experimentation is just one aspect of RG. Overall, the aims are fourfold:

Support experiments for evolution of geodetic standards.
Support development of geodetic transformations.
Hence, provide easy access to a number of basic geodetic operations, not limited to coordinate operations.
Support experiments with data flow and alternative abstractions. Mostly as a tool for aims (1, 2, 3)

All four aims are guided by a wish to amend explicitly identified shortcomings in the existing geodetic system landscape.

Documentation

The documentation is currently limited, but take a look at:

The coordinate operator documentation
The description of kp, the Rust Geodesy coordinate processing program
This essayistic rumination, outlining the overall philosophy and architecture of Rust Geodesy.
The API documentation at Docs.rs
The examples
The tests embedded in the source code

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or here)
MIT license (LICENSE-MIT or here)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules

inner_op_authoring

Preamble for InnerOp modules (built-in or user defined)

internal

Preamble for crate-internal modules

preamble

The bread-and-butter, shrink-wrapped for external use

Structs

Coord

Generic 4D coordinate tuple, with no fixed interpretation of the elements

Ellipsoid

Representation of a (potentially triaxial) ellipsoid.

Grid

Minimal

A minimalistic context provider, supporting only built in and run-time defined operators. Usually sufficient for cartographic uses, and for internal test authoring.

Op

The defining parameters and functions for an operator

Plain

A context provider, supporting built in and run-time defined operators, external grids, and macros. Sufficient for most uses, especially geodetic grid development. May get somewhat clunky when working with large numbers of grids and macros, as each grid and macro resides in individual files.

Enums

Bibliography

Some literature, that has been useful in designing and implementing this library.

Direction

Fwd: Indicate that a two-way operator, function, or method, should run in the forward direction. Inv: Indicate that a two-way operator, function, or method, should run in the inverse direction.

Error

The Rust Geodesy errror messaging enumeration. Badly needs reconsideration

Traits

Provider

The Provider trait defines the mode of communication between Rust Geodesy internals and the external context (i.e. typically resources like grids, transformation definitions, or ellipsoid parameters).