navcore_fix/

vessel.rs

//! Own-ship state, how it is assembled, and a simulator to produce it until
//! real readings arrive.
//!
//! Everything a client draws about the vessel is computed here, in Rust,
//! using `nav-math`. A client is handed finished coordinates and does no
//! navigation arithmetic of its own -- otherwise the same arithmetic gets
//! written again for every other client.

use std::time::Duration;

use nav_math::{Position, angle, great_circle};

/// How far ahead the course predictor reaches, in minutes of run at the
/// current speed.
///
/// Six minutes is the usual default in marine navigation practice, and it
/// has a neat property that is why it was chosen: at six minutes the
/// predictor length in nautical miles is a tenth of the speed in knots,
/// so the line doubles as a speed readout once the eye is trained.
const PREDICTOR_MINUTES: f64 = 6.0;

/// Shortest the heading line is ever drawn, in nautical miles. See
/// [`VesselState::heading_line_end`].
const MIN_HEADING_LINE_NM: f64 = 0.15;

/// What a client knows about own ship at one instant.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct VesselState {
    /// Where the vessel is.
    pub position: Position,
    /// Course over ground, degrees true.
    pub cog_deg: f64,
    /// Speed over ground, knots.
    pub sog_kn: f64,
    /// Heading, degrees true, when the vessel has a compass.
    ///
    /// Differs from course when there is leeway or current. `None` when
    /// the vessel has no heading sensor; substituting course in that
    /// case would misrepresent a measurement as heading.
    pub heading_deg: Option<f64>,
}

impl VesselState {
    /// The far end of the course predictor: where the vessel reaches if it
    /// holds this course and speed for `PREDICTOR_MINUTES`.
    #[must_use]
    pub fn predictor_end(&self) -> Position {
        let distance_nm = self.sog_kn * (PREDICTOR_MINUTES / 60.0);
        great_circle::destination(self.position, self.cog_deg, distance_nm)
    }

    /// The far end of the heading line: where the bow points, which
    /// differs from the course over ground under leeway or current.
    ///
    /// Length matches the course predictor so the angle between them is
    /// directly comparable, with a floor (`MIN_HEADING_LINE_NM`) so
    /// the line stays visible for a vessel stopped in a tideway. `None`
    /// when there is no compass; no line is drawn in that case.
    #[must_use]
    pub fn heading_line_end(&self) -> Option<Position> {
        let heading_deg = self.heading_deg?;
        let distance_nm = (self.sog_kn * (PREDICTOR_MINUTES / 60.0)).max(MIN_HEADING_LINE_NM);
        Some(great_circle::destination(
            self.position,
            heading_deg,
            distance_nm,
        ))
    }
}

/// A [`VesselState`] under construction, built up one reading at a time.
///
/// Readings arrive as separate calls to its setters regardless of
/// source -- a Signal K delta, a parsed NMEA 0183 sentence, a replayed
/// passage -- and this type only tracks whether enough have arrived
/// for a complete state. It has no knowledge of the source protocol.
#[derive(Debug, Clone, Copy, Default)]
pub struct FixBuilder {
    position: Option<Position>,
    cog_deg: Option<f64>,
    sog_kn: Option<f64>,
    heading_deg: Option<f64>,
}

impl FixBuilder {
    /// Nothing heard yet.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Records a position. Only a position update marks a fix as
    /// fresh; course and speed updates alone must not reset the age of
    /// a stalled position.
    pub fn set_position(&mut self, position: Position) {
        self.position = Some(position);
    }

    /// Records course over ground, degrees true.
    pub fn set_course_over_ground(&mut self, deg: f64) {
        self.cog_deg = Some(deg);
    }

    /// Records speed over ground, knots.
    pub fn set_speed_over_ground(&mut self, kn: f64) {
        self.sog_kn = Some(kn);
    }

    /// Records heading, degrees true. Never required -- see
    /// [`VesselState::heading_deg`].
    pub fn set_heading(&mut self, deg: f64) {
        self.heading_deg = Some(deg);
    }

    /// A complete state, if enough has arrived to build one.
    ///
    /// Heading may be missing -- a vessel without a compass has no
    /// heading line. Position, course and speed are required; there is
    /// no meaningful default for any of them.
    #[must_use]
    pub fn complete(self) -> Option<VesselState> {
        Some(VesselState {
            position: self.position?,
            cog_deg: self.cog_deg?,
            sog_kn: self.sog_kn?,
            heading_deg: self.heading_deg,
        })
    }
}

/// Moves a vessel over the ground, producing a state to render before a
/// real position source is available.
///
/// A pure function of elapsed time rather than wall-clock time, so the
/// same call sequence produces the same track on every run, and a
/// session can be replayed faster than real time.
#[derive(Debug, Clone)]
pub struct Simulator {
    state: VesselState,
    /// Degrees per second, positive to starboard. Nonzero so the
    /// simulated course visibly changes over time.
    turn_rate_deg_s: f64,
}

