Crate bearingpro 

Marine navigation: compass corrections, the sailings, dead reckoning, position fixing and collision avoidance.

magnetic course = compass course  + deviation(compass course)
true course     = magnetic course + variation

What the types do for you

Every angle in this crate is a newtype that carries its reference frame: CompassCourse, MagneticCourse, TrueCourse, GyroCourse, Variation, Deviation, RelativeBearing. Passing a magnetic course where a true one belongs, or a variation where a course belongs, does not compile. Distances and speeds are types too — Distance and Speed — so knots cannot be handed to something expecting metres per second.

Each type also owns its range invariant: a Direction is always finite and always in [0°, 360°), a Latitude always in [-90°, 90°]. That is why the pure corrections return a value rather than a Result.

Nothing in this crate panics on caller-supplied data. Bad input comes back as a NavigationError.

Example

use bearingpro::{
    navigation_solutions::{
        convert_compass_course_to_true_course, convert_true_course_to_compass_course,
    },
    CompassCourse, DeviationTable, InterpolationMethod, TrueCourse, Variation,
};

// A swing: deviation observed on every tenth of the compass, 000° to 350°.
let table = DeviationTable::from_deviation_vec(vec![
    -2.5, -0.5, 1.6, 4.4, -1.7, 0.0, 1.0, 0.3, -0.9, // 000°..080°
    0.5, -1.2, 0.8, -0.3, 1.7, -2.1, 0.4, -0.6, 1.2, // 090°..170°
    -1.3, 0.0, 0.9, -1.1, 1.5, -0.7, -13.2, -15.7, -17.9, // 180°..260°
    -19.2, -18.1, 1.8, -0.4, 0.7, -0.2, 1.4, -4.4, -2.9, // 270°..350°
])?;

let variation = Variation::new(-2.7)?;

// What is the ship actually making good, steering 003° by the compass?
let solution = convert_compass_course_to_true_course(
    CompassCourse::new(3.0)?,
    variation,
    &table,
    InterpolationMethod::Cubic,
)?;
assert_eq!(format!("{}", solution.course), "358.2°T");

// And back again: the inverse solves for the compass course the table is
// indexed by, so the two directions agree.
let back = convert_true_course_to_compass_course(
    solution.course,
    variation,
    &table,
    InterpolationMethod::Cubic,
)?;
assert!((back.course.degrees() - 3.0).abs() < 1e-9);

// This particular swing jumps 12.5° between 230° and 240°, which is steeper
// than a compass can be steered by. The result says so instead of leaving
// you to discover it at sea.
assert!(solution.advisories.non_invertible_table);

Modules

• angle — the frame-tagged angle types and their invariants.
• units — angles, distances and speeds, so the unit is never in doubt.
• position — latitude, longitude, and how a position is written down.
• deviation — deviation tables, periodic interpolation, coefficient fitting.
• navigation_solutions — course and bearing conversions, gyro error, the current triangle.
• sailings — rhumb line, great circle, WGS-84 geodesic, cross-track error.
• dead_reckoning — DR and estimated positions, traverses, leeway.
• fix — position lines, fixes, cocked hats, distance off.
• relative_motion — closest approach, radar plotting, the avoiding manoeuvre.
• route — passage plans: legs, distances, schedule, progress along the track.
• error — the single error type everything returns.

Which model is used where

The spherical sailings use a mean Earth radius of 6371.0088 km; sailings::geodesic uses the WGS-84 ellipsoid. Position lines are rhumb lines and cross exactly on a Mercator chart; range fixes and relative motion are worked in a plane. Each function’s documentation says which applies.

Feature flags

• std (default) — uses the standard library’s floating point maths.
• libm — for no_std targets. Build with --no-default-features --features libm.
• serde — serialise and deserialise the value types. Deserialisation goes through the same validation as construction, so a stored file cannot produce a latitude of 500° or a deviation table with duplicate headings.

The crate has no dependencies at all in its default configuration.

Re-exports

pub use angle::wrap180;

pub use angle::wrap360;

pub use angle::Compass;

pub use angle::CompassBearing;

pub use angle::CompassCourse;

pub use angle::Deviation;

pub use angle::Direction;

pub use angle::Frame;

pub use angle::Gyro;

pub use angle::GyroBearing;

pub use angle::GyroCourse;

pub use angle::Magnetic;

pub use angle::MagneticBearing;

pub use angle::MagneticCourse;

pub use angle::RelativeBearing;

pub use angle::Side;

pub use angle::True;

pub use angle::TrueBearing;

pub use angle::TrueCourse;

pub use angle::Variation;

pub use angle::MAX_DEVIATION_DEG;

pub use angle::MAX_VARIATION_DEG;

pub use dead_reckoning::EstimatedPosition;

pub use dead_reckoning::Leg;

pub use deviation::DeviationAnalysis;

pub use deviation::DeviationCoefficients;

pub use deviation::DeviationNode;

pub use deviation::DeviationTable;

pub use deviation::Interpolation;

pub use deviation::InterpolationMethod;

pub use deviation::SmithCoefficients;

pub use deviation::SwingObservation;

pub use deviation::CARDINAL_DIRECTIONS;

pub use deviation::STANDARD_TABLE_LEN;

pub use error::NavigationError;

pub use error::Result;

pub use fix::CockedHat;

pub use fix::Fix;

pub use fix::PositionLine;

pub use fix::TwoBearingDistance;

pub use navigation_solutions::Advisories;

pub use navigation_solutions::CourseSolution;

pub use navigation_solutions::Current;

pub use navigation_solutions::GroundTrack;

pub use navigation_solutions::SteeringSolution;

pub use navigation_solutions::COARSE_TABLE_GAP_DEG;

pub use navigation_solutions::LARGE_DEVIATION_DEG;

pub use navigation_solutions::LARGE_VARIATION_DEG;

pub use position::EastWest;

pub use position::Latitude;

pub use position::Longitude;

pub use position::NorthSouth;

pub use position::Position;

pub use relative_motion::Approach;

pub use relative_motion::Avoidance;

pub use relative_motion::Contact;

pub use relative_motion::Cpa;

pub use relative_motion::TargetSolution;

pub use relative_motion::Vessel;

pub use route::LegKind;

pub use route::Progress;

pub use route::Route;

pub use route::RouteLeg;

pub use sailings::Arrival;

pub use sailings::CrossTrack;

pub use sailings::Sailing;

pub use sailings::TrackSide;

pub use sailings::EARTH_RADIUS;

pub use units::Angle;

pub use units::Distance;

pub use units::Speed;

Modules

angle

Angle types that carry their reference frame in the type system.

dead_reckoning

Dead reckoning: where the ship will be, and where she probably is.

deviation

Deviation tables and the interpolation that reads them.

error

Error types shared by every fallible operation in this crate.

fix

Fixing the ship’s position from what can be seen and measured.

navigation_solutions

Course and bearing conversions, and the current triangle.

position

Geographic position: latitude, longitude, and the pair of them.

relative_motion

Relative motion: closest approach, radar plotting, and getting out of the way.

route

Passage planning: a chain of waypoints, and where you are along it.

sailings

Getting from one position to another: the sailings.

units

Angles, distances and speeds as types rather than bare f64.