Add more documentation on scaling of scenarios

docs/source/input_files.rst

@@ -37,6 +37,7 @@ Example 1: Complete specified situation::
         ]
     }
 
+
 The numerical values are given in maritime units:
 
 * `title` and `description` are strings that describe the situation and used for documentation purposes.
@@ -65,6 +66,7 @@ At some time in the future, given by the `vectorTime`, the target ship will be l
 with a radius given by `maxMeetingDistance` (see encounter settings below) and a center point given by the own ship position. This is not necessarily the
 closest point of approach. The `maxMeetingDistance` parameter is common for all encounters and is specified in `src/trafficgen/settings/encounter_settings.json`.
 
+
 Example 2: Minimum specified situation::
 
     {
@@ -179,7 +181,9 @@ The file is written in JSON format and is on the following structure::
 
 Encounter settings
 ~~~~~~~~~~~~~~~~~~
+
 The encounter setting file specified parameters that are common for all encounters.
+
 The file is written in JSON format and located in the `src/trafficgen/settings/encounter_settings.json`::
 
     {
@@ -227,6 +231,7 @@ The file is written in JSON format and located in the `src/trafficgen/settings/e
 
 The values are given in maritime units. The `theta13Criteria`, `theta14Criteria` and `theta15Criteria` 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 `relativeSpeed` is the range for the relative speed between own ship and target ship.
 The `vectorRange` is the range for the vector time given in minutes.
 The `situationLength` is the length of the situation in minutes.

docs/source/usage.rst

@@ -56,3 +56,24 @@ 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).
+
+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.