navcore_enc_store/

corridor.rs

//! The band of water a leg actually occupies.
//!
//! A vessel is allowed to be off track by the leg's own cross-track
//! limit, so checking only the drawn line would pass a route that
//! threads between two rocks but cannot actually be steered. This
//! builds the band of water either side of the track that must be
//! clear -- the same check an ECDIS performs.
//!
//! Port and starboard are tracked separately: a buoyed channel can
//! have, for example, fifty metres of clearance to starboard and
//! twenty to port, which a single symmetric half-width cannot express.
//! IEC 61174 tracks them separately for the same reason.

use geo::{Coord, LineString, Polygon};
use nav_math::{Position, angle, great_circle, rhumb};

/// Longest a piece of the band may be before it is broken up, in nautical
/// miles.
///
/// The band's edges are offsets of a curved track, which is not
/// straight in longitude and latitude. Approximating them as straight
/// segments between distant corners would cut the corner inward on one
/// side, hiding dangers there. A quarter mile keeps that error well
/// below the band's own width, and sets the resolution at which a
/// check reports where a danger was first encountered.
pub(crate) const SEGMENT_NM: f64 = 0.25;

/// How a leg is drawn between its two ends.
///
/// This crate has no dependency on the route domain, so a caller with
/// a route supplies which sailing each leg used.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Sailing {
    /// Constant bearing: a straight line on a Mercator projection, the
    /// default representation for a plotted leg.
    #[default]
    Rhumb,
    /// The shortest path over the sphere; its bearing changes
    /// continuously. The difference from a rhumb line is significant
    /// only on legs of hundreds of miles, where checking the rhumb
    /// line instead would check the wrong water.
    GreatCircle,
}

/// One leg of a route, with the water it is allowed to wander into.
///
/// Known limitation: a leg crossing the antimeridian is not handled.
/// The band is built in longitude and latitude, so a leg from 179°E to
/// 179°W would be drawn the long way around the world, checking the
/// wrong hemisphere. Splitting such a leg at 180° and checking the
/// halves separately would fix this; not yet implemented.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Leg {
    /// Where the leg starts.
    pub from: Position,
    /// Where it ends.
    pub to: Position,
    /// How far the vessel may stray to port of the track, in nautical miles.
    pub port_xtd_nm: f64,
    /// The same to starboard.
    pub starboard_xtd_nm: f64,
    /// How the leg is drawn.
    pub sailing: Sailing,
}

/// A short piece of a leg, with the band around that piece.
#[derive(Debug, Clone)]
pub struct Segment {
    /// Distance from the start of the leg to where this piece begins.
    pub start_nm: f64,
    /// Where this piece begins, on the leg itself.
    pub start: Position,
    /// The band of water around this piece.
    pub band: Polygon<f64>,
}

impl Leg {
    /// A leg with the same tolerance to port and starboard, for a
    /// caller with a single corridor figure and no route to supply
    /// per-side values.
    #[must_use]
    pub fn symmetric(from: Position, to: Position, half_width_nm: f64) -> Self {
        Self {
            from,
            to,
            port_xtd_nm: half_width_nm,
            starboard_xtd_nm: half_width_nm,
            sailing: Sailing::default(),
        }
    }

    /// The leg's length, measured the way the leg is drawn.
    #[must_use]
    pub fn length_nm(&self) -> f64 {
        match self.sailing {
            Sailing::Rhumb => rhumb::distance_nm(self.from, self.to),
            Sailing::GreatCircle => great_circle::distance_nm(self.from, self.to),
        }
    }

    /// The tighter of the two tolerances -- the precision the chart
    /// data must resolve to, regardless of how much room the wider
    /// side allows.
    #[must_use]
    pub fn narrowest_xtd_nm(&self) -> f64 {
        self.port_xtd_nm.min(self.starboard_xtd_nm)
    }

    /// The point `along_nm` from the start, on the track itself.
    #[must_use]
    pub fn point_at(&self, along_nm: f64) -> Position {
        match self.sailing {
            Sailing::Rhumb => {
                rhumb::destination(self.from, rhumb::bearing_deg(self.from, self.to), along_nm)
            }
            // Sailing the departure bearing of a great circle *is* sailing
            // the great circle; the bearing only reads differently further
            // along, which is what course_at is for.
            Sailing::GreatCircle => great_circle::destination(
                self.from,
                great_circle::initial_bearing_deg(self.from, self.to),
                along_nm,
            ),
        }
    }

    /// The course being steered at a point on the track, degrees true.
    ///
    /// Constant on a rhumb line; changes continuously on a great
    /// circle, so the band is offset from the local course at each
    /// point rather than from a single bearing for the whole leg.
    #[must_use]
    pub fn course_at(&self, position: Position, along_nm: f64) -> f64 {
        match self.sailing {
            Sailing::Rhumb => rhumb::bearing_deg(self.from, self.to),
            Sailing::GreatCircle => {
                // At the far end there is no remaining leg to take a
                // bearing along, so the arrival bearing is the answer.
                if along_nm >= self.length_nm() - f64::EPSILON {
                    great_circle::final_bearing_deg(self.from, self.to)
                } else {
                    great_circle::initial_bearing_deg(position, self.to)
                }
            }
        }
    }

    /// The whole band, as one polygon, for the R-Tree index lookup,
    /// which requires a single bounding box.
    ///
    /// `None` for a leg of zero length (no direction, hence no sides)
    /// or zero tolerance.
    #[must_use]
    pub fn band(&self) -> Option<Polygon<f64>> {
        let length_nm = self.length_nm();
        if length_nm <= 0.0 || self.port_xtd_nm <= 0.0 || self.starboard_xtd_nm <= 0.0 {
            return None;
        }
        Some(self.band_between(0.0, length_nm))
    }

    /// The leg cut into pieces, in sailing order.
    ///
    /// Checking piece by piece lets a check report the distance along
    /// the leg where a hazard is first met, rather than only that one
    /// exists.
    #[must_use]
    pub fn segments(&self) -> Vec<Segment> {
        let length_nm = self.length_nm();
        if length_nm <= 0.0 || self.port_xtd_nm <= 0.0 || self.starboard_xtd_nm <= 0.0 {
            return Vec::new();
        }

        let mut segments = Vec::new();
        let mut start_nm = 0.0;
        while start_nm < length_nm {
            let end_nm = (start_nm + SEGMENT_NM).min(length_nm);
            segments.push(Segment {
                start_nm,
                start: self.point_at(start_nm),
                band: self.band_between(start_nm, end_nm),
            });
            start_nm = end_nm;
        }
        segments
    }

    /// The band around the stretch of leg between two distances along
    /// it.
    ///
    /// Squared off at both ends rather than rounded: the water swept
    /// while turning from one leg to the next depends on speed and
    /// turn rate, which this function does not model, so it makes no
    /// claim about turn areas.
    fn band_between(&self, start_nm: f64, end_nm: f64) -> Polygon<f64> {
        // Walk the centre line at the segment resolution, so a long stretch
        // keeps its shape instead of becoming a single sagging quadrilateral.
        let mut centre = Vec::new();
        let mut along_nm = start_nm;
        loop {
            let point = self.point_at(along_nm);
            centre.push((point, self.course_at(point, along_nm)));
            if along_nm >= end_nm {
                break;
            }
            along_nm = (along_nm + SEGMENT_NM).min(end_nm);
        }

        // Up the port side and back down the starboard one.
        let mut ring: Vec<Coord<f64>> = centre
            .iter()
            .map(|(point, course)| {
                offset(*point, angle::norm_360(course - 90.0), self.port_xtd_nm)
            })
            .collect();
        ring.extend(centre.iter().rev().map(|(point, course)| {
            offset(*point, angle::norm_360(course + 90.0), self.starboard_xtd_nm)
        }));

        Polygon::new(LineString::new(ring), Vec::new())
    }
}

