From 0d5160f315028f9f5297d22825936b3a52aeb011 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Tue, 8 Apr 2025 18:41:52 +0200 Subject: [PATCH 1/2] add more documentation on scaling of scenarios --- docs/source/input_files.rst | 2 +- docs/source/usage.rst | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/source/input_files.rst b/docs/source/input_files.rst index 3ec3995..bc24f13 100644 --- a/docs/source/input_files.rst +++ b/docs/source/input_files.rst @@ -40,7 +40,7 @@ Example 1: Complete specified situation:: The values are giben in maritime units. The `common_vector` is given in minutes. For radar plotting (plotting vessel positions and relative motions), the `common_vector` and `vector_time` are used together with ship speed to display where the ship will be in e.g. 10 minutes (Common vector is the common time vector used on a radar plot, e.g 10, 15, 20 minutes. The length of the arrow in the plot -will then be the speed times this time vector). +will then be the speed times this time vector, `common_vector`). Speed and course of the own ship, which is the ship to be tested, are given in knots and degrees, respectively. The own ship position is given in latitudinal and longitudinal (degree). The reference point is the initial position of own ship. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index b9cb17a..9a2e03c 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -56,3 +56,15 @@ This will open a browser window/tab with an OpenStreetMap background and the tra radar plot as an overlay. Note that the integer needs to be within the range of the number of generated situations, for example 1 - 12 if you generated 12 situations. + + +Scaling encounters +~~~~~~~~~~~~~~~~~~ +As you may have understood from the documentation the input files, the scale of encounters +(i.e. how many meters or nautical miles does the scenario play out over) +is determined by time-based parameters. +If you want to change the range that the scenario plays out over, +you will need to change the following parameters: + +* in the input situation file: change `vectorTime`: the time at which the target vessel will be in the encounter circle with the ownship. (Note; the encounter circle radius is defined by the max_meeting_distance in `encounter_settings.json`.) +* in `encounter_settings.json`: change `vector_range` (the range within which `vectorTime` is varied, min), `situation_length` (total duration of situation, min), and `evolve_time` (duration in which situation evolves, min). From 4f923191f8a84704537ec59207780fec4bd4cf98 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Wed, 9 Apr 2025 15:45:24 +0200 Subject: [PATCH 2/2] add more documentation on scaling of scenarios, calculation of encounter positions etc. --- docs/source/input_files.rst | 21 +++++++++++---------- docs/source/usage.rst | 11 ++++++++++- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/source/input_files.rst b/docs/source/input_files.rst index bc24f13..ec4def7 100644 --- a/docs/source/input_files.rst +++ b/docs/source/input_files.rst @@ -38,7 +38,7 @@ Example 1: Complete specified situation:: } The values are giben in maritime units. The `common_vector` is given in minutes. For radar plotting (plotting vessel positions and relative motions), -the `common_vector` and `vector_time` are used together with ship speed to display where the ship will be in e.g. 10 minutes +the `common_vector` and `vectorTime` are used together with ship speed to display where the ship will be in e.g. 10 minutes (Common vector is the common time vector used on a radar plot, e.g 10, 15, 20 minutes. The length of the arrow in the plot will then be the speed times this time vector, `common_vector`). Speed and course of the own ship, which is the ship to be tested, are given in knots and degrees, respectively. @@ -47,18 +47,19 @@ The reference point is the initial position of own ship. An encounter may be fully described as shown above, but the user may also deside to input less data, as demonstrated in Example 2. Desired encounter type is mandatory, -while the `beta`, `relative_speed` and `vector_time` parameters are optional: +while the `beta`, `relative_speed` and `vectorTime` parameters are optional: * `desired_encounter_type` is either head-on, overtaking-give-way, overtaking-stand-on, crossing-give-way, and crossing-stand-on. * `beta` is the relative bearing between the own ship and the target ship as seen from the own shop, given in degrees. * `relative_speed` is relative speed between the own ship and the target ship as seen from the own ship, such that a relative speed of 1.2 means that the target ship's speed is 20% higher than the speed of the own ship. An encounter is built using a maximum meeting distance [nm], see the paper linked in the introduction for more info. -At some time in the future, given by the `vector_time`, the target ship will be located somewhere inside a circle +At some time in the future, given by the `vectorTime`, the target ship will be located somewhere inside a circle with a radius given by `max_meeting_distance` and a center point given by the own ship position. This is not necessarily the closest point of approach. The `max_meeting_distance` parameter is common for all encounters and is specified in `src/trafficgen/settings/encounter_settings.json`. +If you set max_meeting_distance to zero, you ensure a scenario where vessels would collide. Example 2: Minimum specified situation:: @@ -152,7 +153,7 @@ The file is written in JSON format and located in the `src/trafficgen/data/own_s "shipType": "Passenger" } -The values are given in maritime units. sogMax is the maximum speed over ground in knots, and the dimensions are given in meters. +The values are given in maritime units. `sogMax` is the maximum speed over ground in knots, and the dimensions are given in meters. Target ship files ~~~~~~~~~~~~~~~~~ @@ -171,8 +172,8 @@ The file is written in JSON format and is on the following structure:: Encounter settings ~~~~~~~~~~~~~~~~~~ -The encounter setting file spesified parameters that are common from -all encounters. The file is written in JSON format and located in the `src/trafficgen/settings/encounter_settings.json`:: +The encounter settings file specifies parameters that are common for all encounters. +The file is written in JSON format and located in the `src/trafficgen/settings/encounter_settings.json`:: { "classification": { @@ -220,9 +221,9 @@ all encounters. The file is written in JSON format and located in the `src/traff The values are given in maritime units. The `theta13_criteria`, `theta14_criteria` and `theta15_criteria` are the criteria for the classification of the encounters. The `theta15` is the range for the relative bearing between own ship and target ship. The `relative_speed` is the range for the relative speed between own ship and target ship. -The `vector_range` is the range for the vector time. -The `situation_length` is the length of the situation in minutes. -The `max_meeting_distance` is the maximum meeting distance in nautical miles. +The `vector_range` is the range for the vector time. If vector_time is not specified, a time point will be randomly sampled within vector_range. +The `situation_length` is the length of the situation in minutes. The ownship is by default planned to travel in a straight line from its start position, for situation_length minutes. +The `max_meeting_distance` is the maximum meeting distance in nautical miles. This is the range around the ownship, in which the target ship will be, at the encounter time. The `common_vector` is the common time vector used on a radar plot. -The `evolve_time` is the time in minutes for the situation to evolve. +The `evolve_time` is the time in minutes for the situation to evolve (before the encounter), ensuring the same COLREG type. The `disable_land_check` is a boolean value that determines if the land check should be disabled or not. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 9a2e03c..442f96f 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -67,4 +67,13 @@ If you want to change the range that the scenario plays out over, you will need to change the following parameters: * in the input situation file: change `vectorTime`: the time at which the target vessel will be in the encounter circle with the ownship. (Note; the encounter circle radius is defined by the max_meeting_distance in `encounter_settings.json`.) -* in `encounter_settings.json`: change `vector_range` (the range within which `vectorTime` is varied, min), `situation_length` (total duration of situation, min), and `evolve_time` (duration in which situation evolves, min). +* in `encounter_settings.json`: change `vector_range` (the range within which `vectorTime` is varied, min), `situation_length` (total duration of situation, min). + +By default, the ownship will travel in a straight line from its start position, defined in the input file, to a position that is `situation_length` minutes into the future. + +For the target ship, the future position of 'meeting' is calculated based on the ownship initial position, the vector_time, and the maximum meeting distance. +At time vector_time, the target ship should be within max_meeting_distance radius of the ownship position (at vector time). + +If vector_time is not set, but vector_range is, then the ship traffic generator will randomly sample a vector time within the range of vector_range. + +Note; the `evolve_time` parameter specifies the duration in which the situation should evolve, or rather; ship traffic generator checks that for the duration of (encounter time - evolve time), the vessels are in the same COLREG situation. This ensures that the COLREG encounter is the same type also for some time (evolve_time) before the actual encounter is started.