Merge branch 'master' into develop

.github/workflows/draft-pdf.yaml

@@ -0,0 +1,23 @@
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v2
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

BUILD.md

@@ -1,6 +1,8 @@
 # Building
 
-The build process should be fairly familiar. The instructions provided are for Windows x64.
+The build process should be fairly familiar. 
+
+## Windows
 
 1. Ensure you have the required dependencies:
     - Python 3.8 *ONLY*
@@ -17,20 +19,48 @@ python3 -m venv spgr
 .\spgr\Scripts\activate.bat
 ```
 
-3. Clone the repository
+3. Clone the repository. There are some data files that are stored in git LFS, so we ensure that the hooks are installed first, then `git clone` is able to download both sets of files.
 
 ```commandline
+git lfs install
 git clone https://github.com/aliaksei135/seedpod_ground_risk.git
 ```
 
 4. Install requirements
 
 ```commandline
 cd seedpod_ground_risk
-
 pip install -r requirements.txt
 ```
 
+## Linux
+
+1. Install dependencies
+
+```bash
+sudo apt install libgeos-dev libgdal-dev proj-bin libbz2-dev
+```
+
+2. Create and activate a virtual environment, any should do. Here we use `virtualenv`:
+
+```bash
+python -m venv spgr
+source spgr/bin/activate
+```
+
+3. Clone the repository. There are some data files that are stored in git LFS, so we ensure that the hooks are installed first, then `git clone` is able to download both sets of files.
+```commandline
+git lfs install
+git clone https://github.com/aliaksei135/seedpod_ground_risk.git
+```
+
+4. Install requirements
+
+```commandline
+cd seedpod_ground_risk
+pip install -r requirements-linux.txt
+```
+
 This is enough to run and develop on.
 
 # Packaging
@@ -42,6 +72,8 @@ When packaging don't forget to check versions in both `setup.py` and `make_insta
 
 ### Installer
 
+**Currently, this is only supported on Windows.**
+
 The installer uses `PyInstaller` to extract all the dependencies and `InnoSetup` to create a Windows installer package
 out of them.
 
@@ -61,16 +93,13 @@ level optimisation `-OO`, as this removes some docstrings that break dependencie
 
 ### Wheel
 
-1. Inside the root repository directory with the virtualenv active. Ensure you have up to date build tools:
+**Building wheels is supported on both Windows and Linux**
 
-```commandline
-pip install --upgrade build
-```
-
-2. Build the wheel as usual:
+1. Inside the root repository directory with the virtualenv active. Ensure you have up to date build tools:
 
 ```commandline
-python -m build
+cd seedpod_ground_risk
+pip wheel . -w dist
 ```
 
 The `.whl` file will be built in `dist`. You can install this as required:
