trafficgen.encounter¶

Functions to generate encounters.

The encounters consist of one own ship and one to many target ships. The generated encounters may be of type head-on, overtaking give-way and stand-on and crossing give-way and stand-on.

Functions

`assign_beta`(encounter_type, encounter_settings)	Assign random (uniform) relative bearing.
`assign_beta_from_list`(beta_limit)	Assign random (uniform) relative bearing.
`assign_future_position_to_target_ship`(...)	Randomly assign future position of target ship.
`assign_sog_to_target_ship`(encounter_type, ...)	Assign random (uniform) sog to target ship depending on type of encounter.
`assign_vector_time`(vector_time_range)	Assign random (uniform) vector time.
`calculate_min_vector_length_target_ship`(...)	Calculate minimum vector length (target ship sog x vector).
`calculate_relative_bearing`(...)	Calculate relative bearing between own ship and target ship.
`calculate_ship_cog`(pos_0, pos_1, lat_lon0)	Calculate ship cog between two waypoints.
`check_encounter_evolvement`(own_ship, ...)	Check encounter evolvement.
`decide_target_ship`(target_ships_static)	Randomly pick a target ship from a list of target ships.
`define_own_ship`(desired_traffic_situation, ...)	Define own ship based on information in desired traffic situation.
`determine_colreg`(alpha, beta, ...)	Determine the colreg type.
`find_start_position_target_ship`(...)	Find start position of target ship using desired beta and vector length.
`generate_encounter`(desired_encounter_type, ...)	Generate an encounter.

trafficgen.encounter.assign_beta(encounter_type: EncounterType, encounter_settings: EncounterSettings) → float¶

Assign random (uniform) relative bearing.

Parameters:

encounter_type (EncounterType) – Type of encounter
encounter_settings (EncounterSettings) – Encounter settings

Returns:

relative_bearing – Relative bearing between own ship and target ship seen from own ship [rad]

Return type:

float

trafficgen.encounter.assign_beta_from_list(beta_limit: list[float]) → float¶

Assign random (uniform) relative bearing.

The beta between own ship and target ship depending is somewhere between the limits given by beta_limit.

Parameters:: beta_limit (list[float]) – Limits for beta {min, max} [rad]
Returns:: relative_bearing – Relative bearing between own ship and target ship seen from own ship [rad]
Return type:: float

trafficgen.encounter.assign_future_position_to_target_ship(own_ship_position_future: GeoPosition, lat_lon0: GeoPosition, max_meeting_distance: float) → GeoPosition¶

Randomly assign future position of target ship.

If drawing a circle with radius max_meeting_distance around future position of own ship, future position of target ship shall be somewhere inside this circle.

Parameters:

own_ship_position_future (GeoPosition) – Own ship position at a given time in the future {lat, lon} [rad]
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]
max_meeting_distance (float) – Maximum distance between own ship and target ship at a given time in the future [m]

Returns:

future_position_target_ship – Future position of target ship {lat, lon} [rad]

Return type:

GeoPosition

trafficgen.encounter.assign_sog_to_target_ship(encounter_type: EncounterType, own_ship_sog: float, min_target_ship_sog: float, relative_sog_setting: EncounterRelativeSpeed) → float¶

Assign random (uniform) sog to target ship depending on type of encounter.

Parameters:

encounter_type (EncounterType) – Type of encounter
own_ship_sog (float) – Own ship speed over ground [m/s]
min_target_ship_sog (float) – Minimum target ship speed over ground [m/s]
relative_sog_setting (EncounterRelativeSpeed) – Relative speed over ground setting dependent on encounter [-]

Returns:

target_ship_sog – Target ship speed over ground [m/s]

Return type:

float

trafficgen.encounter.assign_vector_time(vector_time_range: list[float]) → float¶

Assign random (uniform) vector time.

Parameters:: vector_time_range (list[float]) – Minimum and maximum value for vector time [min]
Returns:: vector_time – Vector time [min]
Return type:: float

trafficgen.encounter.calculate_min_vector_length_target_ship(own_ship_position: GeoPosition, own_ship_cog: float, target_ship_position_future: GeoPosition, desired_beta: float, lat_lon0: GeoPosition) → float¶

Calculate minimum vector length (target ship sog x vector).

This is done to ensure that ship sog is high enough to find proper situation.

Parameters:

own_ship_position (GeoPosition) – Own ship initial position, latitudinal [rad] and longitudinal [rad]
own_ship_cog (float) – Own ship initial cog [rad]
target_ship_position_future (GeoPosition) – Target ship future position, latitudinal [rad] and longitudinal [rad]
desired_beta (float) – Desired relative bearing between own ship and target ship seen from own ship [rad]
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]

Returns:

min_vector_length – Minimum vector length (target ship sog x vector)

Return type:

float

trafficgen.encounter.calculate_relative_bearing(position_own_ship: GeoPosition, heading_own_ship: float, position_target_ship: GeoPosition, heading_target_ship: float, lat_lon0: GeoPosition) → tuple[float, float]¶

Calculate relative bearing between own ship and target ship.

Parameters:

position_own_ship (GeoPosition) – Own ship position {lat, lon} [rad]
heading_own_ship (float) – Own ship heading [rad]
position_target_ship (GeoPosition) – Target ship position {lat, lon} [rad]
heading_target_ship (float) – Target ship heading [rad]
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]

Returns:

beta (float) – Relative bearing between own ship and target ship seen from own ship [rad]
alpha (float) – Relative bearing between target ship and own ship seen from target ship [rad]

trafficgen.encounter.calculate_ship_cog(pos_0: GeoPosition, pos_1: GeoPosition, lat_lon0: GeoPosition) → float¶

Calculate ship cog between two waypoints.

