Tutorials for the next release

docs/conf.py

@@ -23,11 +23,11 @@
 from string import Template
 
 def get_tutorial_images():
-    TUTORIAL_URL = "https://fz-juelich.sciebo.de/s/7DUjGMgP1HFvakG/download"
-    TUTORIAL_DIR = 'videos/gif'
+    TUTORIAL_URL = "https://fz-juelich.sciebo.de/s/KcF29hPNRzkxN6q/download"
+    TUTORIAL_DIR = 'videos/mp4'
     if not os.path.exists(TUTORIAL_DIR):
         os.makedirs(TUTORIAL_DIR)
-    TUTORIAL_ARCHIVE = 'videos/gif/tutorials.zip'
+    TUTORIAL_ARCHIVE = 'videos/mp4/tutorials.zip'
     if not os.path.exists(TUTORIAL_ARCHIVE):
         response = requests.get(TUTORIAL_URL)
         open(TUTORIAL_ARCHIVE, "wb").write(response.content)
@@ -119,7 +119,10 @@ def get_tutorial_images():
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx_rtd_theme']
+extensions = ['sphinx_rtd_theme', 'sphinxcontrib.video']
+
+# raise a warning when a secondary source is missing.
+video_enforce_extra_source = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -259,6 +262,8 @@ def get_tutorial_images():
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
+
+# videos is secondary source for sphinxcontrib-videos, everything below gets into _build/html/_static
 html_static_path = ['mss_theme', 'gallery/plots', 'videos']
 
 # Add any extra paths that contain custom files (such as robots.txt or

docs/environment.yml

@@ -15,6 +15,7 @@ dependencies:
       - xstatic
       - defusedxml
       - sphinx_rtd_theme
+      - sphinxcontrib-video
       - sphinx
       - fs
       - netCDF4

docs/gentutorials.rst

@@ -203,4 +203,4 @@ batch scripts
 
 Two batch scripts can be used to create tutorials.
 `start_tutorial.sh` is to create one tutorial and `tutorials.batch`
-is used to create all tutorials compressed to gifcycles.
+is used to create all tutorials.

docs/tutorial.rst

@@ -6,7 +6,32 @@ During GSOC 2021 a bunch of new tutorials were programmed by Hrithik Kumar Verma
 a `public share <https://fz-juelich.sciebo.de/s/IzNGi24Ki68iV7t#pdfviewer>`_
 
 
-Some videos about the Mission Support System (MSS)
+Get familiar by some videos about the Mission Support System (MSS).
+
+
+  .. video:: _static/mp4/tutorial_waypoints.mp4
+     :autoplay:
+     :loop:
+     :alt: This is the waypoints tutorial,i.e., whenever we are going to plan
+           a flight track, we have to place the waypoints in some places and,
+           form a flight path.
+           The origin is set at Nagpur, New Delhi being the first way point.
+           Clicking ADD WAY POINT BUTTON, we can add new way points.
+           The WAY POINTS 2,3,4 and 5 are added at required locations.
+           We are moving the WAY POINT NO.5 by clicking the MOVE WAY POINT button.
+           We can see that blue dot is demonstrating the click and we hit a WAY POINT.
+           Now, we are going to delete a WAY POINT, it is asking for the confirmation to delete it or not.
+           For placing the WAY POINTS and other operations, we have options to select Europe, Germany, and so on.
+           Selecting GLOBAL displays the  world map.
+           For a customised map, we can click on zoom button, and drag the cursor over map, clicking left.
+           We can also pan the map.
+           Clicking Left and Right arrow buttons changes the map region to previous and next respectively.
+           Clicking Home button on the top left shows the global view of the map.
+           Finally we can save the map by clicking SAVE button. This saves the image in .png format.
+
+
+
+
 
 .. toctree::
    :maxdepth: 4

docs/tutorials/tutorial_hexagoncontrol.rst

@@ -1,7 +1,16 @@
-Tableview and hexagon flight patterns
--------------------------------------
+Table View and Hexagon Flight Patterns
+--------------------------------------
 
-For tomographic imaging, a hexagonal flight pattern with tablevin the flight path can be integrated.
+For tomographic imaging, a hexagonal flight pattern can be integrated by a docking widget of Table View
 
-
- .. image:: /videos/gif/tutorial_hexagoncontrol.gif
+   .. video:: ../_static/mp4/tutorial_hexagoncontrol.mp4
+     :alt: Top View windows is opened (CTRL+H).
+           We select the "global (cyl)" for the world map.
+           Zooming in for the required region.
+           Assuming Delhi as the center we are to place waypoints around it in a hexagonal fashion.
+           Opening Table View (CTRL+T). It contains the latitudinal and longitudinal locations of waypoints.
+           Doing this manually will not be perfect and hence, hexagon control!
+           Clicking on "(select to open control)", and selecting "(hexagonal control)"
+           This screen can be used to place the latitude and longitude of center, and radius of hexagon.
+           We can see the changes in the Top View.
+           Angle of first point can also be changed, which is by default set at 0.

