Crate kinavis_colregs

Expand description

COLREGs steering and sailing rules: encounter type, responsibility, permitted manoeuvre.

CPA/TCPA is kinematics and lives in the collision assessment; this crate holds the rules. Their sector widths are conventions and their application depends on the waters (TSS, narrow channels), so they are versioned separately, the conventions are explicit in ColregsConfig, and every answer names the deciding Rule.

§Rules applied

Vessels in sight of one another (Visibility::InSight):

Rule 13, overtaking: a vessel coming up from more than 22.5° abaft the other’s beam keeps out of the way, whatever the categories. Coming up requires a closing range; astern and opening is treated as crossing geometry.
Rule 18, responsibilities: power-driven gives way to sailing, fishing, RAM and NUC, in that order of precedence; a vessel constrained by her draught is not to be impeded.
Rule 14, head-on: two power-driven vessels on reciprocal or nearly reciprocal courses both alter to starboard.
Rule 15, crossing: the power-driven vessel with the other on her starboard side gives way.
Rule 12, sailing vessels: port tack keeps clear of starboard tack; on the same tack, windward keeps clear of leeward.
Rule 17, stand-on vessel: keeps course and speed; may act if the give-way vessel does not; does not alter to port for a vessel on her port side.

Restricted visibility (Visibility::Restricted), Rule 19: no stand-on vessel; no alteration to port for a vessel forward of the beam, none towards a vessel abeam or abaft the beam.

Rules 9 and 10 (narrow channels, TSS) are not applied. Between two vessels of the same category other than power-driven or sailing (e.g. two fishing vessels) the rules are silent; the head-on and crossing geometry is applied and reported as Rule 14 or 15.

use kinavis::relative_motion::{Contact, Vessel};
use kinavis_colregs::{
    rule_of_the_road, ColregsConfig, Encounter, Party, Responsibility, Situation,
    VesselCategory, Visibility,
};
use kinavis_kernel::{Distance, Side, Speed, TrueBearing, TrueCourse};

// Steering north at twelve knots; a power-driven vessel five miles off
// on the starboard bow, steering west at the same speed.
let own = Party::new(
    Vessel { course: TrueCourse::new(0.0)?, speed: Speed::from_knots(12.0)? },
    VesselCategory::PowerDriven,
);
let target = Party::new(
    Vessel { course: TrueCourse::new(270.0)?, speed: Speed::from_knots(12.0)? },
    VesselCategory::PowerDriven,
);
let contact = Contact {
    bearing: TrueBearing::new(45.0)?,
    range: Distance::from_nautical_miles(5.0)?,
};
let situation = Situation::new(own, target, contact, Visibility::InSight);

let ruling = rule_of_the_road(&situation, &ColregsConfig::STANDARD)?;
assert_eq!(ruling.encounter(), Encounter::Crossing { target_on: Side::Starboard });
assert_eq!(ruling.responsibility(), Responsibility::GiveWay);
assert_eq!(format!("{}", ruling.rule()), "Rule 15");
// Give way by altering to starboard and passing astern; not to port,
// which would cross ahead.
let may = ruling.manoeuvre();
assert!(may.starboard && !may.port && may.slow_down && !may.hold);

// A sailing vessel would stand on regardless of geometry.
let sailing = Situation::new(
    own,
    Party::new(target.motion(), VesselCategory::Sailing { tack: None }),
    contact,
    Visibility::InSight,
);
let ruling = rule_of_the_road(&sailing, &ColregsConfig::STANDARD)?;
assert_eq!(ruling.responsibility(), Responsibility::GiveWay);
assert_eq!(format!("{}", ruling.rule()), "Rule 18");

§Feature flags

std (default) — standard library maths in the kernel.
libm — for no_std targets: --no-default-features --features libm.
serde — serialisation of the value types.

No allocation; builds for bare-metal targets.

Structs§

ColregsConfig: Conventions used to apply the rules.
Party: One vessel in an encounter: motion and category.
PermittedManoeuvre: Constraints the rules place on own ship’s manoeuvre.
Ruling: Result of applying the rules to a situation.
Situation: Encounter: own ship, the other vessel, its bearing and range, and conditions.

Enums§

Encounter: Encounter type from own ship’s side.
Responsibility: Who keeps out of the way.
Rule: Deciding rule.
Tack: Side of a sailing vessel the wind is on.
VesselCategory: Vessel category per Rule 3, ordered as in Rule 18.
Visibility: Whether the vessels are in sight of one another.

Functions§

rule_of_the_road: Applies the rules to a situation.