Parameters:

pos_0 (GeoPosition) – First waypoint {lat, lon} [rad]
pos_1 (GeoPosition) – Second waypoint {lat, lon} [rad]
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]

Returns:

cog – Ship coourse over ground [rad]

Return type:

float

trafficgen.encounter.check_encounter_evolvement(own_ship: OwnShip, own_ship_cog: float, own_ship_position_future: GeoPosition, lat_lon0: GeoPosition, target_ship_sog: float, target_ship_cog: float, target_ship_position_future: GeoPosition, desired_encounter_type: EncounterType, encounter_settings: EncounterSettings) → bool¶

Check encounter evolvement.

The generated encounter should be the same type of encounter (head-on, crossing, give-way) also some time before the encounter is started.

Parameters:

own_ship (OwnShip) – Own ship information such as initial position, sog and cog
own_ship_cog (float) – Own ship cog [rad]
own_ship_position_future (GeoPosition) – Own ship future position {lat, lon} [rad].
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]
target_ship_sog (float) – Target ship speed over ground [m/s]
target_ship_cog (float) – Target ship course over ground [rad]
target_ship_position_future (GeoPosition) – Target ship future position {lat, lon} [rad]
desired_encounter_type (EncounterType) – Desired type of encounter to be generated
encounter_settings (EncounterSettings) – Encounter settings

Returns:

encounterOK – Returns True if encounter ok, False if encounter not ok

Return type:

bool

trafficgen.encounter.decide_target_ship(target_ships_static: list[ShipStatic]) → ShipStatic¶

Randomly pick a target ship from a list of target ships.

Parameters:: target_ships (list[ShipStatic]) – List of target ships with static information
Returns:: target_ship – The target ship, info of type, size etc.
Return type:: ShipStatic

trafficgen.encounter.define_own_ship(desired_traffic_situation: SituationInput, own_ship_static: ShipStatic, encounter_settings: EncounterSettings, lat_lon0: GeoPosition) → OwnShip¶

Define own ship based on information in desired traffic situation.

Parameters:

desired_traffic_situation (SituationInput) – Information about type of traffic situation to generate
own_ship_static (ShipStatic) – Static information of own ship.
encounter_settings (EncounterSettings) – Necessary setting for the encounter
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]

Returns:

own_ship – Own ship including static, initial and waypoints.

Return type:

OwnShip

trafficgen.encounter.determine_colreg(alpha: float, beta: float, theta13_criteria: float, theta14_criteria: float, theta15_criteria: float, theta15: list[float]) → EncounterType¶

Determine the colreg type.

Colreg type is based on alpha, relative bearing between target ship and own ship seen from target ship, and beta, relative bearing between own ship and target ship seen from own ship.

Parameters:

alpha (float) – Relative bearing between target ship and own ship seen from target ship [rad]
beta (float) – Relative bearing between own ship and target ship seen from own ship [rad]
theta13_criteria (float) – Tolerance for “coming up with” relative bearing
theta14_criteria (float) – Tolerance for “reciprocal or nearly reciprocal cogs”, “when in any doubt… assume… [head-on]”
theta15_criteria (float) – Crossing aspect limit, used for classifying a crossing encounter
theta15 (list[float]) – 22.5 deg aft of the beam, used for classifying a crossing and an overtaking encounter [rad, rad]

Returns:

encounter_classification – Classification of the encounter

Return type:

EncounterType

trafficgen.encounter.find_start_position_target_ship(own_ship_position: GeoPosition, lat_lon0: GeoPosition, own_ship_cog: float, target_ship_position_future: GeoPosition, target_ship_vector_length: float, desired_beta: float, desired_encounter_type: EncounterType, encounter_settings: EncounterSettings) → tuple[GeoPosition, bool]¶

Find start position of target ship using desired beta and vector length.

Parameters:

own_ship_position (GeoPosition) – Own ship position {lat, lon} [rad]
lat_lon0 (GeoPosition) – Reference point, latitudinal [rad] and longitudinal [rad]
own_ship_cog (float) – Own ship course over ground [rad]
target_ship_position_future (GeoPosition) – Target ship future position {lat, lon} [rad]
target_ship_vector_length (float) – vector length (target ship sog x vector)
desired_beta (float) – Desired bearing between own ship and target ship seen from own ship [rad]
desired_encounter_type (EncounterType) – Desired type of encounter to be generated
encounter_settings (EncounterSettings) – Encounter settings

Returns:

start_position_target_ship (GeoPosition) – Initial position of target ship {lat, lon} [rad]
start_position_found (bool) – False if position not found, True if position found

trafficgen.encounter.generate_encounter(desired_encounter_type: EncounterType, own_ship: OwnShip, target_ships_static: list[ShipStatic], encounter_number: int, beta_default: list[float] | float | None, relative_sog_default: float | None, vector_time_default: float | None, settings: EncounterSettings) → tuple[TargetShip, bool]¶

Generate an encounter.

Parameters:

desired_encounter_type (EncounterType) – Desired encounter to be generated.
own_ship (OwnShip) – Information about own ship that will encounter a target ship.
target_ships_static (list[ShipStatic]) – List of target ships including static information that may be used in an encounter.
encounter_number (Int) – Integer identifying the encounter.
beta_default (list[float] | float | None) – User defined beta. If not set, this is None [rad].
relative_sog_default (float | None) – User defined relative sog between own ship and target ship. If not set, this is None [m/s].
vector_time_default (float | None) – User defined vector time. If not set, this is None [min].
settings (EncounterSettings) – Encounter settings

Returns:

target_ship (TargetShip) – target ship information, such as initial position, sog and cog
encounter_found (bool) – True=encounter found, False=encounter not found