Merging dev into main

CHANGELOG.md

@@ -5,7 +5,20 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 
 ## [Unreleased]
 
--/-
+## [0.8.0] - 2025-05-09
+
+### Changed
+* vectorTime may now be a single float (exact time) or a list of two floats [from, to]. vectorRange is removed from settings file.
+* evolveTime is changed to situationDevelopTime.
+* Removed Basemap-package and added pyproj package.
+* Small update of ruff.toml file to remove a few warnings.
+* Documented the use of Waypoints for own ship.
+* camelCasing used for encounter settings; was previously snake_case.
+* Added missing info and spelling errors in data/example_situation_input.
+* Numpy cross product only allowed for 3D vectors from numpy 2; manually calculating the cross product for 2D vectors in method: calculate_min_vector_length_target_ship.
+* Updated documentation; fix spelling errors, add link to github.io, explain Usage, add note on defining python version with uv sync, add note on activating venv.
+* Fix build issues; move click and click-log to non-dev dependencies.
+* Fix issue with file reading when using non-default paths, and add test for it.
 
 ## [0.7.2] - 2025-03-14
 
@@ -31,22 +44,19 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 * Updating workflows
 * Removed maxSpeed from the output files generated using the tool
 
-
 ## [0.6.0] - 2024-11-11
 
 ### Changed
 
 * Updated to download-artifact@v4  (from download-artifact@v3)
 
-
 ## [0.5.0] - 2024-04-26
 
 ### Changed
 
 * removed specific names for target ships. Files generated with target ship 1, 2 etc.
 * changed tests. Still need to figure out why some tests "fail" using CLI.
 
-
 ## [0.4.0] - 2024-04-19
 
 ### Changed
@@ -57,7 +67,6 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
   is not just a number, but could also be a range
 * situation length is used when checking if target ship is passing land
 
-
 ## [0.3.0] - 2024-04-10
 
 ### Changed
@@ -66,7 +75,6 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 * lat/lon used instead of north/east
 * the generated output files are using "maritime" units: knots and degrees
 
-
 ## [0.2.0] - 2024-01-11
 
 ### Changed
@@ -81,16 +89,13 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 * removed cyclic import
 * length of encounter may be specified by user
 
-
 ## [0.1.0] - 2023-11-08
 
 * First release on PyPI.
 
-
 <!-- Markdown link & img dfn's -->
 [0.6.0]: https://github.com/dnv-opensource/ship-traffic-generator/releases/tag/v0.6.0
 [0.5.0]: https://github.com/dnv-opensource/ship-traffic-generator/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/dnv-opensource/ship-traffic-generator/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/dnv-opensource/ship-traffic-generator/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dnv-opensource/ship-traffic-generator/releases/tag/v0.2.0
-[trafficgen]: https://github.com/dnv-opensource/ship-traffic-generator

README.md

@@ -5,7 +5,10 @@ the tool will generate a set of traffic situations. The traffic situations may b
 
 A paper is written describing the background for the tool and how it works <a href="./docs/source/ICMASS23_verfying_caga_systems.pdf" target="_blank">[paper]</a>
 
