Add low level LrmScale implementation

Author: Tristramg

src/lib.rs

@@ -7,6 +7,8 @@ mod lrs_generated;
 
 #[deny(missing_docs)]
 pub mod curves;
+#[deny(missing_docs)]
+pub mod lrm;
 pub use lrs_generated::*;
 
 #[test]

src/lrm.rs

@@ -0,0 +1,243 @@
+//! A LRM (linear reference model) is an abstract representation
+//! where the geometry and real distances are not considered
+
+use thiserror::Error;
+
+/// Errors when manipulating an LrmScale
+#[derive(Error, Debug, PartialEq)]
+pub enum LrmScaleError {
+    /// Returned when building a scale from a builder and no name anchor was provided
+    #[error("a scale needs at least one named anchor")]
+    NoNamedAnchor,
+    /// All the named anchors must be unique within a same scale
+    #[error("duplicated anchor: {0}")]
+    DuplicatedAnchorName(String),
+    /// Could not find the position on the curve as the anchor is not known
+    #[error("anchor is unknown in the LrmScale")]
+    UnknownAnchorName,
+    /// Could not find an anchor that matches a given offset
+    #[error("no anchor found")]
+    NoAnchorFound,
+}
+
+/// An anchor is a reference point that is well known from which the location is computed
+#[derive(PartialEq, Debug)]
+
+pub struct Anchor {
+    /// Some anchors might not be named
+    /// e.g. the first anchor of the LRM
+    pub id: Option<String>,
+    /// Offset to the start of the scale. Can be negative
+    pub offset: f64,
+}
+
+impl Anchor {
+    /// Build a named anchor
+    pub fn new(name: &str, offset: f64) -> Self {
+        Self {
+            id: Some(name.to_owned()),
+            offset,
+        }
+    }
+
+    /// Build an unamed anchor
+    pub fn new_unamed(offset: f64) -> Self {
+        Self { id: None, offset }
+    }
+}
+
+/// A helper to build a scale by adding consecutives anchors
+
+pub struct ScaleBuilder {
+    anchors: Vec<Anchor>,
+    cummulative_distances: Vec<f64>,
+}
+
+impl ScaleBuilder {
+    /// Create a new builder with the initial anchor
+    pub fn new(start: Anchor) -> Self {
+        Self {
+            anchors: vec![start],
+            cummulative_distances: vec![0.],
+        }
+    }
+    /// Distance_to_previous is measured along a curve
+    /// The curve might not start at the same 0 (e.g. the curve is longer than the scale)
+    /// or the curve might not progress at the same rate (e.g. the curve is a schematic representation that distorts distances)
+    pub fn add(&mut self, anchor: Anchor, distance_to_previous: f64) -> &mut Self {
+        self.anchors.push(anchor);
+        let last_distance = self.cummulative_distances.last().unwrap_or(&0.);
+        self.cummulative_distances
+            .push(distance_to_previous + last_distance);
+        self
+    }
+
+    /// Requires at least one named anchor
+    /// Will fail if none is present and if the anchors names are duplicated
+    /// This will consume the builder that can not be used after
+    pub fn build(self) -> Result<LrmScale, LrmScaleError> {
+        let mut names = std::collections::HashSet::new();
+        for anchor in self.anchors.iter() {
+            if let Some(name) = &anchor.id {
+                if names.contains(&name) {
+                    return Err(LrmScaleError::DuplicatedAnchorName(name.to_string()));
+                } else {
+                    names.insert(name);
+                }
+            }
+        }
+
+        if names.is_empty() {
+            Err(LrmScaleError::NoNamedAnchor)
+        } else {
+            Ok(LrmScale {
+                anchors: self.anchors,
+                cummulated_distances: self.cummulative_distances,
+            })
+        }
+    }
+}
+
+/// A measure defines a location on the LRM scale
+/// It is given as an anchor name and an offset on that scale
+/// It is often represented as 12+100 to say “100 meters after the anchor 12”
+pub struct LrmMeasure {
+    /// Name of the anchor. While it is often named after a kilometer position
+    /// it can be anything (a letter, a landmark) and where it is named after a position,
+    /// there is no guarantee that its value matches actual distance
+    anchor_name: String,
+    /// The offset from the anchor
+    offset: f64,
+}
+
+/// Represents an a LRM Scale and allows to map [Measure] to a position along a curve
+#[derive(PartialEq, Debug)]
+pub struct LrmScale {
+    // The anchors are milestones from which positions are measured
+    anchors: Vec<Anchor>,
+    // The distances between anchors
+    // Implementation detail: the first distance is 0.
+    // This allows to have two vectors of the same size and iterate by zipping them
+    cummulated_distances: Vec<f64>,
+}
+
+impl LrmScale {
+    /// Locates a point along a curve given an anchor and a offset
+    /// The offset might be negative
+    pub fn locate_point(&self, measure: LrmMeasure) -> Result<f64, LrmScaleError> {
+        self.iter_named()
+            .find(|(anchor_id, _distance)| anchor_id == &&measure.anchor_name)
+            .map(|(_anchor_id, distance)| distance + measure.offset)
+            .ok_or(LrmScaleError::UnknownAnchorName)
+    }
+
+    /// Returns a measure given a distance along the curve
+    /// The corresponding anchor is the named anchor that gives the smallest positive offset
+    /// If such an anchor does not exists, the first named anchor is used
+    pub fn locate_anchor(&self, offset: f64) -> Result<LrmMeasure, LrmScaleError> {
+        let smallest_measure = self
+            .iter_named()
+            .rev()
+            .find(|(_anchor_id, distance)| distance < &&offset)
+            .map(|(anchor_id, distance)| LrmMeasure {
+                anchor_name: anchor_id.to_owned(),
+                offset: offset - distance,
+            });
+
+        // If we found a solution, let’s return it
+        // Otherwise we use the first named anchor with a negative offset
+        if let Some(measure) = smallest_measure {
+            Ok(measure)
+        } else {
+            self.iter_named()
+                .next()
+                .map(|(anchor_id, distance)| LrmMeasure {
+                    anchor_name: anchor_id.to_owned(),
+                    offset: offset - distance,
+                })
+                .ok_or(LrmScaleError::NoAnchorFound)
+        }
+    }
+
+    // Private helper function that iterates only over named anchors names and their cummulated distances
+    fn iter_named(&self) -> impl DoubleEndedIterator<Item = (&String, &f64)> {
+        self.anchors
+            .iter()
+            .zip(self.cummulated_distances.iter())
+            .filter_map(|(anchor, distance)| anchor.id.as_ref().map(|id| (id, distance)))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn scale() -> LrmScale {
+        let mut b = ScaleBuilder::new(Anchor::new("a", 0.));
+        b.add(Anchor::new("b", 100.), 100.);
+        b.build().unwrap()
+    }
+
+    #[test]
+    fn builder() {
+        // Everything as planed
+        let scale = scale();
+        assert_eq!(scale.cummulated_distances, vec![0., 100.]);
+
+        // Missing named anchor
+        let b = ScaleBuilder::new(Anchor::new_unamed(0.));
+        let scale = b.build();
+        assert_eq!(scale, Err(LrmScaleError::NoNamedAnchor));
+
+        // Duplicated name
+        let mut b = ScaleBuilder::new(Anchor::new("a", 0.));
+        b.add(Anchor::new("a", 100.), 100.);
+        let scale = b.build();
+        assert_eq!(
+            scale,
+            Err(LrmScaleError::DuplicatedAnchorName("a".to_string()))
+        );
+    }
+
+    #[test]
+    fn locate_point() {
+        let scale = scale();
+
+        // Everything a usual
+        let p = scale.locate_point(LrmMeasure {
+            anchor_name: "b".to_string(),
+            offset: 50.,
+        });
+        assert_eq!(p, Ok(150.));
+
+        // Negative offsets
+        let p = scale.locate_point(LrmMeasure {
+            anchor_name: "a".to_string(),
+            offset: -50.,
+        });
+        assert_eq!(p, Ok(-50.));
+
+        // Unknown anchor
+        let p = scale.locate_point(LrmMeasure {
+            anchor_name: "c".to_string(),
+            offset: 50.,
+        });
+        assert_eq!(p, Err(LrmScaleError::UnknownAnchorName));
+    }
+
+    #[test]
+    fn locate_anchor() {
+        let scale = scale();
+
+        let anchor = scale.locate_anchor(150.).unwrap();
+        assert_eq!(anchor.anchor_name, "b");
+        assert_eq!(anchor.offset, 50.);
+
+        let anchor = scale.locate_anchor(40.).unwrap();
+        assert_eq!(anchor.anchor_name, "a");
+        assert_eq!(anchor.offset, 40.);
+
+        let anchor = scale.locate_anchor(-10.).unwrap();
+        assert_eq!(anchor.anchor_name, "a");
+        assert_eq!(anchor.offset, -10.);
+    }
+}