# CommonOcean Rules
This repository contains a python traffic rule monitor for ships. The implemented rules and parameters are described
in the paper "Temporal Logic Formalization of Marine Traffic Rules" by Hanna Krasowski and Matthias Althoff.
## Getting Started
This introduction will give you an overview how to install, parametrize,
and execute the Marine Traffic Rule Monitor. The scenarios to evaluate have to be represented in the [CommonOcean format](https://commonocean.cps.cit.tum.de).
We recommend Ubuntu 18.04 as operating system.
For the monitor you need at least Python 3.8 and the following packages:
* *commonocean-io* == 2023.1
* *matplotlib* >= 2.5.0
* *numpy* >= 1.16.4
* *metric-temporal-logic* >= 0.1.4
* *python-monitors* >= 0.1.1
* *ruamel.yaml* >= 0.16.10
* *bezier* >= 2020.2.3
* *antlr4-python3-runtime* >= 4.7.2
* *scipy*
The usage of the Anaconda Python distribution is recommended.
If you want to use our functions and classes in your custom projects (e.g., in the [CommonOcean Drivability Checker](https://commonocean.cps.cit.tum.de/commonocean-dc)), you can install CommonOcean Rules as a module by doing
```
pip install commonocean-rules
```
If you want to create scenario videos, the ffmpeg packages has to be installed as well:
```
sudo snap install ffmpeg
```
Or, if you are a macOS user:
```
brew install ffmpeg
```
## Running the Marine Traffic Rule Monitor
There exist two options to run the Marine Traffic Rule Monitor:
* *[main.py](./rules/main.py)* : Traffic rule evaluation for a single scenario or all scenarios which are located within predefined directories.
* *[solution_viz.py](./rules/solution_viz.py)* : Traffic rule evaluation for a single scenario while also generating a video for the scenario.
The main file can be started from the root directory of this project via commandline by executing:
```
python -m rules.main --max_num_scenarios #Scenarios --scenario_directories /directory_1/ ... /directory_2
```
This should be used for the sequential evaluation of scenarios.
The scenario directories are relative to the root folder, remember to keep them inside the repo.
In the following the different parameters are explained:
* **max_num_scenarios**: The maximum number scenarios which should be evaluated. The default number is *10*.
* **scenario_directories**: List of scenario directories (relative to the root directory).
You can list the different parameters by executing `python main.py -h`.
The temporal logic formulas of the rules and the rule specific parametrization can be found in the file *[traffic_rules_ship.yaml](./rules/traffic_rules_ship.yaml)*.
Simulation and vehicle parameters can be set in the file *[config_ship.yaml](./rules/config_ship.yaml)*.
In adition, the solution_viz file can be started from the root directory of the project via commandline by executing
```
python -m rules.solution_viz --input_path /folder/of/input/scenario/ --scenario 'ScenarioFile.xml' --output_path /folder/for/output/video/
```
Pay attention that here the folders' paths need to be the absolute ones, as they represent the directories in which we get our scenario and then output the video. Also, don't forget the / (forward slash) in the end of the path name.
## Changelog
Compared to version 1.0.0, the following features have been changed:
- The module now uses the new version of CommonOcean IO (2023.1)
- The package is no longer compatible with Python 3.7
## Authors of code project
Hanna Krasowski
Sebastian Maierhofer
Bruno Maione
**If you use our formalized traffic rules for research, please consider citing our paper:**
```
@inproceedings{Krasowski2021a,
author = {Krasowski, Hanna and Althoff, Matthias},
title = {Temporal Logic Formalization of Marine Traffic Rules},
booktitle = {Proc. of the IEEE Intelligent Vehicles Symposium},
year = {2021},
}
```
Raw data
{
"_id": null,
"home_page": "https://commonocean.cps.cit.tum.de/",
"name": "commonocean-rules",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "rule monitor for ships",
"author": "Cyber-Physical Systems Group, Technical University of Munich",
"author_email": "commonocean@lists.lrz.de",
"download_url": "https://files.pythonhosted.org/packages/10/5e/8ce0517b3a1b3676f11375e19bf78c10188d6ba872bd5b50791c175f1562/commonocean-rules-1.0.2.tar.gz",
"platform": null,
"description": "# CommonOcean Rules\n\nThis repository contains a python traffic rule monitor for ships. The implemented rules and parameters are described\nin the paper \"Temporal Logic Formalization of Marine Traffic Rules\" by Hanna Krasowski and Matthias Althoff.\n\n## Getting Started\nThis introduction will give you an overview how to install, parametrize, \nand execute the Marine Traffic Rule Monitor. The scenarios to evaluate have to be represented in the [CommonOcean format](https://commonocean.cps.cit.tum.de).\n\nWe recommend Ubuntu 18.04 as operating system.\nFor the monitor you need at least Python 3.8 and the following packages:\n\n* *commonocean-io* == 2023.1\n* *matplotlib* >= 2.5.0\n* *numpy* >= 1.16.4\n* *metric-temporal-logic* >= 0.1.4\n* *python-monitors* >= 0.1.1\n* *ruamel.yaml* >= 0.16.10 \n* *bezier* >= 2020.2.3\n* *antlr4-python3-runtime* >= 4.7.2\n* *scipy*\n\nThe usage of the Anaconda Python distribution is recommended.\n\nIf you want to use our functions and classes in your custom projects (e.g., in the [CommonOcean Drivability Checker](https://commonocean.cps.cit.tum.de/commonocean-dc)), you can install CommonOcean Rules as a module by doing\n```\npip install commonocean-rules\n```\n\nIf you want to create scenario videos, the ffmpeg packages has to be installed as well:\n```\nsudo snap install ffmpeg\n```\n\nOr, if you are a macOS user:\n```\nbrew install ffmpeg\n```\n\n## Running the Marine Traffic Rule Monitor\nThere exist two options to run the Marine Traffic Rule Monitor:\n* *[main.py](./rules/main.py)* : Traffic rule evaluation for a single scenario or all scenarios which are located within predefined directories.\n* *[solution_viz.py](./rules/solution_viz.py)* : Traffic rule evaluation for a single scenario while also generating a video for the scenario.\n\nThe main file can be started from the root directory of this project via commandline by executing:\n```\npython -m rules.main --max_num_scenarios #Scenarios --scenario_directories /directory_1/ ... /directory_2\n```\n\nThis should be used for the sequential evaluation of scenarios.\nThe scenario directories are relative to the root folder, remember to keep them inside the repo.\n\nIn the following the different parameters are explained:\n* **max_num_scenarios**: The maximum number scenarios which should be evaluated. The default number is *10*.\n* **scenario_directories**: List of scenario directories (relative to the root directory).\n\nYou can list the different parameters by executing `python main.py -h`. \n\nThe temporal logic formulas of the rules and the rule specific parametrization can be found in the file *[traffic_rules_ship.yaml](./rules/traffic_rules_ship.yaml)*. \nSimulation and vehicle parameters can be set in the file *[config_ship.yaml](./rules/config_ship.yaml)*.\n\nIn adition, the solution_viz file can be started from the root directory of the project via commandline by executing\n```\npython -m rules.solution_viz --input_path /folder/of/input/scenario/ --scenario 'ScenarioFile.xml' --output_path /folder/for/output/video/\n```\n\nPay attention that here the folders' paths need to be the absolute ones, as they represent the directories in which we get our scenario and then output the video. Also, don't forget the / (forward slash) in the end of the path name.\n\n## Changelog\n\nCompared to version 1.0.0, the following features have been changed:\n\n- The module now uses the new version of CommonOcean IO (2023.1)\n- The package is no longer compatible with Python 3.7\n\n## Authors of code project\n\nHanna Krasowski \nSebastian Maierhofer\nBruno Maione\n\n**If you use our formalized traffic rules for research, please consider citing our paper:**\n```\n@inproceedings{Krasowski2021a,\n\tauthor = {Krasowski, Hanna and Althoff, Matthias},\n\ttitle = {Temporal Logic Formalization of Marine Traffic Rules},\n\tbooktitle = {Proc. of the IEEE Intelligent Vehicles Symposium},\n\tyear = {2021},\n}\n```\n\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3.0",
"summary": "Implementation of rule monitor for ships",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://commonocean.cps.cit.tum.de/"
},
"split_keywords": [
"rule",
"monitor",
"for",
"ships"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "abf57de5c222c0cfa16e8223edf28e04a221f2886924549fb79179760b43a8b4",
"md5": "9660fc87ba313ed1c0425b851fcd2c78",
"sha256": "cdcb42818ecf3ce539f568adda5d98c011d06a2ffdf88e817ff10788c4f433f7"
},
"downloads": -1,
"filename": "commonocean_rules-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9660fc87ba313ed1c0425b851fcd2c78",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 59658,
"upload_time": "2023-09-26T13:30:46",
"upload_time_iso_8601": "2023-09-26T13:30:46.826691Z",
"url": "https://files.pythonhosted.org/packages/ab/f5/7de5c222c0cfa16e8223edf28e04a221f2886924549fb79179760b43a8b4/commonocean_rules-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "105e8ce0517b3a1b3676f11375e19bf78c10188d6ba872bd5b50791c175f1562",
"md5": "55dca424950a108a49846957918f99dc",
"sha256": "83eec5b01f9628fd6aa7ab75d88455369705f190b0adf01cd78aec3bc4f0ef76"
},
"downloads": -1,
"filename": "commonocean-rules-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "55dca424950a108a49846957918f99dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 39194,
"upload_time": "2023-09-26T13:30:49",
"upload_time_iso_8601": "2023-09-26T13:30:49.188477Z",
"url": "https://files.pythonhosted.org/packages/10/5e/8ce0517b3a1b3676f11375e19bf78c10188d6ba872bd5b50791c175f1562/commonocean-rules-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-26 13:30:49",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "commonocean-rules"
}
JSON