Tutorials with usage examples.

aerospaceresearch · Jul 2, 2019 · e2202a2 · e2202a2
1 parent 0278665
commit e2202a2
Show file tree

Hide file tree

Showing 53 changed files with 646 additions and 9 deletions.
diff --git a/directdemod/merger.py b/directdemod/merger.py
@@ -1,6 +1,6 @@
 """
 This module provides an API for merging multiple images.
-It extracts needed information and projects images on mercator
+It extracts needed information and projects images onto mercator
 projection.
 """
 

diff --git a/directdemod/misc.py b/directdemod/misc.py
@@ -264,7 +264,7 @@ def main() -> None:
     parser.add_argument('-f',
                         '--file_sdr',
                         required=True,
-                        help='Path to SDR recording file.')
+                        help='Path to recorded SDR file.')
     parser.add_argument('-i',
                         '--image_name',
                         required=True,

diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle
diff --git a/docs/_build/doctrees/index.doctree b/docs/_build/doctrees/index.doctree
diff --git a/docs/_build/doctrees/tutorials.doctree b/docs/_build/doctrees/tutorials.doctree
diff --git a/docs/_build/doctrees/visualization.doctree b/docs/_build/doctrees/visualization.doctree
diff --git a/docs/_build/html/_modules/directdemod/chunker.html b/docs/_build/html/_modules/directdemod/chunker.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/comm.html b/docs/_build/html/_modules/directdemod/comm.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/decode_afsk1200.html b/docs/_build/html/_modules/directdemod/decode_afsk1200.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/decode_funcube.html b/docs/_build/html/_modules/directdemod/decode_funcube.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/decode_meteorm2.html b/docs/_build/html/_modules/directdemod/decode_meteorm2.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/decode_noaa.html b/docs/_build/html/_modules/directdemod/decode_noaa.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/demod_am.html b/docs/_build/html/_modules/directdemod/demod_am.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/demod_fm.html b/docs/_build/html/_modules/directdemod/demod_fm.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/filters.html b/docs/_build/html/_modules/directdemod/filters.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/georeferencer.html b/docs/_build/html/_modules/directdemod/georeferencer.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/log.html b/docs/_build/html/_modules/directdemod/log.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/merger.html b/docs/_build/html/_modules/directdemod/merger.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 
@@ -148,7 +149,7 @@
   <h1>Source code for directdemod.merger</h1><div class="highlight"><pre>
 <span></span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">This module provides an API for merging multiple images.</span>
-<span class="sd">It extracts needed information and projects images on mercator</span>
+<span class="sd">It extracts needed information and projects images onto mercator</span>
 <span class="sd">projection.</span>
 <span class="sd">&quot;&quot;&quot;</span>
 

diff --git a/docs/_build/html/_modules/directdemod/misc.html b/docs/_build/html/_modules/directdemod/misc.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 
@@ -412,7 +413,7 @@ <h1>Source code for directdemod.misc</h1><div class="highlight"><pre>
     <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span>
                         <span class="s1">&#39;--file_sdr&#39;</span><span class="p">,</span>
                         <span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
-                        <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Path to SDR recording file.&#39;</span><span class="p">)</span>
+                        <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Path to recorded SDR file.&#39;</span><span class="p">)</span>
     <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-i&#39;</span><span class="p">,</span>
                         <span class="s1">&#39;--image_name&#39;</span><span class="p">,</span>
                         <span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>

diff --git a/docs/_build/html/_modules/directdemod/sink.html b/docs/_build/html/_modules/directdemod/sink.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/directdemod/source.html b/docs/_build/html/_modules/directdemod/source.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/index.html b/docs/_build/html/_modules/index.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_modules/json/encoder.html b/docs/_build/html/_modules/json/encoder.html
@@ -83,6 +83,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/_sources/index.rst.txt b/docs/_build/html/_sources/index.rst.txt
@@ -18,6 +18,7 @@ Some tutorials on how to use the modules and write your own scripts or to extend
    gettingstarted.rst
    modules.rst
    visualization.rst
+   tutorials.rst
 
 
 Indices and tables

diff --git a/docs/_build/html/_sources/tutorials.rst.txt b/docs/_build/html/_sources/tutorials.rst.txt
@@ -0,0 +1,125 @@
+.. DirectDemod documentation master file, created by
+   sphinx-quickstart on Thu May 17 00:16:36 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Tutorials
+======================
+
+This section presents several usage examples of directdemod package.
+Each usage example is accompanied with thorough explanation and
+an appropriate data, which is stored in `tutorial/data/` folder.
+
+Data extraction (misc.py)
+--------------------------
+
+`misc.py` script is used to perform data extraction of satellite parameters. When running, `misc.py`
+will extract data from SDR file, create copy of provided image with .tif extension and embed
+extracted data as json into it. CLI interface receives following console options:
+
+-f, --file_sdr  path to recorded SDR file
+-i, --image_name  path to decoded and preprocessed image
+-t, --tle  path to tle file
+-s, --sat_type  satellite type
+
+Tle and satellite type parameters are optional.
+The `tutorial/data/metadata` directory contains sample files - sdr file and the decoded image.
+Sample command:
+::
+
+    python directdemod/misc.py -f tutorial/data/metadata/SDRSharp_20190521_170204Z_137500000Hz_IQ.wav \
+    -i tutorial/tutorial/data/metadata/image.png
+
+Created `image.tif` file will contain the satellite data (orbit parameters, satellite type etc. )
+in json format along with the image itself; it will be ready for performing georeferencing.
+
+Georeferencer
+----------------------
+
+Georeferencer class is intended to provide methods for georeferencing NOAA images.
+It provides CLI interface for running the program from command line. CLI interface takes following
+options (map, resample and output_file are optional):
+
+-i, --image_name  path to image file
+-o, --output_file  name of output file
+-m, --map  flag to create map overlay
+-r, --resample  resample algorithm
+
+Georeferencer assumes that the image passed via `--image_name` option contains a descriptor file
+embedded within it. If the file doesn't contain it, the processing will result in an error.
+
+As an example usage let's say we have a decoded and preprocessed NOAA image `start.png` and the file
+it was extracted from `SDRSharp_20190521_170204Z_137500000Hz_IQ.wav`. To receive a georeferenced image
+we need to do the following:
+
+1. Extract the information from `.wav` file name and save it to `start.tif` file.
+2. Georeference tif file.
+
+To extract data `misc.py` command is used (see misc.py docs).
+::
+
+    python directdemod/misc.py -f tutorial/data/georef/SDRSharp_20190521_170204Z_137500000Hz_IQ.wav \
+    -i tutorial/tutorial/data/georef/start.png
+
+
+To georeference the file we use `georeferencer.py` file. `start.tif` will contain georeferenced image.
+::
+
+    python directdemod/georeferencer.py -i tutorial/data/georef/start.tif
+
+Map Overlay
+----------------
+
+Map overlay can be created using `--map` option of the georeferencer. After the georeferencing is done
+map borders shapefile will be overlayed on top of it.
+
+To create an overlay over image use the following command.
+::
+
+    python directdemod/georeferencer.py -m -i tutorial/data/overlay/no_overlay.tif \
+    -o tutorial/data/overlay/with_overlay.tif
+
+Merger
+---------------
+
+Merge is used to combine several georeferenced images into one single raster, taking care
+of overlapping regions. Merger CLI interface has following console options:
+
+-f, --files  list of input files
+-o, --output  name of output file
+-r, --resample  resample algorithm
+
+Resample option receives one of the four merging method names:
+
+1. first
+2. last
+3. average
+4. max
+
+The `tutorial/data/merge` directory contains several example usage files. `image1.tif` and
+`image2.tif` are sample files for merging. Use following command to merge them (resample average):
+::
+
+   python directdemod/merger.py -o tutorial/data/merge/merged.tif -r average \
+   --files tutorial/data/merge/image1.tif tutorial/data/merge/image2.tif
+
+The `tutorial/data/merge/merged.tif` file will be created after running the above command.
+You can compare it with other merging methods (`average.tif`, `max.tif`, `first.tif`, `last.tif`).
+
+Map generation tutorial
+-----------------------
+
+To generate visualization of raster use `generate_map.py` interface.
+The following command will generate a TMS (Tile Map Service) and 2 visualization files in
+`samples/tms` directory.
+
+::
+
+   python directdemod/generate_map.py --raster samples/decoded/raster.tif --tms samples/tms
+
+You can run `map.html` by opening it directly in the browser.
+To run `globe.html` go to tms directory and start the http server on port 8000 (python3):
+
+``python -m http.server 8000``
+
+Then open browser and go to `http://localhost:8000/globe.html`.
diff --git a/docs/_build/html/genindex.html b/docs/_build/html/genindex.html
@@ -84,6 +84,7 @@
 <li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/index.html b/docs/_build/html/index.html
@@ -84,6 +84,7 @@
 <li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
 </ul>
 
 
@@ -181,6 +182,14 @@ <h1>Welcome to DirectDemod’s documentation!<a class="headerlink" href="#welcom
 <li class="toctree-l2"><a class="reference internal" href="visualization.html#json-encoder">Json encoder</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="tutorials.html#data-extraction-misc-py">Data extraction (misc.py)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorials.html#georeferencer">Georeferencer</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorials.html#map-overlay">Map Overlay</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorials.html#merger">Merger</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorials.html#map-generation-tutorial">Map generation tutorial</a></li>
+</ul>
+</li>
 </ul>
 </div>
 </div>

diff --git a/docs/_build/html/objects.inv b/docs/_build/html/objects.inv
diff --git a/docs/_build/html/py-modindex.html b/docs/_build/html/py-modindex.html
@@ -86,6 +86,7 @@
 <li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
 </ul>
 
 

diff --git a/docs/_build/html/search.html b/docs/_build/html/search.html
@@ -84,6 +84,7 @@
 <li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">DirectDemod: Getting Started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="modules.html">DirectDemod: Modules documentation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="visualization.html">Visualizations routine</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
 </ul>