Crate geodesy

source ·
Expand description

§Geodesy

§Abstract

Rust Geodesy is - unsurprisingly - a geodesy library written in the Rust programming language.

Rust Geodesy provides a number of features to support a number of objectives.

The most important features are

  • a set of more than 20 geodetic transformation primitives
  • a set of more than 40 primitives for operations on the ellipsoid
  • a means for composing these primitives into more complex operations.

The most important objectives are

  • to support new, and hopefully better, abstractions,
  • to use these abstractions to build better, simpler, and more tractable, geospatial standards, transformations, and software.

If any of this resonates with you, read on after this minimal usage example…

§Usage

Initialize a new project, using Geodesy:

$ cargo new foo
     Created binary (application) `foo` package

$ cd foo
$ cargo add geodesy

Then copy this to the foo/src/main.rs file: A minimal example, computing the UTM coordinates of some Scandinavian capitals

use geodesy::prelude::*;

fn main() -> Result<(), Box<Error>> {
    let mut context = Minimal::new();
    let utm33 = context.op("utm zone=33")?;

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

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

and try it out:

$ cargo r
    Finished dev [unoptimized + debuginfo] target(s) in 0.11s
     Running `C:\FLOW\AD\RG\foo\target\debug\foo.exe`

[Coor2D([308124.36786033923, 6098907.825005002]), Coor2D([672319.9640879404, 6543920.334127973])]

§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 fundamental transformation functionality of RG is fairly complete (i.e. on par with the datum shift/reference frame transformation capability of PROJ), while the number of projections supported is a far cry from PROJ’s enormous gamut. It does, however, support a suite of the most important ones:

  • Transverse Mercator
  • Universal Transverse Mercator (UTM)
  • Web Mercator
  • Mercator
  • Oblique Mercator
  • Lambert Conformal Conic
  • Lambert Azimuthal Equal Area

But fundamentally, RG is born as a geodesy, rather than cartography library. And while PROJ benefits from four decades of reality hardening, RG, being a platform for experiments, does not have operational robustness as a main focus. 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 compared to PROJ is not just a matter of functional pruning. It is 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 designed to be 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 (at least) 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:

  • 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, and this related comparison between PROJ and RG
  • The API documentation at Docs.rs
  • The examples
  • The tests embedded in the source code
  • This rather concrete and this more philosophical description of the main discrepancy between geodesy and geomatics, RG tries to elucidate and amend.

§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.

Modules§

  • authoring
    Extended prelude for authoring Contexts and InnerOp modules (built-in or user defined)
  • math
    Miscellaneous math functions for general use
  • prelude
    The bread-and-butter, shrink-wrapped for external use

Structs§

  • Coor2D
    Generic 2D Coordinate tuple, with no fixed interpretation of the elements
  • Coor3D
    Generic 3D coordinate tuple, with no fixed interpretation of the elements
  • Coor4D
    Generic 4D coordinate tuple, with no fixed interpretation of the elements
  • Coor32
    Generic 2D Coordinate tuple, with no fixed interpretation of the elements. A tiny coordinate type: Just one fourth the weight of a Coor4D. Probably only useful for small scale world maps, without too much zoom.
  • Ellipsoid
    Representation of a (potentially triaxial) ellipsoid.
  • InnerOp
    Blueprint for the functions doing the actual transformation work.
  • Minimal
    A minimalistic context provider, supporting only built in and run-time defined operators. Usually sufficient for cartographic uses, and for internal test authoring.
  • Ntv2Grid
    Grid for using the NTv2 format.
  • Op
    The defining parameters and functions for an operator
  • OpConstructor
    Blueprint for the overall instantiation of an operator.
  • OpDescriptor
    The fundamental elements of an operator (i.e. everything but steps and args)
  • OpHandle
    The key, returned to the user, representing the actual operation handled by the Context
  • ParsedParameters
    The InnerOp specific representation of the operator arguments.
  • 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 or macros, as each reside in its own file.
  • RawParameters
    Interface between the high level Op::op() and the low level functionality in the InnerOps

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 error messaging enumeration. Badly needs reconsideration
  • OpParameter
    The OpParameter enumeration is used to represent which defining parameters are valid for a given Operation.

Traits§

  • AngularUnits
    Methods for changing the coordinate representation of angles. Dimensionality untold, the methods operate on the first two dimensions only.
  • Context
    Modes of communication between the Rust Geodesy internals and the external world (i.e. resources like grids, transformation definitions, or ellipsoid parameters).
  • CoordinateMetadata
    The ISO-19111 Coordinate Metadata gamut includes an optional epoch and one of two possible ways of representing the CRS
  • CoordinateSet
    CoordinateSet is the fundamental coordinate access interface in ISO-19111. Strictly speaking, it is not a set, but (in abstract terms) rather an indexed list, or (in more concrete terms): An array.
  • CoordinateTuple
    CoordinateTuple is the ISO-19111 atomic spatial/spatiotemporal referencing element. So loosely speaking, a CoordinateSet is a collection of CoordinateTuples.
  • Grid
  • Tokenize
    Convenience methods for lexical analysis of operator definitions.

Functions§

  • parse_proj
    Translate a PROJ string into Rust Geodesy format. Since PROJ is syntactically unrestrictive, we do not try to detect any syntax errors: If the input is so cursed as to be intranslatable, this will become clear when trying to instantiate the result as a Geodesy operator. We do, however, check for and report on two semantically refusable cases: First, that PROJ does not support nested pipelines (the nesting must be done indirectly through an init-file), second that Rust Geodesy does not support init-files. Hence no support for any kind of nesting here.