docs/tutorials/tutorial_introduction_topview.rst

@@ -1,6 +1,43 @@
-Topview and selecting of layers
--------------------------------
+Top View and Selecting of Layers
+--------------------------------
 
-Selection and display of different data in the topview with the help of the layer chooser.
+Selection and display of different data in the Top View with the help of the layer chooser.
 
- .. image:: /videos/gif/tutorial_wms.gif
+  .. video:: ../_static/mp4/tutorial_wms.mp4
+     :alt: When we open the Top View (CTRL+H) of the map, the Web Map Service is already opened by default.
+           It collects its data from the server: "open-mss dot org" that provides demodata for the meteorological or
+           atmospheric informations as layer lists.
+           As we click on the "server layer" option, the layer list window opens that lists out various layers.
+           We just have to enter the WMS url and get capabilities for those layers.
+           So, here we find various layers: Divergence and Geopotential Height,
+           Equivalent potential temperature and geo potential height, etc.
+           When we click on the "Divergence" layer, some divergence in height that are marked by blue and
+           red lines are displayed.
+           Similarly, when we move on to the "Equivalent potential temperature" layer,
+           we find various temperature potentials at various places on the map.
+           We can also customize the levels, that is, the pressure levels after selecting a particular layer.
+           As we enter "temperature" in layer filter, all the relevant layers related to temperature are displayed.
+           In multilayering, we can see more than one layers such as temperature and pressure together
+           at the same time displayed onto the map.
+           Suppose we are using any layer frequently, we can just star it and find it easily using layer filter.
+           Now coming to "Divergence and Geopotential Height", we can check the map at various atmospheric pressures such
+           as at 150 hPa or 200 hPa or 500 hPa.
+           Initialisation shows the date and time from which the data is available. Here it is 17/10/12.
+           Valid shows the date and time till the data available is valid.
+           Here it is 17/10/12 and time is 12:00 UTC.
+           We can customize these points as per our requirement.
+           We can select the various initialization and valid interval slots as per availability.
+           For example, when we select 3 hours initialization time, we can see the date and time marked crossed
+           as there is no such initialization time ahead or back.
+           Similarly, when we select 6 hours valid time we can see the time changes to 18:00 UTC.
+           Coming to the auto-update, if it is checked then whatever is selected on the list gets updated on
+           the map automatically.
+           If the "auto update" option is not checked then we have to press retrieve after
+           each selection on the layer list.
+           If we select "use cache" as checked, then it takes less time to load the data from layer list
+           on the map but if its unchecked it takes more time to load.
+           We can also click on "clear cache" to clear the cache that is stored locally for the layer lists data.
+           There is a "delete trashcan button" on the top left corner of the layer list to clear all the
+           layers loaded from the server.
+           Clicking on remove deletes the layer data on the map.
+           Now we close the WMS layer list window.

docs/tutorials/tutorial_kml.rst

@@ -1,6 +1,26 @@
-Topview and KML data
---------------------
+Top View and KML Data
+---------------------
 
-es can be displayed in the Topview. Color and line width can be adjusted.
+es can be displayed in the Top View. Color and line width can be adjusted.
 
- .. image:: /videos/gif/tutorial_kml.gif
+  .. video:: ../_static/mp4/tutorial_kml.mp4
+     :alt: Open the TopView (CTRL+H)
+           After clicking on "(select to open control)", click on KML OVERLAY. The UI will look as shown.
+           KML files can be used to show the geographical boundary which helps in planning the WAY POINTS.
+           We can put the WAY POINTS along this line. We will now see how to add, move, select KML files.
+           We can see two KML files here, one is COLOR.KML ; and the another one is FOLDER.KML.
+           COLOR.KML is in black colour, FOLDER.KML is denoted by black colour.
+           The box is checked that shows that these KML files are shown in the map, if unchecked, it will not show.
+           Now, we will add KML files by clicking on ADD KML FILES.
+           The dialogue will be opened and it will add the path where the KML file is present.
+           You can also select it through the file dialogue.
+           When we add a KML file, the default colour is Black and the default linewidth is 2 units.
+           Now, let's change colour and line width of the KML files. Before that, we add another KML file.
+           Both the KML files will be opened when we will open the GLOBAL map.
+           Both the files are in black colour.
+           Now, we will change colour of FOLDER.KML file by selecting it and clicking on CHANGE COLOUR.
+           We change it from Black to blue followed by blue to green.
+           Changing it for some time...
+           Now, we change line width by changing its numerical value whose range is 0 to 10.
+           We change it to different values to obtain different linewidths.
+           The top view is closed and the tutorial ends.

docs/tutorials/tutorial_mscolab.rst