impl Simulator {
    /// A vessel under way in the Gulf of Trieste, where this project's
    /// charts have coverage.
    #[must_use]
    pub fn new() -> Self {
        Self {
            state: VesselState {
                position: Position::new(45.5500, 13.7300),
                cog_deg: 300.0,
                sog_kn: 6.2,
                heading_deg: Some(297.0),
            },
            turn_rate_deg_s: 0.35,
        }
    }

    /// Advances the vessel by `dt` and returns the new state.
    pub fn tick(&mut self, dt: Duration) -> VesselState {
        let seconds = dt.as_secs_f64();

        self.state.cog_deg = angle::norm_360(self.state.cog_deg + self.turn_rate_deg_s * seconds);
        // Heading lags the course by a fixed offset here; with no wind or
        // current model there is nothing better to base it on, and pretending
        // otherwise would invent data.
        self.state.heading_deg = Some(angle::norm_360(self.state.cog_deg - 3.0));

        let distance_nm = self.state.sog_kn * (seconds / 3600.0);
        self.state.position =
            great_circle::destination(self.state.position, self.state.cog_deg, distance_nm);

        self.state
    }

    /// The current state without advancing it.
    #[must_use]
    pub fn state(&self) -> VesselState {
        self.state
    }
}

impl Default for Simulator {
    fn default() -> Self {
        Self::new()
    }
}

/// A plausible wind, for a simulated run with no boat to have a real one.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SimulatedWind {
    /// Degrees true -- an absolute bearing the wind blows *from*.
    pub direction_true_deg: f64,
    /// Knots.
    pub speed_kn: f64,
}

/// A plausible wind for a simulated run, for features built on wind
/// data (laylines, a wind readout) to have something to display before
/// a real wind source exists.
///
/// A plain function of `now` rather than a [`Simulator`] method, since
/// wind needs no accumulated state, only elapsed time. Direction and
/// speed oscillate slowly rather than staying fixed, so a change a
/// caller makes -- to a beat-angle setting, say -- remains
/// distinguishable from the simulated wind's own variation.
///
/// `now` is elapsed time since the run started, deterministic like
/// every other simulated value, so a recorded session replays
/// identically.
#[must_use]
pub fn simulated_wind(now: Duration) -> SimulatedWind {
    let t = now.as_secs_f64();
    SimulatedWind {
        direction_true_deg: angle::norm_360(270.0 + 15.0 * (t / 40.0).sin()),
        speed_kn: 12.0 + 3.0 * (t / 25.0).sin(),
    }
}

/// Formats a latitude as degrees and decimal minutes, the conventional
/// format in marine navigation (charts, almanacs, radio position
/// reports), rather than the decimal degrees used internally.
#[must_use]
pub fn format_latitude(lat_deg: f64) -> String {
    let hemisphere = if lat_deg < 0.0 { 'S' } else { 'N' };
    format!("{}{hemisphere}", degrees_minutes(lat_deg.abs(), 2))
}

/// Formats a longitude, three-digit degrees as is conventional.
#[must_use]
pub fn format_longitude(lon_deg: f64) -> String {
    let hemisphere = if lon_deg < 0.0 { 'W' } else { 'E' };
    format!("{}{hemisphere}", degrees_minutes(lon_deg.abs(), 3))
}

fn degrees_minutes(value: f64, degree_width: usize) -> String {
    let mut degrees = value.trunc();
    let mut minutes = (value - degrees) * 60.0;

    // 59.996' rounds to 60.00' at two decimals, which is not a minute that
    // exists. Carry it into the degrees instead of printing it.
    if minutes >= 59.995 {
        minutes = 0.0;
        degrees += 1.0;
    }

    format!("{:0degree_width$.0}\u{00b0}{:05.2}\u{2032}", degrees, minutes)
}

#[cfg(test)]
mod simulated_wind_tests {
    use super::*;

    #[test]
    fn it_stays_within_a_believable_range() {
        for secs in 0..600 {
            let wind = simulated_wind(Duration::from_secs(secs));
            assert!((0.0..360.0).contains(&wind.direction_true_deg), "{wind:?}");
            assert!(wind.speed_kn > 0.0, "{wind:?}");
        }
    }

