Merge pull request #83 from digitalfabrik/feature/documentation

Add simulation documentation, fix #69
digitalfabrik · Dec 3, 2023 · 4c0add9 · 4c0add9
2 parents 6c7a9e7 + ea58c0b
commit 4c0add9
Show file tree

Hide file tree

Showing 5 changed files with 54 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -34,13 +34,13 @@ Authentication can be provided in two ways:
 
 1. Clone this repository and change into the new directory:
    ```bash
-   gh repo clone digitalfabrik/leeway
+   git clone [email protected]:digitalfabrik/opendrift-leeway-webgui.git leeway
    cd leeway
    ```
-2. Create a virtual environment and activate it:
+2. Create a virtual environment outside of the project directory and activate it:
    ```bash
-   python3 -m venv .venv
-   source .venv/bin/activate
+   python3 -m venv ~/.venv
+   source ~/.venv/bin/activate
    ```
 3. Install the dependencies:
    ```bash

diff --git a/opendrift_leeway_webgui/leeway/templates/base.html b/opendrift_leeway_webgui/leeway/templates/base.html
@@ -4,11 +4,11 @@
 {% get_current_language as LANGUAGE_CODE %}
 <html lang="{{ LANGUAGE_CODE }}">
     <head>
-        <meta charset="utf-8"/>
+        <meta charset="utf-8" />
         <meta name="description"
-              content="OpenDrift Leeway simulations for Search and Rescue operations"/>
+              content="OpenDrift Leeway simulations for Search and Rescue operations" />
         <meta name="keywords"
-              content="OpenDrift, Leeway, SAR, Search, Rescue, Simulation, Drift"/>
+              content="OpenDrift, Leeway, SAR, Search, Rescue, Simulation, Drift" />
         <title>Leeway Simulation</title>
         <link rel="stylesheet" href="{% static 'css/style.css' %}"/>
     </head>
@@ -24,7 +24,7 @@
             <p>
                 <a href="https://github.com/digitalfabrik/opendrift-leeway-webgui">Source Code</a>
                 {% if user.is_authenticated %}
-                    | <a href="{% url "simulation_list" %}">List of simulations</a> | <a href="{% url "simulation_form" %}">New Simulation</a> | <a href="{% url "logout" %}">Logout</a>
+                  | <a href="{% url "simulation_documentation" %}">Documentation</a> | <a href="{% url "simulation_list" %}">List of simulations</a> | <a href="{% url "simulation_form" %}">New Simulation</a> | <a href="{% url "logout" %}">Logout</a>
                 {% endif %}
             </p>
         </main>

diff --git a/opendrift_leeway_webgui/leeway/templates/leeway/leewaysimulation_documentation.html b/opendrift_leeway_webgui/leeway/templates/leeway/leewaysimulation_documentation.html
@@ -0,0 +1,26 @@
+{% extends "base.html" %}
+{% block content %}
+    <h2>Leeway Simulation Documentation</h2>
+    <h3>Background</h3>
+    <p>This software acts as a web user interface for the <a href="https://opendrift.github.io/gallery/example_leeway.html">OpenDrift Leeway</a> model. The basis for the simulation are experiments performed by the US Coast Guard in 1999. The results are published on <a href="https://ntrl.ntis.gov/NTRL/dashboard/searchResults/titleDetail/ADA366414.xhtml">https://ntrl.ntis.gov</a>, which include desriptions of the objects that were tested (2-13 and following pages).</p>
+    <h3>E-Mail Interface</h3>
+    <p>If you have a low bandwidth connection, you can use the e-mail interface. The simulation parameters can be set in the e-mail subject. Your e-mail address needs to be registered for you user account in this tool first. The result of the simulation will be sent to your e-mail address within a couple of minutes.</p>
+    <ol>
+      <li>Create a new e-mail</li>
+      <li>Enter simulation parameters with adjusted values in the subject: <pre>latitude=33.333;longitude=14.444;duration=48;start_time=2022-12-10 00:00:00;object_type=27</pre></li>
+      <li>Send the mail to <pre>{{ SERVER_EMAIL }}</pre></li>
+    </ol>
+    The default object type for simulatoins is a life raft (ID: 27). Some alternatives are:
+    <ul>
+      <li>Person in Water (unknown state): 1</li>
+      <li>Person in Water (conscious): 2</li>
+      <li>Person in water (deceased): 6</li>
+      <li>Life raft: 27</li>
+      <li>Skif, V-hull: 45</li>
+    </ul>
+    <h3>Interpreting Simulation Result</h3>
+    <p>When the simulation is finished, you will receive an e-mail that contains an attached image with the simulation results.</p>
+    <p>The simulation will randomly distribute 100 test particles around your entered coordinates. The default radius for distributing the particles is 1000 meters. If the coordinates are not very clear, you can increase this radius.</p>
+    <p>The starting points of the simulated particles are marked with green dots. If the particle ends up floating in water at the end of the simulation, the particle is marked blue. If the particle ends up on shore, it is marked green.</p>
+    <p>The image shows the trajectories of particles from the starting points to the ending points. The color of the trajectories incdicates the position of a particle at a given time. For example the color green always shows the position of the particles after ~50% of the simulated time range, while orange shows the positions at ~75%.</p>
+{% endblock content %}
diff --git a/opendrift_leeway_webgui/leeway/urls.py b/opendrift_leeway_webgui/leeway/urls.py
@@ -12,12 +12,18 @@
     IndexRedirectView,
     LeewaySimulationCreateView,
     LeewaySimulationDetailView,
+    LeewaySimulationDocumentation,
     LeewaySimulationListView,
 )
 
 #: The url patterns of this module (see :doc:`django:topics/http/urls`)
 urlpatterns = [
     path("", IndexRedirectView.as_view(), name="index"),
+    path(
+        "documentation/",
+        LeewaySimulationDocumentation.as_view(),
+        name="simulation_documentation",
+    ),
     path(
         "simulations/",
         include(

diff --git a/opendrift_leeway_webgui/leeway/views.py b/opendrift_leeway_webgui/leeway/views.py
@@ -2,6 +2,7 @@
 from django.contrib import messages
 from django.contrib.auth.mixins import LoginRequiredMixin
 from django.urls import reverse_lazy
+from django.views.generic import TemplateView
 from django.views.generic.base import RedirectView
 from django.views.generic.detail import DetailView
 from django.views.generic.edit import CreateView
@@ -21,6 +22,19 @@ class IndexRedirectView(RedirectView):
     pattern_name = settings.LOGIN_REDIRECT_URL
 
 
+class LeewaySimulationDocumentation(TemplateView):
+    """
+    Display end user documentation for using the tool
+    """
+
+    template_name = "leeway/leewaysimulation_documentation.html"
+
+    def get_context_data(self, **kwargs):
+        context = super(LeewaySimulationDocumentation, self).get_context_data(**kwargs)
+        context["SERVER_EMAIL"] = settings.SERVER_EMAIL
+        return context
+
+
 class LeewaySimulationCreateView(LoginRequiredMixin, CreateView):
     """
     The view for rendering and submitting the simulation form