@@ -1,7 +1,93 @@
 Introduction to MSUI and MSColab
 --------------------------------
+
 Using the different views of the MSUI with a fictitious flight path and demo data.
 In comparison to the standalone mode of the MSUI an example setup of users is
 shown on a MSColab server and the possibilities of interactions.
 
- .. image:: /videos/gif/tutorial_mscolab.gif
+  .. video:: ../_static/mp4/tutorial_mscolab.mp4
+     :alt: MSColab stores data in an online server, and can be used to access the data remotely as also working in a
+           team where everyone contributes his part. It is used for collaborating with the users as a team together
+           and working on a shared MSColab operation.
+           In the window opened, enter MSColab url and click on connect.
+           "successfully connected to the MSColab server"
+           we can enter Email id and Password for an existing user, else we can click on Add user to register a new user.
+           Filling new user details, and clicking OK.
+           As, the user exists, we are logged in.
+           Now the user John Doe is logged in to MSColab.
+           He can now start working on shared operation.
+           Go to File  and then New and then MSColab Operation option.
+           Add MSColab operation
+           MSS operation window opens
+           name the path, give the Description of the operation.
+           we can also choose a flight track file or dot FTML file, which is stored on our computer.
+           Add operation by clicking OK.
+           "your operation was successfully created"
+           Double click on the shared operation name to activate it.
+           While working on a shared file, we can control who can access this operation.
+           Go to Operation and then below Maintenance, "Manage Users."
+           Admin Window-MSS pops up.
+           The left side has list of users without permission, while the right side has a list of those users who have been granted an access to this operation.
+           In All Users without permission section, we can select all users at a time or deselect all of them, or we can search for  a user.
+           We search for the user "test" in the server.
+           Now we empty the search bar.
+           After selecting users, we click on Add button, which moves these users to All users with permission section to the right side of the window.
+           For the users who have access permission to the operation, we can also change the access roles.
+           Here for b, we have changed the permission from collaborator to admin.
+           We can alo delete a user with a permission by selecting user and clicking on delete button.
+           Changing their access roles....
+           We can filter users based on their roles being Collaborator, admin or viewer.
+           Filtering for some time....
+           We can also communicate with fellow users in our operation.
+           Go to Operation and then Chat option.
+           Click on it.
+           MSColab chat window pops up.
+           The left pan shows the list of people who have access to this operation.
+           Enter the message in the space provided.
+           Typing the texts.....
+           click on send button, or press Enter.
+           Typing another message....
+           we can upload files by clicking on upload and browsing for the file.
+           Here, we send the mss logo to all the users to see.
+           We can also search for a message by entering a phrase or complete text and then pressing previous or next as we need to find the message.
+           Next, we close the chat window.
+           Now, we will see how to manage version history.
+           We will go to operations and then click version history..
+           Version history is basically a record in the changes performed in the waypoints of the flight  track.
+           We can switch to a particular version history and name that version according to our choice or just checkout to that version.
+           In that case, the current waypoints will be changed to that version of waypoints and their locations.
+           Now we will just surf through all the version history.
+           We change the name of one version history to "Initial Waypoints" by clicking on "Name Version"
+           Now, we select another waypoint version and then checkout to that version by clicking on checkout button.
+           It asks for a confirmation.
+           Now we close the version history window...
+           We then select work asynchronously checkbox. It means that we are offline at present.
+           Later, we can save our changes to server or fetch new changes from the server changed by other people or the changes present on the server the last time.
+           We then open Top View and move the waypoints for making changes...
+           We then open drop down menu of "save to server."
+           It will open a window.
+           We can either click overwrite server waypoints with local waypoints or local waypoints with server waypoints.
+           We click overwrite with local waypoints.
+           The server waypoint changes with the work we have done locally.
+           Now it gives a confirmation message. "Added local waypoints to server"
+           Now we will close the window.
+           We will again start work synchronously with other users by unchecking "Work Unsynchronously."
+           We can switch between local flight tracks and shared operation by double clicking any one of them.
+           Remember, at any point only one flight track can be active, either local or shared.
+           Now we make changes in the Top View of local flight track.
+           Opening Top View and making the changes....
+           Adding waypoints....
+           We can see new waypoints are added here in a different fashion.
+           It is different from the first set of waypoints we have selected and added.
+           We now close the Top View.
+           The local flight track got changed.
+           Now for confirming, we open the shared flightrack by activating it.
+           We open Top View and can see it is different form local flightrack.
+           We now close the Top View and answer the confirmation.
+           We now delete the operation, see Maintenance in the Operation menu.
+           We have to retype its name for the confirmation for deleting it.
+           Now, we click on John Doe's User profile and we select the Profile of the user.
+           We can see his email and server its connected to!
+           Now, we log the user out.
+           We close the MSColab window and it asks for confirmation.
+           This is all about MSColab.