    #[test]
    fn it_is_deterministic_from_the_same_clock() {
        let a = simulated_wind(Duration::from_secs(123));
        let b = simulated_wind(Duration::from_secs(123));
        assert_eq!(a, b);
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn close(a: f64, b: f64, tol: f64) -> bool {
        (a - b).abs() < tol
    }

    #[test]
    fn the_predictor_is_a_tenth_of_the_speed_in_miles() {
        // The property that makes six minutes the conventional choice.
        let state = VesselState {
            position: Position::new(45.0, 13.0),
            cog_deg: 0.0,
            sog_kn: 6.0,
            heading_deg: Some(0.0),
        };
        let run = great_circle::distance_nm(state.position, state.predictor_end());
        assert!(close(run, 0.6, 1e-9), "got {run}");
    }

    #[test]
    fn a_stopped_vessel_has_no_predictor() {
        let state = VesselState {
            position: Position::new(45.0, 13.0),
            cog_deg: 90.0,
            sog_kn: 0.0,
            heading_deg: Some(90.0),
        };
        // Not exact equality: the destination formula round-trips the
        // latitude through asin(sin(x)), which need not land on the same bit
        // pattern. The property being asserted is that the vector has no
        // length, and that is what to measure.
        let run = great_circle::distance_nm(state.position, state.predictor_end());
        assert!(close(run, 0.0, 1e-12), "stopped vessel predicted {run} NM ahead");
    }

    #[test]
    fn the_heading_line_survives_the_vessel_stopping() {
        let state = VesselState {
            position: Position::new(45.0, 13.0),
            cog_deg: 90.0,
            sog_kn: 0.0,
            heading_deg: Some(45.0),
        };
        let end = state.heading_line_end().expect("a compass");
        let run = great_circle::distance_nm(state.position, end);
        assert!(close(run, MIN_HEADING_LINE_NM, 1e-9), "got {run}");
        // And it still points at the bow, not at the course.
        let brg = great_circle::initial_bearing_deg(state.position, end);
        assert!(close(brg, 45.0, 1e-6), "heading line ran off on {brg}");
    }

    #[test]
    fn under_way_the_two_lines_are_the_same_length_and_differ_only_in_angle() {
        let state = VesselState {
            position: Position::new(45.0, 13.0),
            cog_deg: 300.0,
            sog_kn: 6.2,
            heading_deg: Some(297.0),
        };
        let cog_run = great_circle::distance_nm(state.position, state.predictor_end());
        let heading_end = state.heading_line_end().expect("a compass");
        let hdg_run = great_circle::distance_nm(state.position, heading_end);
        assert!(close(cog_run, hdg_run, 1e-9), "{cog_run} vs {hdg_run}");

        let separation = angle::diff(
            great_circle::initial_bearing_deg(state.position, state.predictor_end()),
            great_circle::initial_bearing_deg(state.position, heading_end),
        );
        assert!(close(separation, 3.0, 1e-6), "got {separation}");
    }

    #[test]
    fn ticking_moves_the_vessel_at_its_speed() {
        let mut sim = Simulator::new();
        sim.turn_rate_deg_s = 0.0; // straight, so distance is checkable
        let before = sim.state();
        let after = sim.tick(Duration::from_secs(3600));
        let run = great_circle::distance_nm(before.position, after.position);
        assert!(close(run, before.sog_kn, 1e-3), "one hour ran {run} NM");
    }

    #[test]
    fn the_simulated_course_stays_a_valid_bearing() {
        let mut sim = Simulator::new();
        for _ in 0..2000 {
            let s = sim.tick(Duration::from_secs(1));
            assert!((0.0..360.0).contains(&s.cog_deg), "cog {} left range", s.cog_deg);
            let heading = s.heading_deg.expect("the simulator has a compass");
            assert!((0.0..360.0).contains(&heading), "heading {heading} left range");
        }
    }

    #[test]
    fn a_vessel_without_a_compass_gets_no_heading_line() {
        // Not a line along the course, which would look like a measurement
        // and hide the leeway the two lines exist to show. Nothing at all.
        let state = VesselState {
            position: Position::new(45.0, 13.0),
            cog_deg: 90.0,
            sog_kn: 5.0,
            heading_deg: None,
        };
        assert!(state.heading_line_end().is_none());
        // The course predictor is unaffected: it needs no compass.
        assert!(great_circle::distance_nm(state.position, state.predictor_end()) > 0.0);
    }

    #[test]
    fn positions_are_degrees_and_decimal_minutes() {
        assert_eq!(format_latitude(45.55), "45\u{00b0}33.00\u{2032}N");
        assert_eq!(format_longitude(13.73), "013\u{00b0}43.80\u{2032}E");
    }

    #[test]
    fn the_southern_and_western_hemispheres_are_not_negative_numbers() {
        assert_eq!(format_latitude(-33.8688), "33\u{00b0}52.13\u{2032}S");
        assert_eq!(format_longitude(-5.2), "005\u{00b0}12.00\u{2032}W");
    }

    #[test]
    fn sixty_minutes_carries_into_the_degree() {
        // 45.99999 deg is 45 deg 59.9994', which must not print as 45°60.00'.
        assert_eq!(format_latitude(45.999_99), "46\u{00b0}00.00\u{2032}N");
    }

    #[test]
    fn a_builder_with_only_a_position_is_not_a_state() {
        let mut builder = FixBuilder::new();
        builder.set_position(Position::new(45.5, 13.7));
        assert!(builder.complete().is_none(), "position alone is not a state");

        builder.set_course_over_ground(300.0);
        assert!(builder.complete().is_none());

        builder.set_speed_over_ground(6.2);
        assert!(builder.complete().is_some());
    }

    #[test]
    fn a_builder_with_no_compass_still_produces_a_state() {
        let mut builder = FixBuilder::new();
        builder.set_position(Position::new(45.5, 13.7));
        builder.set_course_over_ground(300.0);
        builder.set_speed_over_ground(6.2);

        let state = builder.complete().expect("a state");
        assert!(state.heading_deg.is_none());
    }
}