From e3d6bb0d2ef0cf9c55bc98f0df9f7120a7ff8072 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:07:43 +0200 Subject: [PATCH 1/7] Update README.md add direct link to documentation pages --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index a12fb42..6c6eb6d 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ 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 [paper] +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 From 22c40afb5c38595f02593fa73fc4c8bc005c21b7 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:19:28 +0200 Subject: [PATCH 2/7] Update README.md add another mention of pre-generated docs to bottom documentation bit --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c6eb6d..fc29e05 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,10 @@ source .venv/bin/activate ``` ### 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 ``` From 05d6ad3bf94e62d291c22507e75d4cd00b6ae2e6 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:33:54 +0200 Subject: [PATCH 3/7] Update README.md add a bit about usage and installing the package (dev) --- README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fc29e05..a59d5bf 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ A paper is written describing the background for the tool and how it works ..on Windows: @@ -49,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 @@ -67,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`. @@ -91,11 +103,18 @@ 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 . +``` + ### Documentation For pre-generated package documentation, see [https://dnv-opensource.github.io/ship-traffic-generator/](https://dnv-opensource.github.io/ship-traffic-generator/) From 0f96ce7e22625a7b9475696624ba58d23e385d52 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:53:51 +0200 Subject: [PATCH 4/7] Update README.md add testing: pytest command --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index a59d5bf..340eb9c 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,12 @@ source .venv/bin/activate uv pip install -e . ``` +### Test the install + +```sh +pytest . +``` + ### Documentation For pre-generated package documentation, see [https://dnv-opensource.github.io/ship-traffic-generator/](https://dnv-opensource.github.io/ship-traffic-generator/) From a89834b1e3b0fb7760cda0cd3764d1b0ca7ff347 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Fri, 4 Apr 2025 10:10:27 +0200 Subject: [PATCH 5/7] fix spelling errors --- docs/source/input_files.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/source/input_files.rst b/docs/source/input_files.rst index 3ec3995..2b677ca 100644 --- a/docs/source/input_files.rst +++ b/docs/source/input_files.rst @@ -37,7 +37,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 values are given 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). @@ -112,7 +112,7 @@ Example 3: Generate multiple situations using `numSituations`:: ] } -The next example show how it is possible to give a range for the relative bearing between own ship and target ship +The next example shows how it is possible to give a range for the relative bearing between own ship and target ship. Example 4: Assign range for `beta`:: @@ -137,7 +137,7 @@ Example 4: Assign range for `beta`:: Own ship file ~~~~~~~~~~~~~~~ -The own ship file specify the own ship which is the ship to be controlled by the control system under test. +The own ship file specifies the own ship, which is the ship to be controlled by the control system under test. The file is written in JSON format and located in the `src/trafficgen/data/own_ship`:: { @@ -152,7 +152,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 +171,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 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`:: { "classification": { @@ -226,3 +226,4 @@ The `max_meeting_distance` is the maximum meeting distance in nautical miles. 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 `disable_land_check` is a boolean value that determines if the land check should be disabled or not. +We refer to the paper for more information on these parameters. From 3fe0cece378cd6aa3fdf26049cf0f9ab7d917b27 Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Mon, 7 Apr 2025 15:57:51 +0200 Subject: [PATCH 6/7] add note to input_files doc, update changelog for PR --- CHANGELOG.md | 10 ++-------- docs/source/input_files.rst | 6 ++++-- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db1bc4b..fdfa988 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e ## [0.7.2] - 2025-03-14 +* 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. + ### Changed * Fixed ruff errors which appeared during last nightly build @@ -31,14 +33,12 @@ 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 @@ -46,7 +46,6 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e * 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 +56,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 +64,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 +78,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. - [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 diff --git a/docs/source/input_files.rst b/docs/source/input_files.rst index 2b677ca..3f4e808 100644 --- a/docs/source/input_files.rst +++ b/docs/source/input_files.rst @@ -42,8 +42,10 @@ the `common_vector` and `vector_time` are used together with ship speed to displ (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). 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. +The own ship position is given in latitudinal and longitudinal (decimal degrees). +The reference point, used for conversion to x/y, is the initial position of own ship. + +> **Note:** in order to change the location of the traffic situations you are generating, you should change the initial lat/lon position of the own ship, in the input file(s). This is used as the origin point or reference point for all generated traffic situations, i.e. the (0,0) location. 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, From 695aa2f1daf8236862ac47f6dd31bb0e80204bcf Mon Sep 17 00:00:00 2001 From: Stephanie Kemna <6518317+StephanieKemna@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:06:32 +0200 Subject: [PATCH 7/7] move changelog item to correct position --- CHANGELOG.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fdfa988..04e8ee8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,12 +5,10 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e ## [Unreleased] --/- +* 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. ## [0.7.2] - 2025-03-14 -* 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. - ### Changed * Fixed ruff errors which appeared during last nightly build