@@ -84,4 +113,4 @@ then import the module:
 ```python
 import seedpod_ground_risk # Import entire module
 import seedpod_ground_risk.cli # Only the CLI
-```
+```

README.md

@@ -9,15 +9,14 @@ used by pathfinding algorithms to determine routes that have a fixed risk thresh
 All data processing is performed locally, so performance depends on your machine spec. At least 8GiB of RAM is essential
 however.
 
-Developed as part of the [SEEDPOD project](https://cascadeuav.com/seedpod/) funded by the E-Drone project grant
-([EP/V002619/1)](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/V002619/1).
+Funded by the Engineering and Physical Sciences Research Council on the E-Drone project
+([EP/V002619/1](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/V002619/1)).
 
 ## Disclaimer
 
 ***This is intended to provide guidance on overflight risks in terms of risk-to-life (RtL) and is by no means an
 extensive or complete picture of the ground risks. While the software is intended to promote safe drone flight, use of
-this software does not in itself guarantee safe or legal drone operation. Follow
-the [drone code](https://dronesafe.uk/drone-code/).***
+this software does not in itself guarantee safe or legal drone operation. For the UK, [the CAA provides further information](https://caa.co.uk/drones)***
 
 ## Usage
 
@@ -38,7 +37,7 @@ See `BUILD.md` for further instructions.
 
     MIT License
 
-    Copyright (c) 2021 Aliaksei Pilko
+    Copyright (c) 2022 Aliaksei Pilko
 
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to deal
@@ -56,4 +55,4 @@ See `BUILD.md` for further instructions.
     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
+    SOFTWARE.

paper/paper.bib

@@ -0,0 +1,27 @@
+@INPROCEEDINGS{Hammer:2017,
+	author={Hammer, Jonathan and Murray, Alexander R. and Lowman, Alexa},
+	booktitle={2017 IEEE/AIAA 36th Digital Avionics Systems Conference (DASC)},
+	title={Safety analysis paradigm for UAS: Development and use of a common architecture and fault tree model},
+	year={2017},
+	pages={1-10},
+	doi={10.1109/DASC.2017.8102039}
+}
+@INPROCEEDINGS{Cour-Harbo:2020,
+	author={la Cour-Harbo, Anders},
+	booktitle={2020 International Conference on Unmanned Aircraft Systems (ICUAS)}, 
+	title={Ground impact probability distribution for small unmanned aircraft in ballistic descent}, 
+	year={2020},
+	pages={1442-1451},
+	doi={10.1109/ICUAS48674.2020.9213990}
+}
+
+@INPROCEDINGS{Ancel:2017,
+	author = {Ersin Ancel and Francisco M. Capristan and John V. Foster and Ryan C. Condotta},
+	title = {Real-time Risk Assessment Framework for Unmanned Aircraft System (UAS) Traffic Management (UTM)},
+	booktitle = {17th AIAA Aviation Technology, Integration, and Operations Conference},
+	year = {2017},
+	doi = {10.2514/6.2017-3273},
+	URL = {https://arc.aiaa.org/doi/abs/10.2514/6.2017-3273},
+	eprint = {https://arc.aiaa.org/doi/pdf/10.2514/6.2017-3273}
+}
+

paper/paper.md

@@ -0,0 +1,80 @@
+---
+title: "SEEDPOD Ground Risk: A Python application and library for Uncrewed Aerial Systems ground risk analysis and risk-aware path finding"
+tags:
+  - python
+  - "uncrewed aerial systems"
+  - "unmanned aerial systems"
+  - "aviation safety"
+  - risk
+  - "ground risk"
+authors:
+  - name: Aliaksei Pilko 
+    orcid: 0000-0003-0023-0300 
+    affiliation: 1
+  - name: Zachary Tait
+    orcid: 0000-0002-5016-6821 
+    affiliation: 1 
+affiliations:
+  - name: Faculty of Engineering and the Environment, University of Southampton 
+    index: 1 
+date: 28/11/2021 
+bibliography: paper.bib
+---
+
+# Summary
+
+The proliferation of Uncrewed Aerial Systems (UAS) for a wide range of use-cases, from logistics to urban air mobility,
+is increasing. A common theme in the majority of use-cases is the operation in and around urban areas, where a critical
+failure of one or more onboard systems can result in the UAS departing controlled flight and posing a hazard to, amongst
+other parties not considered here, third parties located on the ground in the vicinity of the UAS.
+
+There are established methods of probabilistically modelling onboard failures, such as failure tree
+analysis [@Hammer:2017], to arrive at an overall probability of the UAS departing controlled flight. This can be
+combined with impact probability density modelling [@Cour-Harbo:2020] to assign probabilities to impact a given cell.
+Once cell probabilities are assigned, a population model determines the probability of striking a person within each
+cell. Impact fatality models [@Ancel:2017] are further used to transform this to probabilities of causing a fatality in
+each cell.
+
+A full UAS ground risk map is generated by summing all probabilities for a Loss of Control (LoC) occurring at a
+specified altitude for each cell. This represents the probability of causing harm or a fatality (depending on the summed
+probabilities) if the aircraft were to fail at that location.
+
+The general equation is $$P_{\mathrm{harm}}(x,y) = P_{\mathrm{LoC}} P_{\mathrm{strike|LoC}}(x,y) P_
+{\mathrm{harm|strike}}(x,y)$$ where $x,y$ are grid indices referring to the location of LoC, $P_{\mathrm{harm}}$ is the
+probability of causing harm, $P_{\mathrm{LoC}}$ is the probability of the aircraft entering a LoC state; this can be
+found using aforementioned methods, $P_{\mathrm{strike|LoC}}$ is the probability of striking a person given the LoC has
+occurred, $P_{\mathrm{harm|strike}}$ is the probability of the strike causing a given harm, usually a fatality.
+
+Each probability component is driven by a different set of models, however the overall procedure is identical in that
+every cell in the risk map must be iterated over and a LoC modeled at that location, then the resultant single point
+risk map summed to represent the overall probability for that LoC location. It is this element of the process that can
+be parallelised without synchronisation between threads/processes.
+
+# Statement of Need
+
+SEEDPOD Ground Risk is a Python application and package that enables the generation of risk maps by implementing fast
+GPU-accelerated routines for the risk calculation as well as being, to the authors best knowledge, the first open-source
+probabilistic ground risk assessment tool. Numba is used for all calculation acceleration and enable the fallback to
+JIT-compiled CPU code where a compatible NVIDIA GPU is not detected. A common set of scientific and geospatial Python
+packages are used, such as NumPy, SciPy, Pandas, and GeoPandas.
+
+The software is intended to allow for further development and testing of different constituent models as part of a
+holistic ground risk assessment process. This enables the exploration of individual model effects on the final ground
+risk map without the reimplementation of the remainder of the process and with the benefit of the code optimisation
+already performed.
+
+The use of the Python programming language allows for rapid prototyping due to the interpreted nature of the language as
+opposed to a compiled language. This, however results in lower computational performance compared to an equivalent C++
+implementation.
+
+A basic user interface is implemented to allow for non-expert users to utilise the tool and promote the safer flight of
+UAS. This is packaged in an installer that ensures all dependencies are installed with the package. The user interface
+exposes much the same functionality as the API in a no-code environment.
+
+# Acknowledgements
+
+This work is funded by the Engineering and Physical Sciences Research Council as part of the E-Drone project under grant
+number EP/V002619/1. The authors would like to thank András Sóbester, James Scanlan, and Mario Ferraro for their guidance
+and advice on theoretical aspects of the work.
+
+# References

seedpod_ground_risk/cli/spgr.py

@@ -195,14 +195,10 @@ def path():
 @click.option('--wind-direction', default=90, type=click.INT,
               help='The wind bearing. This is the direction the wind is coming from.')
 @click.option('--wind_speed', default=5, type=click.FLOAT, help='Wind speed at the flight altitude in m/s')
-@click.option('--algo', default='ra*', type=click.STRING,
-              help='Pathfinding algorithm to use. Current options are ["ra*", "ga"]')
-@click.argument('algo_args', nargs=-1, type=click.UNPROCESSED)
 def make(min_lat, max_lat, min_lon, max_lon,
          start_lat, start_lon, end_lat, end_lon,
          aircraft, failure_prob, output_path, resolution, hour, altitude,
-         airspeed, wind_direction, wind_speed,
-         algo, algo_args):
+         airspeed, wind_direction, wind_speed):
     """
     Path minimising the fatality risk posed.
 
@@ -212,7 +208,7 @@ def make(min_lat, max_lat, min_lon, max_lon,
 
     If an aircraft config json file is not specified, a default aircraft with reasonable parameters is used.
 
-    All coordinates should be in decimal degrees and form a non degenerate polygon.
+    All coordinates should be in decimal degrees and form a non degenerate polygon. The path start and end coordinates must be within the bounds
 
     """
     import geopandas as gpd
@@ -228,13 +224,15 @@ def make(min_lat, max_lat, min_lon, max_lon,
                                          wind_direction, wind_speed)
     res = make_fatality_grid(aircraft, strike_grid, v_is)
 
-    snapped_path = make_path(res, bounds, (start_lat, start_lon), (end_lat, end_lon), algo=algo)
+    snapped_path = make_path(res, bounds, (start_lat, start_lon), (end_lat, end_lon))
     if snapped_path:
         dataframe = gpd.GeoDataFrame({'geometry': [snapped_path]}).set_crs('EPSG:4326')
         dataframe.to_file(os.path.join(output_path, f'path.geojson'), driver='GeoJSON')
     else:
         print('Path could not be found')
 
+
+path.add_command(make)
 
 # path
 ############################