Module reference_frame

Geodetic reference frame transformations

Geodetic reference frames define the coordinate system used to represent positions on the Earth. Different reference frames are commonly used in different regions of the world, and for different purposes. For example, global reference frames, such as the International Terrestrial Reference Frame (ITRF), are used for global positioning, while regional reference frames, such as the European Terrestrial Reference Frame (ETRF), are used for regional positioning. Due to the movement of the earth’s crust apparently fixed positions will move over time. Because of this it’s important to note only take note of a position, but also the time at which that position was determined. In most regions of the earth the crust moves at a constant speed, meaning that if you are able to determine the local velocity of the crust you can easily determine what the position of a static point would have been in the past. It is commong for regional reference frames to define a common reference epoch that all positions should be transformed to, allowing the direct comparison of positions even if they were determined at different times. Regional reference frames also typically are defined to be “fixed” to a particular tectonic plate, meaning the large majority of the velocity for points on that tectonic plate are cancelled out. In contrast, global reference frames are not fixed to any particular tectonic plate, so most places on earth will have a measurable velocity. Global reference frames also typically do not have a common reference epoch, so determining one’s local velocity is important to be able to compare positions or to transform a coordinate from a global reference frame to a regional reference frame.

This module provides several types and functions to help transform a set of coordinates from one reference frame to another, and from one epoch to another. Several sets of transformation parameters are included for converting between common reference frames. To start out, you must have a Coordinate that you want to transform. This consists of a position, an epoch, and a reference frame as well as an optional velocity. You then need to get the Transformation object that describes the transformation from the reference frame of the coordinate to the desired reference frame. You can then call the transform method on the transformation object to get a new coordinate in the desired reference frame. This transformation will change the position and velocity of the coordinate, but it does not the change the epoch of the coordinate. If you need to change the epoch of the coordinate you will need to use the Coordinate::adjust_epoch method which uses the velocity of the coordinate to determine the position at the new epoch.

Example

use swiftnav::{
    coords::{Coordinate, ECEF},
    reference_frame::{get_transformation, ReferenceFrame, TransformationNotFound},
    time::UtcTime
};

let transformation = get_transformation(ReferenceFrame::ITRF2014, ReferenceFrame::NAD83_2011)
    .unwrap();

let epoch_2020 = UtcTime::from_date(2020, 3, 15, 0, 0, 0.).to_gps_hardcoded();
let itrf_coord = Coordinate::with_velocity(
    ReferenceFrame::ITRF2014, // The reference frame of the coordinate
    ECEF::new(-2703764.0, -4261273.0, 3887158.0), // The position of the coordinate
    ECEF::new(-0.221, 0.254, 0.122), // The velocity of the coordinate
    epoch_2020); // The epoch of the coordinate

let epoch_2010 = UtcTime::from_date(2010, 1, 1, 0, 0, 0.).to_gps_hardcoded();
let itrf_coord = itrf_coord.adjust_epoch(&epoch_2010); // Change the epoch of the coordinate

let nad83_coord = transformation.transform(&itrf_coord);
// Alternatively, you can use the `transform_to` method on the coordinate itself
let nad83_coord: Result<Coordinate, TransformationNotFound> =
    itrf_coord.transform_to(ReferenceFrame::NAD83_2011);

Structs

ReferenceFrameIter

An iterator over the variants of ReferenceFrame

TimeDependentHelmertParams

15-parameter Helmert transformation parameters

Transformation

A transformation from one reference frame to another.

TransformationGraph

A helper type for finding transformations between reference frames that require multiple steps

TransformationNotFound

Error indicating that no transformation was found between two reference frames

Enums

ReferenceFrame

Reference Frames

Functions

get_transformation

Find a transformation from one reference frame to another