Merge pull request #34 from antarctica/1.1.6

1.1.6

.gitignore

@@ -26,7 +26,6 @@ outputs/*
 docs_builder/*
 testing.ipynb
 docs/build/*
-docs/html/*
 dev_venv/*
 *.ipynb
 splitting_experiments/*

README.md

@@ -1,36 +1,36 @@
+# Meshiφ (MeshiPhi)
+
 ![](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://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> -->
+<!-- <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/MeshiPhi/"><img src="https://img.shields.io/badge/Manual%20-github.io%2FMeshiPhi%2F-red" alt="Manual Page"></a>
+<a href="https://pypi.org/project/meshiphi/"><img src="https://img.shields.io/pypi/v/meshiphi" alt="PyPi"></a>
+<a href="https://github.com/antarctica/meshiphi/tags"><img src="https://img.shields.io/github/v/tag/antarctica/MeshiPhi" alt="Release Tag"></a>
+<a href="https://github.com/antarctica/MeshiPhi/issues"><img src="https://img.shields.io/github/issues/antarctica/MeshiPhi" alt="Issues"></a>
+<a href="https://github.com/antarctica/MeshiPhi/blob/main/LICENSE"><img src="https://img.shields.io/github/license/antarctica/MeshiPhi" alt="License"></a> 
+
 
-# Meshiφ (MeshiPhi)
 
 Introducing Meshiφ, a versatile software package designed for comprehensive earth modeling and navigation planning. Meshiφ works by discretizing the Earth's surface into a non-uniform grid, allocating higher resolution in regions of geographic diversity, and conserving lower resolution in more uniform regions. The software also incorporates data-driven vehicle models, with the ability to calculate speed limits and fuel needs for specific vessels within each grid cell. These mesh objects can be output in standard formats, such as GeoJSON and GeoTIFF, enabling data-visualisation via GIS software such as ArcGIS. 
 
 ## Installation
-The Meshiφ package has an optional dependance on GDAL, which is required to produce outputs in GeoJSON or GeoTIFF formats. More information on setting up GDAL can be found in the manual pages linked above. Once these requirements are met then the software can be installed by:
+Meshiφ can be installed via pip or by cloning the repository from GitHub.
 
-Github:
+ Pip: 
 ```
-git clone https://github.com/Antarctica/MeshiPhi
-python setup.py install
+pip install meshiphi
 ```
 
- Pip: 
+Github: (for local development)
 ```
-pip install meshiphi
+git clone https://github.com/Antarctica/MeshiPhi
+cd MeshiPhi
+pip install -e .
 ```
 
-> NOTE: The installation process may vary slightly dependent on OS. Please consult the documentation for further installation guidance.
+The Meshiφ package has an optional dependency on GDAL, which is required to produce outputs in GeoJSON or GeoTIFF formats. More information on setting up GDAL can be found in the manual pages linked above. Once these requirements are met then the software can be installed by:
 
-## Required Data sources
-Meshiφ 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
+> NOTE: The installation process may vary slightly dependent on OS. Please consult the documentation for further installation guidance.
 
 ## Documentation
 Sphinx is used to generate documentation for this project. The dependencies can be installed through pip:
@@ -45,6 +45,13 @@ Sometimes the cache needs to be cleared for internal links to update. If facing
 ```
 rm -r docs/build/.doctrees/
 ```
+
+## Required Data sources
+Meshiφ 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
+
+
 ## Developers
 Samuel Hall, Harrison Abbot, Ayat Fekry, George Coombs, Jonathan Smith, Maria Fox, and James Byrne 
 
@@ -59,5 +66,3 @@ Jonathan D. Smith, Samuel Hall, George Coombs, James Byrne, Michael A. S. Thorne
 
 For more information please see the attached ``LICENSE`` file. 
 
-[version]: https://img.shields.io/PolarRoute/v/datadog-metrics.svg?style=flat-square
-[downloads]: https://img.shields.io/PolarRoute/dm/datadog-metrics.svg?style=flat-square

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: e1bbf1467da075d11c4c3dc808fb152e
+config: 30f730049513b06b62ef00a8243579cc
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_sources/index.rst.txt

@@ -4,8 +4,11 @@ Welcome to the MeshiPhi Manual Pages
 MeshiPhi is a tool for the discretisation of environmental data with a non uniform resolution based on the variance of
 the data. This software package has been developed by the **British Antarctic Survey** (BAS), initially as part of a
 route planning tool for the BAS research vessel RRS Sir David Attenborough, though it can be applied to any geospatial data.
-The software is written in Python and is open source. The package contains limited plotting functionality, which is
-described in the :ref:`Mesh Plotting <mesh_plotting>` section.
+The software is written in Python and is open source. 
+
+The package contains limited plotting functionality, which is described in the :ref:`Mesh Plotting` section. For 
+extended plotting functionality, we recommend using the GeoPlot package, which is also developed by BAS. This is available at 
+the following GitHub repository: `GeoPlot <https://github.com/antarctica/GeoPlot>`_
 
 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/meshiphi>`_.
@@ -20,13 +23,12 @@ Contents:
    :maxdepth: 2
    :numbered:
 
-   ./sections/Code_overview
    ./sections/Installation
    ./sections/ipython_notebooks
    ./sections/Command_line_interface
+   ./sections/Code_overview
    ./sections/Configuration/Configuration_overview
    ./sections/Outputs
    ./sections/Dataloaders/overview
    ./sections/Mesh_Construction/Mesh_construction_overview
-   ./sections/Examples
    ./sections/Plotting/mesh_plotting

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

@@ -0,0 +1,18 @@
+**********
+Background
+**********
+
+
+Code Structure
+##############
+The outline of this manual is to provide the user with all the tools that they need to run the software for a set of examples. We also hope that the background information supplied for each section allows the user to understand the methods used throughout this toolkit.
+
+The separate stages of the codebase can be broken down into:
+
+1. :ref:`Dataloaders <dataloaders-overview>` - Reading in different datasets of differing types. Throughout this section we will outline the form that the input datasets should take and useful tips for pre-processing your data.
+2. :ref:`Mesh Construction <mesh_construction_overview>` - Generating a Digital Twin of the environmental conditions. In this section we outline the different Python classes that are used to construct a discretised representation across the user defined datasets, giving a coding background to the dynamic splitting of the mesh to finer resolution in regions of datasets that are spatially varying.
+
+Each stage of this pipeline makes use of a configuration file, found in the :ref:`Configuration Overview` section of the documentation
+and produces an output file, the form of which can be found in the :ref:`outputs` section of this document.
+
+In addition to the main section of the codebase we have also developed a series of plotting classes that allows the user to generate interactive maps and static figures for the Mesh Features. These can be found in the `Plotting` section later in the manual.

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

@@ -0,0 +1,143 @@
+###############################
+Command Line Interface
+###############################
+
+The MeshiPhi package provides CLI entry points, used to build a digital environment from a hetrogeneous collection of source data. 
+This digital environment file (mesh) may then be exported to a variety of file formats for use in other systems, such as GIS software. 
+The produced mesh file also interfaces directly with PolarRoute, BAS's route planning software to provide optinal routes through mesh.
+
+^^^^^^^^^^^
+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 :ref:`configuration - mesh construction` section of the documentation.
+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)
+
+
+The format of the returned mesh.json file is explain in :ref:`the mesh.json file` section of the documentation.
+
+
+
+^^^^^^^^^^^
+export_mesh
+^^^^^^^^^^^
+Once a mesh has been built using the :ref:`create_mesh` command, it can be exported other file types for 
+use in other systems (such as GIS software) using the the *export_mesh* command.
+
+::
+
+    export_mesh <mesh.json> <output_location> <output_format> 
+
+positional arguments:
+
+::
+
+    mesh : A digital environment file.
+    output_location : The location to save the exported mesh.
+    output_format : The format to export the mesh to.
+
+
+supported output formats are:
+  * .json (default) [JSON]
+  * geo.json (collection of polygons for each cell in the mesh) [GEOJSON]
+  * .tif (rasterised mesh) [TIF]
+  * .png [PNG]
+
+optional arguments:
+
+::
+
+    -v : verbose logging
+    -o : output location
+    -format_conf: configuration file for output format (required for TIF export, optional for GEOJSON)
+
+the format of the *<format_conf.json>* file required for .tif export is as follows:
+
+::
+
+    {
+        "data_name": "elevation",
+        "sampling_resolution": [
+            150,
+            150
+        ],
+        "projection": "3031",
+        "color_conf": "path to/color_conf.txt"
+    }
+
+where the variables are as follows:
+  * **data_name** : The name of the data to be exported. This is the name of the data layer in the mesh.
+  * **sampling_resolution** : The resolution of the exported mesh. This is a list of two values, the first being the x resolution and the second being the y resolution.
+  * **projection** : The projection of the exported mesh. This is a string of the EPSG code of the projection.
+  * **color_conf** : The path to the color configuration file. This is a text file containing the color scheme to be used when exporting the mesh. The format of this file is as follows:
+
+::
+
+    0 240 250 160  
+    30 230 220 170  
+    60 220 220 220 
+    100 250 250 250 
+
+The color_conf.txt contains 4 columns per line: the data_name value and the 
+corresponding red, green, blue value between 0 and 255.
+
+When using the *-format_conf* option for GEOJSON output the only variable required is the **data_name**. This specifies which of the data layers you want to export as a single GEOJSON file.
+
+^^^^^^^^^^^^
+rebuild_mesh
+^^^^^^^^^^^^
+
+Once a mesh has been built using the :ref:`create_mesh` command the *rebuild_mesh* command allows a user to rebuild it based on the
+original configs stored within the mesh file. This is primarily useful for debugging or to update old meshes produced with an older version
+of the package. Running this command will also reapply any vessel performance simulations, if these were run on the original mesh.
+
+::
+
+    rebuild_mesh <mesh.json>
+
+optional arguments:
+
+::
+
+    -v : verbose logging
+    -o : output location
+
+
+^^^^^^^^^^^^^^^^^^^^^
+plot_mesh (GeoPlot)
+^^^^^^^^^^^^^^^^^^^^^
+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 :ref:`export_mesh` command.
+
+::
+
+    plot_mesh <mesh.json>
+
+optional arguments:
+
+:: 
+
+        -v : verbose logging
+        -o : output location

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

@@ -0,0 +1,34 @@
+######################################
+Configuration Overview
+######################################
+
+In this section we will outline the standard structure for a configuration file used in 
+all portions of the PolarRoute software package.
+
+Each stage of the route-planning process is configured by a separate configuration file. 
+The configuration files are written in JSON, and are passed to each stage of the 
+route-planning process as command-line arguments or through a Python script.
+
+Example configuration files are provided in the `config` directory.
+
+Descriptions of the configuration options for the Mesh Construction can be found in 
+the :ref:`Configuration - Mesh Construction` section of the documentation.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   ./Mesh_construction_config
+
+
+Config Validation
+^^^^^^^^^^^^^^^^^
+
+At each major stage of the code (mesh construction, vessel performance modelling, 
+and route planning), the configs supplied are validated using a template JSON Schema.
+These schema check that the correct keywords and datatypes are provided in the config 
+JSON's, as well as the waypoints CSV file. They also perform rudimentary checks on the
+values to ensure that they make sense (e.g. startTime is before endTime).
+
+.. automodule:: meshiphi.config_validation.config_validator
+   :members: