From 1382937e53fa039bfab25edc286b14683520eb94 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Tue, 19 Nov 2024 08:53:53 +0100 Subject: [PATCH 01/11] Use spoilers to tidy up README --- README.md | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ae407b62..46e2a56a 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,8 @@ We will shortly add a [tutorial](https://github.com/KIT-MRT/arbitration_graphs/p ## Installation -### Prerequisites +
+Prerequisites First make sure all dependencies are installed: - [glog](https://github.com/google/glog) @@ -83,8 +84,10 @@ First make sure all dependencies are installed: - [Crow](https://crowcpp.org) (optional, needed for GUI only) See also the [`Dockerfile`](./Dockerfile) for how to install these packages under Debian or Ubuntu. +
-### Installation using Debian package (recommended) +
+Installation using Debian package (recommended) We provide a Debian package for easy installation on Debian-based distributions. Download the latest `.deb` packages for the [core library](https://github.com/KIT-MRT/arbitration_graphs/releases/latest/download/libarbitration-graphs-core-dev.deb) @@ -94,8 +97,10 @@ and optionally for [the gui](https://github.com/KIT-MRT/arbitration_graphs/relea sudo dpkg -i libarbitration-graphs-core-dev.deb sudo dpkg -i libarbitration-graphs-gui-dev.deb ``` +
-### Using Docker image with pre-installed library +
+Using Docker image with pre-installed library We provide a Docker image with the library and all dependencies already installed globally. @@ -110,8 +115,10 @@ So, it can be easily loaded with CMake: find_package(arbitration_graphs REQUIRED) ``` +
-### Building from source using CMake +
+Building from source using CMake Clone the repository: @@ -132,10 +139,13 @@ sudo cmake --install . In order to skip compiling the GUI, use `cmake -DBUILD_GUI=false ..` instead. +
+ ## Development -### Using Docker image +
+Using Docker image Clone the repository and run the development image @@ -149,8 +159,11 @@ docker compose run --rm arbitration_graphs_devel This mounts the source into the container's `/home/blinky/arbitration_graphs` folder. There, you can edit the source code, compile and run the tests etc. +
+ -### Compiling unit tests +
+Compiling unit tests In order to compile with tests define `BUILD_TESTS=true` ```bash @@ -166,8 +179,11 @@ Run all unit tests with CTest: cmake --build . --target test ``` +
+ -### Serving the WebApp GUI +
+Serving the WebApp GUI The GUI consists of - a web server with static WebApp files, see [`gui/app`](./gui/app) @@ -183,3 +199,6 @@ If you intend to override these, please use the `APP_DIRECTORY` environment vari ``` APP_DIRECTORY=/my/custom/app/path my_awesome_executable ``` + +
+ From 2808cf56bf3129dacee1a4a7442038be79efa4a4 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Tue, 19 Nov 2024 09:01:20 +0100 Subject: [PATCH 02/11] Add links to badges --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 46e2a56a..b8da7b39 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Arbitration Graphs -![Latest Release](https://img.shields.io/github/v/release/KIT-MRT/arbitration_graphs?color=green) -![License](https://img.shields.io/github/license/KIT-MRT/arbitration_graphs) -![Unit Test Status](https://img.shields.io/github/actions/workflow/status/KIT-MRT/arbitration_graphs/run-unit-tests.yaml?branch=main&label=tests) +[![Latest Release](https://img.shields.io/github/v/release/KIT-MRT/arbitration_graphs?color=green)](https://github.com/KIT-MRT/arbitration_graphs/releases) +[![License](https://img.shields.io/github/license/KIT-MRT/arbitration_graphs)](./LICENSE) +[![Unit Test Status](https://img.shields.io/github/actions/workflow/status/KIT-MRT/arbitration_graphs/run-unit-tests.yaml?branch=main&label=tests)](https://github.com/KIT-MRT/arbitration_graphs/actions/workflows/run-unit-tests.yaml?query=branch%3Amain) **Hierarchical behavior models for complex decision-making and behavior generation in robotics!** From dc0c4d8b264a9d9554fb689609522a01f8488101 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Tue, 19 Nov 2024 08:46:56 +0100 Subject: [PATCH 03/11] Add citation section into main README --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index b8da7b39..8e70f51f 100644 --- a/README.md +++ b/README.md @@ -202,3 +202,18 @@ APP_DIRECTORY=/my/custom/app/path my_awesome_executable +## Citation + +If you use arbitration graphs in your research, we would be pleased if you cite our publication: + +```bibtex +@misc{spieker2024arbitrationgraphs, + title={Better Safe Than Sorry: Enhancing Arbitration Graphs for Safe and Robust Autonomous Decision-Making}, + author={Piotr Spieker and Nick Le Large and Martin Lauer}, + year={2024}, + eprint={2411.10170}, + archivePrefix={arXiv}, + primaryClass={cs.RO}, + url={https://arxiv.org/abs/2411.10170}, +} +``` From a9cc9b0338c0c7fb5e0a1286e81d2d413734c086 Mon Sep 17 00:00:00 2001 From: Piotr Spieker Date: Tue, 19 Nov 2024 10:39:01 +0100 Subject: [PATCH 04/11] Add installation instructions for .zip/.tar.gz --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 8e70f51f..12fd9d99 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,22 @@ sudo dpkg -i libarbitration-graphs-gui-dev.deb ``` +
+Installation from .zip/.tar.gz + +As this is a header-only library, no platform-specific compilation is needed. +So, you can also install the files directly from our release [`.zip` or `.tar.gz` archives](https://github.com/KIT-MRT/arbitration_graphs/releases/latest): + +```bash +tar xf arbitration_graphs-core.tar.gz --directory=/ +tar xf arbitration_graphs-gui.tar.gz --directory=/ +``` + +This installs into `/usr/[include,lib,share]/arbitration_graphs`. +Please read [Serving the WebApp GUI](#serving-the-webapp-gui) below, if you consider custom installation paths and want to use the GUI. + +
+
Using Docker image with pre-installed library From 31fca68020a74ba96523a4fe1395951cb6b1d2ca Mon Sep 17 00:00:00 2001 From: Piotr Spieker Date: Tue, 19 Nov 2024 13:01:18 +0100 Subject: [PATCH 05/11] Add a contributors section to the Readme --- README.md | 65 +++++++++++++++++++++++ docs/assets/css/style.scss | 4 ++ docs/assets/img/In-Blue-128@2x.png | Bin 0 -> 2023 bytes docs/assets/img/ORCID-iD_icon_vector.svg | 4 ++ docs/assets/img/github-mark-white.svg | 1 + docs/assets/img/github-mark.svg | 1 + 6 files changed, 75 insertions(+) create mode 100755 docs/assets/img/In-Blue-128@2x.png create mode 100644 docs/assets/img/ORCID-iD_icon_vector.svg create mode 100644 docs/assets/img/github-mark-white.svg create mode 100644 docs/assets/img/github-mark.svg diff --git a/README.md b/README.md index 12fd9d99..5d9dea15 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,71 @@ APP_DIRECTORY=/my/custom/app/path my_awesome_executable
+ +## Contributors + +This library and repo has been crafted with ❤️ by + +**Christoph Burger** +  + + + ChristophBurger89 + +  + + LinkedIn logo + christoph-burger + +  + + ORCID iD + 0009-0002-9147-8749 +
+**Nick Le Large** +  + + + ll-nick + +  + + LinkedIn logo + nick-le-large + +  + + ORCID iD + 0009-0006-5191-9043 +
+**Piotr Spieker** +  + + + orzechow + +  + + LinkedIn logo + piotr-spieker + +  + + ORCID iD + 0000-0002-0449-3741 + + +Christoph and Piotr coded the core in a pair-programming session. +Piotr also contributed the GUI and GitHub Page. +Nick implemented the awesome PacMan demo and tutorial, with drafting support by Christoph, reviews and finetuning by Piotr. + +The repository is maintained by Piotr Spieker  + + + orzechow + + + ## Citation If you use arbitration graphs in your research, we would be pleased if you cite our publication: diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss index 56f05937..d911bef1 100644 --- a/docs/assets/css/style.scss +++ b/docs/assets/css/style.scss @@ -13,3 +13,7 @@ // Add table of contents navbar @import 'toc'; + +img.github-logo { + content: url(/docs/assets/img/github-mark.svg); +} \ No newline at end of file diff --git a/docs/assets/img/In-Blue-128@2x.png b/docs/assets/img/In-Blue-128@2x.png new file mode 100755 index 0000000000000000000000000000000000000000..4b3bd5f50971f60a7fa47648e13013787c1e464a GIT binary patch literal 2023 zcmb_dYgiL!7M@8UDaj;(f+7%c0TEpS4ds?1XjBj)luHN~K_H8ogm4Q=!IeuQC<<09 zpj{Qjl;t82DxgKSRt!mqpjbgJQUL`iD6Jw^aMb|mH=#fG=gu?F%sKCzbKdv7-;XH_ z4)i4v%n1+#kyw7-YzTru2t%J>!7EV~$pOjB-~f&fNC~_iM4%$_6-2(0$Ws#d3Ib2D zK6wNIvF?^gv_t_K8}U>GzLF$BD-i)GLyJKRkq3|!P=)Y2$^0&aub?C-|C%XKgTS2E z1A2)91qm%yB0PmNuZP6%1RxkfN?e)WqnieXs8$IFLD{FtU8p3Uf}DU-Bd9_ZNI@f! z4>W_cQ`e%TBy|HEr2qG6-ZC3)Cc@iYQPKz!oSSdZQ~RD41Y1A*um% zp}U~CjzSlc)6^uCLiaTR6rdUm69Kh?EbK&tcYp(0trn;yg3{ca>tMd5YoEJfv^mg+u%A)s*u*MSOPjt)_P146lY zsuh<|QeF>uQqzFpz(aH$(6S-}OjGhdJOt-mmCgw|{x7#iw*FV`9cF?`@um z{Lo!J^i68`7TaX&j(*=Ogr$t&17-SOG-@_{q}==}0{M|#D`VWbC|V3kuh}VYxBBme zOpi5KoRNiRbe8H}OOm4=oj3cwj(Pf7@26k3mOGa;th?;GX%rR`SM4qGdJ{6gur2P~ z&!*?syXVsea*ge6CVu^1`rFgaAFlSyO|#pY69c2DFRq#R8T|Y2C$5i7{gHv}8-O5v z9Lswf=MemID74Zx1UWVl7Vu`cweiCP+1R75gC(h-Xm{pCP#?X`KcgaGpB`MBZCzA) z*2J%rp~%`D`!`p@KMUN8Y}wTumHiZ9Q|PA2W5QDdbzyPk;!`H|=Po}HALG=UyzvdU zuHI#qdymyfz3r{fZZL#Tu$tE}FPSu819ufwllQRi`{Z*H<#vPFdR0-9GaTZ!ySpKx zJRYV=^qZj7a!e#dcq{fse~RmZ{+tH;6a9sz9)sLFRO`tx=DMhlt8Lc8 z8$z?=Jwgn*Zg)(loo8SkF+0J@*pgeAO52Z*oQSsXhD%)Ae+bmW4@>@G<1SxKi>`w+ zvYK9IZpQ}5U5w17gqr#u=(x@K)A(XIkh{4M5#dI5?~@RR9j&qH9Yd?kr1;i~E-0cY z#zEo*YxI(l$JXl|73u<&V6mL@r5gKLHjBZGnUU}ZRONARc-OPZlx!! zI+#WApQ$J8(@ggk_LSY7U80{GYtVAS#o>^>WI_goL(1K-3@W&WiG-{Aw=x&IkE$kF z|0=<<+5Hc5oIk(j*>dn}gQm^ypWTMGZrn(F93m4-N**>;ysyq{`Ge4i<;*tbk?{42 zdzRTy({PsElDxK+OiNp^OGkRgiLL4y(HKVMwu9v_3x}hwZV!vrq~u_ZX2{8Dn_Ue= zGV^z=O^>XZDRwW1rtG#dGcBmSp)^m4za_PQ)ZT*`xQ_bO^*E8_h$SP1?wcer?h_RR zG{XhsRONQ;StW}dRD{r<8SuZ@L!&bfZ7Hwy<3bUPz9XeA7)IQslM^sK>9C~lkP^%7 znTIAF3-HYR8F)hgMG{kkKkwotKRW}{lMhSG95C1K|9l@Wcl52sGw4niZi(`qcr>>S z%o4-0c6sCHqGG>Gl}*1oa?!N|{%vT+_vEX(;64X8`66ygM?MDjE$uYLNV`vISF>Wb|l9 zlV{1Qai`{mTFGRg3<@etCDU3kRGany64uj3|A8wK>`kb2K|}>6dxq$8B72UlglbtG z-xk2J#d)zL?0iX{`>U~Ig?b@tj&_LC$85#J%m-r>{>@li%--R-wO0+t#oDd0R`R%7 z^uPB1xVm2duSufrC*nFQ3+|OI7SgMZ7SaYc3uz;-_$P56=TZqg9p>tfJMXojBL2b0 z@Aluks~_o=VR@rYbK~A&Mp@4E^3t^JKu*A@I6GA2rAMGrUdO-Ev}v?EIx?@3vb4!t zT*VQ;OJ8e+AHwDjWJIl(#g+4(wl0>v8>LJxq^vvMo>-PynhHye&OUFUGbYe2Sw4Z@ J-*4yU{RxExM3w*m literal 0 HcmV?d00001 diff --git a/docs/assets/img/ORCID-iD_icon_vector.svg b/docs/assets/img/ORCID-iD_icon_vector.svg new file mode 100644 index 00000000..375b457a --- /dev/null +++ b/docs/assets/img/ORCID-iD_icon_vector.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/assets/img/github-mark-white.svg b/docs/assets/img/github-mark-white.svg new file mode 100644 index 00000000..d5e64918 --- /dev/null +++ b/docs/assets/img/github-mark-white.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/img/github-mark.svg b/docs/assets/img/github-mark.svg new file mode 100644 index 00000000..37fa923d --- /dev/null +++ b/docs/assets/img/github-mark.svg @@ -0,0 +1 @@ + \ No newline at end of file From 25c3c954505013d8144e957d64017a2d256a9719 Mon Sep 17 00:00:00 2001 From: Piotr Spieker Date: Tue, 19 Nov 2024 13:01:37 +0100 Subject: [PATCH 06/11] Order dependencies and group by required/optional --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5d9dea15..1634c792 100644 --- a/README.md +++ b/README.md @@ -78,9 +78,9 @@ We will shortly add a [tutorial](https://github.com/KIT-MRT/arbitration_graphs/p First make sure all dependencies are installed: - [glog](https://github.com/google/glog) -- [Googletest](https://github.com/google/googletest) (optional, if you want to build unit tests) -- [yaml-cpp](https://github.com/jbeder/yaml-cpp) - [util_caching](https://github.com/KIT-MRT/util_caching) +- [yaml-cpp](https://github.com/jbeder/yaml-cpp) +- [Googletest](https://github.com/google/googletest) (optional, if you want to build unit tests) - [Crow](https://crowcpp.org) (optional, needed for GUI only) See also the [`Dockerfile`](./Dockerfile) for how to install these packages under Debian or Ubuntu. From b934f1e49398babeda1fbe208b66333397f90878 Mon Sep 17 00:00:00 2001 From: Piotr Spieker Date: Tue, 19 Nov 2024 13:02:54 +0100 Subject: [PATCH 07/11] Explain core/gui library parts in installation section --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 1634c792..ea7a8010 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,12 @@ We will shortly add a [tutorial](https://github.com/KIT-MRT/arbitration_graphs/p ## Installation +The `arbitration_graphs` library consists of two parts +- **Core** + This is what it's all about – base classes for arbitrators and behavior components, implementations of various arbitration schemes, behavior verification, … +- **GUI** *optional* + Draws a live visual representation of the arbitration state (full graph, currently active behavior, current costs of behaviors, …) in a WebApp GUI. Supports SVG export as the one above (great for publications). +
Prerequisites From 0d78b28c38e8a1d3aca9a9a0a7e61074d1520a21 Mon Sep 17 00:00:00 2001 From: Piotr Spieker Date: Tue, 19 Nov 2024 13:03:13 +0100 Subject: [PATCH 08/11] Praise header-only library and MIT license in Readme --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index ea7a8010..bc76ffb4 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,10 @@ TODO: add example arbitration graph from robotics (with POMDP, RL methods) Use tightly integrated verifiers to ensure that only safe and valid behavior commands are executed. - 🪂 **Graceful Degradation** Your behavior is unreliable or unsafe? Arbitrators will gracefully fall back to the next-best option. +- 📦 **Header-Only** + Simple integration – just include this header-only C++ library! +- 📜 **Permissive License** + Published under MIT license to ensure maximum flexibility for your projects. ## Demo From 41d791d4b1ee0535ca73ea47cb4f6539fdb8ce65 Mon Sep 17 00:00:00 2001 From: ll-nick <68419636+ll-nick@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:59:55 +0100 Subject: [PATCH 09/11] Apply suggestions from code review Co-authored-by: Piotr Spieker --- README.md | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index bc76ffb4..670fa1f0 100644 --- a/README.md +++ b/README.md @@ -298,13 +298,38 @@ The repository is maintained by Piotr Spieker  If you use arbitration graphs in your research, we would be pleased if you cite our publication: ```bibtex -@misc{spieker2024arbitrationgraphs, - title={Better Safe Than Sorry: Enhancing Arbitration Graphs for Safe and Robust Autonomous Decision-Making}, - author={Piotr Spieker and Nick Le Large and Martin Lauer}, - year={2024}, - eprint={2411.10170}, - archivePrefix={arXiv}, - primaryClass={cs.RO}, - url={https://arxiv.org/abs/2411.10170}, +@misc{spieker2024ArbitrationGraphs, + title={Better Safe Than Sorry: Enhancing Arbitration Graphs for Safe and Robust Autonomous Decision-Making}, + author={Piotr Spieker and Nick Le Large and Martin Lauer}, + year={2024}, + eprint={2411.10170}, + eprinttype = {arXiv}, + archivePrefix={arXiv}, + primaryClass={cs.RO}, + doi = {10.48550/arXiv.2411.10170}, + url={https://arxiv.org/abs/2411.10170}, +} + +@inproceedings{orzechowski2020ArbitrationGraphs, + title = {Decision-{{Making}} for {{Automated Vehicles Using}} a {{Hierarchical Behavior-Based Arbitration Scheme}}}, + booktitle = {Intelligent {{Vehicles Symposium}}}, + author = {Orzechowski, Piotr F. and Burger, Christoph and Lauer, Martin}, + date = {2020-10}, + pages = {767--774}, + publisher = {IEEE}, + location = {Las Vegas, NV, USA}, + issn = {2642-7214}, + doi = {10.1109/IV47402.2020.9304723}, +} + +@article{lauer2010CognitiveConceptsAutonomous, + title = {Cognitive Concepts in Autonomous Soccer Playing Robots}, + author = {Lauer, Martin and Hafner, Roland and Lange, Sascha and Riedmiller, Martin}, + date = {2010}, + journaltitle = {Cognitive Systems Research}, + volume = {11}, + number = {3}, + pages = {287--309}, + doi = {10.1016/j.cogsys.2009.12.003}, } ``` From e2eebd13fda3ca61e9a99918e6f9dc350193e9fd Mon Sep 17 00:00:00 2001 From: Piotr Spieker Date: Tue, 19 Nov 2024 16:08:44 +0100 Subject: [PATCH 10/11] =?UTF-8?q?Add=20@ll-nick=20to=20list=20of=20maintai?= =?UTF-8?q?ners=20=E2=9D=A4=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 670fa1f0..fef8d169 100644 --- a/README.md +++ b/README.md @@ -291,6 +291,12 @@ The repository is maintained by Piotr Spieker  orzechow +and +Nick Le Large  + + + ll-nick +. ## Citation From fbbf2360a468ef534457b327d39d462f68e4a585 Mon Sep 17 00:00:00 2001 From: Nick Le Large Date: Tue, 19 Nov 2024 16:19:26 +0100 Subject: [PATCH 11/11] Tiny fix for multiple publications --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fef8d169..a8916361 100644 --- a/README.md +++ b/README.md @@ -301,7 +301,7 @@ Nick Le Large  ## Citation -If you use arbitration graphs in your research, we would be pleased if you cite our publication: +If you use arbitration graphs in your research, we would be pleased if you cite our work: ```bibtex @misc{spieker2024ArbitrationGraphs,