Merge pull request #13 from osrd-project/various_improvements

Various improvements

Author: Tristramg

schema/lrs.fbs

@@ -62,7 +62,7 @@ table Connection {
     endpoint:Endpoint = null;
 }
 
-///  A traversal is a path in a network.
+/// A traversal is a path in a network.
 /// Traversals may be used to model roads, railway tracks, railway lines or trips.
 /// Traversals are defined as a sequence of segment and direction pairs.
 enum Direction : byte { Increasing = 1, Decreasing = 2 }
@@ -124,7 +124,7 @@ table LinearReferencingMethod {
     /// And that LRM is the reference for the two other traversals corresponding to each direction
     used_on:[TraversalRef];
     anchor_indices:[uint64] (required);
-    distances:[uint64] (required);
+    distances:[double] (required);
     /// The unit used to measure the distance between anchors
     distance_unit:DistanceUnit = Meters;
     /// The unit used to express measures relative to anchors (12+230)

src/curves.rs

@@ -9,94 +9,89 @@ use geo::prelude::*;
 use geo::{coord, Line, LineString, Point, Rect};
 use thiserror::Error;
 
-/// A curve is the fundamental building block for an LRM
-/// It provides basic primitives to locate/project points on it
-/// A curve can be part of a larger curve (e.g. for optimisation purpurses and have better bounding boxes)
-/// The curve can be implemented
+/// A `Curve` is the fundamental building block for an LRM.
+/// It provides basic primitives to locate/project points on it.
+/// A `Curve` can be part of a larger `Curve` (e.g. for optimisation purposes and to have better bounding boxes).
+/// The `Curve` can be implemented.
 pub trait Curve {
-    /// Project the point to the closest position on the curve
-    /// Will fail if the curve is invalid (e.g. no points on it)
-    /// or if the point is to far away
-    /// If the curve is a piece of a larger curve (start_offset > 0)
-    /// then the distance_along_curve if from the whole curve, not just the current piece
+    /// Builds a new `Curve` from a [LineString].
+    /// `max_extent` is the maximum distance that is considered to be “on the curve”.
+    /// `max_extent` plays a role in the bounding box.
+    fn new(geom: LineString, max_extent: f64) -> Self;
+
+    /// Projects the [Point] to the closest position on the `Curve`.
+    /// Will fail if the `Curve` is invalid (e.g. no `Point` on it)
+    /// or if the `Point` is too far away.
+    /// If the `Curve` is a piece of a larger `Curve` (`start_offset > 0`)
+    /// then the `distance_along_curve` if from the whole `Curve`, not just the current piece.
     fn project(&self, point: Point) -> Result<CurveProjection, CurveError>;
 
-    /// Returns the geographical position of a point on the curve
-    /// Will return an error if the CurveProjection is not on this Curve
-    fn resolve(&self, projection: &CurveProjection) -> Result<Point, CurveError>;
+    /// Returns the geographical position of a [Point] on the `Curve`.
+    /// Will return an error if the `CurveProjection` is not on this `Curve`.
+    fn resolve(&self, projection: CurveProjection) -> Result<Point, CurveError>;
 
-    /// Bounding box of the curve with a buffer of `max_extent`
+    /// Bounding box of the `Curve` with a buffer of `max_extent`.
     fn bbox(&self) -> Rect;
 
-    /// The length of the curve
+    /// The length of the `Curve`.
     fn length(&self) -> f64;
 
-    /// Computes the normal at a given offset on the curve
-    /// Will return an error if the curve is invalid or the offset is outside of the curve
-    /// Points to the positive side (left)
+    /// Computes the normal at a given offset on the `Curve`.
+    /// Will return an error if the `Curve` is invalid or the offset is outside of the `Curve`.
+    /// Points to the positive side (left).
     fn get_normal(&self, offset: f64) -> Result<(f64, f64), CurveError>;
 
-    /// Returns the point where the curve and the segment intersect
-    /// If the segment intersects the curve multiple times, an intersection is chosen randomly
-    /// When the segment is colinear with the curve it is ignored
+    /// Returns the [Point] where the `Curve` and the segment intersect.
+    /// If the segment intersects the `Curve` multiple times, an intersection is chosen randomly.
+    /// When the segment is colinear with the `Curve` it is ignored.
     fn intersect_segment(&self, segment: Line) -> Option<Point>;
 
-    /// Is the geometry valid. Depending on the representation
-    /// It must have at least two coordinates
-    /// If there are exactly two coordinates, they must be different
+    /// Is the geometry valid. Depending on the representation.
+    /// It must have at least two coordinates.
+    /// If there are exactly two coordinates, they must be different.
     fn is_valid(&self) -> bool;
+
+    /// How far from the `Curve` could be considered to be still on the `Curve`.
+    fn max_extent(&self) -> f64;
 }
 
-/// Errors when manipulating the curves
-#[derive(Error, Debug)]
+/// Errors when manipulating the [Curve] objects.
+#[derive(Error, Debug, PartialEq)]
 pub enum CurveError {
-    /// Depeding on the curve implementation the condition of validity might differ
+    /// The condition of validity might differ depending on the [Curve] implementation.
     #[error("the curve geometry is not valid")]
     InvalidGeometry,
-    /// At least a coordinate is non a finite number (NaN, inifinite)
+    /// At least one coordinate is non a finite number (`NaN`, `infinite`).
     #[error("the coordinates are not finite")]
     NotFiniteCoordinates,
-    /// A considered point is not on the curve
+    /// The considered [Point] is not on the [Curve].
     #[error("the point is not on the curve")]
     NotOnTheCurve,
 }
 
 /// Implementation based on [LineString]:
-/// the curve is a string of continous [Line]
-/// The coordinates are reprensented by f64.
-/// That means a precison of about 1_000_000th of a mm for a curve that spans around the Earth
+/// the [Curve] is a string of continous [Line].
+/// The coordinates are reprensented by `f64`.
+/// That means a precison of about 1_000_000th of a mm for a `Curve` that spans around the Earth.
 pub struct LineStringCurve {
-    /// When curve might be a piece of a longer curve
-    /// then the start_offset allows to know how fare along the longer curve we are
+    /// When a [Curve] might be a piece of a longer `Curve`
+    /// then the `start_offset` allows to know how fare along the longer `Curve` we are.
     pub start_offset: f64,
 
-    /// The max distance that is considered of being part of the curve
-    /// It is used to compute the bounding box
+    /// The max distance that is considered of being part of the [Curve].
+    /// It is used to compute the bounding box.
     pub max_extent: f64,
 
-    /// The coordinates are considered as being planar
-    /// All distance and length computations are in units of those coordinates
+    /// The coordinates are considered to be planar.
+    /// All distance and length calculations are expressed in the same units as coordinates.
     pub geom: LineString,
 
     length: f64,
 }
 
 impl LineStringCurve {
-    /// Build a new curve from a LineString
-    /// max_extent is the maximum distance that is considered to be “on the curve”
-    /// max_extent plays a role in the bounding box
-    pub fn new(geom: LineString, max_extent: f64) -> Self {
-        let length = geom.euclidean_length();
-        Self {
-            start_offset: 0.,
-            max_extent,
-            geom,
-            length,
-        }
-    }
-
-    /// Splits the LineString into smaller curves of at most `max_len` length
-    /// If the initial geometry is invalid, it returns an empty vector
+    /// Splits the [LineString] into smaller [Curve] objects of at most `max_len` length.
+    /// If the initial geometry is invalid, it returns an empty vector.
     pub fn new_fragmented(geom: LineString, max_len: f64, max_extent: f64) -> Vec<Self> {
         let n = (geom.euclidean_length() / max_len).ceil() as usize;
         geom.line_segmentize(n)
@@ -112,6 +107,16 @@ impl LineStringCurve {
 }
 
 impl Curve for LineStringCurve {
+    fn new(geom: LineString, max_extent: f64) -> Self {
+        let length = geom.euclidean_length();
+        Self {
+            start_offset: 0.,
+            max_extent,
+            geom,
+            length,
+        }
+    }
+
     fn project(&self, point: Point) -> Result<CurveProjection, CurveError> {
         if !self.is_valid() {
             return Err(CurveError::InvalidGeometry);
@@ -128,7 +133,7 @@ impl Curve for LineStringCurve {
                     Orientation::Clockwise => 1.,
                     _ => -1.,
                 };
-                let offset = (point.euclidean_distance(&self.geom) * sign) as isize;
+                let offset = point.euclidean_distance(&self.geom) * sign;
 
                 Ok(CurveProjection {
                     distance_along_curve,
@@ -139,7 +144,7 @@ impl Curve for LineStringCurve {
         }
     }
 
-    fn resolve(&self, projection: &CurveProjection) -> Result<Point, CurveError> {
+    fn resolve(&self, projection: CurveProjection) -> Result<Point, CurveError> {
         let fraction = (projection.distance_along_curve - self.start_offset) / self.length();
         if !(0. ..=1.).contains(&fraction) || fraction.is_nan() {
             Err(CurveError::NotOnTheCurve)
@@ -182,17 +187,17 @@ impl Curve for LineStringCurve {
     }
 
     fn get_normal(&self, offset: f64) -> Result<(f64, f64), CurveError> {
-        // We find the point where the normal is computed
-        let point = self.resolve(&CurveProjection {
+        // We find the Point where the normal is computed
+        let point = self.resolve(CurveProjection {
             distance_along_curve: offset,
-            offset: 0,
+            offset: 0.,
         })?;
 
-        // We find the line where the point is located
+        // We find the line where the Point is located
         // This line will be used to construct the normal:
         // - we translate it so that it starts at `0,0`
-        // - we rotated it by 90°
-        // - we scale it in order to be a unit vector
+        // - we rotate it by 90°
+        // - we scale it in order to become a unit vector
         let line = self
             .geom
             .lines_iter()
@@ -211,18 +216,23 @@ impl Curve for LineStringCurve {
     fn is_valid(&self) -> bool {
         self.geom.coords_count() >= 2 && (self.geom.coords_count() > 2 || !self.geom.is_closed())
     }
+
+    fn max_extent(&self) -> f64 {
+        self.max_extent
+    }
 }
 
-/// Represents a point in space projected on the curve
+/// Represents a [Point] in space projected on the [Curve]
+#[derive(Clone, Copy)]
 pub struct CurveProjection {
-    /// How far from the curve start is located the point
-    /// If the curve is part of a larger curve, start_offset is strictly positive
-    /// and the start_offset will be considered
+    /// How far from the [Curve] start is located the [Point]
+    /// If the `Curve` is part of a larger `Curve`, `start_offset` is strictly positive
+    /// and the `start_offset` will be considered
     pub distance_along_curve: f64,
-    /// How far is the point from the curve (euclidian distance)
-    /// It is positive if the point is located on the left of the curve
-    /// and negative if the point is on the right
-    pub offset: isize,
+    /// How far is the [Point] from the [Curve] (euclidian distance)
+    /// It is positive if the `Point` is located on the left of the `Curve`
+    /// and negative if the `Point` is on the right
+    pub offset: f64,
 }
 
 #[cfg(test)]
@@ -244,11 +254,11 @@ mod tests {
 
         let projected = c.project(point! {x: 1., y: 1.}).unwrap();
         assert_eq!(1., projected.distance_along_curve);
-        assert_eq!(1, projected.offset);
+        assert_eq!(1., projected.offset);
 
         let projected = c.project(point! {x: 1., y: -1.}).unwrap();
         assert_eq!(1., projected.distance_along_curve);
-        assert_eq!(-1, projected.offset);
+        assert_eq!(-1., projected.offset);
 
         c.start_offset = 1.;
         let projected = c.project(point! {x: 1., y: -1.}).unwrap();
@@ -261,18 +271,18 @@ mod tests {
 
         let mut projection = CurveProjection {
             distance_along_curve: 1.,
-            offset: 0,
+            offset: 0.,
         };
-        let p = c.resolve(&projection).unwrap();
+        let p = c.resolve(projection).unwrap();
         assert_eq!(p.x(), 1.);
         assert_eq!(p.y(), 0.);
 
         c.start_offset = 1.;
-        let p = c.resolve(&projection).unwrap();
+        let p = c.resolve(projection).unwrap();
         assert_eq!(p.x(), 0.);
 
         projection.distance_along_curve = 4.;
-        assert!(c.resolve(&projection).is_err());
+        assert!(c.resolve(projection).is_err());
     }
 
     #[test]
@@ -296,7 +306,7 @@ mod tests {
         let segment = Line::new(coord! {x: 10., y: 10.}, coord! {x:20., y: 10.});
         assert!(c.intersect_segment(segment).is_none());
 
-        // Colinear
+        // Collinear
         let segment = Line::new(coord! {x: 0., y:0.,}, coord! {x: 1., y:0.});
         assert!(c.intersect_segment(segment).is_none());
 

src/lrs_generated.rs

@@ -105,7 +105,7 @@ pub const ENUM_VALUES_DIRECTION: [Direction; 2] = [
   Direction::Decreasing,
 ];
 
-///  A traversal is a path in a network.
+/// A traversal is a path in a network.
 /// Traversals may be used to model roads, railway tracks, railway lines or trips.
 /// Traversals are defined as a sequence of segment and direction pairs.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
@@ -1992,11 +1992,11 @@ impl<'a> LinearReferencingMethod<'a> {
     unsafe { self._tab.get::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'a, u64>>>(LinearReferencingMethod::VT_ANCHOR_INDICES, None).unwrap()}
   }
   #[inline]
-  pub fn distances(&self) -> flatbuffers::Vector<'a, u64> {
+  pub fn distances(&self) -> flatbuffers::Vector<'a, f64> {
     // Safety:
     // Created from valid Table for this object
     // which contains a valid value in this slot
-    unsafe { self._tab.get::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'a, u64>>>(LinearReferencingMethod::VT_DISTANCES, None).unwrap()}
+    unsafe { self._tab.get::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'a, f64>>>(LinearReferencingMethod::VT_DISTANCES, None).unwrap()}
   }
   /// The unit used to measure the distance between anchors
   #[inline]
@@ -2028,7 +2028,7 @@ impl flatbuffers::Verifiable for LinearReferencingMethod<'_> {
      .visit_field::<TraversalRef>("traversal_index", Self::VT_TRAVERSAL_INDEX, false)?
      .visit_field::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'_, TraversalRef>>>("used_on", Self::VT_USED_ON, false)?
      .visit_field::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'_, u64>>>("anchor_indices", Self::VT_ANCHOR_INDICES, true)?
-     .visit_field::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'_, u64>>>("distances", Self::VT_DISTANCES, true)?
+     .visit_field::<flatbuffers::ForwardsUOffset<flatbuffers::Vector<'_, f64>>>("distances", Self::VT_DISTANCES, true)?
      .visit_field::<DistanceUnit>("distance_unit", Self::VT_DISTANCE_UNIT, false)?
      .visit_field::<DistanceUnit>("measure_unit", Self::VT_MEASURE_UNIT, false)?
      .finish();
@@ -2041,7 +2041,7 @@ pub struct LinearReferencingMethodArgs<'a> {
     pub traversal_index: Option<&'a TraversalRef>,
     pub used_on: Option<flatbuffers::WIPOffset<flatbuffers::Vector<'a, TraversalRef>>>,
     pub anchor_indices: Option<flatbuffers::WIPOffset<flatbuffers::Vector<'a, u64>>>,
-    pub distances: Option<flatbuffers::WIPOffset<flatbuffers::Vector<'a, u64>>>,
+    pub distances: Option<flatbuffers::WIPOffset<flatbuffers::Vector<'a, f64>>>,
     pub distance_unit: DistanceUnit,
     pub measure_unit: DistanceUnit,
 }
@@ -2087,7 +2087,7 @@ impl<'a: 'b, 'b> LinearReferencingMethodBuilder<'a, 'b> {
     self.fbb_.push_slot_always::<flatbuffers::WIPOffset<_>>(LinearReferencingMethod::VT_ANCHOR_INDICES, anchor_indices);
   }
   #[inline]
-  pub fn add_distances(&mut self, distances: flatbuffers::WIPOffset<flatbuffers::Vector<'b , u64>>) {
+  pub fn add_distances(&mut self, distances: flatbuffers::WIPOffset<flatbuffers::Vector<'b , f64>>) {
     self.fbb_.push_slot_always::<flatbuffers::WIPOffset<_>>(LinearReferencingMethod::VT_DISTANCES, distances);
   }
   #[inline]