Refactor reference frame module (#135)

One last refactor for usability. This PR contains two primary changes,
along with a scattering of clean ups and documentation re-writes.

# Support for handling new reference frames

Previously the `ReferenceFrame` enum contained a set list of known
reference frames, and we made sure to maintain an internal list of
transformations for that set list of reference frames. This approach is
obviously pretty inflexible, so I've added a new variant to
`ReferenceFrame` called `Other` to enable defining new reference frames
at run-time. A `String` is used to represent the unknown reference frame
types. This slots in easily with our use of the `strum` macros for
converting the reference frame enums into or from strings, but this does
make the `ReferenceFrame` type no longer triviably copy-able.

I've attempted to reduce the number of clones of the new
`ReferenceFrame`, but they can't be completely avoided without a
significantly different approach of representing new reference frame
types at run-time. I'd be happy to hear suggestions on alternative
approaches if anyone has any.

# Simplify managing reference frame transformations

Previously it was expected that the user of the crate would get the list
of hard-coded transformations with the `get_transformation` function. If
you needed a single transformation that would suffice, but if we didn't
have a direct transformation hard-coded for you then you'd need to
perform multiple transformations. The `TransformationGraph` struct was
available to help to figure out the shortest path of transformations
from one reference frame to another, but the `TransformationGraph`
object didn't actually handle the transformations for you. In short it
was a bit of a pain to use the crate for simple transformations and a
major pain to do more complicated transformations.

To improve the situation I've replaced the old `TransformationGraph`
type with a new `TransformationRepository` type which both maintains the
graph of transformations and also applies multiple transformations for
you in sequence when needed. You're able to easily get one pre-populated
with the hard-coded transformations available, or an empty one, then add
any additional transformations defined at run-time to the graph.

Author: jbangelo

swiftnav/src/coords/mod.rs

@@ -84,10 +84,7 @@ pub use ellipsoid::*;
 pub use llh::*;
 pub use ned::*;
 
-use crate::{
-    reference_frame::{get_transformation, ReferenceFrame, TransformationNotFound},
-    time::GpsTime,
-};
+use crate::{reference_frame::ReferenceFrame, time::GpsTime};
 use nalgebra::Vector2;
 
 /// WGS84 local horizontal coordinates consisting of an Azimuth and Elevation, with angles stored as radians
@@ -193,7 +190,7 @@ impl AsMut<Vector2<f64>> for AzimuthElevation {
 /// Complete coordinate used for transforming between reference frames
 ///
 /// Velocities are optional, but when present they will be transformed
-#[derive(Debug, PartialEq, PartialOrd, Clone, Copy)]
+#[derive(Debug, PartialEq, PartialOrd, Clone)]
 pub struct Coordinate {
     reference_frame: ReferenceFrame,
     position: ECEF,
@@ -218,7 +215,7 @@ impl Coordinate {
         }
     }
 
-    /// Create a new [`Coordinate`] object with a velocity value
+    /// Create a new [`Coordinate`] object with no velocity value
     #[must_use]
     pub fn without_velocity(
         reference_frame: ReferenceFrame,
@@ -233,7 +230,7 @@ impl Coordinate {
         }
     }
 
-    /// Create a new [`Coordinate`] object with no velocity
+    /// Create a new [`Coordinate`] object with a velocity
     #[must_use]
     pub fn with_velocity(
         reference_frame: ReferenceFrame,
@@ -251,8 +248,8 @@ impl Coordinate {
 
     /// Get the reference frame of the coordinate
     #[must_use]
-    pub fn reference_frame(&self) -> ReferenceFrame {
-        self.reference_frame
+    pub fn reference_frame(&self) -> &ReferenceFrame {
+        &self.reference_frame
     }
 
     /// Get the position of the coordinate
@@ -276,7 +273,7 @@ impl Coordinate {
     /// Use the velocity term to adjust the epoch of the coordinate.
     /// When a coordinate has no velocity the position won't be changed.
     #[must_use]
-    pub fn adjust_epoch(&self, new_epoch: &GpsTime) -> Self {
+    pub fn adjust_epoch(self, new_epoch: &GpsTime) -> Self {
         let dt =
             new_epoch.to_fractional_year_hardcoded() - self.epoch.to_fractional_year_hardcoded();
         let v = self.velocity.unwrap_or_default();
@@ -288,17 +285,6 @@ impl Coordinate {
             reference_frame: self.reference_frame,
         }
     }
-
-    /// Transform the coordinate from into a new reference frame
-    ///
-    /// # Errors
-    ///
-    /// An error is returned if a transformation from the coordinate's reference frame to the requested
-    /// reference frame could not be found.
-    pub fn transform_to(&self, new_frame: ReferenceFrame) -> Result<Self, TransformationNotFound> {
-        get_transformation(self.reference_frame, new_frame)
-            .map(|transformation| transformation.transform(self))
-    }
 }
 
 #[cfg(test)]
@@ -519,7 +505,7 @@ mod tests {
             initial_epoch,
         );
 
-        let new_coord = initial_coord.adjust_epoch(&new_epoch);
+        let new_coord = initial_coord.clone().adjust_epoch(&new_epoch);
 
         assert_eq!(initial_coord.reference_frame, new_coord.reference_frame);
         assert_float_eq!(new_coord.position.x(), 1.0, abs <= 0.001);