+For package documentation, see [https://dnv-opensource.github.io/ship-traffic-generator/](https://dnv-opensource.github.io/ship-traffic-generator/)
+
 ## Installation
+
 To install Ship Traffic Generator, run this command in your terminal:
 ```sh
 pip install trafficgen
@@ -17,11 +20,18 @@ You can check your installation by running:
 uv run trafficgen --help
 ```
 
-See documentation for usage of the Ship Traffic Generator.
+## Usage
+
+For simplest usage, clone this repo, then run ```pip install -e .``` (you may want to do this in a local environment, such as a venv, see an example with `uv` below).
+
+Then run: ```trafficgen gen-situation```.  You can add the option `-v` for visualization.
+
+For further explanations, see the [documentation pages](https://dnv-opensource.github.io/ship-traffic-generator/) of the Ship Traffic Generator.
 
 ## Development Setup
 
 ### Install UV
+
 This project uses `uv` as package manager.
 If you haven't already, install [uv](https://docs.astral.sh/uv), preferably using it's ["Standalone installer"](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2) method: <br>
 ..on Windows:
@@ -47,6 +57,7 @@ If you don't already have a compatible version installed on your machine, you wa
 uv python install
 ```
 This will install the latest stable version of Python into the uv Python directory, i.e. as a uv-managed version of Python.
+> **Note**: you can also do this after you clone the repo, see below.
 
 Alternatively, and if you want a standalone version of Python on your machine, you can install Python either via `winget`:
 ```sh
@@ -65,12 +76,15 @@ cd ship-traffic-generator
 ```
 
 ### Install dependencies
+
 Run `uv sync -U` to create a virtual environment and install all project dependencies into it:
 ```sh
 uv sync -U
 ```
 > **Note**: Using `--no-dev` will omit installing development dependencies.
 
+> **Note**: You can also define the python environment at the same time, by running for example ```uv sync -U -p 3.12``` to install Python 3.12.
+
 > **Note**: `uv` will create a new virtual environment called `.venv` in the project root directory when running
 > `uv sync` the first time. Optionally, you can create your own virtual environment using e.g. `uv venv`, before running
 > `uv sync`.
@@ -89,13 +103,29 @@ To manually activate the virtual environment, run one of the "known" legacy comm
 ```sh
 .venv\Scripts\activate.bat
 ```
+> **Note**: If you use the cmd terminal in VS Code, it will show this activated venv as (trafficgen) at the start of every line command.
 ..on Linux:
 ```sh
 source .venv/bin/activate
 ```
 
+### Install the package
+
+```sh
+uv pip install -e .
+```
+
+### Test the install
+
+```sh
+pytest .
+```
+
 ### Documentation
-To generate documentation use:
+
+For pre-generated package documentation, see [https://dnv-opensource.github.io/ship-traffic-generator/](https://dnv-opensource.github.io/ship-traffic-generator/)
+
+To generate documentation from the source code, use:
 ```sh
 uv run docs/make.bat html
 ```

data/example_situations_input/example_several_situations_01_1_ts.json

@@ -9,13 +9,15 @@
             },
             "sog": 7.0,
             "cog": 0.0,
+            "heading": 0.0,
             "navStatus": "Under way using engine"
         }
     },
     "numSituations": 5,
-    "encounter": [
+    "encounters": [
         {
-            "desiredEncounterType": "overtaking-give-ay"
+            "desiredEncounterType": "overtaking-give-way",
+            "vectorTime": 15.0
         }
     ]
 }

data/example_situations_input/example_several_situations_02_2_ts.json

@@ -9,16 +9,19 @@
             },
             "sog": 7.0,
             "cog": 0.0,
+            "heading": 0.0,
             "navStatus": "Under way using engine"
         }
     },
     "numSituations": 4,
-    "encounter": [
+    "encounters": [
         {
-            "desiredEncounterType": "overtaking-give-way"
+            "desiredEncounterType": "overtaking-give-way",
+            "vectorTime": [15.0,20.0]
         },
         {
-            "desiredEncounterType": "crossing-give-way"
+            "desiredEncounterType": "crossing-give-way",
+            "vectorTime": 25.0
         }
     ]
 }

data/example_situations_input/example_situation_01_1_ts.json

@@ -9,10 +9,11 @@
             },
             "sog": 10.0,
             "cog": 270.0,
+            "heading": 0.0,
             "navStatus": "Under way using engine"
         }
     },
-    "encounter": [
+    "encounters": [
         {
             "desiredEncounterType": "head-on",
             "relativeSpeed": 1.2,

data/example_situations_input/example_situation_02_1_ts.json

@@ -9,12 +9,14 @@
             },
             "sog": 10.0,
             "cog": 0.0,
+            "heading": 0.0,
             "navStatus": "Under way using engine"
         }
     },
-    "encounter": [
+    "encounters": [
         {
-            "desiredEncounterType": "crossing-give-way"
+            "desiredEncounterType": "crossing-give-way",
+            "vectorTime": 25.0
         }
     ]
 }

data/example_situations_input/example_situation_03_1_ts.json

@@ -9,12 +9,14 @@
             },
             "sog": 10.0,
             "cog": 0.0,
+            "heading": 0.0,
             "navStatus": "Under way using engine"
         }
     },
-    "encounter": [
+    "encounters": [
         {
-            "desiredEncounterType": "crossing-stand-on"
+            "desiredEncounterType": "crossing-stand-on",
+            "vectorTime": 15.0
         }
     ]
 }

data/example_situations_input/example_situation_04_1_ts.json

@@ -9,12 +9,17 @@
             },
             "sog": 7.0,
             "cog": 0.0,
+            "heading": 0.0,
             "navStatus": "Under way using engine"
         }
     },
-    "encounter": [
+    "encounters": [
         {
-            "desiredEncounterType": "overtaking-give-way"
+            "desiredEncounterType": "overtaking-give-way",
+            "vectorTime": [
+                15.0,
+                25.0
+            ]
         }
     ]
 }

data/example_situations_input/example_situation_waypoints_01_1_ts.json

@@ -0,0 +1,62 @@
+{
+    "title": "CR-Waypoints",
+    "description": "Crossing situations, waypoints added for own ship.",
+    "ownShip": {
+        "initial": {
+            "position": {
+                "lat": 58.763449,
+                "lon": 10.490654
+            },
+            "sog": 4.5,
+            "cog": 0.0,
+            "heading": 0.0,
+            "navStatus": "Under way using engine"
+        },
+        "waypoints": [
+            {
+                "position": {
+                    "lat": 58.763449,
+                    "lon": 10.490654
+                },
+                "data": {
+                    "sog": {
+                        "value": 4.5
+                    }
+                }
+            },
+            {
+                "position": {
+                    "lat": 58.680833,
+                    "lon": 10.355278
+                },
+                "data": {
+                    "sog": {
+                        "value": 4.5
+                    }
+                }
+            },
+            {
+                "position": {
+                    "lat": 58.571944,
+                    "lon": 10.137778
+                },
+                "data": {
+                    "sog": {
+                        "value": 4.4
+                    }
+                }
+            }
+        ]
+    },
+    "encounters": [
+        {
+            "desiredEncounterType": "crossing-give-way",
+            "relativeSpeed": 1.2,
+            "vectorTime": 20.0,
+            "beta": [
+                45.0,
+                120.0
+            ]
+        }
+    ]
+}

docs/source/conf.py

@@ -1,4 +1,3 @@
-# ruff: noqa
 # mypy: ignore-errors
 
 # Configuration file for the Sphinx documentation builder.
@@ -26,7 +25,7 @@
 author = "Tom Arne Pedersen, Claas Rostock, Minos Hemrich"
 
 # The full version, including alpha/beta/rc tags
-release = "0.7.2"
+release = "0.8.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration