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,284 @@
+//! 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>,
+
+    /// Distance from the start of the scale in the scale space. Can be negative
+    pub scale_position: f64,
+
+    /// Real distance from the start of the 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 curve_position: f64,
+}
+
+// Private struct to be used when we only deal with anchor that have names
+struct NamedAnchor {
+    id: String,
+    scale_position: f64,
+    curve_position: f64,
+}
+
+impl Anchor {
+    /// Build a named anchor
+    pub fn new(name: &str, scale_position: f64, curve_position: f64) -> Self {
+        Self {
+            id: Some(name.to_owned()),
+            scale_position,
+            curve_position,
+        }
+    }
+
+    /// Build an unamed anchor
+    pub fn new_unamed(scale_position: f64, curve_position: f64) -> Self {
+        Self {
+            id: None,
+            scale_position,
+            curve_position,
+        }
+    }
+}
+
+/// A helper to build a scale by adding consecutives anchors with relative distances
+/// When having all the anchors and their distances in both scale and real position,
+/// it is simpler to directly build the LrmScale from an Vec<Anchor>
+
+pub struct ScaleBuilder {
+    anchors: Vec<Anchor>,
+}
+
+impl ScaleBuilder {
+    /// Create a new scale with an initial anchor
+    pub fn new(anchor: Anchor) -> Self {
+        Self {
+            anchors: vec![anchor],
+        }
+    }
+
+    /// Create a new builder with an initial named anchor, and initial positions at 0
+    pub fn new_named(first_anchor_name: &str) -> Self {
+        Self::new(Anchor {
+            id: Some(first_anchor_name.to_string()),
+            scale_position: 0.,
+            curve_position: 0.,
+        })
+    }
+
+    /// distance_to_previous is the value in the scale it might differ from the real distance measured
+    /// When real_distance is None, they are considered to be equal
+    pub fn add(
+        &mut self,
+        anchor_name: &str,
+        distance_to_previous: f64,
+        real_distance: Option<f64>,
+    ) -> &mut Self {
+        let (last_distance, last_real_distance) = self
+            .anchors
+            .last()
+            .map(|anchor| (anchor.scale_position, anchor.curve_position))
+            .unwrap_or((0., 0.));
+
+        self.anchors.push(Anchor {
+            id: Some(anchor_name.to_owned()),
+            scale_position: last_distance + distance_to_previous,
+            curve_position: last_real_distance + real_distance.unwrap_or(distance_to_previous),
+        });
+        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,
+            })
+        }
+    }
+}
+
+/// 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>,
+}
+
+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| anchor.id == measure.anchor_name)
+            .map(|anchor| anchor.curve_position + 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, curve_position: f64) -> Result<LrmMeasure, LrmScaleError> {
+        let smallest_measure = self
+            .iter_named()
+            .rev()
+            .find(|anchor| anchor.curve_position < curve_position)
+            .map(|anchor| LrmMeasure {
+                anchor_name: anchor.id,
+                offset: curve_position - anchor.curve_position,
+            });
+
+        // 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| LrmMeasure {
+                    anchor_name: anchor.id,
+                    offset: curve_position - anchor.curve_position,
+                })
+                .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 = NamedAnchor> + '_ {
+        self.anchors.iter().filter_map(|anchor| {
+            anchor.id.as_ref().map(|id| NamedAnchor {
+                id: id.to_owned(),
+                scale_position: anchor.scale_position,
+                curve_position: anchor.curve_position,
+            })
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn scale() -> LrmScale {
+        let mut b = ScaleBuilder::new(Anchor::new("a", 0., 0.));
+        b.add("b", 100., None);
+        b.build().unwrap()
+    }
+
+    #[test]
+    fn builder() {
+        // Everything as planed
+        let scale = scale();
+        assert_eq!(scale.anchors[0].curve_position, 0.);
+        assert_eq!(scale.anchors[1].curve_position, 100.);
+
+        // Missing named anchor
+        let b = ScaleBuilder::new(Anchor::new_unamed(0., 0.));
+        let scale = b.build();
+        assert_eq!(scale, Err(LrmScaleError::NoNamedAnchor));
+
+        // Duplicated name
+        let mut b = ScaleBuilder::new(Anchor::new("a", 0., 0.));
+        b.add("a", 100., None);
+        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 mut b = ScaleBuilder::new(Anchor::new("a", 0., 0.));
+        b.add("b", 100., None);
+        b.add("c", 200., Some(1000.));
+        let scale = b.build().unwrap();
+
+        let measure = scale.locate_anchor(150.).unwrap();
+        assert_eq!(measure.anchor_name, "b");
+        assert_eq!(measure.offset, 50.);
+
+        let measure = scale.locate_anchor(40.).unwrap();
+        assert_eq!(measure.anchor_name, "a");
+        assert_eq!(measure.offset, 40.);
+
+        let measure = scale.locate_anchor(-10.).unwrap();
+        assert_eq!(measure.anchor_name, "a");
+        assert_eq!(measure.offset, -10.);
+    }
+}