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.
Note: python version should be higher then 3.6, preferably 3.7. In tutorials below python command refers to python3.
Note on warnings: depending on your python version you can see the following warnings, which is ok, they are not the errors of the program.
YAMLLoadWarning: calling yaml.load() without Loader=… is deprecated
Warning 1: TIFFReadDirectoryCheckOrder:Invalid TIFF directory; tags are not sorted in ascending order
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/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:
Extract the information from .wav file name and save it to start.tif file.
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/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:
first
last
average
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.
Help¶
If you encountered an error or want to add a fix, you can contact us directly on
github.com/aerospaceresearch/DirectDemod
.