merging in GSOC2021-HrithikKumarVerma

docs/components.rst

@@ -8,5 +8,6 @@ Components
    deployment
    mscolab
    demodata
+   tutorials
 
 

docs/development.rst

@@ -1,6 +1,5 @@
 .. _development:
 
-===========
 Development
 ===========
 
@@ -134,6 +133,7 @@ Installing dependencies
 
 MSS is based on the software of the conda-forge channel located, so we have to add this channel to the default::
 
+
   $ conda config --add channels conda-forge
 
 Your content of the .condarc config file should have conda-forge on top::

docs/samples/config/mss/performance_simple.json.sample → docs/samples/config/mss/performance_simple.json

@@ -10,6 +10,6 @@
     "_comment2": "takeoff_weight: maximum weight for takeoff (lbs)",
     "_comment3": "empty_weight: aircraft weight without fuel (lbs)",
     "_comment4": "climb/descent: weight(lbs), altitude(ft), duration(min), distance(nm), fuel(lbs)",
-    "_comment5": "cruise: weight(lbs), altitude(ft), total air speed(nm/h), fuel flow(lbs/h)"
+    "_comment5": "cruise: weight(lbs), altitude(ft), total air speed(nm/h), fuel flow(lbs/h)",
     "_comment6": "ceiling: polynomial coeficients for relating weight (lbs) with peak flightlevel (hft). Leftmost coefficient is the intercept."
 }

docs/tutorials.rst

