Crate geodesy

source ·
Expand description

Geodesy

Abstract

// Find the UTM coordinates of some Scandinavian capitals
use geodesy::preamble::*;
fn main() -> anyhow::Result<()> {
    let mut context = Minimal::new();
    let utm33 = context.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];

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

Concrete

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
  • One equal area projection: The Lambert Azimuthal Equal Area (LAEA) 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:

  1. Support experiments for evolution of geodetic standards.
  2. Support development of geodetic transformations.
  3. Hence, provide easy access to a number of basic geodetic operations, not limited to coordinate operations.
  4. 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:

License

Rust Geodesy: Copyright 2020, 2021, 2022, 2023 by Thomas Knudsen knudsen.thomas@gmail.com.

Licensed under either of

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.

Re-exports

pub use crate::Direction::Fwd;
pub use crate::Direction::Inv;

Modules

inner_op_authoring
Preamble for InnerOp modules (built-in or user defined)
internal
Preamble for crate-internal modules, and authoring of Context providers
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.
Minimal
A minimalistic context provider, supporting only built in and run-time defined operators. Usually sufficient for cartographic uses, and for internal test authoring.
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

Context
The Context 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).