Docs update v0.3

.gitignore

@@ -26,5 +26,4 @@ outputs/*
 docs_builder/*
 testing.ipynb
 docs/build/*
-docs/html/*
 dev_venv/*

README.md

@@ -1,38 +1,43 @@
+# PolarRoute
+
 ![](logo.jpg)
 
-<a href="https://colab.research.google.com/drive/12D-CN10X7xAcXn_df0zNLHtdiiXxZVkz?usp=sharing"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab" alt="Colab">
 <a href="https://antarctica.github.io/PolarRoute/"><img src="https://img.shields.io/badge/Manual%20-github.io%2FPolarRoute%2F-red" alt="Manual Page">
-<a href="https://pypi.org/project/polar-route/"><img src="https://img.shields.io/pypi/v/polar-route" alt="PyPi">
+<a href="https://colab.research.google.com/drive/12D-CN10X7xAcXn_df0zNLHtdiiXxZVkz?usp=sharing"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab" alt="Colab">
+<a href="https://pypi.org/project/polar-route/"><img src="https://img.shields.io/pypi/v/polar-route" alt="PyPI">
 <a href="https://github.com/antarctica/PolarRoute/tags"><img src="https://img.shields.io/github/v/tag/antarctica/PolarRoute" alt="Release Tag"></a>
 <a href="https://github.com/antarctica/PolarRoute/issues"><img src="https://img.shields.io/github/issues/antarctica/PolarRoute" alt="Issues"></a>
 <a href="https://github.com/antarctica/PolarRoute/blob/main/LICENSE"><img src="https://img.shields.io/github/license/antarctica/PolarRoute" alt="License"></a>
 
-# PolarRoute
-PolarRoute is a long-distance maritime polar route planning package, taking into account complex changing environmental conditions. The codebase allows the construction of optimised routes through three main stages: discrete modelling of the environmental conditions using a non-uniform mesh, the construction of mesh-optimal paths, and physics informed path smoothing. In order to account for different vehicle properties we construct a series of data driven functions that can be applied to the environmental mesh to determine the speed limitations and fuel requirements for a given vessel and mesh cell, representing these quantities graphically and geospatially.
+PolarRoute is a long-distance maritime polar route planning package, able to take into account complex and changing environmental conditions. It allows the construction of optimised routes through three main stages: discrete modelling of the environmental conditions using a non-uniform mesh, the construction of mesh-optimal paths, and physics informed path smoothing. In order to account for different vehicle properties we construct a series of data-driven functions that can be applied to the environmental mesh to determine the speed limitations and fuel requirements for a given vessel and mesh cell. The environmental modelling component of this functionality is provided by the [MeshiPhi](https://github.com/antarctica/MeshiPhi) library.
 
 ## Installation
-The PolarRoute package requires GDAL files to be installed. This software can be installed on Windows by running the required wheels for GDAL and FIONA. More information can be found in the manual pages linked above. Once these requirements are met then the software can be installed by:
 
-Github:
+PolarRoute is available from PyPI and can be installed by running: 
 ```
-git clone https://github.com/Antarctica/PolarRoute
-python setup.py install
+pip install polar-route
 ```
 
- Pip: 
+Alternatively you can install PolarRoute by downloading the source code from GitHub:
 ```
-pip install polar-route
+git clone https://github.com/Antarctica/PolarRoute
+pip install -e ./PolarRoute
 ```
+Use of `-e` is optional, based on whether you want to be able to edit the installed copy of the package.
 
-> NOTE: The installation process may vary slightly dependent on OS. Please consult the documentation for further installation guidance.
+> NOTE: Some features of the PolarRoute package require GDAL to be installed. Please consult the documentation for further guidance.
 
 ## Required Data sources
-Polar-route has been built to work with a variety of open-source atmospheric and oceanographic data sources. 
-A list of supported data sources and their associated data-loaders is given in the 
-'Data Loaders' section of the manual
+PolarRoute has been built to work with a variety of open-source atmospheric and oceanographic data sources. For testing and demonstration purposes it is also possible to generate artificial Gaussian Random Field data.  
+
+A full list of supported data sources and their associated dataloaders is given in the 
+'Dataloader Overview' section of the [MeshiPhi manual](https://antarctica.github.io/MeshiPhi/)
 
 ## Documentation
-Sphinx is used to generate documentation for this project. The dependencies can be installed through pip:
+The documentation for the package is available to read at: https://antarctica.github.io/PolarRoute/
+
+If you make changes to the source of the documentation you will need to rebuild the corresponding html files using Sphinx.
+The dependencies for this can be installed through pip:
 ```
 pip install sphinx sphinx_markdown_builder sphinx_rtd_theme rinohtype
 ```
@@ -42,19 +47,18 @@ sphinx-build -b html ./docs/source ./docs/html
 ```
 Sometimes the cache needs to be cleared for internal links to update. If facing this problem, run this from the PolarRoute directory.
 ```
-rm -r docs/build/.doctrees/
+rm -r docs/html/.doctrees/
 ```
 ## Developers
 Jonathan Smith, Samuel Hall, George Coombs, James Byrne,  Michael Thorne, Maria Fox, Harrison Abbot, Ayat Fekry
 
 ## Collaboration
 We are currently assessing the best practice for collaboration on the codebase, until then please contact [[email protected]]([email protected]) for further info.
 
-
 ## License
 This software is licensed under a MIT license, but request users cite our publication.  
 
-Jonathan D. Smith, Samuel Hall, George Coombs, James Byrne, Michael A. S. Thorne,  J. Alexander Brearley, Derek Long, Michael Meredith, Maria Fox,  (2022), Autonomous Passage Planning for a Polar Vessel, arXiv, https://arxiv.org/abs/2209.02389
+Jonathan D. Smith, Samuel Hall, George Coombs, James Byrne, Michael A. S. Thorne, J. Alexander Brearley, Derek Long, Michael Meredith, Maria Fox, (2022), Autonomous Passage Planning for a Polar Vessel, arXiv, https://arxiv.org/abs/2209.02389
 
 For more information please see the attached ``LICENSE`` file. 
 

docs/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 9d6a109539075ab46ad3eba1940d0e3c
+config: 9148f976cde425ab5b276686e1a054e9
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_sources/index.rst.txt

@@ -2,12 +2,14 @@ Welcome to the PolarRoute Manual Pages
 ======================================
 
 PolarRoute is a tool for the optimisation of routes for maritime vehicles travelling in polar waters.
-It leverages `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_; a package designed to
+It depends on `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_; a package designed to
 discretise the world from heterogeneous data sources (follow link for more details and docs).
-This software package has been developed by the **British Antarctic Survey** (BAS), primarily for the 
-optimisation of polar routes for the BAS research vessel RRS Sir David Attenborough, though it is applicable 
+This software package has been developed by the **British Antarctic Survey** (BAS). It was originally designed primarily for the
+optimisation of polar routes for the BAS research vessel RRS Sir David Attenborough, however it is applicable
 to any vessel (e.g. AUVs). The software is written in Python and is open source.
 
+Plotting functionality for the outputs of PolarRoute is provided by the `GeoPlot <https://github.com/antarctica/GeoPlot>`_ package, also developed at BAS.
+
 For more information on the project, please visit the `PolarRoute website <https://www.bas.ac.uk/project/autonomous-marine-operations-planning/>`_
 and follow our `GitHub repository <https://github.com/antarctica/PolarRoute>`_.
 
@@ -21,14 +23,12 @@ Contents:
    :maxdepth: 2
    :numbered:
 
-   ./sections/Code_overview
    ./sections/Installation
-   ./sections/ipython_notebooks
+   ./sections/Examples
    ./sections/Command_line_interface
    ./sections/Configuration/Configuration_overview
    ./sections/Outputs
+   ./sections/Code_overview
    ./sections/Vehicle_specifics
    ./sections/Route_calculation
    ./sections/Route_optimisation
-   ./sections/Examples
-

docs/html/_sources/sections/Command_line_interface.rst.txt

@@ -1,14 +1,37 @@
+.. _cli:
+
 ###############################
 Command Line Interface
 ###############################
 
 The PolarRoute package provides multiple CLI entry points, intended to be used in succession to plan a route through a digital environment.
 
-.. figure:: ./Figures/PolarRoute_CLI.png
-   :align: center
-   :width: 700
+^^^^^^^^^^^
+create_mesh
+^^^^^^^^^^^
+The *create_mesh* entry point builds a digital environment file from a collection of source data, which can then be used
+by the vessel performance modeller and route planner.
+
+::
+
+    create_mesh <config.json>
+
+positional arguments:
+
+::
+
+    config : A configuration file detailing how to build the digital environment. JSON parsable
+
+The format of the required *config.json* file can be found in the `"Configuration - Mesh Construction" <https://antarctica.github.io/MeshiPhi/html/sections/Configuration/Mesh_construction_config.html>`_ section of the `MeshiPhi documentation <https://antarctica.github.io/MeshiPhi/>`_ .
+There are also example configuration files available in the directory :code:`examples/environment_config/grf_example.config.json`
+
+optional arguments:
+
+::
+
+    -v (verbose logging)
+    -o <output location> (set output location for mesh)
 
-   *Overview figure of the Command Line Interface entry points of PolarRoute*
 
 ^^^^^^^^^^^
 add_vehicle
@@ -24,11 +47,11 @@ positional arguments:
 
 ::
 
-    vessel_config : A configuration file detailing the vessel to be simulated in the digital environment.
+    vessel_config : A configuration file giving details of the vessel to be simulated.
     mesh : A digital environment file.
 
-The format for the required *<vessel.json>* file can be found in the :ref:`configuration - vessel performance modeller` section of the documentation.
-The required *<mesh.json>* file can be created using the *create_mesh* command from the `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_ package.
+The format for the required *vessel.json* file can be found in the :ref:`configuration - vessel performance modeller` section of the documentation.
+The required *mesh.json* file can be created using the *create_mesh* command from the `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_ package.
 
 optional arguments are
 
@@ -81,11 +104,11 @@ positional parameters:
     waypoints: A .csv file containing waypoints to be travelled between.
 
 
-The format for the required *<route_config.json>* file can be found in the :ref:`configuration - route planning` section of the documentation.
-The required *<vessel_mesh.json>* file can be generated using the :ref:`add_vehicle` command shown above.
-The format for the required *<waypoints.csv>* file is as follows:
+The format for the required *route_config.json* file can be found in the :ref:`configuration - route planning` section of the documentation.
+The required *vessel_mesh.json* file can be generated using the :ref:`add_vehicle` command shown above.
+The format for the required *waypoints.csv* file is as follows:
 
-As table:
+As a table:
 
 +------------------+---------------+---------------+---------+---------------+
 | Name             | Lat           | Long          | Source  | Destination   |
@@ -101,7 +124,7 @@ As table:
 | Elephant Island  | -60.54722222  | -55.18138889  |         |               |
 +------------------+---------------+---------------+---------+---------------+
 
-As .csv:
+In .csv format:
 
 ::
 
@@ -112,8 +135,8 @@ As .csv:
     Falklands,-55.63472222,-64.88,,
     Elephant Island,-60.54722222,-55.18138889,,
 
-Additional waypoints may be added by extending the '<waypoints.csv>' file. Which waypoints are navigated between is determined by 
-added a **X** in either the *Source* or *Destination* columns. When processed, the route planner will create routes from all 
+Additional waypoints may be added by extending the *waypoints.csv* file. Which waypoints are navigated between is determined by
+adding an **X** in either the *Source* or *Destination* columns. When processed, the route planner will create routes from all
 waypoints marked with an **X** in the source column to all waypoints marked with a **X** in the *destination* column. 
 
 optional arguments are
@@ -126,7 +149,7 @@ optional arguments are
     -d (output Dijkstra path as well as smoothed path)
 
 
-The format of the returned *<route.json>* file is explained in :ref:`the route.json file` section of the documentation.
+The format of the returned *route.json* file is explained in :ref:`the route.json file` section of this documentation.
 
 ^^^^^^^^^^^^^^^
 calculate_route
@@ -153,7 +176,7 @@ optional arguments:
 
 Running this command will calculate the cost of a route between a set of waypoints provided in either csv or geojson
 format. The route is assumed to travel from waypoint to waypoint in the order they are given, following a rhumb line.
-The format of the output *<route.json>* file is identical to that from the :ref:`optimise_routes` command.
+The format of the output *route.json* file is identical to that from the :ref:`optimise_routes` command.
 This is explained in :ref:`the route.json file` section of the documentation. The time and fuel cost of the route will
 also be logged out once the route file has been generated. If the user-defined route crosses a cell in the mesh that is
 considered inaccessible to the vessel then a warning will be displayed and no route will be saved.
@@ -185,7 +208,25 @@ optional arguments:
 ^^^^^^^^
 Plotting
 ^^^^^^^^
-Meshes produced at any stage in the route planning process can be visualised using the GeoPlot 
-library found at the relevant `GitHub page <https://github.com/antarctica/GeoPlot>`_. Meshes and routes can also be
-plotted in other GIS software such as QGIS by exporting the mesh to a common format such as .geojson or .tif using
-the export_mesh command described in the `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_ docs.
+Meshes produced at any stage in the route planning process can be visualised using the :code:`plot_mesh` cli command from the `GeoPlot <https://github.com/antarctica/GeoPlot>`_
+library. Meshes and routes can also be plotted in other GIS software such as QGIS by exporting the mesh to a commonly used format such
+as .geojson or .tif using the export_mesh command described in the `MeshiPhi <https://github.com/antarctica/MeshiPhi>`_ docs.
+
+::
+
+    plot_mesh <mesh.json>
+
+optional arguments:
+
+::
+
+        -v : verbose logging
+        -o : output location
+        -a : add directional arrows to routes
+        -r : plot an additional route from a file
+
+.. figure:: ./Figures/PolarRoute_CLI.png
+   :align: center
+   :width: 700
+
+   *Overview figure of the Command Line Interface entry points of PolarRoute*

docs/html/_sources/sections/Configuration/Configuration_overview.rst.txt

@@ -11,6 +11,8 @@ route-planning process as command-line arguments or through a Python script.
 
 Example configuration files are provided in the `config` directory.
 
+The format of the config used to generate an environmental mesh can be found in the `"Configuration - Mesh Construction" <https://antarctica.github.io/MeshiPhi/html/sections/Configuration/Mesh_construction_config.html>`_ section of the `MeshiPhi documentation <https://antarctica.github.io/MeshiPhi/>`_ .
+
 Descriptions of the configuration options for the Vessel Performance Modelling can 
 be found in the :ref:`Configuration - Vessel Performance Modeller` section of the 
 documentation.

docs/html/_sources/sections/Configuration/Route_planning_config.rst.txt

@@ -1,3 +1,5 @@
+.. _route config:
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Configuration - Route Planning
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^