/// One position offset sideways, as a coordinate the geometry crate wants:
/// longitude first, which is the opposite order to a [`Position`].
fn offset(from: Position, bearing_deg: f64, distance_nm: f64) -> Coord<f64> {
    let p = rhumb::destination(from, bearing_deg, distance_nm);
    Coord {
        x: p.lon_deg,
        y: p.lat_deg,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use geo::{Contains, Intersects, Point};

    fn leg() -> Leg {
        Leg::symmetric(
            Position::new(45.50, 13.60),
            Position::new(45.50, 13.80),
            0.1,
        )
    }

    #[test]
    fn a_leg_of_no_length_has_no_band() {
        let point = Position::new(45.5, 13.6);
        let leg = Leg::symmetric(point, point, 0.1);
        assert!(leg.band().is_none());
        assert!(leg.segments().is_empty());
    }

    #[test]
    fn a_leg_with_no_width_has_no_band() {
        // Zero tolerance is not "check the line exactly", it is a setting
        // that cannot be honoured. Better to have no band than a band of
        // nothing that quietly passes every route.
        let mut leg = leg();
        leg.starboard_xtd_nm = 0.0;
        assert!(leg.band().is_none());
    }

    #[test]
    fn the_band_holds_the_track_it_was_built_around() {
        // Tested with the same predicate the check uses. The two ends of the
        // leg sit exactly on the band's boundary -- the band is squared off
        // at the waypoints, it does not reach round them -- and `contains`
        // excludes a boundary while `intersects` includes it. A rock at the
        // waypoint has to be found, so `intersects` is the right question
        // here and in the check.
        let leg = leg();
        let band = leg.band().expect("a band");
        for step in 0..=10 {
            let along_nm = leg.length_nm() * f64::from(step) / 10.0;
            let on_track = leg.point_at(along_nm);
            assert!(
                band.intersects(&Point::new(on_track.lon_deg, on_track.lat_deg)),
                "the track itself fell outside its own band at {along_nm} NM"
            );
        }
    }

    #[test]
    fn the_band_reaches_the_tolerance_and_not_much_further() {
        let leg = leg();
        let band = leg.band().expect("a band");
        let middle = leg.point_at(leg.length_nm() / 2.0);
        let course = leg.course_at(middle, leg.length_nm() / 2.0);

        let inside = rhumb::destination(middle, course + 90.0, 0.09);
        let outside = rhumb::destination(middle, course + 90.0, 0.15);
        assert!(band.contains(&Point::new(inside.lon_deg, inside.lat_deg)));
        assert!(!band.intersects(&Point::new(outside.lon_deg, outside.lat_deg)));
    }

    #[test]
    fn the_two_sides_are_measured_separately() {
        // The channel case: room to starboard, none to port. A band that
        // averaged the two would approve water on the wrong side and
        // condemn water on the right one.
        let leg = Leg {
            port_xtd_nm: 0.02,
            starboard_xtd_nm: 0.20,
            ..leg()
        };
        let band = leg.band().expect("a band");
        let middle = leg.point_at(leg.length_nm() / 2.0);
        let course = leg.course_at(middle, leg.length_nm() / 2.0);

        let wide_side = rhumb::destination(middle, course + 90.0, 0.15);
        let narrow_side = rhumb::destination(middle, course - 90.0, 0.15);
        assert!(
            band.contains(&Point::new(wide_side.lon_deg, wide_side.lat_deg)),
            "starboard tolerance was not honoured"
        );
        assert!(
            !band.intersects(&Point::new(narrow_side.lon_deg, narrow_side.lat_deg)),
            "port tolerance was widened to match starboard"
        );
    }

    #[test]
    fn the_narrower_side_is_the_one_the_chart_has_to_answer_for() {
        let leg = Leg {
            port_xtd_nm: 0.02,
            starboard_xtd_nm: 0.20,
            ..leg()
        };
        assert_eq!(leg.narrowest_xtd_nm(), 0.02);
    }

    #[test]
    fn a_great_circle_leg_is_shorter_than_the_rhumb_line_it_replaces() {
        let from = Position::new(50.0, -5.0);
        let to = Position::new(40.0, -60.0);
        let rhumb_leg = Leg::symmetric(from, to, 1.0);
        let gc_leg = Leg {
            sailing: Sailing::GreatCircle,
            ..rhumb_leg
        };
        assert!(gc_leg.length_nm() < rhumb_leg.length_nm() - 10.0);
    }

    #[test]
    fn a_great_circle_band_follows_its_own_track_and_not_the_rhumb_line() {
        // The point of carrying the sailing at all. On an ocean leg the two
        // tracks are far apart, so a band built on the wrong one checks
        // water the vessel never crosses -- and misses the water it does.
        let from = Position::new(50.0, -5.0);
        let to = Position::new(40.0, -60.0);
        let gc_leg = Leg {
            sailing: Sailing::GreatCircle,
            ..Leg::symmetric(from, to, 5.0)
        };
        let band = gc_leg.band().expect("a band");

        let half_way_gc = gc_leg.point_at(gc_leg.length_nm() / 2.0);
        assert!(
            band.intersects(&Point::new(half_way_gc.lon_deg, half_way_gc.lat_deg)),
            "the great circle track left its own band"
        );

        let rhumb_leg = Leg::symmetric(from, to, 5.0);
        let half_way_rhumb = rhumb_leg.point_at(rhumb_leg.length_nm() / 2.0);
        assert!(
            !band.intersects(&Point::new(half_way_rhumb.lon_deg, half_way_rhumb.lat_deg)),
            "the rhumb line should be nowhere near this band"
        );
    }

    #[test]
    fn the_pieces_cover_the_leg_end_to_end_in_order() {
        let leg = leg();
        let segments = leg.segments();
        assert!(segments.len() > 1, "a leg longer than a segment splits");

        assert_eq!(segments[0].start_nm, 0.0);
        for pair in segments.windows(2) {
            assert!(pair[0].start_nm < pair[1].start_nm, "pieces out of order");
        }
        let last = segments.last().expect("pieces");
        assert!(
            last.start_nm < leg.length_nm(),
            "a piece started past the end of the leg"
        );
    }

    #[test]
    fn a_piece_only_covers_its_own_stretch() {
        // The whole point of the pieces is telling *where* something was
        // met, so a piece that reached the far end of the leg would make
        // every report say "at zero miles".
        let leg = leg();
        let first = &leg.segments()[0];
        let far_end = Point::new(leg.to.lon_deg, leg.to.lat_deg);
        assert!(!first.band.intersects(&far_end));
    }
}