@@ -0,0 +1,194 @@
+==============================================================================
+A user guide for tool chain of automated tutorials for the MSUI user interface
+==============================================================================
+
+The tool chain for tutorials are automatically generated tutorials by use of python scripts to automate the software to
+perform different tasks and hence, demonstrating and explaining to the user various parts of the MSS software. It tells
+the user about the different technical aspects of MSS which a new user would take time to know that, otherwise.
+
+There are nine such total automating scripts that are meant for explaining nine such parts or sub parts of MSS software
+and it's use.
+Listing them below as:
+
+* tutorial_hexagoncontrol.py for explaining hexagon control in table view.
+
+* tutorial_kml.py for explaining kml dockwidget in topview.
+
+* tutorial_mscolab.py for understanding mscolab feature of MSS.
+
+* tutorial_performancesettings.py for giving a demo what is there in performance settings of table view.
+
+* tutorial_remotesensing.py for demonstrating remote sensing dockwidget of topview.
+
+* tutorial_satellitetrack.py for demonstrating satellite track dockwidget of topview.
+
+* tutorial_views.py for demonstrating the top view, sideview, table view and linear view together.
+
+* tutorial_waypoints.py for demonstrating how to place waypoints in topview.
+
+* tutorial_wms.py for explaining web map service section of topview.
+
+Other important files with their functions are as follows:
+
+* screenrecorder.py for opening a screen recorder window which is a small window in the top right corner of the
+  rectangular recording area on the screen. The window gets closed when you press 'q' keeping the window in focus. This
+  will also stop the recording of the screen when window gets closed.
+
+* cursor.py which is used for generating the image of the present cursor image.
+
+* audio.py which translates and converts into speech the texts and saves them as .mp3 files.
+
+System Requirements
+===================
+Keep the following things in mind before running a script
+
+* You should have only an **US keyboard layout**. If you have a different keyboard layout, you just need to change it to
+  US keyboard!
+* The **cursor.py** python file will run only on Linux and not on Windows for grabbing the mouse pointer image.
+
+* The screenrecorder.py works only in **Full HD Screens**.
+
+* The screen recording starts as the recording window appears and ends when you quit the recording window by pressing
+  'q' when the window is being displayed in the foreground.
+
+* The **audio.py** file should have translation APIs and text-to-speech (t2s) APIs written at specified places inside it
+  to run successfully! It has a #ToDo to read.
+
+
+Getting Started..
+=================
+
+On the Anaconda terminal, type the following ::
+
+ cd ..../MSS/$
+ $ export PYTHONPATH=.../MSS        # Path of MSS
+ $ conda activate mssdev
+
+
+ (mssdev)$ mamba install --file requirements.d/tutorials.txt
+ (mssdev)$ conda deactivate
+ (base)$ conda activate mssdev
+
+
+This will install all the dependencies required for running of the tutorials.
+
+
+**On Linux additionally** ::
+
+    $ sudo apt-get install scrot
+    $ sudo apt-get install python3-tk
+    $ sudo apt-get install python3-dev
+    $ sudo apt-get install libx11-dev libxext-dev libxfixes-dev libxi-dev
+
+
+Now, just go into the **../MSS/tutorials/** directory ::
+
+    $ cd ../MSS/tutorials/
+
+
+**Note**
+
+You must go into the tutorials directcory and then run the .py files. And always remember to add the PYTHONPATH to
+........../MSS/ directory.
+You cannot just do like this ::
+
+    $ python MSS/tutorials/sreenrecorder.py     # This will be problematic.
+
+
+In Linux for making the cursor visible as a highlighter, perform the following
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you are in Windows, there is no need of this highlighter. It is by default that it also records the mouse-pointer.
+
+* Clone the repository https://github.com/swillner/highlight-pointer.git into a directory eg. `highlighter` on your system
+
+Change directory into that location ::
+
+$ cd highlighter/highlight-pointer/
+$ make
+
+After the `make` gets successful, run ::
+
+$ ./highlight-pointer -r 10
+
+This will make your cursor highlighted as a red cursor having radius as 10. You can minimize the terminal and continue
+your work with the highlighted cursor.
+When you have to stop just open that terminal again and type **CTRL + C**
+
+For more details in its customization, you can visit https://github.com/swillner/highlight-pointer
+
+The Running of the Scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Each python file inside MSS/tutorials can be run directly like ::
+
+(mssdev)~/..MSS/tutorials/ $ python screenrecorder.py
+
+For recording anything on your screen. The videos will be then saved to `MSS/tutorials/Screen Recordings/`
+
+For all the tutorials, you can do the same, example ::
+
+(mssdev)~/..MSS/tutorials/ $ python tutorial_remotesensing.py
+(mssdev)~/..MSS/tutorials/ $ python tutorial_satellitetrack.py
+(mssdev)~/..MSS/tutorials/ $ python tutorial_hexagoncontrol.py
+
+The `MSS/tutorials/textfiles` contain descriptions of the tutorial videos in text format, these later can be
+converted to audio files by `audio.py` script after adding certain #ToDOs there.
+
+**Note**
+In  tutorials development, when creating a class of Screen Recorder as ::
+
+$ rec = ScreenRecorder(x_start, y_start, width, height) or $ rec = ScreenRecorder()
+$ rec.capture()
+$ rec.stop_capture()
+
+When no arguments are passed to ScreenRecorder class during object creation, it records full screen but if you have to
+record a particular area of screen, just pass the below parameters.
+
+* "x_start" is the starting pixel from left or how many pixels from the left panel it will capture the screen area.
+* "y_Start" is the starting pixel from top or how many pixels down from the top panel, it will start capture.
+* "width" is the pixel length from x_start that will form the recording area.
+* "height is the pixel length from y_start that will from the recording area.
+
+The top left corner is (0,0) and the width for eg is 1920 and the height for eg is 1080 of my screen.
+
+Knowing MouseInfo()
+~~~~~~~~~~~~~~~~~~~
+For deciding the pixels, or know how  much length or height i should go down or what is the relative distance of one
+point from the other, pyautogui's mouseInfo() comes to the rescue ::
+
+    (mssdev)$ python
+    $ import pyautogui
+    $ pyautogui.mouseInfo()
+
+This will open a window which will be very helpful in development and other pixel position related things.
+
+.. Important::
+  MSS/tutorials is still under development, so if the automation makes problems in your system, it may be due to certain
+  parameters specific to your system and also since it is not widely used and tried, there will be always a scope of
+  improvement. Kindly report that bug or discrepancies to https://github.com/Open-MSS/MSS/issues/new
+
+Videos post processing via ffmpeg
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The post processing of the videos can be done using ffmpeg in Command Line Interface.
+
+The generated video size is too large, so if you want to reduce the size, you can ::
+
+    $ cd MSS/tutorials/Screen Recordings/
+    (mssdev)$ ffmpeg -i input.mp4 -vcodec h264 -acodec mp2 output.mp4
+
+For trimming the videos from a start (00:14:00) and end time (05:19:00), you can ::
+
+    $ cd MSS/tutorials/Screen Recordings/
+    (mssdev)$ ffmpeg -i input.mp4 -ss 00:14:00 -to 05:19:00 -c:v libx264 -crf 30 output.mp4
+
+For cropping the video
+(you can also use Screen Recorder for selected screen area recording feature as described above) ::
+
+    $ cd MSS/tutorials/Screen Recordings/
+    (mssdev)$ fmpeg -i input.mp4 -filter_complex "[0:v]crop=1919:978:0:33[cropped]" -map "[cropped]" output.mp4
+
+    # “crop=width:height:x:y” is the format
+
+For merging audios into the video ::
+
+    (mssdev)$ ffmpeg -i input.mp4 -i audio.mp3 -c:v copy -c:a aac output.mp4
+In this case, the video and audio must be in same directory and you should cd into that directory.

requirements.d/tutorials.txt

@@ -0,0 +1,9 @@
+# This file may be used to create an environment using:
+# $ conda create --name <env> --file <this file>
+# platform: linux-64
+mouseinfo=0.1.3=pypi_0
+opencv=4.5.2=py39hf3d152e_0
+playsound=1.3.0=pypi_0
+pyautogui=0.9.48=py39hde42818_1
+pyscreeze=0.1.27=pyhd8ed1ab_0
+python-mss=6.1.0=pyhd3deb0d_0

tutorials/audio.py

@@ -0,0 +1,107 @@
+"""
+    mss.tutorials.audio
+    ~~~~~~~~~~~~~~~~~~~
+
+    This python script is meant for generating audio of our choice from text files describing the tutorial.
+
+    This file is part of mss.
+
+    :copyright: Copyright 2021 Hrithik Kumar Verma
+    :copyright: Copyright 2021 by the mss team, see AUTHORS.
+    :license: APACHE-2.0, see LICENSE for details.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+import os
+import time
+import playsound
+from glob import glob
+
+# ToDo We have to add translation services
+# e.g. https://cloud.google.com/translate/docs, https://www.deepl.com/pro?cta=menu-plans/
+
+"""
+Please import here, the modules you need for text translations (tt) and text-to-speech conversions (t2s).
+Example:
+        import xyz as tt                # For translating text
+        from zyx import abc as t2s      # For converting text to speech
+"""
+# xyz don't add credential of API keys here, this has to be done later as secret for a CI call
+
+
+class TutorialAudio:
+    """
+        This is the audio class for storing audio files and playing them.
+    """
+    def __init__(self):
+        """
+            The constructor sets the translator object and audio path for storing the audios.
+        """
+        # Use here instead of None the function of the translator for eg tt.Translator()
+        self.translate = None
+        self.audio_path = os.path.join(os.getcwd(), "Audio Files")
+        os.makedirs(self.audio_path, exist_ok=True)
+
+    def translate_text(self, input_text, input_lang, output_lang):
+        """
+        This function is used to translate texts packets in the output language passed to the function.
+        """
+        txt = self.translate.translate(input_text, src=input_lang, dest=output_lang)
+        return txt.text
+
+    def text_to_audio(self, source_lang, destination_lang):
+        """
+        This function is used to convert text file into speech of selected choice passed as parameter and store the
+        audio files and playing them. It converts all text files one by one present in the "tutorials/textfiles" folder.
+        """
+        for f in glob("textfiles/*.txt"):
+            print(f"\nINFO : Please wait, the text file {f} is being converted to audio file...\n")
+            with open(f) as file:
+                source_text = file.read()
+                if source_lang == destination_lang:
+                    destination_text = source_text
+                else:
+                    destination_text = self.translate_text(source_text, source_lang, destination_lang)
+                print(destination_text)
+                # Use here instead of None the function of the speech converter t2s()
+                # add the function to translate text to speech (input parameters are destination_text, destination_lang)
+                destination_speech = None
+            pathstring = os.path.splitext(f)[0]
+            pathstring_list = pathstring.split("/")
+            audio_file = pathstring_list[len(pathstring_list) - 1] + f"_{destination_lang}_" + ".mp3"
+            destination_speech.save(os.path.join(self.audio_path, audio_file))
+            print(f"\n\nINFO : Converted the text file {f} into audio file successfully!\n\n")
+
+        for f in glob(f"{self.audio_path}/*.mp3"):
+            try:
+                print(f"\nPlaying {f}........\n")
+                playsound.playsound(f)
+                print(f".\n.\n.\n.\nFinished Playing the {f} file!")
+            except KeyboardInterrupt:
+                print("The preview of the mp3 file has been finished.")
+            time.sleep(1)
+
+
+def main():
+    audutorial = TutorialAudio()
+    # Since the text file is written in english, the input language is english.
+    input_lang = 'en'
+    # English, French, German respectively in output_languages. We could add more number of languages according
+    # to our choice and need in the below list.
+    output_languages = ['en', 'fr', 'de']
+    # Presently, the output audio stream has been set to German.
+    audutorial.text_to_audio(input_lang, output_languages[2])
+
+
+if __name__ == '__main__':
+    main()